@reticlehq/server 3.8.1 → 3.9.0

package/dist/surface/tools/run-report.d.ts

@@ -14,8 +14,8 @@ export declare function renderRunReport(report: RunReport): string;
 export declare function endsRun(tool: string, args: Record<string, unknown>): boolean;
 /** What an answer says the run saved or read. An answer that refused counts for nothing. */
 export declare function noteToolResult(ledger: RunLedger, tool: string, args: Record<string, unknown>, result: unknown): void;
-/** The report as an answer field, or no field when the ledger holds no run. Empties the ledger. */
-export declare function runReportField(ledger: RunLedger, root: string | undefined, env: Record<string, string | undefined>, now: number): Partial<Record<typeof RUN_REPORT_FIELD, {
+/** The owner's report as an answer field, or no field when the owner has no run. Ends that run. */
+export declare function runReportField(ledger: RunLedger, root: string | undefined, env: Record<string, string | undefined>, now: number, owner?: string): Partial<Record<typeof RUN_REPORT_FIELD, {
     report: RunReport;
     markdown: string;
     instruction: string;

package/dist/surface/tools/run-report.js

@@ -34,12 +34,15 @@ function headline(report) {
     const count = (v) => all.filter((each) => v === each).length;
     const total = all.length;
     const word = `${HEAD}${WORD[report.verified]}**${SEP}`;
-    if (0 === total)
+    if (0 === total) {
         return `${word}${Said.NOTHING_CHECKED}`;
-    if (Verified.NO === report.verified)
+    }
+    if (Verified.NO === report.verified) {
         return `${word}${String(count(Verified.NO))} of ${plural(total, 'check')} did not hold`;
-    if (Verified.YES === report.verified)
+    }
+    if (Verified.YES === report.verified) {
         return `${word}${String(total)} of ${plural(total, 'check')} held`;
+    }
     return `${word}${String(total - count(Verified.YES) - count(Verified.NO))} of ${plural(total, 'check')} undecided`;
 }
 /** The report as markdown: the verdict, each claim with its evidence, then what the run left. */
@@ -95,39 +98,48 @@ const INTENT_READS = new Set(['list', 'index', 'subject', 'get']);
 const isRecord = (value) => null !== value && 'object' === typeof value && !Array.isArray(value);
 /** What an answer says the run saved or read. An answer that refused counts for nothing. */
 export function noteToolResult(ledger, tool, args, result) {
-    if (!isRecord(result) || result['error'] !== undefined)
+    if (!isRecord(result) || result['error'] !== undefined) {
         return;
+    }
     if (ReticleTool.FLOW_SAVE === tool || ReticleTool.FLOW_SAVE_RECORDED === tool) {
         const name = result['name'];
-        if ('string' === typeof name)
+        if ('string' === typeof name) {
             ledger.flowSaved(name);
+        }
         return;
     }
     const action = asString(args['action']);
     if (ReticleTool.INTENT === tool) {
         // The intent ledger in `.reticle/intent/` is the memory an unlinked project has.
-        if (IntentWrite.RECORD === action)
+        if (IntentWrite.RECORD === action) {
             ledger.memoryWritten();
+        }
         const declared = args['intents'];
-        if (IntentWrite.DECLARE === action && Array.isArray(declared))
+        if (IntentWrite.DECLARE === action && Array.isArray(declared)) {
             ledger.memoryWritten(declared.length);
-        if (action !== undefined && INTENT_READS.has(action))
+        }
+        if (action !== undefined && INTENT_READS.has(action)) {
             ledger.memoryRead([JSON.stringify(result)]);
+        }
         return;
     }
-    if (ReticleTool.MEMORY !== tool)
+    if (ReticleTool.MEMORY !== tool) {
         return;
-    if ('add' === action && result['added'] !== undefined)
+    }
+    if ('add' === action && result['added'] !== undefined) {
         ledger.memoryWritten();
+    }
     const known = result['known'];
-    if (Array.isArray(known))
+    if (Array.isArray(known)) {
         ledger.memoryRead(known.map((entry) => JSON.stringify(entry)));
+    }
 }
-/** The report as an answer field, or no field when the ledger holds no run. Empties the ledger. */
-export function runReportField(ledger, root, env, now) {
-    if (ledger.isEmpty())
+/** The owner's report as an answer field, or no field when the owner has no run. Ends that run. */
+export function runReportField(ledger, root, env, now, owner) {
+    if (ledger.isEmpty(owner)) {
         return {};
-    const taken = ledger.take(now);
+    }
+    const taken = ledger.take(now, owner);
     const silenced = env[UPGRADE_HINT_SILENCE_ENV] !== undefined;
     const linked = root === undefined || linkedToPlatform(root, env);
     const report = silenced || linked ? taken : { ...taken, cloud: CLOUD_VALUE_LINE };

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

@@ -96,6 +96,11 @@ export interface ToolDeps<Ext = unknown> {
     } | undefined>;
     /** The one dev server running in the caller's project folder, for a lease that names no url. */
     projectAppUrl?: () => Promise<string | undefined>;
+    /**
+     * The first-session offer for this attach id's first call, when no app is attached and the
+     * project is not wired (see zero-install-first-call.ts). Absent: no offer.
+     */
+    firstSessionOffer?: (attachId: string) => string | undefined;
     /** cross-run outcome memory (.reticle/project.json). */
     project: ProjectStore;
     /** optional native-input provider. undefined ⇒ everything stays synthetic. */
@@ -303,10 +308,17 @@ export declare const EnvelopeKey: {
      * what it cannot see, and the command that wires the app for good. See zero-install-first-call.ts.
      */
     readonly ZERO_INSTALL: "zero_install";
+    /**
+     * Once per agent connection, on its first call: this unwired web app can be checked now with the
+     * lease, and `init` needs the user's consent. See zero-install-first-call.ts.
+     */
+    readonly FIRST_SESSION_OFFER: "first_session_offer";
     /** Once-per-session advisory lines an agent's own call carries. See agent/notices.ts. */
     readonly NOTICES: "notices";
     /** The end-of-run report, on the call that ends an agent's run. See run-report.ts. */
     readonly RUN_REPORT: "runReport";
+    /** On the third identical call with the same result: what to try instead. See repeat-hint.ts. */
+    readonly REPEAT_HINT: "repeatHint";
 };
 export type EnvelopeKey = (typeof EnvelopeKey)[keyof typeof EnvelopeKey];
 /**

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

@@ -99,10 +99,17 @@ export const EnvelopeKey = {
      * what it cannot see, and the command that wires the app for good. See zero-install-first-call.ts.
      */
     ZERO_INSTALL: 'zero_install',
+    /**
+     * Once per agent connection, on its first call: this unwired web app can be checked now with the
+     * lease, and `init` needs the user's consent. See zero-install-first-call.ts.
+     */
+    FIRST_SESSION_OFFER: 'first_session_offer',
     /** Once-per-session advisory lines an agent's own call carries. See agent/notices.ts. */
     NOTICES: 'notices',
     /** The end-of-run report, on the call that ends an agent's run. See run-report.ts. */
     RUN_REPORT: RUN_REPORT_FIELD,
+    /** On the third identical call with the same result: what to try instead. See repeat-hint.ts. */
+    REPEAT_HINT: 'repeatHint',
 };
 /**
  * The sentence every session-bound result carries while its leased tab runs on a stubbed shell.

package/dist/surface/tools/tools.js

@@ -1,7 +1,7 @@
 import { TESTID_FOUND_UNDER_SCHEMA } from './query-hint-schema.js';
 import { z } from 'zod';
-import { EMPTY_SESSION_LIST_OUTPUT, emptySessionList, nextStepBesideLiveSessions, } from './empty-session-list.js';
-import { AttrNamesSchema, QueryBy, ReticleCommand, SnapshotMode } from '@reticlehq/core';
+import { EMPTY_SESSION_LIST_OUTPUT, emptySessionList, NEXT_STEP_FIELD, nextStepBesideLiveSessions, } from './empty-session-list.js';
+import { AttrNamesSchema, NearestTargetSchema, 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';
@@ -145,11 +145,12 @@ export const RAW_TOOLS = withCompactEnvelope([
             })));
             const sessions = await list();
             // An empty list is a dead end on its own; see empty-session-list.ts for what it carries.
-            if (0 === sessions.length)
+            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 nextStep = nextStepBesideLiveSessions(deps, sessions);
-            return nextStep === undefined ? { sessions } : { sessions, next_step: nextStep };
+            return nextStep === undefined ? { sessions } : { sessions, [NEXT_STEP_FIELD]: nextStep };
         },
     },
     {
@@ -284,7 +285,7 @@ export const RAW_TOOLS = withCompactEnvelope([
             name: z
                 .string()
                 .optional()
-                .describe('Accessible name filter — narrows results when `by` is role and the page has many elements of that role.'),
+                .describe('Exact accessible-name filter - narrows results when `by` is role and the page has many elements of that role. Matches the whole name; use `text` for a partial match.'),
             scope: z
                 .string()
                 .optional()
@@ -398,6 +399,10 @@ export const RAW_TOOLS = withCompactEnvelope([
                     .optional()
                     .describe('Present when a ROLE+NAME search missed and that role DOES carry a nearly-matching name — role+name is exact, so "Mesh" does not find "2 Mesh". Retry with one of these spellings; no snapshot needed.'),
                 testidFoundUnder: TESTID_FOUND_UNDER_SCHEMA,
+                nearest: z
+                    .array(NearestTargetSchema)
+                    .optional()
+                    .describe('Present when a search missed and the page has visible targets like the one asked for: up to 3, the asked role first, then by name similarity. Each has a ref to retry with. nameTruncated is true when the name was cut. Advice only, never a match.'),
             })
                 .optional()
                 .describe('Present only on zero matches — tells you what IS on the page so you can diagnose the miss.'),
@@ -422,8 +427,9 @@ export const RAW_TOOLS = withCompactEnvelope([
             // Accept the predicate's named-field spelling too — see query-shape.ts.
             const args = normalizeQueryArgs(rawArgs);
             const empty = emptyQueryRefusal(args);
-            if (empty !== undefined)
+            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'],
@@ -603,14 +609,17 @@ export const RETIRED_FROM_SURFACE = [
  * The browser counts what leanness passed over, so the tool can say which of the two it is.
  */
 function noteEmptyLeanTree(result, mode) {
-    if (SnapshotMode.INTERACTIVE !== mode)
+    if (SnapshotMode.INTERACTIVE !== mode) {
         return result;
+    }
     const row = asRecord(result);
-    if (0 !== asNumber(row['nodes']))
+    if (0 !== asNumber(row['nodes'])) {
         return result;
+    }
     const skipped = asNumber(row['leanSkipped']) ?? 0;
-    if (0 === skipped)
+    if (0 === skipped) {
         return result;
+    }
     return {
         ...row,
         note: `no element on this page carries an interactive ARIA role, so this mode found nothing — ` +
@@ -635,18 +644,22 @@ function noteEmptyLeanTree(result, mode) {
  * empty tree it replaces.
  */
 function noteHiddenPage(result, mode) {
-    if (SnapshotMode.STATUS === mode)
+    if (SnapshotMode.STATUS === mode) {
         return result;
+    }
     const row = asRecord(result);
-    if (0 !== asNumber(row['nodes']))
+    if (0 !== asNumber(row['nodes'])) {
         return result;
+    }
     // A note already there is the more specific one (leanness), and two explanations for one empty
     // tree is worse than the better of them alone.
-    if (row['note'] !== undefined)
+    if (row['note'] !== undefined) {
         return result;
+    }
     const skipped = asNumber(row['hiddenSkipped']) ?? 0;
-    if (0 === skipped)
+    if (0 === skipped) {
         return result;
+    }
     return {
         ...row,
         note: `this is NOT an empty page: ${String(skipped)} subtree(s) were skipped because their root ` +

package/dist/telemetry/argument-shape.js

@@ -18,7 +18,7 @@
  * exact values allowed — anything outside the list is reported as `other`, so a schema change can
  * never quietly start forwarding free text.
  */
-import { ActionType, FeedbackKind, QueryBy, SnapshotMode } from '@reticlehq/core';
+import { ActionType, FeedbackKind, QueryBy, ReticleTool, SnapshotMode } from '@reticlehq/core';
 /**
  * Parameters whose values are enums WE define, and the exact values allowed on the wire. An
  * unrecognized value reports `other` rather than itself; that fallback is what makes this safe
@@ -35,6 +35,9 @@ const SAFE_ENUM_PARAMS = new Map([
     ['by', new Set(Object.values(QueryBy))],
     ['mode', new Set(Object.values(SnapshotMode))],
     ['kind', new Set(Object.values(FeedbackKind))],
+    // `reticle_run { tool }` names the tool it calls. Our own tool names, so the session summary can
+    // say which tools agents reach through it. A name that is not a Reticle tool reports `other`.
+    ['tool', new Set(Object.values(ReticleTool))],
     // `level` has no core enum — console levels come from the DOM console API, not from us. Listed
     // literally BECAUSE there is nothing to derive from, which is a different situation from the four
     // above and the reason it is called out rather than left looking like an oversight.
@@ -49,10 +52,12 @@ export const OTHER_VALUE = 'other';
  */
 export function allowParamValues(name, values) {
     const allowed = SAFE_ENUM_PARAMS.get(name);
-    if (allowed === undefined)
+    if (allowed === undefined) {
         return;
-    for (const value of values)
+    }
+    for (const value of values) {
         allowed.add(value);
+    }
 }
 /**
  * The reportable form of one parameter: `name` on its own, or `name:value` when the parameter is a
@@ -60,10 +65,12 @@ export function allowParamValues(name, values) {
  */
 export function describeParam(name, value) {
     const allowed = SAFE_ENUM_PARAMS.get(name);
-    if (allowed === undefined)
+    if (allowed === undefined) {
         return name;
-    if (typeof value !== 'string')
+    }
+    if (typeof value !== 'string') {
         return name;
+    }
     return `${name}:${allowed.has(value) ? value : OTHER_VALUE}`;
 }
 /**
@@ -96,10 +103,12 @@ export function describeCliFlags(argv) {
     const flags = new Set();
     for (const arg of argv) {
         // A bare `--` ends the options: everything after it is passed through to something else.
-        if (END_OF_OPTIONS === arg)
+        if (END_OF_OPTIONS === arg) {
             break;
-        if (!arg.startsWith('--'))
+        }
+        if (!arg.startsWith('--')) {
             continue;
+        }
         // `--port=9000` — split so the NAME is reported and the value is discarded with everything else.
         const name = arg.split('=')[0] ?? arg;
         flags.add(KNOWN_CLI_FLAGS.has(name) ? name : OTHER_VALUE);

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

@@ -4,7 +4,8 @@
  * 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';
+import { TelemetryActor, type GateCompleted } from '@reticlehq/core/telemetry';
+import { type Telemetry } from './telemetry.js';
 /** True when this command represents a person typing something. Exported for the gate. */
 export declare function isHumanCliCommand(command: string): boolean;
 /**
@@ -23,3 +24,11 @@ export declare function cliActorOf(env: NodeJS.ProcessEnv): TelemetryActor;
  */
 export declare function claimInstallReport(command: string, firstRun: boolean, stateDir: string): boolean;
 export declare function reportCliRun(argv: readonly string[]): void;
+/**
+ * `gate_completed`: how one `reticle gate` run ended.
+ *
+ * `cli_command_run` says that the gate ran. Only this event says whether it passed. The gate is a
+ * one-shot command that exits immediately, so the send is DETACHED, like `init_completed`.
+ * Best-effort: a metric never changes what the gate decides.
+ */
+export declare function reportGateCompleted(gate: GateCompleted, telemetry?: Pick<Telemetry, 'emit'>): void;

package/dist/telemetry/cli-telemetry.js

@@ -161,3 +161,18 @@ export function reportCliRun(argv) {
         flags: describeCliFlags(argv),
     });
 }
+/**
+ * `gate_completed`: how one `reticle gate` run ended.
+ *
+ * `cli_command_run` says that the gate ran. Only this event says whether it passed. The gate is a
+ * one-shot command that exits immediately, so the send is DETACHED, like `init_completed`.
+ * Best-effort: a metric never changes what the gate decides.
+ */
+export function reportGateCompleted(gate, telemetry = getTelemetry()) {
+    try {
+        void telemetry.emit(TelemetryEventKind.GATE_COMPLETED, { gate, detach: true });
+    }
+    catch {
+        /* a metric never fails the gate */
+    }
+}

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

@@ -11,6 +11,7 @@
  * event loop alive and tax the command by most of a second.
  */
 import { type InitOutcome } from '@reticlehq/core/telemetry';
-export { InitFailure } from '@reticlehq/init';
+import { InitFailure } from '@reticlehq/init';
+export { InitFailure };
 /** Report one init outcome. Best-effort; setup must never fail because a metric did. */
 export declare function reportInitOutcome(init: InitOutcome): void;

package/dist/telemetry/init-telemetry.js

@@ -10,12 +10,56 @@
  * same treatment `cli_command_run` gets, for the same reason: an in-process fetch would keep the
  * event loop alive and tax the command by most of a second.
  */
-import { TelemetryEventKind } from '@reticlehq/core/telemetry';
+import { OnboardingPhase, OnboardingStop, TelemetryEventKind, } from '@reticlehq/core/telemetry';
+import { InitFailure } from '@reticlehq/init';
 import { getTelemetry } from './telemetry.js';
 import { INSTALL_STATE_DIR, resolveInstallSource } from './install-source.js';
+import { reportOnboardingStop } from './onboarding-funnel.js';
 // The failure vocabulary lives in `@reticlehq/init`, which is what classifies a failed run.
 // Re-exported so every consumer here is unchanged.
-export { InitFailure } from '@reticlehq/init';
+export { InitFailure };
+const PROJECT_DETECTED = 'project_detected';
+const INSTRUMENTED = 'instrumented';
+const APP_CONNECTED = 'app_connected';
+/**
+ * Each init failure as one stop, with the first-run step it blocked. A `Record` over the whole
+ * enum, so a new `InitFailure` does not compile until it names its stop.
+ */
+const INIT_STOP = {
+    [InitFailure.NO_PACKAGE_JSON]: { step: PROJECT_DETECTED, stop: OnboardingStop.NO_WEB_APP },
+    [InitFailure.MALFORMED_PACKAGE_JSON]: {
+        step: PROJECT_DETECTED,
+        stop: OnboardingStop.SETUP_FAILED,
+    },
+    [InitFailure.PREFLIGHT]: { step: PROJECT_DETECTED, stop: OnboardingStop.SETUP_FAILED },
+    [InitFailure.DEPENDENCY_INSTALL]: { step: INSTRUMENTED, stop: OnboardingStop.SETUP_FAILED },
+    [InitFailure.MCP_REGISTRATION]: { step: INSTRUMENTED, stop: OnboardingStop.MCP_NOT_REGISTERED },
+    [InitFailure.OTHER]: { step: INSTRUMENTED, stop: OnboardingStop.UNCLASSIFIED },
+    [InitFailure.BRIDGE_OCCUPIED]: { step: APP_CONNECTED, stop: OnboardingStop.SETUP_FAILED },
+    [InitFailure.DEV_SERVER]: { step: APP_CONNECTED, stop: OnboardingStop.DEV_SERVER_FAILED },
+    [InitFailure.APP_CONNECTION]: { step: APP_CONNECTED, stop: OnboardingStop.APP_NOT_CONNECTED },
+    [InitFailure.RUNTIME_ERROR]: { step: APP_CONNECTED, stop: OnboardingStop.UNCLASSIFIED },
+    [InitFailure.INTERRUPTED]: { step: APP_CONNECTED, stop: OnboardingStop.INTERRUPTED },
+};
+const INIT_STOP_UNKNOWN = INIT_STOP[InitFailure.OTHER];
+function initStop(reason) {
+    if (reason !== undefined && Object.hasOwn(INIT_STOP, reason)) {
+        return INIT_STOP[reason];
+    }
+    return INIT_STOP_UNKNOWN;
+}
+/** The stop row of a failed init, or nothing for a run that worked. */
+function reportInitStop(init) {
+    if (init.ok) {
+        return;
+    }
+    reportOnboardingStop({
+        phase: OnboardingPhase.FIRST_RUN,
+        ...initStop(init.reason),
+        ...(init.reason === undefined ? {} : { reason: init.reason }),
+        ...(init.stack === undefined ? {} : { stack: init.stack }),
+    }, { detach: true });
+}
 /** Report one init outcome. Best-effort; setup must never fail because a metric did. */
 export function reportInitOutcome(init) {
     try {
@@ -27,6 +71,7 @@ export function reportInitOutcome(init) {
             // marker, same refusal to infer — see install-source.ts.
             installSource: resolveInstallSource(process.env, INSTALL_STATE_DIR),
         });
+        reportInitStop(init);
     }
     catch {
         /* a metric must never break `reticle init` */

package/dist/telemetry/install-trace.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
-import { OnboardingStepSchema } from '@reticlehq/core/telemetry';
+import { OnboardingStepSchema, OnboardingStop } from '@reticlehq/core/telemetry';
 import { reportOnboardingStep } from './onboarding-funnel.js';
 /**
  * What the one-line installer could not report itself.
@@ -27,6 +27,22 @@ const TRACE_FILE = 'install-trace.jsonl';
  * file must not turn into thousands of events. Far above any real install, which writes three.
  */
 const MAX_LINES = 32;
+/**
+ * The stop that each installer failure reason names. The keys are the reasons that `install.sh`
+ * and `install.ps1` write. A reason not in this table gets no stop.
+ */
+const INSTALLER_STOP = {
+    no_node: OnboardingStop.NO_NODE,
+    node_too_old: OnboardingStop.NODE_TOO_OLD,
+    no_npm: OnboardingStop.CLI_INSTALL_FAILED,
+    npm_install: OnboardingStop.CLI_INSTALL_FAILED,
+    not_on_path: OnboardingStop.CLI_INSTALL_FAILED,
+};
+function installerStop(reason) {
+    return reason !== undefined && Object.hasOwn(INSTALLER_STOP, reason)
+        ? INSTALLER_STOP[reason]
+        : undefined;
+}
 /**
  * Drain the installer's breadcrumbs, once.
  *
@@ -36,8 +52,9 @@ const MAX_LINES = 32;
  */
 export function drainInstallTrace(stateDir) {
     const path = join(stateDir, TRACE_FILE);
-    if (!existsSync(path))
+    if (!existsSync(path)) {
         return 0;
+    }
     let drained = 0;
     try {
         const lines = readFileSync(path, 'utf8')
@@ -55,9 +72,11 @@ export function drainInstallTrace(stateDir) {
             // deliberate belt-and-braces: this is the one path where the payload is a file a person can
             // edit, and rule 3 is that unvalidated text never reaches the wire.
             const step = OnboardingStepSchema.safeParse(parsed);
-            if (!step.success)
+            if (!step.success) {
                 continue;
-            void reportOnboardingStep(step.data);
+            }
+            const stop = installerStop(step.data.reason);
+            void reportOnboardingStep({ ...step.data, ...(stop === undefined ? {} : { stop }) });
             drained += 1;
         }
     }

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

@@ -1,4 +1,4 @@
-import { OnboardingPhase, type OnboardingStep } from '@reticlehq/core/telemetry';
+import { OnboardingPhase, type OnboardingStep, type OnboardingStop } from '@reticlehq/core/telemetry';
 /**
  * The one place an onboarding step is reported.
  *
@@ -11,7 +11,24 @@ import { OnboardingPhase, type OnboardingStep } from '@reticlehq/core/telemetry'
  * arriving as a step name would be a rule-3 leak that no reader would ever notice, because a funnel
  * with one weird row still renders.
  */
-export declare function reportOnboardingStep(step: OnboardingStep): Promise<boolean>;
+export declare function reportOnboardingStep(step: OnboardingStep, opts?: {
+    detach?: boolean;
+}): Promise<boolean>;
+/** One stop: the rung it blocked and its name. The status is always `failed`. */
+export type StopRow = Omit<OnboardingStep, 'status' | 'stop'> & {
+    stop: OnboardingStop;
+};
+/**
+ * Report one stop on the path to a first verdict, once for each process and stop name.
+ *
+ * A daemon can fail to launch Chromium on every lease. One row says the stop happened here; more
+ * rows count retries, not people. Use `detach` from a CLI that exits next, or the row is lost.
+ */
+export declare function reportOnboardingStop(row: StopRow, opts?: {
+    detach?: boolean;
+}): void;
+/** Tests only: forget the stops this process sent. */
+export declare function resetOnboardingStops(): void;
 /**
  * Time a step and report it, whatever happens to it.
  *

package/dist/telemetry/onboarding-funnel.js

@@ -12,13 +12,35 @@ import { getTelemetry } from './telemetry.js';
  * arriving as a step name would be a rule-3 leak that no reader would ever notice, because a funnel
  * with one weird row still renders.
  */
-export async function reportOnboardingStep(step) {
+export async function reportOnboardingStep(step, opts = {}) {
     const parsed = OnboardingStepSchema.safeParse(step);
     // A malformed step is DROPPED rather than sent or thrown. Sending it would put unvalidated text on
     // the wire; throwing would let a metric change what the user's install does, which rule 5 forbids.
-    if (!parsed.success)
+    if (!parsed.success) {
         return false;
-    return getTelemetry().emit(TelemetryEventKind.ONBOARDING_STEP, { onboarding: parsed.data });
+    }
+    return getTelemetry().emit(TelemetryEventKind.ONBOARDING_STEP, {
+        onboarding: parsed.data,
+        ...(true === opts.detach ? { detach: true } : {}),
+    });
+}
+const stopsSent = new Set();
+/**
+ * Report one stop on the path to a first verdict, once for each process and stop name.
+ *
+ * A daemon can fail to launch Chromium on every lease. One row says the stop happened here; more
+ * rows count retries, not people. Use `detach` from a CLI that exits next, or the row is lost.
+ */
+export function reportOnboardingStop(row, opts = {}) {
+    if (stopsSent.has(row.stop)) {
+        return;
+    }
+    stopsSent.add(row.stop);
+    void reportOnboardingStep({ ...row, status: OnboardingStepStatus.FAILED }, opts);
+}
+/** Tests only: forget the stops this process sent. */
+export function resetOnboardingStops() {
+    stopsSent.clear();
 }
 /**
  * Time a step and report it, whatever happens to it.

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

@@ -10,6 +10,7 @@
  * never arrived: the POST was killed every time and nothing threw.
  */
 import { type ProxyExitReason, type WakeRefusalPresence } from '@reticlehq/core/telemetry';
+import type { DaemonDeath } from '@reticlehq/core';
 import { type SessionMetrics } from './session-metrics.js';
 import { type Telemetry } from './telemetry.js';
 export declare function flushProxySessionMetrics(telemetry?: Telemetry, metrics?: SessionMetrics): Promise<void>;
@@ -37,7 +38,7 @@ export declare function reportProxyExited(reason: ProxyExitReason, telemetry?: T
 /** Everything the proxy sends on its way out. Awaited, then the caller exits. */
 export declare function flushProxyExit(reason: ProxyExitReason): Promise<void>;
 /** Send `daemon_died_unclean`. Fire-and-forget is fine for callers: the process lives on. */
-export declare function reportDaemonDiedUnclean(ageMs: number, telemetry?: Telemetry): Promise<void>;
+export declare function reportDaemonDiedUnclean(ageMs: number, cause?: Omit<DaemonDeath, 'ageMs'>, telemetry?: Telemetry): Promise<void>;
 /**
  * Send `wake_refused`, once per process. A dormant proxy refuses again on every client request, and
  * one event per request would count the client's retries, not the refusal.

package/dist/telemetry/proxy-telemetry.js

@@ -73,9 +73,9 @@ export async function flushProxyExit(reason) {
     await Promise.allSettled([flushProxySessionMetrics(), reportProxyExited(reason)]);
 }
 /** Send `daemon_died_unclean`. Fire-and-forget is fine for callers: the process lives on. */
-export async function reportDaemonDiedUnclean(ageMs, telemetry = getTelemetry()) {
+export async function reportDaemonDiedUnclean(ageMs, cause, telemetry = getTelemetry()) {
     await telemetry.emit(TelemetryEventKind.DAEMON_DIED_UNCLEAN, {
-        daemonDeath: { ageMs: Math.max(0, Math.round(ageMs)) },
+        daemonDeath: { ...cause, ageMs: Math.max(0, Math.round(ageMs)) },
     });
 }
 /**

package/dist/telemetry/session-metrics.d.ts

@@ -15,7 +15,7 @@
  * 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, type AgentNudgeKind, type ConnectFailure, type SessionSummary } from '@reticlehq/core/telemetry';
+import { BrowserLaunchKind, ConnectFailure, type AgentNudgeKind, type SessionSummary } from '@reticlehq/core/telemetry';
 import type { HudUseData } from '@reticlehq/core';
 import { type HudSignals } from './hud-metrics.js';
 /**