@reticlehq/server 2.11.0 → 2.13.0

package/dist/setup/setup-command.js

@@ -0,0 +1,199 @@
+/**
+ * The wire: everything init established, plus the world, plus the phases.
+ *
+ * Kept apart from cli.ts so the assembly is readable in one place and so `handleInit` stays the
+ * three lines it was. The only decision here is which effects to hand over; the sequencing lives in
+ * run-setup.ts and the pieces it calls.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { planAgentConfigs } from './agent-configs.js';
+import { AppShape, readShape } from './desktop-shape.js';
+import { stopOnInterrupt } from './interrupt.js';
+import { applyAgentPlan, applyAgentSkills } from './agent-writer.js';
+import { ApprovalOutcome, grantAutoApproval } from './auto-approve.js';
+import { agentIo } from './agent-io.js';
+import { EnsureDaemon, ensureDaemon, nodeEnsureDaemonDeps } from './ensure-daemon.js';
+import { openInBrowser } from '../cli/cli-launch.js';
+import { chooseDriver, DRIVERS, shouldEscalate } from './drive-plan.js';
+import { driveWith } from './drive-agent.js';
+import { binaryExists, flowsSaved, listSessions, OwnedDevServer, probePage, } from './node-effects.js';
+import { runSetupPhases, } from './run-setup.js';
+/** The capabilities file init scaffolds, in the order a project is likely to have it. */
+const CAPABILITY_FILES = ['reticle-dev.tsx', 'reticle-dev.ts', 'reticle-dev.jsx', 'reticle-dev.js'];
+/** `electron` in either dependency list, read the same way init's desktop doctor reads it. */
+function hasElectronDependency(dir) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+        if ('object' !== typeof pkg || null === pkg)
+            return false;
+        const p = pkg;
+        return undefined !== { ...p.dependencies, ...p.devDependencies }['electron'];
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Register with the agents `init` does not reach, and leave the skill where one loads skills from.
+ *
+ * init covers eight clients and only where it finds them installed, which leaves VS Code's USER
+ * scope unwritten — it exists on machines today, and init only ever writes the project-scope file,
+ * so a VS Code user has no tools outside the directory they ran init in.
+ */
+export function registerOtherAgents(print) {
+    const platform = process.platform;
+    const home = homedir();
+    const results = applyAgentPlan(planAgentConfigs({ home, platform, exists: agentIo.exists, readFile: agentIo.readFile }), agentIo);
+    const wrote = results.filter((r) => 'created' === r.action || 'merged' === r.action);
+    if (0 < wrote.length) {
+        print(`registered the MCP server with ${wrote.length} more agent(s): ${wrote.map((r) => r.name).join(', ')}`);
+    }
+    // A format we will not rewrite is somebody's to edit, so it has to be said rather than skipped.
+    for (const manual of results.filter((r) => 'manual' === r.action)) {
+        print(`${manual.name}: ${manual.why} — add the reticle entry to ${manual.file} by hand.`);
+    }
+    const skills = applyAgentSkills(agentIo, { home, platform });
+    if (0 < skills.length)
+        print(`wrote the /reticle skill for ${skills.length} agent(s)`);
+    // Registration alone still leaves an Accept dialog in front of every call, and a verification run
+    // makes dozens of them: the loop is only autonomous once the tools are pre-approved.
+    const approvals = grantAutoApproval(agentIo, { home, platform });
+    const granted = approvals.filter((a) => ApprovalOutcome.GRANTED === a.outcome);
+    if (0 < granted.length) {
+        print(`pre-approved the reticle tools in ${granted.map((a) => a.name).join(', ')} — no Accept prompt per call`);
+    }
+    for (const noted of approvals.filter((a) => undefined !== a.warn)) {
+        print(`${noted.name}: ${String(noted.warn)}`);
+    }
+}
+/**
+ * Run the phases against the real world.
+ *
+ * The dev server is stopped on every ending except success, where it is handed to the user: an
+ * instrumented app they can watch is the deliverable, and killing it would leave them with config
+ * files and a dead tab.
+ */
+export async function runSetupCommand(input, print) {
+    if (input.registerAgents)
+        registerOtherAgents(print);
+    // Before the app is booted, because the app's whole job from here is to dial this port. Without
+    // it the phases wait out their budget and then report the SDK as the thing that failed.
+    const daemon = await ensureDaemon(input.bridgePort, nodeEnsureDaemonDeps());
+    if (EnsureDaemon.UNAVAILABLE === daemon) {
+        print(`could not start the Reticle daemon on port ${String(input.bridgePort)}, so nothing is listening for the app to connect to. Run \`npx @reticlehq/server serve --port ${String(input.bridgePort)}\` and try again.`);
+    }
+    // Which shell this is decides three things the phases would otherwise get wrong: opening a
+    // browser (harmful for desktop, where the app's own window is the client), waiting for an HTTP
+    // port (a Tauri webview has none), and how long the app gets to appear (a cold `tauri dev` builds
+    // Rust first). The same evidence init's desktop doctor reads.
+    const shape = readShape({
+        hasTauriConf: existsSync(join(input.appDir, 'src-tauri', 'tauri.conf.json')),
+        hasElectronDep: hasElectronDependency(input.appDir),
+    });
+    if (AppShape.WEB !== shape)
+        print(`detected a ${shape} app`);
+    const server = new OwnedDevServer();
+    // Both roots, because in a monorepo `.reticle/` sits at the app root rather than where setup ran.
+    const flowRoots = [input.invokedAt, input.appDir];
+    let lastDrive;
+    let escalated;
+    const effects = {
+        startDevServer: (command, cwd) => {
+            print(`starting: ${command}`);
+            server.start(command, cwd, input.env);
+            return Promise.resolve();
+        },
+        devServerOutput: () => server.output(),
+        devServerExited: () => server.exited(),
+        devServerQuietForMs: () => server.quietForMs(),
+        observedPorts: () => server.listeningPorts(),
+        probePage,
+        openBrowser: async (url) => {
+            const failure = await openInBrowser(url);
+            if (null !== failure) {
+                print(`could not open a browser (${failure}). On a machine with none — CI, a container, an SSH ` +
+                    'session — take a tab Reticle owns instead: reticle_run({ tool: "reticle_lease", args: ' +
+                    `{ action: "acquire", url: "${url}" } }).`);
+            }
+        },
+        listSessions: () => listSessions(input.bridgePort),
+        // Asked before the drive rather than inferred from its result: "nothing to drive with" and
+        // "drove and proved nothing" are different answers and only the second is a failure.
+        driverAvailable: () => null !==
+            chooseDriver(DRIVERS, (bin) => ({ present: binaryExists(bin), runs: binaryExists(bin) })),
+        drive: (url, session) => {
+            const driver = chooseDriver(DRIVERS, (bin) => ({
+                present: binaryExists(bin),
+                // Present is not enough: a CLI that does not run produces an empty session that looks
+                // exactly like success.
+                runs: binaryExists(bin),
+            }));
+            if (null === driver)
+                return Promise.resolve(null);
+            // Only when the SESSION says they were never finished. init fills this file for a
+            // conventional app — it detects a state library and the testids — so opening it otherwise
+            // spends a turn on work already done, and grants write access nobody needed.
+            const capabilitiesFile = false === session.hasCapabilities
+                ? CAPABILITY_FILES.map((f) => join(input.appDir, 'src', f)).find((p) => existsSync(p))
+                : undefined;
+            print('');
+            print(`  ▸ WATCH ${url} NOW — the HUD is on, and you are about to see Reticle drive your app.`);
+            print('');
+            const request = {
+                url,
+                sessionId: session.sessionId,
+                tabThrottled: false,
+                budgetUsd: input.driveBudgetUsd,
+                ...(undefined === input.flow ? {} : { flow: input.flow }),
+                ...(undefined === input.driveModel ? {} : { model: input.driveModel }),
+                ...(undefined === capabilitiesFile ? {} : { unfinishedCapabilitiesFile: capabilitiesFile }),
+            };
+            lastDrive = driveWith(driver, request, input.appDir);
+            // A weak flow only ACTS, so it passes when the feature is broken — and setup replays saved
+            // flows, which turns one weak recording into a permanent green. Re-record it rather than
+            // hand the trade to the user.
+            if (shouldEscalate({
+                escalationEnabled: input.escalateWeakFlow,
+                fasterModel: input.driveModel,
+                flowSaved: flowsSaved(flowRoots),
+                ...(undefined === lastDrive.grade ? { grade: undefined } : { grade: lastDrive.grade }),
+            })) {
+                print(`the saved flow graded \`${lastDrive.grade ?? 'unknown'}\` — re-recording with the default model`);
+                const stronger = driveWith(driver, { ...request, model: undefined }, input.appDir);
+                escalated = { from: lastDrive.grade ?? 'unknown', to: stronger.grade ?? 'unknown' };
+                if (undefined !== stronger.grade)
+                    lastDrive = stronger;
+            }
+            if (undefined !== lastDrive.incomplete) {
+                print(`the drive did not finish, and ${lastDrive.incomplete}`);
+            }
+            return Promise.resolve('' === lastDrive.text ? null : lastDrive.text);
+        },
+        flowsSaved: () => flowsSaved(flowRoots),
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        note: print,
+    };
+    // A `finally` does not run on SIGINT, and this phase owns a detached dev server — see interrupt.ts.
+    const releaseSignals = stopOnInterrupt(() => {
+        server.stop();
+    }, process);
+    try {
+        const outcome = await runSetupPhases({ ...input, shape }, effects);
+        // The app stays up only when there is something worth watching.
+        if (outcome.ok)
+            server.handOver();
+        return {
+            ...outcome,
+            ...(undefined === escalated ? {} : { escalated }),
+            ...(undefined === lastDrive?.turns ? {} : { driveTurns: lastDrive.turns }),
+            ...(undefined === lastDrive?.costUsd ? {} : { driveCostUsd: lastDrive.costUsd }),
+        };
+    }
+    finally {
+        releaseSignals();
+        server.stop();
+    }
+}

package/dist/setup/setup-options.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The contract between the agent and the script.
+ *
+ * Everything setup does is deterministic except for the handful of things that require reading a
+ * repository and a human's request and understanding both. Those are exactly what an agent is good
+ * at and code is not, so they arrive here as ARGUMENTS rather than as steps somebody walks through:
+ * the agent decides, the script executes, and neither does the other's job.
+ *
+ * What only an agent can know, and therefore what belongs in this type:
+ *
+ *   --flow      which journey proves the thing the user cares about. Code can enumerate buttons; it
+ *               cannot know that checkout matters and the theme toggle does not. Measured, naming
+ *               it took one app's drive from a ten-minute timeout to 138 seconds, because the turns
+ *               go into FINDING a flow and naming one removes that search.
+ *   --app       which app in a monorepo the user meant. init can find the ones that are servable;
+ *               only the request says which of them is being worked on.
+ *   --env       what the app needs to get past its own front door. A key in .env.example, a mock
+ *               backend named in the README, the variable that skips an auth wall: all readable by
+ *               an agent, none inferable by a script. Without this a real app sits on a login
+ *               screen and there is no flow to drive at all.
+ *   --dev-cmd   the command, when the project's own scripts do not say it plainly.
+ *   --url       the app is already running here, so do not start anything.
+ *
+ * Everything else on this type is an operator's dial, not an agent's judgement.
+ */
+/** The bridge port. NOT the dev server's, and conflating them is a documented setup failure. */
+export declare const DEFAULT_BRIDGE_PORT = 4400;
+/** Per-phase budget. The drive gets its own, much larger one. */
+export declare const DEFAULT_PHASE_TIMEOUT_MS = 120000;
+/** What the drive may spend before it is stopped. */
+export declare const DEFAULT_DRIVE_BUDGET_USD = 3;
+export interface SetupOptions {
+    /** The journey to drive, in the caller's own words. */
+    readonly flow?: string | undefined;
+    /** Which app in a monorepo. */
+    readonly app?: string | undefined;
+    /** Environment the app needs in order to reach a usable state. */
+    readonly env?: Readonly<Record<string, string>> | undefined;
+    /** The dev command, when the project's scripts do not say it plainly. */
+    readonly devCommand?: string | undefined;
+    /** The app is already served here. */
+    readonly url?: string | undefined;
+    readonly bridgePort: number;
+    readonly phaseTimeoutMs: number;
+    readonly driveBudgetUsd: number;
+    readonly driveModel?: string | undefined;
+    /** Register the MCP with the other coding agents on this machine. */
+    readonly registerAgents: boolean;
+    /** Open a browser. False for CI, a headless box, or a tab the user already has. */
+    readonly openBrowser: boolean;
+    /** Drive a flow. False leaves step five to the caller, and is the only honest way to skip it. */
+    readonly drive: boolean;
+    /** Re-record with the stronger model when the saved flow is graded weaker than `asserted`. */
+    readonly escalateWeakFlow: boolean;
+    /** Restart a dev server whose bundle predates the build-config edit. */
+    readonly restartStaleDevServer: boolean;
+    /** Write files and stop, which is what `init` did before it grew the runtime phases. */
+    readonly filesOnly: boolean;
+    /** A license key, written to .env and never echoed. */
+    readonly licenseKey?: string | undefined;
+}
+export declare const DEFAULT_SETUP_OPTIONS: SetupOptions;
+/** One `KEY=VALUE`, as an agent would pass it. Everything after the first `=` is the value. */
+export declare function parseEnvAssignment(pair: string): {
+    key: string;
+    value: string;
+} | null;
+/**
+ * Fold repeated `--env KEY=VALUE` into one map, ignoring what cannot be a variable.
+ *
+ * A malformed pair is dropped rather than guessed at: an agent that meant `--env` and typed
+ * something else should see its variable missing, not see setup invent one.
+ */
+export declare function collectEnv(pairs: readonly string[]): Record<string, string>;

package/dist/setup/setup-options.js

@@ -0,0 +1,67 @@
+/**
+ * The contract between the agent and the script.
+ *
+ * Everything setup does is deterministic except for the handful of things that require reading a
+ * repository and a human's request and understanding both. Those are exactly what an agent is good
+ * at and code is not, so they arrive here as ARGUMENTS rather than as steps somebody walks through:
+ * the agent decides, the script executes, and neither does the other's job.
+ *
+ * What only an agent can know, and therefore what belongs in this type:
+ *
+ *   --flow      which journey proves the thing the user cares about. Code can enumerate buttons; it
+ *               cannot know that checkout matters and the theme toggle does not. Measured, naming
+ *               it took one app's drive from a ten-minute timeout to 138 seconds, because the turns
+ *               go into FINDING a flow and naming one removes that search.
+ *   --app       which app in a monorepo the user meant. init can find the ones that are servable;
+ *               only the request says which of them is being worked on.
+ *   --env       what the app needs to get past its own front door. A key in .env.example, a mock
+ *               backend named in the README, the variable that skips an auth wall: all readable by
+ *               an agent, none inferable by a script. Without this a real app sits on a login
+ *               screen and there is no flow to drive at all.
+ *   --dev-cmd   the command, when the project's own scripts do not say it plainly.
+ *   --url       the app is already running here, so do not start anything.
+ *
+ * Everything else on this type is an operator's dial, not an agent's judgement.
+ */
+/** The bridge port. NOT the dev server's, and conflating them is a documented setup failure. */
+export const DEFAULT_BRIDGE_PORT = 4400;
+/** Per-phase budget. The drive gets its own, much larger one. */
+export const DEFAULT_PHASE_TIMEOUT_MS = 120_000;
+/** What the drive may spend before it is stopped. */
+export const DEFAULT_DRIVE_BUDGET_USD = 3;
+export const DEFAULT_SETUP_OPTIONS = {
+    bridgePort: DEFAULT_BRIDGE_PORT,
+    phaseTimeoutMs: DEFAULT_PHASE_TIMEOUT_MS,
+    driveBudgetUsd: DEFAULT_DRIVE_BUDGET_USD,
+    registerAgents: true,
+    openBrowser: true,
+    drive: true,
+    escalateWeakFlow: true,
+    restartStaleDevServer: true,
+    filesOnly: false,
+};
+/** One `KEY=VALUE`, as an agent would pass it. Everything after the first `=` is the value. */
+export function parseEnvAssignment(pair) {
+    const at = pair.indexOf('=');
+    if (0 >= at)
+        return null;
+    const key = pair.slice(0, at).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+        return null;
+    return { key, value: pair.slice(at + 1) };
+}
+/**
+ * Fold repeated `--env KEY=VALUE` into one map, ignoring what cannot be a variable.
+ *
+ * A malformed pair is dropped rather than guessed at: an agent that meant `--env` and typed
+ * something else should see its variable missing, not see setup invent one.
+ */
+export function collectEnv(pairs) {
+    const env = {};
+    for (const pair of pairs) {
+        const parsed = parseEnvAssignment(pair);
+        if (null !== parsed)
+            env[parsed.key] = parsed.value;
+    }
+    return env;
+}

package/dist/setup/transcripts.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Does a transcript exist for this Claude Code session.
+ *
+ * Two roots, because a shared-config install writes elsewhere and a restart that checks only one of
+ * them refuses a session that is perfectly real.
+ */
+export declare function claudeTranscriptExists(sessionId: string): boolean;
+/**
+ * The codex conversation running in `cwd`, when one is.
+ *
+ * Codex names no session in the environment — unlike Claude Code — so it is recognised from the
+ * rollout file it is writing. Not yet wired to a reader here: returning undefined means "no codex
+ * session identified", which is the honest answer until one exists, and the decision it feeds says
+ * plainly that the client identified no conversation.
+ */
+export declare function codexSessionFor(_cwd: string): string | undefined;

package/dist/setup/transcripts.js

@@ -0,0 +1,43 @@
+/**
+ * Which conversation is asking, and does it really exist.
+ *
+ * Both answers come off the filesystem, so they are kept away from the pure decision in relaunch.ts
+ * — that is the part worth testing, and it is the part that can be wrong without anybody noticing.
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Does a transcript exist for this Claude Code session.
+ *
+ * Two roots, because a shared-config install writes elsewhere and a restart that checks only one of
+ * them refuses a session that is perfectly real.
+ */
+export function claudeTranscriptExists(sessionId) {
+    for (const base of [
+        join(homedir(), '.claude-shared', 'projects'),
+        join(homedir(), '.claude', 'projects'),
+    ]) {
+        try {
+            for (const project of readdirSync(base)) {
+                if (existsSync(join(base, project, `${sessionId}.jsonl`)))
+                    return true;
+            }
+        }
+        catch {
+            /* that history directory does not exist on this machine */
+        }
+    }
+    return false;
+}
+/**
+ * The codex conversation running in `cwd`, when one is.
+ *
+ * Codex names no session in the environment — unlike Claude Code — so it is recognised from the
+ * rollout file it is writing. Not yet wired to a reader here: returning undefined means "no codex
+ * session identified", which is the honest answer until one exists, and the decision it feeds says
+ * plainly that the client identified no conversation.
+ */
+export function codexSessionFor(_cwd) {
+    return undefined;
+}

package/dist/status-payload.d.ts

@@ -24,8 +24,21 @@ interface StatusPayload {
      * running the command we tell them to run in `init`'s closing line deserves the same sentence.
      */
     why?: string;
+    /** Port of the verify HTTP endpoint this daemon serves — present only when started with `--http`. */
+    verifyPort?: number;
 }
 export declare function statusPayload(sessionCount: number, sessions: SessionInfo[], 
 /** The no-session diagnosis, injected so this stays pure and the port probe stays off this path. */
-why?: string): StatusPayload;
+why?: string, verifyPort?: number): StatusPayload;
+/**
+ * Why `serve --http` cannot claim success against an already-running daemon — or undefined when
+ * that daemon already serves the verify HTTP endpoint on the wanted port.
+ *
+ * `serve` never hands flags to a daemon that is already up, so `--http`/`--http-port` against one
+ * used to be accepted, dropped, and reported as success (#687). This is the read side of the
+ * `verifyPort` field above: the daemon says which port it serves, and `serve` compares. A daemon
+ * too old to report the field — or one that did not answer /status — reads as "not honoured",
+ * which errs loud rather than green.
+ */
+export declare function verifyEndpointMismatch(status: unknown, wantedPort: number): string | undefined;
 export {};

package/dist/status-payload.js

@@ -2,7 +2,7 @@ import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
 import { SERVER_VERSION } from './version/server-version.js';
 export function statusPayload(sessionCount, sessions, 
 /** The no-session diagnosis, injected so this stays pure and the port probe stays off this path. */
-why) {
+why, verifyPort) {
     return {
         running: true,
         version: SERVER_VERSION,
@@ -12,5 +12,27 @@ why) {
         // Only when there is nothing to explain away: a diagnosis printed beside a live session would
         // contradict it.
         ...(0 === sessionCount && why !== undefined ? { why } : {}),
+        ...(verifyPort === undefined ? {} : { verifyPort }),
     };
 }
+/**
+ * Why `serve --http` cannot claim success against an already-running daemon — or undefined when
+ * that daemon already serves the verify HTTP endpoint on the wanted port.
+ *
+ * `serve` never hands flags to a daemon that is already up, so `--http`/`--http-port` against one
+ * used to be accepted, dropped, and reported as success (#687). This is the read side of the
+ * `verifyPort` field above: the daemon says which port it serves, and `serve` compares. A daemon
+ * too old to report the field — or one that did not answer /status — reads as "not honoured",
+ * which errs loud rather than green.
+ */
+export function verifyEndpointMismatch(status, wantedPort) {
+    const served = 'object' === typeof status && status !== null
+        ? status['verifyPort']
+        : undefined;
+    if (served === wantedPort)
+        return undefined;
+    const fix = 'stop it (`reticle stop`) and run `reticle serve --http` again';
+    return 'number' === typeof served
+        ? `the daemon already running serves the verify HTTP endpoint on :${String(served)}, not :${String(wantedPort)} — ${fix}`
+        : `a daemon is already running without the verify HTTP endpoint — \`--http\` cannot be applied to it; ${fix}`;
+}

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

@@ -1,5 +1,5 @@
 import { AutomationHint } from '@reticlehq/core';
-export interface AutomationInput {
+interface AutomationInput {
     env: NodeJS.ProcessEnv;
     fileExists: (path: string) => boolean;
     hasTty: boolean;
@@ -15,3 +15,4 @@ export interface AutomationInput {
 export declare function resolveAutomationHint(input: AutomationInput): AutomationHint | undefined;
 /** The real reading, taken once per process. */
 export declare function currentAutomationHint(env: NodeJS.ProcessEnv): AutomationHint | undefined;
+export {};

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

@@ -53,4 +53,11 @@ export interface DaemonTelemetry {
  * 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.
  */
-export declare function installDaemonTelemetry(cwd: string, now?: () => number): DaemonTelemetry;
+export declare function installDaemonTelemetry(cwd: string, now?: () => number, 
+/**
+ * The bridge port this daemon bound, so the profile can say whether an app for this project has
+ * EVER connected. Optional: a caller that does not know the port gets a profile without that bit
+ * rather than one with a guessed `false`, which is the value the whole field exists to make
+ * trustworthy.
+ */
+port?: number): DaemonTelemetry;

package/dist/telemetry/daemon-telemetry.js

@@ -10,10 +10,34 @@ import { TelemetryEventKind } from '@reticlehq/core';
 import { getTelemetry } from './telemetry.js';
 import { getSessionMetrics } from './session-metrics.js';
 import { profileProject } from './project-profile.js';
-import { startUpdateCheck } from '../update/update-nudge.js';
+import { hasProjectConnectedBefore } from '../session/connection-memory.js';
+import { readProjectId } from '../cli/cli-port.js';
+import { reticleStateHome } from '../daemon/daemon.js';
+import { startUpdateCheck, updateNudgeState } from '../update/update-nudge.js';
 import { markDaemonStart } from './mcp-connection.js';
 import { markInstrumentationClock } from './app-instrumented.js';
 import { markStallClock, STALL_AFTER_MS, stallUptime } from '../session/stall-clock.js';
+/**
+ * Whether an app for this project has ever reached Reticle, read from the same durable memory the
+ * no-session diagnosis and the server instructions read.
+ *
+ * Best-effort: an unreadable state home must never be the reason a daemon start emits nothing, and
+ * `undefined` here means "not measured" rather than "no". A `false` invented from a read error is
+ * exactly the lie this field exists to avoid — it would put the working installs into the cohort we
+ * are trying to size.
+ */
+function installFacts(cwd, port) {
+    if (port === undefined)
+        return undefined;
+    try {
+        return {
+            appConnectedBefore: hasProjectConnectedBefore(reticleStateHome(), port, readProjectId(cwd)),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Let the daemon finish coming up before walking the source tree for a profile. */
 const PROJECT_PROFILE_DELAY_MS = 5_000;
 /**
@@ -44,11 +68,34 @@ export const SESSION_FLUSH_MS = 5 * 60 * 1000;
  * and 74% of daemons never serve a tool at all.
  */
 export const FIRST_FLUSH_MS = 90 * 1000;
+/**
+ * Attach what the update nudge did to a summary that is about to be sent.
+ *
+ * Merged HERE rather than inside `SessionMetrics` deliberately: the nudge's state lives in the
+ * update module, and a second copy of it in the metrics object would be one more thing that can
+ * drift from the flag the delivery path actually reads. `summarize()` stays a pure roll-up of
+ * counters.
+ */
+function withNudgeState(summary) {
+    const nudge = updateNudgeState();
+    return {
+        ...summary,
+        updateNudged: nudge.shown,
+        ...(nudge.offered === undefined ? {} : { updateOffered: nudge.offered }),
+    };
+}
 /**
  * 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.
  */
-export function installDaemonTelemetry(cwd, now = () => Date.now()) {
+export function installDaemonTelemetry(cwd, now = () => Date.now(), 
+/**
+ * The bridge port this daemon bound, so the profile can say whether an app for this project has
+ * EVER connected. Optional: a caller that does not know the port gets a profile without that bit
+ * rather than one with a guessed `false`, which is the value the whole field exists to make
+ * trustworthy.
+ */
+port) {
     const metrics = getSessionMetrics(now);
     void getTelemetry().emit(TelemetryEventKind.DAEMON_STARTED);
     // Ask npm whether a newer Reticle exists, so the agent can tell the human. Nothing checked before
@@ -66,7 +113,7 @@ export function installDaemonTelemetry(cwd, now = () => Date.now()) {
     setTimeout(() => {
         try {
             void getTelemetry().emit(TelemetryEventKind.PROJECT_PROFILED, {
-                project: profileProject(cwd, now()),
+                project: profileProject(cwd, now(), installFacts(cwd, port)),
             });
         }
         catch {
@@ -93,7 +140,7 @@ export function installDaemonTelemetry(cwd, now = () => Date.now()) {
             return; // an idle window is not worth an event
         // NOT daemon_stopped: the daemon is still running. See SESSION_PROGRESS.
         void getTelemetry().emit(TelemetryEventKind.SESSION_PROGRESS, {
-            session: metrics.summarize(false),
+            session: withNudgeState(metrics.summarize(false)),
         });
         metrics.reset();
     };
@@ -114,7 +161,7 @@ export function installDaemonTelemetry(cwd, now = () => Date.now()) {
                 // The rich one: the whole session in a single event — duration, the tool histogram, error
                 // shapes, verifications, browser launches. This is what replaced the per-tool-call event.
                 await getTelemetry().emit(TelemetryEventKind.DAEMON_STOPPED, {
-                    session: metrics.summarize(true, exit),
+                    session: withNudgeState(metrics.summarize(true, exit)),
                 });
             })();
             return stopped;

package/dist/telemetry/error-class.js

@@ -30,7 +30,7 @@ export const ErrorClass = {
 const PATTERNS = [
     [/confirmdangerous|destructive action blocked/i, ErrorClass.REFUSAL],
     [
-        /\brefus(e|ed|es|ing)\b|not supported|unsupported|cannot .* a <|contenteditable/i,
+        /\brefus(e|ed|es|ing)\b|not supported|unsupported|cannot .* a <|contenteditable|cannot hover/i,
         ErrorClass.REFUSAL,
     ],
     [

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

@@ -1,10 +1,11 @@
-import { McpScope, type Feedback } from '@reticlehq/core';
+import { McpScope, StackUnknownReason, type Feedback } from '@reticlehq/core';
 /** The context fields — the whole `Feedback` shape minus what the author supplies. */
 export type FeedbackContext = Pick<Feedback, 'stack' | 'stackMajor' | 'runtime' | 'engine' | 'driver' | 'client' | 'clientVersion' | 'mcpScope'>;
 export declare function detectStack(cwd: string, read?: (path: string) => string): {
     stack?: string;
     stackMajor?: number;
     stackSource?: 'cwd' | 'workspace';
+    stackUnknownReason?: StackUnknownReason;
 };
 /**
  * User scope unless the project checks in its own MCP registration. `reticle init` deliberately
@@ -12,6 +13,13 @@ export declare function detectStack(cwd: string, read?: (path: string) => string
  * itself the interesting signal.
  */
 export declare function detectMcpScope(cwd: string, exists?: (path: string) => boolean): McpScope;
+/**
+ * The MCP client on the other end, self-reported in its `initialize` handshake (`claude-code`,
+ * `cursor-vscode`, …). Read through a HOOK rather than sniffing env vars: the handshake is the
+ * client's own claim about itself, while an env-var table is a guess that silently rots every time a
+ * vendor renames a variable. Unset (a CLI run with no MCP peer) simply reports no client.
+ */
+/** Kept as the telemetry-facing name; the mechanism itself lives in mcp/client-identity.ts. */
 export declare function setMcpClientNameHook(hook: () => {
     name?: string;
     version?: string;