@reticlehq/server 3.5.0 → 3.7.0

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

@@ -4,6 +4,7 @@
  * in its own leaf module (no dependency on any tool array) so the per-group tool files can import it
  * without a circular import — `tools.ts` assembles the groups and re-exports `ToolDef`/`ToolDeps`.
  */
+import type { FirstRunWiring } from '../../portal/session/first-run-wiring.js';
 import { z } from 'zod';
 import { type ProjectId, ReticleCommand } from '@reticlehq/core';
 import type { SessionManager } from '../../portal/session/session-manager.js';
@@ -43,8 +44,9 @@ export interface ToolDeps<Ext = unknown> {
      * to: this is a port, and the daemon already resolves exactly this for cloud sync.
      *
      * Absent ⇒ nothing is linked, or the caller is an embedder with no filesystem. Never an error.
+     * `root` is the `.reticle` whose link is asked for; absent, the daemon's own.
      */
-    linkedCloud?: () => Promise<{
+    linkedCloud?: (root?: string) => Promise<{
         url: string;
         apiKey: string;
     } | null>;
@@ -69,6 +71,23 @@ export interface ToolDeps<Ext = unknown> {
     peerSkew?: {
         take(): string | undefined;
     };
+    /**
+     * Who is asking: one id per MCP attach. A browser lease is handed back only to the attach that took
+     * it, so two agents on one origin never share a tab (#1226). Absent ⇒ every acquire gets its own.
+     */
+    attachId?: string;
+    /** Run one sync cycle with the platform now, for `reticle_project { push }`. Absent: not linked here. */
+    syncNow?: () => Promise<unknown>;
+    /** Wires the app on the agent's first use, instead of at installation. Absent: tell, do not wire. */
+    firstRun?: FirstRunWiring;
+    /**
+     * On the first page-needing call with nothing connected, opens this caller's UNWIRED app in a
+     * lease that supplies the SDK (see zero-install-first-call.ts). Absent: answer no-session as before.
+     */
+    openUnwiredApp?: () => Promise<{
+        url: string;
+        notice: string;
+    } | undefined>;
     /** cross-run outcome memory (.reticle/project.json). */
     project: ProjectStore;
     /** optional native-input provider. undefined ⇒ everything stays synthetic. */
@@ -90,7 +109,7 @@ export interface ToolDeps<Ext = unknown> {
      * embedding this engine may not have a filesystem to search. Absent ⇒ `reticleRoot`, which is
      * exactly today's behaviour.
      */
-    artifactRootFor?: (projectId: ProjectId | undefined) => ArtifactRoot;
+    artifactRootFor?: (projectId: ProjectId | undefined, origin?: string) => ArtifactRoot;
     /**
      * A verification run just landed — wake cloud sync instead of waiting for its next tick.
      *
@@ -175,7 +194,17 @@ export interface ToolDef<Ext = unknown> {
      * handed a bag carrying no `ext` at all. That costs nothing here, because `ext` is optional by
      * design: any handler reading it already has to survive `undefined`.
      */
-    handler(deps: ToolDeps<Ext>, args: Record<string, unknown>): Promise<unknown>;
+    handler(deps: ToolDeps<Ext>, args: Record<string, unknown>, call?: ToolCall): Promise<unknown>;
+}
+/**
+ * What the MCP request itself offers a handler: its cancellation, and a way to say it is still
+ * working. Absent off the MCP path (the Harness's own calls, the CLI, tests).
+ */
+export interface ToolCall {
+    /** Aborts when the client cancels or the connection drops. */
+    signal?: AbortSignal;
+    /** Present when the client asked for progress: tells it the call is alive, and how far along. */
+    progress?: (progress: number, message: string) => void;
 }
 /**
  * The optional inline intent, on every tool that draws a verdict.
@@ -241,8 +270,45 @@ export declare const EnvelopeKey: {
     readonly VERSION_SKEW: "version_skew";
     /** A feedback report that was accepted and then failed to send. Only the reporter can act on it. */
     readonly FEEDBACK_UNDELIVERED: "feedback_undelivered";
+    /** Once per project: verified runs exist only on this machine. See platform-moment.ts. */
+    readonly PLATFORM: "platform";
+    /**
+     * This leased tab runs a STUB of the bindings a desktop shell injects (`reticle_lease acquire`'s
+     * `initScript`), so a verdict here is about the app's view logic and not about the real shell.
+     */
+    readonly HOST_STUB: "host_stub";
+    /** The one thing to do next: declare the request, yield, fix sync, connect. See next-step.ts. */
+    readonly NEXT: "next";
+    /** One-shot: a Harness drive started or finished, from any origin, and how to read it. */
+    readonly HARNESS: "harness";
+    /** Where this step's screenshot is (`{ path, source }`), or why there is none. See step-shots.ts. */
+    readonly SCREENSHOT: "screenshot";
+    /**
+     * One-shot: this call's tab was opened by Reticle on an app nobody wired, with the SDK supplied —
+     * 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-session advisory lines an agent's own call carries. See agent/notices.ts. */
+    readonly NOTICES: "notices";
 };
 export type EnvelopeKey = (typeof EnvelopeKey)[keyof typeof EnvelopeKey];
+/**
+ * The sentence every session-bound result carries while its leased tab runs on a stubbed shell.
+ *
+ * Spliced wherever the tab's health is spliced, because the fact matters to exactly the same
+ * readings: a green from a tab whose `window.go` Reticle faked is not evidence about the real shell,
+ * and nothing else in the result would say so.
+ */
+export declare const HOST_STUB_NOTE: string;
+/**
+ * The tools whose every answer leaves a screenshot of the page. A sequence (`reticle_act` with
+ * `steps`) takes one per step, inside the sequence, rather than one for the whole call.
+ */
+export declare const STEP_SHOT_TOOLS: ReadonlySet<string>;
+/** A step-screenshot tool, with the one sentence about its screenshot on the end of its description. */
+export declare function withScreenshotDoc(tool: ToolDef): ToolDef;
+/** The one sentence every tool that takes a step screenshot says about it. */
+export declare const SCREENSHOT_DOC = " `screenshot.path` is a picture of the page at the outcome: open it when the look of the page matters; reading it is your choice.";
 /**
  * Fields that `runTool` / `withControl` splice onto EVERY session-bound tool result at runtime.
  * Merged into each session-bound tool's outputSchema so a schema-strict client (structuredContent
@@ -267,3 +333,17 @@ export declare function snapshotTree(deps: ToolDeps, sessionId: string | undefin
  * imports. See `ToolDeps.snapshots` for why a daemon-wide store cannot be correct.
  */
 export declare const newSnapshotCache: () => SnapshotCache;
+/** The argument a replay takes its redacted fields' values in, for that call only. */
+export declare const CALL_SECRETS_ARG = "secrets";
+/** The secrets the current call supplied, keyed as given (a field, or its variable name). */
+export declare function callSecrets(): Readonly<Record<string, string>> | undefined;
+/**
+ * Take the call's secrets out of its arguments, so nothing downstream — the tool log, the journal,
+ * telemetry — ever sees them.
+ */
+export declare function takeCallSecrets(args: Record<string, unknown>): {
+    secrets: Record<string, string> | undefined;
+    rest: Record<string, unknown>;
+};
+/** Run `fn` with these secrets supplied for it alone. */
+export declare function withCallSecrets<T>(secrets: Readonly<Record<string, string>> | undefined, fn: () => Promise<T>): Promise<T>;

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

@@ -1,11 +1,6 @@
-/**
- * Shared kit for the MCP tool modules — the tool shape, the dependency bag, the common
- * session-id arg, and the two helpers (commandOrThrow, snapshotTree) every tool group needs. Lives
- * in its own leaf module (no dependency on any tool array) so the per-group tool files can import it
- * without a circular import — `tools.ts` assembles the groups and re-exports `ToolDef`/`ToolDeps`.
- */
 import { z } from 'zod';
-import { ReticleCommand, SnapshotMode } from '@reticlehq/core';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { asRecord, asString, ReticleCommand, ReticleTool, SnapshotMode, } from '@reticlehq/core';
 import { normalizeLines } from '../../memory/project/baselines.js';
 import { SnapshotCache } from './read/snapshot-delta.js';
 /**
@@ -84,7 +79,54 @@ export const EnvelopeKey = {
     VERSION_SKEW: 'version_skew',
     /** A feedback report that was accepted and then failed to send. Only the reporter can act on it. */
     FEEDBACK_UNDELIVERED: 'feedback_undelivered',
+    /** Once per project: verified runs exist only on this machine. See platform-moment.ts. */
+    PLATFORM: 'platform',
+    /**
+     * This leased tab runs a STUB of the bindings a desktop shell injects (`reticle_lease acquire`'s
+     * `initScript`), so a verdict here is about the app's view logic and not about the real shell.
+     */
+    HOST_STUB: 'host_stub',
+    /** The one thing to do next: declare the request, yield, fix sync, connect. See next-step.ts. */
+    NEXT: 'next',
+    /** One-shot: a Harness drive started or finished, from any origin, and how to read it. */
+    HARNESS: 'harness',
+    /** Where this step's screenshot is (`{ path, source }`), or why there is none. See step-shots.ts. */
+    SCREENSHOT: 'screenshot',
+    /**
+     * One-shot: this call's tab was opened by Reticle on an app nobody wired, with the SDK supplied —
+     * 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-session advisory lines an agent's own call carries. See agent/notices.ts. */
+    NOTICES: 'notices',
 };
+/**
+ * The sentence every session-bound result carries while its leased tab runs on a stubbed shell.
+ *
+ * Spliced wherever the tab's health is spliced, because the fact matters to exactly the same
+ * readings: a green from a tab whose `window.go` Reticle faked is not evidence about the real shell,
+ * and nothing else in the result would say so.
+ */
+export const HOST_STUB_NOTE = 'a stub for the bindings a desktop shell injects was installed in this tab before its scripts ' +
+    'ran, so a green here is not a verdict against the real shell.';
+/**
+ * The tools whose every answer leaves a screenshot of the page. A sequence (`reticle_act` with
+ * `steps`) takes one per step, inside the sequence, rather than one for the whole call.
+ */
+export const STEP_SHOT_TOOLS = new Set([
+    ReticleTool.ACT,
+    ReticleTool.ACT_AND_WAIT,
+    ReticleTool.NAVIGATE,
+    ReticleTool.ASSERT,
+]);
+/** A step-screenshot tool, with the one sentence about its screenshot on the end of its description. */
+export function withScreenshotDoc(tool) {
+    return STEP_SHOT_TOOLS.has(tool.name)
+        ? { ...tool, description: `${tool.description}${SCREENSHOT_DOC}` }
+        : tool;
+}
+/** The one sentence every tool that takes a step screenshot says about it. */
+export const SCREENSHOT_DOC = ' `screenshot.path` is a picture of the page at the outcome: open it when the look of the page matters; reading it is your choice.';
 /**
  * Fields that `runTool` / `withControl` splice onto EVERY session-bound tool result at runtime.
  * Merged into each session-bound tool's outputSchema so a schema-strict client (structuredContent
@@ -126,3 +168,31 @@ export async function snapshotTree(deps, sessionId) {
  * imports. See `ToolDeps.snapshots` for why a daemon-wide store cannot be correct.
  */
 export const newSnapshotCache = () => new SnapshotCache();
+/** The argument a replay takes its redacted fields' values in, for that call only. */
+export const CALL_SECRETS_ARG = 'secrets';
+/** Secrets a call supplied; never written anywhere, gone when the call ends. */
+const callSecretStore = new AsyncLocalStorage();
+/** The secrets the current call supplied, keyed as given (a field, or its variable name). */
+export function callSecrets() {
+    return callSecretStore.getStore();
+}
+/**
+ * Take the call's secrets out of its arguments, so nothing downstream — the tool log, the journal,
+ * telemetry — ever sees them.
+ */
+export function takeCallSecrets(args) {
+    if (!(CALL_SECRETS_ARG in args))
+        return { secrets: undefined, rest: args };
+    const { [CALL_SECRETS_ARG]: raw, ...rest } = args;
+    const secrets = {};
+    for (const [key, value] of Object.entries(asRecord(raw))) {
+        const text = asString(value);
+        if (text !== undefined && 0 < text.length)
+            secrets[key] = text;
+    }
+    return { secrets, rest };
+}
+/** Run `fn` with these secrets supplied for it alone. */
+export function withCallSecrets(secrets, fn) {
+    return secrets === undefined ? fn() : callSecretStore.run(secrets, fn);
+}

package/dist/surface/tools/tools.js

@@ -1,5 +1,7 @@
+import { TESTID_FOUND_UNDER_SCHEMA } from './query-hint-schema.js';
 import { z } from 'zod';
-import { DiscoveryInvite, AttrNamesSchema, EventType, NoSessionAction, QueryBy, ReticleCommand, SnapshotMode, } from '@reticlehq/core';
+import { EMPTY_SESSION_LIST_OUTPUT, emptySessionList, wireCallerBesideLiveSessions, } from './empty-session-list.js';
+import { AttrNamesSchema, EventType, 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';
@@ -41,23 +43,25 @@ import { VIEWPORT_TOOLS } from '../../portal/input/viewport-tools.js';
 import { SESSION_TOOLS } from '../../portal/session/session-tools.js';
 import { ANNOTATE_TOOLS } from '../../language/flows/annotate-tools.js';
 import { LIVE_CONTROL_TOOLS } from '../../portal/session/live-control-tools.js';
-import { sessionIdShape, commandOrThrow } from './tool-kit.js';
+import { SCREENSHOT_DOC, sessionIdShape, commandOrThrow, withScreenshotDoc, } from './tool-kit.js';
 import { TOOL_SURFACE } from './tool-surface.js';
 import { mergeActWithSequence } from './act-merged.js';
 import { INSPECT_TOOL } from './inspect-tool.js';
 import { applyMerges } from './merge-tools.js';
 import { ACT_TOOLS } from './act-tools.js';
 import { ACT_SEQUENCE_TOOL } from './act-sequence-tool.js';
+import { withCompactEnvelope } from './agent/compact-envelope.js';
 import { OBSERVE_TOOLS } from './observe-tools.js';
 import { LINEAGE_TOOLS } from './lineage-tools.js';
 import { RECONCILE_TOOLS } from './reconcile-tools.js';
 import { READ_TOOLS } from './read-tools.js';
 import { LEASE_TOOLS } from './lease-tools.js';
 import { FEEDBACK_TOOLS } from './feedback-tools.js';
+import { ACCOUNT_TOOLS } from './account-tool.js';
 /** FALLBACK for `diff: true`; the real one is per MCP client on `deps.snapshots`, which says why. */
 const SNAPSHOT_CACHE = new SnapshotCache();
 /** Every handler, including tools retired from the advertised MCP surface. */
-export const RAW_TOOLS = [
+export const RAW_TOOLS = withCompactEnvelope([
     {
         name: ReticleTool.SESSIONS,
         description: 'List connected browser sessions (tab url/title, sessionId, last-seen, health: hidden/focused/throttled, and `realInputAvailable` — true when native CDP/launched real input is driving this tab), plus a `recommendation` naming the in-protocol escape hatch (`reticle_run { tool: "reticle_lease" }`, with `reticle drive` as the human-side equivalent) when a tab is hidden/throttled and may be un-scriptable from here.',
@@ -82,6 +86,11 @@ export const RAW_TOOLS = [
                     .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."),
+                window: z.string().optional().describe('Desktop window label (Tauri: main, setup…).'),
+                documentStatus: z
+                    .number()
+                    .optional()
+                    .describe('Set only for an error page (4xx/5xx): not the app, never auto-selected first.'),
                 lastSeenMs: z.number(),
                 throttled: z.boolean(),
                 focused: z.boolean(),
@@ -112,61 +121,25 @@ export const RAW_TOOLS = [
                     .describe('Continuity of the SDK-to-daemon LINK for this tab, present for any tab the daemon has a record of: how long this attachment has lasted, how many times it dropped and came back, and when the last gap started and how long it lasted. `outages > 0` means a verdict over this window spans a gap where nothing was observed. These are link counters, NOT app health: they say nothing about whether the page origin is still serving, so a tab whose dev server has died reports `outages: 0` with a growing `connectedSinceMs` and is not evidence the app is up.'),
             }))
                 .describe('Connected browser sessions with health state. `projectId` groups sessions by app (stable across port changes); `leased` marks a pool-managed headless context vs a human tab.'),
-            why: z
-                .string()
-                .optional()
-                .describe('Present ONLY when `sessions` is empty: why nothing is connected, and the next action that fixes it. An empty list is never the end of the road — read this before concluding the app cannot be driven.'),
-            next_action: z
-                .object({
-                action: z.nativeEnum(NoSessionAction),
-                command: z.string().optional(),
-                port: z.number().optional(),
-                reason: z.string(),
-            })
-                .optional()
-                .describe("Present ONLY when `sessions` is empty: the same answer as `why`, executable. `command` is the LITERAL command to run, sourced from this project's own package.json scripts and lockfile — it is absent, never guessed, when the project declares no dev script. `action` is one of daemon_split | start_dev_server | run_init | open_app | reopen_app. `daemon_split` outranks the rest and means the app IS running and instrumented, on a DIFFERENT daemon than the one you are attached to — do not start or re-init anything, read `reason`."),
-            talk_to_us: z
-                .string()
-                .optional()
-                .describe('Present ONLY when `sessions` is empty: a call with the founder for the person you are working with. Offer it; never act on it.'),
-            lastKnown: z
-                .object({
-                sessionId: z.string(),
-                url: z.string(),
-            })
-                .optional()
-                .describe('Present ONLY when `sessions` is empty AND a tab was connected to this daemon earlier: the last sessionId and URL that tab was on when it disappeared. A route that 500s tears the page down and the SDK never reconnects — this is the last thing we knew, not a route-500 verdict. An empty list with no lastKnown is a tab that never arrived.'),
+            ...EMPTY_SESSION_LIST_OUTPUT,
         },
         handler: async (deps) => {
             const provider = deps.realInput;
             const leasedIds = new Set(deps.pool?.leasedSessionIds() ?? []);
-            const sessions = await Promise.all(deps.sessions.list().map(async (s) => ({
+            const list = () => Promise.all(deps.sessions.list().map(async (s) => ({
                 ...s,
                 realInputAvailable: provider !== undefined ? await provider.isAvailableFor(s.url) : false,
                 leased: leasedIds.has(s.sessionId),
             })));
-            // An empty list is the most common thing this tool ever returns, and on its own it is a dead
-            // end: the agent asked the one question it knows to ask, got a confident-looking answer with
-            // no next step, and stopped. The daemon already knows WHY nothing is connected — say it here
-            // rather than only when a later tool fails for want of a session.
-            if (0 === sessions.length) {
-                const why = deps.sessions.noSessionHint();
-                // The executable half. `why` is for the human reading the transcript; this is the one the
-                // agent acts on, so it never has to parse a paragraph to find a command inside it.
-                const next = deps.sessions.noSessionNextAction();
-                // The last tab, when one was here. Optional-call: test stubs of SessionManager predate it.
-                const known = deps.sessions.lastKnown?.();
-                const lastKnown = undefined === known ? undefined : { sessionId: known.id, url: known.url };
-                return {
-                    sessions,
-                    ...(why === undefined ? {} : { why }),
-                    ...(next === undefined ? {} : { next_action: next }),
-                    ...(undefined === lastKnown ? {} : { lastKnown }),
-                    // Setup that never connects is where most people give up; it is the talk worth having.
-                    talk_to_us: DiscoveryInvite.AGENT,
-                };
-            }
-            return { sessions };
+            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)
+                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 };
         },
     },
     {
@@ -394,12 +367,17 @@ export const RAW_TOOLS = [
                     .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."),
+                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.
                 nameNearMiss: z
                     .array(z.string())
                     .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,
             })
                 .optional()
                 .describe('Present only on zero matches — tells you what IS on the page so you can diagnose the miss.'),
@@ -465,16 +443,14 @@ export const RAW_TOOLS = [
     // reachable through reticle_run. See affected-tools.ts.
     ...AFFECTED_TOOLS,
     // reticle_coverage — which controls were driven vs never touched. Unadvertised; via reticle_run.
-    // The table is passed as a thunk so the coverage tool can report which of it was called without
-    // importing it back — see buildCoverageTools. Called from the handler, long after TOOLS exists.
-    ...buildCoverageTools(() => TOOLS.map((t) => t.name)),
+    ...buildCoverageTools(),
     // reticle_verify_change — "did my change break anything" in one call. See verify-change-tools.ts.
     ...VERIFY_CHANGE_TOOLS,
     // Live-control: reticle_end_session / reticle_resume / reticle_messages. See live-control-tools.ts.
     ...LIVE_CONTROL_TOOLS,
     // reticle_navigate / reticle_refresh — browser navigation tools. See browser-tools.ts.
-    ...BROWSER_TOOLS,
-    ...ACT_TOOLS,
+    ...BROWSER_TOOLS.map(withScreenshotDoc),
+    ...ACT_TOOLS.map(withScreenshotDoc),
     ACT_SEQUENCE_TOOL,
     ...OBSERVE_TOOLS,
     ...LINEAGE_TOOLS,
@@ -482,7 +458,8 @@ export const RAW_TOOLS = [
     ...LEASE_TOOLS,
     // reticle_feedback — the agent reports that RETICLE failed (not that the app did). See feedback-tools.ts.
     ...FEEDBACK_TOOLS,
-];
+    ...ACCOUNT_TOOLS,
+]);
 /**
  * surface consolidation. Tool defs are re-sent EVERY turn, so the advertised count is a per-turn
  * tax multiplied by loop length. Sibling families collapse into one action-dispatched tool; the member
@@ -522,7 +499,10 @@ export const MERGE_PLANS = [
         // whatever comes first is what an agent discovers; when this sentence opened with `tune` the
         // MANDATORY handback sat past the cut and no agent reading the catalogue ever learned it
         // existed. The rule is: if a tool has an obligation, the obligation goes first.
-        'Session lifecycle and the human channel, by action: "yield" hands control back to the human and is MANDATORY before you stop driving (mode: waiting|ask, between turns); "tune" adjusts the presenter session (e.g. idle-end window); "end" terminates the session for good; "resume" clears a human pause; "messages" drains the human→agent inbox; "review" lists/resolves the mistakes a human pinned to elements; "narrate" states your intent on the presenter HUD.',
+        // The first sentence is all a lean surface shows (160 characters), so it carries the
+        // obligation and the HUD control; the rest is the detail for a full one.
+        'By action: "yield" is MANDATORY before you stop driving; "tune" hides or moves the HUD, or sets the idle window; "account" says the plan, credits and Harness state. ' +
+            'In full: "yield" hands control back to the human (mode: waiting|ask, between turns); "tune" takes `hud` (hidden, shown, removed until reload, or a corner) for when the HUD covers a control you must test, and `idleEndMs`; "end" terminates the session for good; "resume" clears a human pause; "messages" drains the human→agent inbox; "review" lists/resolves the mistakes a human pinned to elements; "narrate" states your intent on the presenter HUD.',
         members: {
             tune: ReticleTool.SESSION_TUNE,
             yield: ReticleTool.YIELD,
@@ -531,6 +511,7 @@ export const MERGE_PLANS = [
             messages: ReticleTool.MESSAGES,
             review: ReticleTool.REVIEW,
             narrate: ReticleTool.NARRATE,
+            account: ReticleTool.ACCOUNT,
         },
         // The handback the lease block orders on every session — the one call an agent MUST make, so it
         // is the one that must not need a schema lookup first.
@@ -538,7 +519,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: a model inside the daemon drives the app for you — 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: '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.',
         members: {
             change: ReticleTool.VERIFY_CHANGE,
             flows: ReticleTool.FLOW_VERIFY,
@@ -768,7 +749,8 @@ export const SURFACE_MERGE_PLANS = [
     },
     {
         name: ReticleTool.ASSERT,
-        description: 'Prove a consequence, by action: "now" evaluates a predicate against the window that already exists, "wait" waits for one to become true within a budget. Both return a verdict; only `verified:"yes"` is a pass.',
+        description: 'Prove a consequence, by action: "now" evaluates a predicate against the window that already exists, "wait" waits for one to become true within a budget. Both return a verdict; only `verified:"yes"` is a pass.' +
+            SCREENSHOT_DOC,
         members: { now: ReticleTool.ASSERT, wait: ReticleTool.WAIT_FOR },
         example: { action: 'now' },
         // Evaluate against the window that already exists. `wait` spends a budget, so it is asked for.
@@ -804,6 +786,8 @@ export const MERGED_SURFACE_PLANS = [
             // surface: on the default one `reticle_sessions` still exists and this tool is purely
             // 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.',
         }
         : plan),
     ...SURFACE_MERGE_PLANS,

package/dist/telemetry/account-envelope.d.ts

@@ -0,0 +1,7 @@
+import { TelemetryAccountState } from '@reticlehq/core/telemetry';
+export interface AccountEnvelope {
+    accountState: TelemetryAccountState;
+    linked: boolean;
+    workspaceId?: string;
+}
+export declare function accountEnvelope(cwd: string, env: NodeJS.ProcessEnv, home: string): AccountEnvelope;

package/dist/telemetry/account-envelope.js

@@ -0,0 +1,61 @@
+/**
+ * Where this machine stands with the platform, for every telemetry event: signed out, signed in, or
+ * this project linked to a workspace, and that workspace's id.
+ *
+ * Read from what the CLI already wrote, never asked of the network: the session file (through
+ * `readAccountState`, which cannot carry the token) and the project's `.reticle/cloud.json`. Read per
+ * event, because a sign-in from the HUD changes the answer mid-session.
+ *
+ * The workspace id is the platform's `orgId`: pseudonymous here, and the key the platform joins its
+ * own records on. The workspace NAME and the signed-in email are never read into this.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ReticleDir } from '@reticlehq/core';
+import { TelemetryAccountState } from '@reticlehq/core/telemetry';
+import { readAccountState } from '../memory/cloud/account-state.js';
+import { linkDirectoryFrom } from '../memory/project/link-directory.js';
+const MAX_WORKSPACE_ID = 128;
+/** The link this project carries, if it is a real one (a project id and a host). */
+function readLink(dir) {
+    try {
+        const raw = JSON.parse(readFileSync(join(dir, ReticleDir.ROOT, ReticleDir.CLOUD_LINK_FILE), 'utf8'));
+        if ('object' !== typeof raw || null === raw)
+            return undefined;
+        const o = raw;
+        const projectId = o['projectId'];
+        const url = o['url'];
+        if ('string' !== typeof projectId || 0 === projectId.length)
+            return undefined;
+        if ('string' !== typeof url || 0 === url.length)
+            return undefined;
+        const orgId = o['orgId'];
+        return 'string' === typeof orgId && 0 < orgId.length && orgId.length <= MAX_WORKSPACE_ID
+            ? { orgId }
+            : {};
+    }
+    catch {
+        return undefined;
+    }
+}
+export function accountEnvelope(cwd, env, home) {
+    let link;
+    try {
+        link = readLink(linkDirectoryFrom(cwd)) ?? readLink(cwd);
+    }
+    catch {
+        link = undefined;
+    }
+    if (link !== undefined) {
+        return {
+            accountState: TelemetryAccountState.LINKED,
+            linked: true,
+            ...(link.orgId === undefined ? {} : { workspaceId: link.orgId }),
+        };
+    }
+    const signedIn = readAccountState(home, env).signedIn;
+    return {
+        accountState: signedIn ? TelemetryAccountState.SIGNED_IN : TelemetryAccountState.SIGNED_OUT,
+        linked: false,
+    };
+}

package/dist/telemetry/agent-client.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Which coding agent an event came from, as a closed value — and how the running `reticle` was
+ * launched. Both are envelope fields, read per event (the client) or once per process (the launch).
+ *
+ * The client is the MCP handshake's `clientInfo.name` for the call in flight (or the only agent
+ * attached), normalised by `agentClientOf`. When no handshake has said anything — a one-shot CLI
+ * command, a proxy, a client that skipped `initialize` — the agent's own marker in the environment
+ * of what it spawned is the fallback. Only markers an agent sets on purpose are read.
+ */
+import { AgentClient, LaunchMethod } from '@reticlehq/core/telemetry';
+export declare function envAgentClient(env: NodeJS.ProcessEnv): AgentClient | undefined;
+/** The client for an event being built now. */
+export declare function currentAgentClient(env: NodeJS.ProcessEnv): AgentClient | undefined;
+/** How the process was launched, from the path of its entry script. Only the bucket leaves. */
+export declare function launchMethodOf(entry: string | undefined): LaunchMethod;

package/dist/telemetry/agent-client.js

@@ -0,0 +1,57 @@
+/**
+ * Which coding agent an event came from, as a closed value — and how the running `reticle` was
+ * launched. Both are envelope fields, read per event (the client) or once per process (the launch).
+ *
+ * The client is the MCP handshake's `clientInfo.name` for the call in flight (or the only agent
+ * attached), normalised by `agentClientOf`. When no handshake has said anything — a one-shot CLI
+ * command, a proxy, a client that skipped `initialize` — the agent's own marker in the environment
+ * of what it spawned is the fallback. Only markers an agent sets on purpose are read.
+ */
+import { AgentClient, LaunchMethod } from '@reticlehq/core/telemetry';
+import { agentClientOf, callingClientName } from '../hooks/coding-agents.js';
+/**
+ * Environment markers a coding agent sets on the processes it spawns. A shared daemon inherits the
+ * environment of whichever agent started it, so this is a fallback after the handshake, never ahead
+ * of it.
+ */
+const ENV_MARKERS = [
+    ['CLAUDECODE', AgentClient.CLAUDE_CODE],
+    ['CODEX_SANDBOX', AgentClient.CODEX],
+    ['CODEX_MANAGED_BY_NPM', AgentClient.CODEX],
+    ['CURSOR_TRACE_ID', AgentClient.CURSOR],
+    ['GEMINI_CLI', AgentClient.GEMINI_CLI],
+];
+export function envAgentClient(env) {
+    return ENV_MARKERS.find(([key]) => (env[key] ?? '') !== '')?.[1];
+}
+/** The client for an event being built now. */
+export function currentAgentClient(env) {
+    return agentClientOf(callingClientName()) ?? envAgentClient(env);
+}
+/**
+ * Where a global install puts packages, by package manager. A path that matches none of these but
+ * still sits in a `node_modules` is a project's own dependency.
+ */
+const GLOBAL_DIRS = [
+    '/lib/node_modules/',
+    '/npm/node_modules/',
+    '/pnpm/global/',
+    '/.volta/',
+    '/.bun/install/global/',
+    '/yarn/global/',
+    '/.nvm/',
+    '/.npm-global/',
+];
+/** How the process was launched, from the path of its entry script. Only the bucket leaves. */
+export function launchMethodOf(entry) {
+    if (entry === undefined)
+        return LaunchMethod.OTHER;
+    const path = entry.replace(/\\/g, '/').toLowerCase();
+    if (path.includes('/_npx/') || path.includes('/dlx-'))
+        return LaunchMethod.NPX;
+    if (GLOBAL_DIRS.some((dir) => path.includes(dir)))
+        return LaunchMethod.GLOBAL;
+    if (path.includes('/node_modules/'))
+        return LaunchMethod.PROJECT;
+    return LaunchMethod.OTHER;
+}

package/dist/telemetry/app-instrumented.js

@@ -15,8 +15,10 @@
  */
 import { OnboardingPhase, OnboardingStepStatus, TelemetryEventKind, } from '@reticlehq/core/telemetry';
 import { getTelemetry } from './telemetry.js';
-import { reportOnboardingStep } from './onboarding-funnel.js';
+import { FirstEver, claimFirstEver, reportFirstStep } from './onboarding-firsts.js';
 let reported = false;
+/** The on-disk claim for the EVENT, kept apart from the `app_connected` step's own claim. */
+const APP_INSTRUMENTED_CLAIM = 'app_instrumented';
 /** Set at daemon start so the first connect can report how long the install sat un-instrumented. */
 let daemonStartedAt;
 export function markInstrumentationClock(now) {
@@ -32,8 +34,13 @@ export function reportAppInstrumented(facts, now = () => Date.now()) {
         return;
     reported = true;
     try {
+        // Still once per RUN: `daemon_started` minus `app_instrumented`, joined on sessionId, is the
+        // documented failure side and needs a row per run. Only the true first on this machine +
+        // project says `firstEver`, so a per-machine count no longer counts daemon restarts.
+        const firstEver = FirstEver.FIRST === claimFirstEver(APP_INSTRUMENTED_CLAIM);
         void getTelemetry().emit(TelemetryEventKind.APP_INSTRUMENTED, {
             instrumentation: {
+                ...(firstEver ? { firstEver: true } : {}),
                 initialized: facts.initialized,
                 agentAttached: facts.agentAttached,
                 // How long the daemon ran before an app showed up. Large values are the interesting ones:
@@ -47,7 +54,7 @@ export function reportAppInstrumented(facts, now = () => Date.now()) {
         //
         // `instrumented` means files were written; THIS means a page actually dialled the bridge. Every
         // silent install bug so far has lived in the gap between those two.
-        void reportOnboardingStep({
+        reportFirstStep({
             phase: OnboardingPhase.FIRST_RUN,
             step: 'app_connected',
             status: OnboardingStepStatus.COMPLETED,