@reticlehq/server 2.4.0 → 2.6.0

package/dist/telemetry/telemetry.js

@@ -16,11 +16,11 @@
  */
 import { spawn } from 'node:child_process';
 import { randomUUID, createHash } from 'node:crypto';
-import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync } from 'node:fs';
+import { appendFileSync, readFileSync, writeFileSync, mkdirSync, existsSync, rmSync, } from 'node:fs';
 import { homedir, platform } from 'node:os';
-import { join } from 'node:path';
-import { TelemetryEventKind, TELEMETRY_EVENT_VERSION, ProjectIdSource, } from '@reticlehq/core';
-import { SERVER_VERSION } from '../server-version.js';
+import { dirname, join } from 'node:path';
+import { TelemetryEventKind, TELEMETRY_EVENT_VERSION, ProjectIdSource, isSessionScoped, } from '@reticlehq/core';
+import { SERVER_VERSION } from '../version/server-version.js';
 const RETICLE_DIR = join(homedir(), '.reticle');
 const ID_FILE = join(RETICLE_DIR, 'telemetry-id');
 const NOTICE_FILE = join(RETICLE_DIR, 'telemetry-notice-shown');
@@ -43,6 +43,22 @@ const POSTHOG_KEY = 'phc_q4yCxKMXHfWQ43VAz4HxJXZFLqFi4nBbg5v3avemggYo';
  */
 const POSTHOG_PERSONLESS = { $process_person_profile: false };
 const SEND_TIMEOUT_MS = 2000;
+/**
+ * Feedback gets its own, much larger budget — and a retry.
+ *
+ * 2s + drop is right for a usage counter: the metric is worthless if it costs the user latency, and
+ * losing one changes nothing. Feedback is the opposite on both counts. It is the only qualitative
+ * channel the product has, it carries an agent's entire root-cause analysis, and losing one loses
+ * work that cannot be reconstructed.
+ *
+ * Measured to the collector with a WARM DNS cache: dns 0.003s, connect 0.233s, tls 0.467s, total
+ * 0.694s — a third of the old budget gone before any payload moves, on the good path. A fresh
+ * short-lived CLI process pays cold DNS and a cold route on top, which is exactly the case that
+ * failed in the field and then succeeded on retry from a warmer process.
+ */
+export const FEEDBACK_TIMEOUT_MS = 15_000;
+export const FEEDBACK_RETRIES = 1;
+export const FEEDBACK_RETRY_BACKOFF_MS = 750;
 /**
  * The sender a `detach: true` emit runs in a disowned child (argv: [url, body]) — an in-process fetch
  * keeps Node's event loop alive until the POST finishes, which taxed every short-lived CLI command
@@ -59,6 +75,7 @@ const Env = {
     DISABLE: 'RETICLE_TELEMETRY', // "0" / "false" / "off" → disabled
     DO_NOT_TRACK: 'DO_NOT_TRACK', // the cross-tool opt-out convention (any truthy value)
     URL: 'RETICLE_TELEMETRY_URL', // override the PostHog host (EU cloud / self-hosted)
+    FILE: 'RETICLE_TELEMETRY_FILE', // record to a local JSONL file and send NOTHING — see the sink note
     KEY: 'RETICLE_TELEMETRY_KEY', // override the PostHog project key
     CI: 'CI', // presence marks a CI environment
     VITEST: 'VITEST', // set by vitest — unit tests must never phone home
@@ -67,6 +84,11 @@ const isDisabled = (env, cwd = process.cwd()) => {
     const off = new Set(['0', 'false', 'off', 'no']);
     if (off.has((env[Env.DISABLE] ?? '').toLowerCase()))
         return true;
+    // Recording to a local file is not "phoning home", and the guards below exist to stop us phoning
+    // home. Chief among them is the source-checkout rule — which is exactly where a release sweep is
+    // driven from, so a sink that inherited it would record nothing and look like it had worked.
+    if ((env[Env.FILE] ?? '') !== '')
+        return false;
     if (env[Env.VITEST] !== undefined)
         return true; // a test run is not a user
     // Developing Reticle is not using Reticle. The `.env` carrying RETICLE_TELEMETRY=0 is gitignored,
@@ -75,8 +97,21 @@ const isDisabled = (env, cwd = process.cwd()) => {
     if (isReticleSourceCheckout(cwd))
         return true;
     const dnt = env[Env.DO_NOT_TRACK];
-    return typeof dnt === 'string' && dnt !== '' && dnt !== '0';
+    return 'string' === typeof dnt && dnt !== '' && dnt !== '0';
 };
+/**
+ * Would telemetry be on here if we ignored the source-checkout guard alone?
+ *
+ * That guard exists so a fresh clone does not phone home on a contributor's first `reticle serve` —
+ * a rule about PASSIVE collection. Feedback is never passive: somebody typed it. Applying the guard
+ * to it means anyone dogfooding from their own checkout files nothing and is told "not sent, unknown
+ * reason", which silently loses every report from exactly the people most likely to write good ones.
+ * Reported from the field, and the reporter only escaped it by happening to run from another repo.
+ *
+ * Every explicit opt-out still applies — RETICLE_TELEMETRY=0, DO_NOT_TRACK, the persisted opt-out
+ * file, and a test run. This lifts one implicit guard for one user-initiated event kind.
+ */
+const onlyBlockedBySourceCheckout = (env, cwd) => isDisabled(env, cwd) && !isDisabled(env, '/');
 /** Read (or mint-and-persist) the anonymous machine id. `firstRun` is true the run that created it. */
 const resolveIdentity = () => {
     try {
@@ -109,17 +144,40 @@ const resolveIdentity = () => {
  * credentials, `.git` suffix and case removed) so `git@github.com:acme/web.git` and
  * `https://github.com/Acme/web` are recognized as the same project rather than two.
  */
-const projectFingerprint = (cwd) => {
-    const { origin } = gitFacts(cwd);
+export const projectFingerprint = (cwd) => {
+    const { origin, root } = gitFacts(cwd);
+    // Ordered by stability, not by preference: an origin is comparable across machines, a repo root is
+    // stable across every directory inside one machine's checkout, a package.json root is the same for
+    // a non-git project — and the raw cwd is stable across nothing, which is why it is last. See
+    // `project-identity.test.ts` for what a wrong order costs.
+    const { key, source } = origin !== undefined
+        ? { key: origin, source: ProjectIdSource.GIT_ORIGIN }
+        : root !== undefined
+            ? { key: root, source: ProjectIdSource.GIT_ROOT }
+            : packageRoot(cwd) !== null
+                ? { key: packageRoot(cwd) ?? cwd, source: ProjectIdSource.PACKAGE_ROOT }
+                : { key: cwd, source: ProjectIdSource.CWD };
     return {
-        projectId: createHash('sha256')
-            .update(origin ?? cwd)
-            .digest('hex')
-            .slice(0, 32),
+        projectId: createHash('sha256').update(key).digest('hex').slice(0, 32),
         // Reported alongside so the analytics knows whether this id is comparable to another machine's.
-        source: origin !== undefined ? ProjectIdSource.GIT_ORIGIN : ProjectIdSource.CWD,
+        source,
     };
 };
+/** Nearest ancestor holding a package.json — the project boundary when there is no git. */
+const packageRoot = (cwd) => {
+    let dir = cwd;
+    // Same bound as the git walk: deep monorepos are well inside 20, and an unbounded loop on a
+    // pathological path would hang the CLI's startup.
+    for (let depth = 0; depth < 20; depth += 1) {
+        if (existsSync(join(dir, 'package.json')))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+    return null;
+};
 /** Print the opt-out notice exactly once per machine (honest disclosure, the OSS-trust bar). */
 const showNoticeOnce = () => {
     try {
@@ -172,7 +230,8 @@ export const setTelemetryEnabled = (enabled, dir = RETICLE_DIR) => {
     mkdirSync(dir, { recursive: true });
     writeFileSync(optOutFile, '1', 'utf8');
 };
-const NOOP = { emit: async () => { }, enabled: false, firstRun: false };
+// A disabled emitter delivers nothing, and says so — `false` is the honest answer, not a courtesy.
+const NOOP = { emit: () => Promise.resolve(false), enabled: false, firstRun: false };
 /**
  * Build the telemetry emitter for this process. Resolves identity + opt-out ONCE; each `emit` builds a
  * fully-validated core event, maps it into PostHog capture shape, and fires a best-effort POST.
@@ -182,7 +241,9 @@ const NOOP = { emit: async () => { }, enabled: false, firstRun: false };
 export const createTelemetry = (opts) => {
     const env = opts.env ?? process.env;
     const cwd = opts.cwd ?? process.cwd();
-    if (isDisabled(env, cwd))
+    // A source checkout silences metrics but must not silence FEEDBACK — see onlyBlockedBySourceCheckout.
+    const feedbackOnly = onlyBlockedBySourceCheckout(env, cwd);
+    if (isDisabled(env, cwd) && !feedbackOnly)
         return NOOP;
     try {
         if (existsSync(OPT_OUT_FILE))
@@ -192,13 +253,15 @@ export const createTelemetry = (opts) => {
         /* unreadable home dir — fall through; the env-var opt-outs above still apply */
     }
     const apiKey = env[Env.KEY] ?? POSTHOG_KEY;
-    if (apiKey === '')
+    if ('' === apiKey)
         return NOOP; // no key baked in (dev/test build) — nowhere to send, stay silent
     const now = opts.now ?? (() => Date.now());
     const doFetch = opts.fetchImpl ?? fetch;
     const url = `${(env[Env.URL] ?? DEFAULT_URL).replace(/\/+$/, '')}${TELEMETRY_PATH}`;
     const ci = env[Env.CI] !== undefined && env[Env.CI] !== '';
     const os = platform();
+    // Negated so it reads the way people say it: UTC+2 is +120, not -120.
+    const tzOffsetMin = -new Date().getTimezoneOffset();
     const { anonymousId, firstRun } = resolveIdentity();
     /**
      * One id per PROCESS, minted in memory and never persisted — which is exactly right: a daemon run
@@ -212,7 +275,22 @@ export const createTelemetry = (opts) => {
         ((command, args) => {
             spawn(command, args, { detached: true, stdio: 'ignore' }).unref();
         });
+    /**
+     * Returns whether the event was actually DELIVERED.
+     *
+     * Every caller but one ignores this and should: a lost metric must never surface to a user. The
+     * exception is `reticle_feedback`, which hands a receipt back to an agent — `sent: true` there was
+     * unconditional, so a DNS miss or a 4xx both read as "filed", and the only qualitative channel the
+     * product has could fail silently while telling the reporter it had worked.
+     *
+     * A detached send reports false: it is handed to a disowned child precisely so the caller does not
+     * wait, so its outcome is genuinely unknown and claiming success would be the same lie.
+     */
     const emit = async (kind, extra) => {
+        // In a Reticle source checkout the emitter carries FEEDBACK and nothing else: somebody typed the
+        // feedback, and no metric is worth phoning home from a contributor's clone.
+        if (feedbackOnly && TelemetryEventKind.FEEDBACK_SUBMITTED !== kind)
+            return false;
         const event = {
             v: TELEMETRY_EVENT_VERSION,
             anonymousId,
@@ -223,6 +301,7 @@ export const createTelemetry = (opts) => {
             version: opts.version,
             ci,
             os,
+            tzOffsetMin,
             projectIdSource,
             ...(extra?.actor !== undefined ? { actor: extra.actor } : {}),
             ...(extra?.command !== undefined ? { command: extra.command } : {}),
@@ -237,19 +316,22 @@ export const createTelemetry = (opts) => {
             ...(extra?.connection !== undefined ? { connection: extra.connection } : {}),
             ...(extra?.init !== undefined ? { init: extra.init } : {}),
             ...(extra?.bug !== undefined ? { bug: extra.bug } : {}),
+            ...(extra?.outage !== undefined ? { outage: extra.outage } : {}),
         };
         // Map the core contract onto PostHog's capture shape: id/name/time move up, the rest are properties.
         // The feedback body is FLATTENED into `feedback_*` properties rather than sent as a nested object:
         // PostHog filters and breakdowns operate on top-level properties, so a nested `feedback.stack`
         // would be invisible to the exact "which stacks report the most bugs" question this exists to
         // answer. One prefix keeps them grouped in the UI without a nested path.
-        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, bug, ...rest } = event;
+        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, bug, outage, ...rest } = event;
         // `$session_id` is PostHog's OWN session property, so sending ours under that name lights up
         // its built-in session views and funnels for free rather than requiring custom HogQL everywhere.
+        // `sessionId` rides only on events that happened inside a daemon run. A one-shot CLI command
+        // mints a per-process id that joins to nothing and inflates every session count — see
+        // isSessionScoped for the measurement.
         const properties = {
             ...rest,
-            sessionId: eventSessionId,
-            $session_id: eventSessionId,
+            ...(isSessionScoped(name) ? { sessionId: eventSessionId, $session_id: eventSessionId } : {}),
         };
         // Each block is flattened under its own prefix rather than nested. PostHog filters, breakdowns and
         // insight builders all operate on TOP-LEVEL properties, so a nested `project.stack` is invisible to
@@ -269,37 +351,68 @@ export const createTelemetry = (opts) => {
             connection,
             init,
             bug,
+            outage,
         };
         for (const [prefix, block] of Object.entries(blocks)) {
             for (const [key, value] of Object.entries(block ?? {})) {
                 properties[`${prefix}_${key}`] = value;
             }
         }
-        const body = JSON.stringify({
-            api_key: apiKey,
-            batch: [
-                {
-                    event: name,
-                    distinct_id: distinctId,
-                    timestamp: new Date(ts).toISOString(),
-                    properties: { ...properties, ...POSTHOG_PERSONLESS },
-                },
-            ],
-        });
+        const capture = {
+            event: name,
+            distinct_id: distinctId,
+            timestamp: new Date(ts).toISOString(),
+            properties: { ...properties, ...POSTHOG_PERSONLESS },
+        };
+        const body = JSON.stringify({ api_key: apiKey, batch: [capture] });
+        const filePath = env[Env.FILE];
+        if (filePath !== undefined && filePath !== '') {
+            // The SAME payload the wire would have carried, built by the same code path and redacted by
+            // the same rules — so what a run records is what a user would have sent. One JSON object per
+            // line, appended, so a whole sweep lands in one file in order.
+            try {
+                appendFileSync(filePath, `${JSON.stringify(capture)}\n`, 'utf8');
+                return true;
+            }
+            catch {
+                return false; // a sink that cannot write must not take the daemon down
+            }
+        }
         try {
-            if (extra?.detach === true && opts.fetchImpl === undefined) {
+            if (true === extra?.detach && opts.fetchImpl === undefined) {
                 spawnDetached(process.execPath, ['-e', DETACHED_SEND_SCRIPT, url, body]);
-                return;
+                return false; // handed off, outcome unknowable from here
+            }
+            // Feedback is slower and retried; everything else keeps the fire-and-forget budget.
+            const isFeedback = TelemetryEventKind.FEEDBACK_SUBMITTED === kind;
+            const timeoutMs = isFeedback ? FEEDBACK_TIMEOUT_MS : SEND_TIMEOUT_MS;
+            const attempts = 1 + (isFeedback ? FEEDBACK_RETRIES : 0);
+            for (let attempt = 0; attempt < attempts; attempt += 1) {
+                if (0 < attempt) {
+                    await new Promise((r) => setTimeout(r, FEEDBACK_RETRY_BACKOFF_MS * attempt));
+                }
+                try {
+                    const response = await doFetch(url, {
+                        method: 'POST',
+                        headers: { 'content-type': 'application/json' },
+                        body,
+                        signal: AbortSignal.timeout(timeoutMs),
+                    });
+                    // A 4xx is a rejected payload, not a delivery. It must not read as filed. It is also not
+                    // worth retrying — the payload will be rejected again — so only a THROW (timeout, DNS,
+                    // connection reset) goes round again.
+                    return response.ok !== false;
+                }
+                catch (error) {
+                    if (attempt === attempts - 1)
+                        throw error;
+                }
             }
-            await doFetch(url, {
-                method: 'POST',
-                headers: { 'content-type': 'application/json' },
-                body,
-                signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
-            });
+            return false;
         }
         catch {
             /* best-effort: a lost metric must never surface to the user */
+            return false;
         }
     };
     return { emit, enabled: true, firstRun };

package/dist/telemetry/verification-of.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Which tool results count as a completed verification, as one pure rule.
+ *
+ * It used to live inline in `runTool` and read `status === 'pass'`, mapping everything else to
+ * "no verdict". That was wrong in both directions at once, and the shape of the error is visible in
+ * the production data:
+ *
+ *   - a FAILING suite emitted nothing, so `verification_completed` only ever fired on greens while
+ *     `bugsInResult` fired on the reds — bugs with no verifications to divide them by;
+ *   - an EMPTY suite ("all 0 flows pass") emitted `verified: yes, passed: true`.
+ *
+ * Extracted because a rule this easy to get wrong, feeding the one number shown to investors, should
+ * be readable and testable on its own rather than inferred from a ternary inside a dispatcher.
+ */
+import { type BrowserBrand, type Verification } from '@reticlehq/core';
+/**
+ * The verification payload for a result, or undefined when nothing was verified.
+ *
+ * `falseGreenCaught` is the one that matters: the assertion PASSED and Reticle still refused to call
+ * it verified. That is the product's thesis reduced to a boolean.
+ */
+export declare function verificationOf(toolName: string, result: Record<string, unknown>, durationMs: number, brand?: BrowserBrand): Verification | undefined;

package/dist/telemetry/verification-of.js

@@ -0,0 +1,84 @@
+/**
+ * Which tool results count as a completed verification, as one pure rule.
+ *
+ * It used to live inline in `runTool` and read `status === 'pass'`, mapping everything else to
+ * "no verdict". That was wrong in both directions at once, and the shape of the error is visible in
+ * the production data:
+ *
+ *   - a FAILING suite emitted nothing, so `verification_completed` only ever fired on greens while
+ *     `bugsInResult` fired on the reds — bugs with no verifications to divide them by;
+ *   - an EMPTY suite ("all 0 flows pass") emitted `verified: yes, passed: true`.
+ *
+ * Extracted because a rule this easy to get wrong, feeding the one number shown to investors, should
+ * be readable and testable on its own rather than inferred from a ternary inside a dispatcher.
+ */
+import { VerifiedReason } from '@reticlehq/core';
+import { VERIFICATION_TOOLS } from '../tools/feedback-tools.js';
+import { getBrowserMode } from './browser-mode.js';
+/**
+ * The deciding clause, read off the result `decideVerified` wrote it onto.
+ *
+ * Narrowed against core's own list rather than forwarded: a result is an untyped record here, and a
+ * value that is not a member is not a reason — absent beats a string nobody can group by. Derived
+ * from the enum, never re-listed, so a new clause is covered the day it exists.
+ */
+const REASONS = new Set(Object.values(VerifiedReason));
+function reasonOf(result) {
+    const raw = result['verifiedReason'];
+    return 'string' === typeof raw && REASONS.has(raw) ? raw : undefined;
+}
+/** Suite statuses. `unverifiable` is a suite that ran but proved nothing — including an empty one. */
+const SuiteStatus = {
+    PASS: 'pass',
+    FAIL: 'fail',
+};
+/**
+ * The verification payload for a result, or undefined when nothing was verified.
+ *
+ * `falseGreenCaught` is the one that matters: the assertion PASSED and Reticle still refused to call
+ * it verified. That is the product's thesis reduced to a boolean.
+ */
+export function verificationOf(toolName, result, durationMs, brand) {
+    if (!VERIFICATION_TOOLS.has(toolName))
+        return undefined;
+    // A paused session REFUSES the call — nothing driven, nothing asserted. The refusal carries a
+    // verdict field so the agent never reads undefined off it, and that field must not be mistaken
+    // here for work that happened.
+    if (true === result['paused'])
+        return undefined;
+    const verified = 'string' === typeof result['verified'] ? result['verified'] : undefined;
+    // flow_verify reports `status: pass|fail|unverifiable`; assert reports a boolean `pass`. Accept
+    // either shape so the whole family is covered without normalizing four tools' contracts for a
+    // metric's convenience — but a status that is neither pass nor fail is NOT a verdict, and an empty
+    // suite reports exactly that.
+    const status = result['status'];
+    const passed = 'boolean' === typeof result['pass']
+        ? result['pass']
+        : status === SuiteStatus.PASS
+            ? true
+            : status === SuiteStatus.FAIL
+                ? false
+                : undefined;
+    if (verified === undefined && passed === undefined)
+        return undefined;
+    const reason = reasonOf(result);
+    return {
+        via: toolName,
+        verified: verified ?? (true === passed ? 'yes' : 'no'),
+        passed: passed ?? 'yes' === verified,
+        falseGreenCaught: true === passed && 'no' === verified,
+        durationMs,
+        // Headless CI, a human watching, or somebody's own dev server — three different products behind
+        // one number until this was recorded.
+        browser: getBrowserMode(),
+        // WHICH browser, when the page said. `attached` is the common case and says only that Reticle
+        // launched nothing; the brand is the difference between "somebody's own browser" and knowing it
+        // was Edge. Omitted when unreported — a desktop webview and an older SDK both have no answer,
+        // and "unknown" would be a value on a dashboard rather than a gap.
+        ...(brand !== undefined ? { brand } : {}),
+        // WHY, not just what. `verified: unknown` covered seven different clauses of the honesty rule
+        // belonging to three different owners — the agent, the app, and Reticle's own blind spots — and
+        // they need opposite responses. A suite verdict has no clause behind it and reports none.
+        ...(reason === undefined ? {} : { reason }),
+    };
+}

package/dist/tools/act-capsule.js

@@ -10,7 +10,7 @@
  * must never fail the run that found it.
  */
 import { ActionType, AnchorKind } from '@reticlehq/core';
-import { CapsuleStore, capsuleId } from '../capsule/capsule-store.js';
+import { CapsuleStore, capsuleId, CAPSULE_VERSION } from '../capsule/capsule-store.js';
 import { ReticleTool } from './tool-names.js';
 import { asRecord, asString } from './tools-helpers.js';
 /** Returns the capsule id when one was written, or undefined when there was nothing to save. */
@@ -23,7 +23,7 @@ export async function saveFailedAssertCapsule(inputs) {
         .map((l) => ('name' in l ? `${l.kind} ${String(l.name)}` : l.kind))
         .join(' AND ');
     const saved = await new CapsuleStore(deps.fs, deps.reticleRoot).save({
-        version: 1,
+        version: CAPSULE_VERSION,
         id,
         createdAt: deps.now(),
         origin: 'failed-assert',

package/dist/tools/act-danger.d.ts

@@ -5,3 +5,15 @@ export declare function assertNotDestructive(action: ActionType, innerArgs: Reco
  * source alone never says so.
  */
 export declare function assertDragNotDestructive(innerArgs: Record<string, unknown>, from: unknown, to: unknown): void;
+/**
+ * `reticle_act_and_wait` cannot drive native input, and used to take `args.native` and ignore it.
+ *
+ * An open `args` passthrough accepted the field, the handler drove the page through the SDK anyway,
+ * and the result claimed success — so an agent asking for the one thing a synthetic click cannot do
+ * (a file picker, the clipboard, an `isTrusted`-gated handler) got a synthetic click and no hint
+ * that its request had been dropped. A silently ignored argument is a false promise; refusing with
+ * the route that DOES work is the honest answer.
+ */
+export declare const NATIVE_INPUT_UNSUPPORTED: string;
+/** Refuse rather than silently drop a native-input request the act-then-wait path cannot honour. */
+export declare function assertNativeInputSupported(innerArgs: Record<string, unknown>): void;

package/dist/tools/act-danger.js

@@ -1,4 +1,4 @@
-import { ActionType, DANGEROUS_ACTION_CONFIRM_ARG, isDangerousActionText } from '@reticlehq/core';
+import { ActionType, DANGEROUS_ACTION_CONFIRM_ARG, NATIVE_INPUT_ARG, isDangerousActionText, } from '@reticlehq/core';
 import { asRecord, asString } from './tools-helpers.js';
 /**
  * Refuse to drive a money-moving or destructive control by accident.
@@ -25,7 +25,7 @@ function descriptorText(value) {
 export function assertNotDestructive(action, innerArgs, inspected) {
     if (action !== ActionType.CLICK && action !== ActionType.DBLCLICK)
         return;
-    if (innerArgs[DANGEROUS_ACTION_CONFIRM_ARG] === true)
+    if (true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG])
         return;
     if (!isDangerousActionText(descriptorText(inspected)))
         return;
@@ -36,9 +36,26 @@ export function assertNotDestructive(action, innerArgs, inspected) {
  * source alone never says so.
  */
 export function assertDragNotDestructive(innerArgs, from, to) {
-    if (innerArgs[DANGEROUS_ACTION_CONFIRM_ARG] === true)
+    if (true === innerArgs[DANGEROUS_ACTION_CONFIRM_ARG])
         return;
     if (!isDangerousActionText(`${descriptorText(from)} ${descriptorText(to)}`))
         return;
     throw new Error(`potentially destructive native action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
 }
+/**
+ * `reticle_act_and_wait` cannot drive native input, and used to take `args.native` and ignore it.
+ *
+ * An open `args` passthrough accepted the field, the handler drove the page through the SDK anyway,
+ * and the result claimed success — so an agent asking for the one thing a synthetic click cannot do
+ * (a file picker, the clipboard, an `isTrusted`-gated handler) got a synthetic click and no hint
+ * that its request had been dropped. A silently ignored argument is a false promise; refusing with
+ * the route that DOES work is the honest answer.
+ */
+export const NATIVE_INPUT_UNSUPPORTED = `reticle_act_and_wait cannot drive native input, so args.${NATIVE_INPUT_ARG} would be ignored. ` +
+    `Use reticle_act { args: { ${NATIVE_INPUT_ARG}: true } } for the trusted click, then assert the ` +
+    'consequence with reticle_assert / reticle_observe using the `since` cursor it returns.';
+/** Refuse rather than silently drop a native-input request the act-then-wait path cannot honour. */
+export function assertNativeInputSupported(innerArgs) {
+    if (true === innerArgs[NATIVE_INPUT_ARG])
+        throw new Error(NATIVE_INPUT_UNSUPPORTED);
+}

package/dist/tools/act-helpers.js

@@ -5,16 +5,16 @@
  * session, a command, or a tool definition — these are total functions over their arguments, which
  * is why they can be tested without a browser and why they were the right thing to move.
  */
-import { ActionType } from '@reticlehq/core';
+import { ActionType, ConsequenceKind } from '@reticlehq/core';
 import { HonestyGrade } from '../honesty/honesty.js';
 import { asNumber, asRecord, asString } from './tools-helpers.js';
 /** The strongest consequence grade a set of expected links proves (signal > net > state > presence). */
 export function gradeOf(links) {
-    if (links.some((l) => l.kind === 'signal'))
+    if (links.some((l) => ConsequenceKind.SIGNAL === l.kind))
         return HonestyGrade.SIGNAL;
-    if (links.some((l) => l.kind === 'net'))
+    if (links.some((l) => ConsequenceKind.NET === l.kind))
         return HonestyGrade.NET;
-    if (links.some((l) => l.kind === 'state'))
+    if (links.some((l) => ConsequenceKind.STATE === l.kind))
         return HonestyGrade.STATE;
     return HonestyGrade.PRESENCE;
 }

package/dist/tools/act-tools.d.ts

@@ -1,10 +1,2 @@
 import { type ToolDef } from './tool-kit.js';
-/**
- * Narrow the wire's `action` to a real ActionType, or undefined.
- *
- * It used to be `asString(args['action']) ?? ''`, so an unknown or missing action became the empty
- * string and travelled on — reaching the browser as a command it could not perform, and reported back
- * as a generic failure rather than "that is not an action". Validate at the boundary, per the project's
- * unknown-plus-narrowing rule, so a typo is rejected where it can still be explained.
- */
 export declare const ACT_TOOLS: ToolDef[];