@reticlehq/server 2.13.1 → 2.14.0

package/dist/telemetry/feedback.d.ts

@@ -21,7 +21,7 @@
  *      existing switch (`RETICLE_TELEMETRY=0`, `DO_NOT_TRACK`, `reticle telemetry disable`) still
  *      disables it too, since it rides the same emitter.
  */
-import { type Feedback } from '@reticlehq/core';
+import { type Feedback } from '@reticlehq/core/telemetry';
 import { type SessionFacts } from './feedback-context.js';
 /** Kills the feedback channel ONLY — adoption counters keep flowing. */
 export declare const FEEDBACK_ENV = "RETICLE_FEEDBACK";
@@ -37,8 +37,8 @@ export declare function redactFeedbackText(input: string, max: number): Redactio
 /** True when the feedback channel is switched off on its own (the emitter's switches apply as well). */
 export declare function feedbackDisabled(env?: NodeJS.ProcessEnv): boolean;
 /** What the author supplies; the environment context is detected, never asked for. */
-export type FeedbackInput = Pick<Feedback, 'source' | 'kind' | 'text' | 'trace' | 'rating' | 'need' | 'impact' | 'currentApproach' | 'model'>;
-export interface FeedbackReceipt {
+type FeedbackInput = Pick<Feedback, 'source' | 'kind' | 'text' | 'trace' | 'rating' | 'need' | 'impact' | 'currentApproach' | 'model'>;
+interface FeedbackReceipt {
     /**
      * DELIVERY confirmed. Only ever true when the send was awaited and the endpoint accepted it —
      * never as an optimistic stand-in for "we handed it to the emitter". That distinction is the whole
@@ -96,3 +96,4 @@ export declare function submitFeedback(input: FeedbackInput, opts?: {
  * CLI prints is then genuinely everything that goes.
  */
 export declare function describeFeedbackPayload(context: Partial<Feedback>): Record<string, unknown>;
+export {};

package/dist/telemetry/feedback.js

@@ -21,7 +21,7 @@
  *      existing switch (`RETICLE_TELEMETRY=0`, `DO_NOT_TRACK`, `reticle telemetry disable`) still
  *      disables it too, since it rides the same emitter.
  */
-import { FeedbackSchema, FEEDBACK_TEXT_MAX, FEEDBACK_TRACE_MAX, FEEDBACK_FIELD_MAX, TelemetryEventKind, } from '@reticlehq/core';
+import { FeedbackSchema, FEEDBACK_TEXT_MAX, FEEDBACK_TRACE_MAX, FEEDBACK_FIELD_MAX, TelemetryEventKind, } from '@reticlehq/core/telemetry';
 import { platform } from 'node:os';
 import { getTelemetry } from './telemetry.js';
 import { noteFeedbackUndelivered } from './feedback-delivery.js';

package/dist/telemetry/git-facts.d.ts

@@ -1,5 +1,5 @@
-import { GitState, RepoForge } from '@reticlehq/core';
-export interface GitFacts {
+import { GitState, RepoForge } from '@reticlehq/core/telemetry';
+interface GitFacts {
     /** none | local_only (init'd, never pushed) | remote (has an origin). */
     state: GitState;
     /** The NORMALIZED origin — hashed by the caller, never sent raw. Absent unless state is `remote`. */

package/dist/telemetry/git-facts.js

@@ -22,7 +22,7 @@
  */
 import { readFileSync, statSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { GitState, RepoForge } from '@reticlehq/core';
+import { GitState, RepoForge } from '@reticlehq/core/telemetry';
 /** How far up the tree to look for a `.git` before giving up. Deep monorepos are still well inside. */
 const MAX_PARENT_WALK = 20;
 /**

package/dist/telemetry/identify.d.ts

@@ -1,4 +1,4 @@
-import { UsageContextKind, type Identity } from '@reticlehq/core';
+import { UsageContextKind, type Identity } from '@reticlehq/core/telemetry';
 /** Re-exported so the CLI has one import for the whole feature; the shape itself lives in core. */
 export { UsageContextKind };
 export type { Identity };

package/dist/telemetry/identify.js

@@ -21,7 +21,7 @@
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { TelemetryEventKind, UsageContextKind } from '@reticlehq/core';
+import { TelemetryEventKind, UsageContextKind } from '@reticlehq/core/telemetry';
 import { getTelemetry } from './telemetry.js';
 const RETICLE_DIR = join(homedir(), '.reticle');
 /** Persisted so the identity survives shells and is attached to later sessions — and so it can be shown back. */

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

@@ -10,19 +10,7 @@
  * 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 { type InitOutcome } from '@reticlehq/core';
-/** Classified init failures — our own vocabulary, never a raw error or a path. */
-export declare const InitFailure: {
-    /** Run outside a project root. The single most common first-run mistake. */
-    readonly NO_PACKAGE_JSON: "no_package_json";
-    /** The manifest exists and is not valid JSON — a trailing comma, usually. Never a stack trace. */
-    readonly MALFORMED_PACKAGE_JSON: "malformed_package_json";
-    /** The package manager failed: offline, a locked registry, a broken install. */
-    readonly DEPENDENCY_INSTALL: "dependency_install";
-    /** The `claude mcp add` step failed — the CLI is missing or refused. Reticle installs but is unreachable. */
-    readonly MCP_REGISTRATION: "mcp_registration";
-    readonly OTHER: "other";
-};
-export type InitFailure = (typeof InitFailure)[keyof typeof InitFailure];
+import { type InitOutcome } from '@reticlehq/core/telemetry';
+export { InitFailure } from '@reticlehq/init';
 /** 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,21 +10,12 @@
  * 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';
+import { TelemetryEventKind } from '@reticlehq/core/telemetry';
 import { getTelemetry } from './telemetry.js';
 import { resolveInstallSource } from './install-source.js';
-/** Classified init failures — our own vocabulary, never a raw error or a path. */
-export const InitFailure = {
-    /** Run outside a project root. The single most common first-run mistake. */
-    NO_PACKAGE_JSON: 'no_package_json',
-    /** The manifest exists and is not valid JSON — a trailing comma, usually. Never a stack trace. */
-    MALFORMED_PACKAGE_JSON: 'malformed_package_json',
-    /** The package manager failed: offline, a locked registry, a broken install. */
-    DEPENDENCY_INSTALL: 'dependency_install',
-    /** The `claude mcp add` step failed — the CLI is missing or refused. Reticle installs but is unreachable. */
-    MCP_REGISTRATION: 'mcp_registration',
-    OTHER: 'other',
-};
+// 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';
 /** Report one init outcome. Best-effort; setup must never fail because a metric did. */
 export function reportInitOutcome(init) {
     try {

package/dist/telemetry/install-source.d.ts

@@ -22,7 +22,7 @@
  * than none: it is the number distribution decisions get steered on, and a guess and a measurement
  * are indistinguishable once they are in the same column.
  */
-import { InstallSource } from '@reticlehq/core';
+import { InstallSource } from '@reticlehq/core/telemetry';
 /** The one marker. Set by a channel on the process that runs the install. */
 export declare const INSTALL_SOURCE_ENV = "RETICLE_INSTALL_SOURCE";
 /**
@@ -55,16 +55,10 @@ export declare function declaredInstallSource(env?: NodeJS.ProcessEnv): InstallS
  */
 export declare function projectInstallSource(cwd: string, env?: NodeJS.ProcessEnv): InstallSource;
 /**
- * The same config with `installSource` added, or `undefined` when there is nothing to add.
- *
- * `installSource` is written only when `.reticle.json` is CREATED, and `init` reports that file as
- * `already exists` on every re-run — so everyone who was already here when the marker shipped, and
- * everyone who ran `init` once without one, keeps `unknown` forever with no way to fix it. That is
- * most of the population the field exists to describe.
- *
- * An EXISTING value is never overwritten. The first channel is the one that brought the user in, and
- * a later `init` through a different route must not take credit for an acquisition it did not make.
- * Anything unparseable is left exactly as it is: a config is user data, and `init` rewriting a file
- * it could not read would be a far worse failure than a missing dimension.
+ * `configWithInstallSource` lives in `@reticlehq/init` — `init` is the only thing that writes
+ * `.reticle.json`, and the scaffolder may not import the daemon. Re-exported here so this module
+ * stays the one place to read about install attribution, and so its tests are unchanged. Which
+ * channel declared itself is still decided above; the plan receives the answer as
+ * `PlanInput.installSource`.
  */
-export declare function configWithInstallSource(source: string | null | undefined, declared: string | undefined): string | undefined;
+export { configWithInstallSource } from '@reticlehq/init';

package/dist/telemetry/install-source.js

@@ -22,7 +22,7 @@
  * than none: it is the number distribution decisions get steered on, and a guess and a measurement
  * are indistinguishable once they are in the same column.
  */
-import { InstallSource } from '@reticlehq/core';
+import { InstallSource } from '@reticlehq/core/telemetry';
 import { findProjectConfig } from '../cli/cli-port.js';
 /** The one marker. Set by a channel on the process that runs the install. */
 export const INSTALL_SOURCE_ENV = 'RETICLE_INSTALL_SOURCE';
@@ -73,32 +73,10 @@ export function projectInstallSource(cwd, env = process.env) {
     return resolveInstallSource(env);
 }
 /**
- * The same config with `installSource` added, or `undefined` when there is nothing to add.
- *
- * `installSource` is written only when `.reticle.json` is CREATED, and `init` reports that file as
- * `already exists` on every re-run — so everyone who was already here when the marker shipped, and
- * everyone who ran `init` once without one, keeps `unknown` forever with no way to fix it. That is
- * most of the population the field exists to describe.
- *
- * An EXISTING value is never overwritten. The first channel is the one that brought the user in, and
- * a later `init` through a different route must not take credit for an acquisition it did not make.
- * Anything unparseable is left exactly as it is: a config is user data, and `init` rewriting a file
- * it could not read would be a far worse failure than a missing dimension.
+ * `configWithInstallSource` lives in `@reticlehq/init` — `init` is the only thing that writes
+ * `.reticle.json`, and the scaffolder may not import the daemon. Re-exported here so this module
+ * stays the one place to read about install attribution, and so its tests are unchanged. Which
+ * channel declared itself is still decided above; the plan receives the answer as
+ * `PlanInput.installSource`.
  */
-export function configWithInstallSource(source, declared) {
-    if (undefined === declared || null === source || undefined === source)
-        return undefined;
-    let parsed;
-    try {
-        parsed = JSON.parse(source);
-    }
-    catch {
-        return undefined;
-    }
-    if (null === parsed || 'object' !== typeof parsed || Array.isArray(parsed))
-        return undefined;
-    const fields = parsed;
-    if (undefined !== fields['installSource'])
-        return undefined;
-    return `${JSON.stringify({ ...fields, installSource: declared }, null, 2)}\n`;
-}
+export { configWithInstallSource } from '@reticlehq/init';

package/dist/telemetry/license-activation.d.ts

@@ -25,9 +25,9 @@
  * resolves to a company only against the issuance ledger held locally, so the analytics backend never
  * holds a customer list.
  */
-import { LicenseActivation } from '@reticlehq/core';
+import { LicenseActivation } from '@reticlehq/core/telemetry';
 /** The activation facts that ride the wire. All absent on a build with no issuer key baked. */
-export interface LicenseFacts {
+interface LicenseFacts {
     licenseId?: string;
     licenseStatus?: LicenseActivation;
     /**
@@ -52,3 +52,4 @@ export interface LicenseFacts {
  * key parsing, which is the part most likely to be handed something malformed.
  */
 export declare function licenseFacts(now: number, env?: NodeJS.ProcessEnv, baked?: string): LicenseFacts;
+export {};

package/dist/telemetry/license-activation.js

@@ -25,7 +25,7 @@
  * resolves to a company only against the issuance ledger held locally, so the analytics backend never
  * holds a customer list.
  */
-import { LicenseActivation } from '@reticlehq/core';
+import { LicenseActivation } from '@reticlehq/core/telemetry';
 import { describeLicense, LICENSE_KEY_ENV } from '../license/license.js';
 /**
  * Resolve activation for one event. The clock is passed in (rule 7) and is the EVENT's clock, not a

package/dist/telemetry/machine-snapshot.d.ts

@@ -1,4 +1,4 @@
-import type { MachineSnapshot } from '@reticlehq/core';
+import type { MachineSnapshot } from '@reticlehq/core/telemetry';
 /**
  * Sample the machine. Never throws — this is called from a crash handler, where the one unacceptable
  * outcome is making the crash worse.

package/dist/telemetry/mcp-connection.js

@@ -9,7 +9,7 @@
  * minutes, and in every other metric that is indistinguishable from enthusiastic use: more sessions,
  * more connects, more activity. The `reconnect` flag is what tells those two stories apart.
  */
-import { TelemetryEventKind } from '@reticlehq/core';
+import { TelemetryEventKind } from '@reticlehq/core/telemetry';
 import { getTelemetry } from './telemetry.js';
 import { appEverConnected } from './app-instrumented.js';
 let connectsSeen = 0;

package/dist/telemetry/project-profile.d.ts

@@ -1,18 +1,4 @@
 import { ProjectSize, type ProjectProfile } from '@reticlehq/core';
-/**
- * The feature FAMILIES, and the on-disk evidence that a project has adopted each. Named rather than
- * counted so the vocabulary stays stable as tools are added, renamed, or merged into action-dispatched
- * families — a count would silently change meaning the next time the tool surface is reorganized.
- */
-export declare const FeatureFamily: {
-    readonly DETERMINISTIC_REPLAY: "deterministic_replay";
-    readonly VISUAL_BASELINE: "visual_baseline";
-    readonly TEXT_BASELINE: "text_baseline";
-    readonly CAPABILITY_CONTRACT: "capability_contract";
-    readonly RUN_ARTIFACTS: "run_artifacts";
-    readonly BUG_CAPSULES: "bug_capsules";
-    readonly CROSS_RUN_HISTORY: "cross_run_history";
-};
 export declare function sizeBucket(sourceFiles: number): ProjectSize;
 /**
  * Project age in whole WEEKS, from the repo's first commit.

package/dist/telemetry/project-profile.js

@@ -21,7 +21,7 @@ import { readProjectId } from '../cli/cli-port.js';
  * counted so the vocabulary stays stable as tools are added, renamed, or merged into action-dispatched
  * families — a count would silently change meaning the next time the tool surface is reorganized.
  */
-export const FeatureFamily = {
+const FeatureFamily = {
     DETERMINISTIC_REPLAY: 'deterministic_replay',
     VISUAL_BASELINE: 'visual_baseline',
     TEXT_BASELINE: 'text_baseline',

package/dist/telemetry/proxy-telemetry.js

@@ -9,7 +9,7 @@
  * The send is awaited. Fire-and-forget microseconds before `process.exit` is how `daemon_stopped`
  * never arrived: the POST was killed every time and nothing threw.
  */
-import { TelemetryEventKind } from '@reticlehq/core';
+import { TelemetryEventKind } from '@reticlehq/core/telemetry';
 import { getSessionMetrics } from './session-metrics.js';
 import { getTelemetry } from './telemetry.js';
 export async function flushProxySessionMetrics(telemetry = getTelemetry(), metrics = getSessionMetrics()) {

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 ConnectFailure, type SessionSummary } from '@reticlehq/core';
+import { BrowserLaunchKind, type ConnectFailure, type SessionSummary } from '@reticlehq/core/telemetry';
 /**
  * Mutable counters for one daemon lifetime. A plain class, not a store: it is process-local, it never
  * persists, and it dies with the daemon.

package/dist/telemetry/session-metrics.js

@@ -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, } from '@reticlehq/core';
+import { BrowserLaunchKind, } from '@reticlehq/core/telemetry';
 import { errorSkeleton, fingerprintError } from './error-fingerprint.js';
 import { describeToolParams } from './argument-shape.js';
 import { machineSnapshot } from './machine-snapshot.js';

package/dist/telemetry/telemetry.d.ts

@@ -1,4 +1,4 @@
-import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type InstallSource, type McpConnection, type McpOutage, type ToolRefusal, type AppInstrumentation, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core';
+import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type InstallSource, type McpConnection, type McpOutage, type ToolRefusal, type AppInstrumentation, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core/telemetry';
 /**
  * PostHog's group type for a licensed customer. Sent as `$groups` so PostHog can aggregate a whole
  * organisation natively: per-company retention, "which orgs went quiet", one row per customer rather
@@ -10,22 +10,6 @@ import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Id
  * analytics side learns a customer list only when we deliberately upload one.
  */
 export declare const POSTHOG_GROUP_ORGANIZATION = "organization";
-/**
- * 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 declare const FEEDBACK_TIMEOUT_MS = 15000;
-export declare const FEEDBACK_RETRIES = 1;
-export declare const FEEDBACK_RETRY_BACKOFF_MS = 750;
 /**
  * One-way project fingerprint: distinct-count of this = "projects Reticle is used in", reveals nothing.
  *

package/dist/telemetry/telemetry.js

@@ -19,7 +19,7 @@ import { randomUUID, createHash } from 'node:crypto';
 import { appendFileSync, readFileSync, writeFileSync, mkdirSync, existsSync, rmSync, } from 'node:fs';
 import { homedir, platform } from 'node:os';
 import { dirname, join } from 'node:path';
-import { TelemetryEventKind, TELEMETRY_EVENT_VERSION, ProjectIdSource, isSessionScoped, } from '@reticlehq/core';
+import { TelemetryEventKind, TELEMETRY_EVENT_VERSION, ProjectIdSource, isSessionScoped, } from '@reticlehq/core/telemetry';
 import { SERVER_VERSION } from '../version/server-version.js';
 const RETICLE_DIR = join(homedir(), '.reticle');
 const ID_FILE = join(RETICLE_DIR, 'telemetry-id');
@@ -67,9 +67,9 @@ const SEND_TIMEOUT_MS = 2000;
  * 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;
+const FEEDBACK_TIMEOUT_MS = 15_000;
+const FEEDBACK_RETRIES = 1;
+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

package/dist/telemetry/tool-refused.d.ts

@@ -10,7 +10,7 @@
  * Emitted from `runTool`, which is the one place both dispatch paths cross, so a tool added later is
  * covered without anybody remembering to cover it.
  */
-import { RefusalReason, type NoSessionReason } from '@reticlehq/core';
+import { RefusalReason, type NoSessionReason } from '@reticlehq/core/telemetry';
 /** Record the branch code for the no-session error being thrown right now. */
 export declare function notePendingNoSessionReason(reason: NoSessionReason | undefined): void;
 /** A call that was served. Breaks the retry chain: what follows it is not a retry of anything. */

package/dist/telemetry/tool-refused.js

@@ -10,7 +10,7 @@
  * Emitted from `runTool`, which is the one place both dispatch paths cross, so a tool added later is
  * covered without anybody remembering to cover it.
  */
-import { RefusalReason, TelemetryActor, TelemetryEventKind, } from '@reticlehq/core';
+import { RefusalReason, TelemetryActor, TelemetryEventKind, } from '@reticlehq/core/telemetry';
 import { getTelemetry } from './telemetry.js';
 /**
  * Refusal events one daemon run will send.

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

@@ -13,7 +13,7 @@
 import type { Session } from '../session/session.js';
 import { type SuccessorRegistry } from '../session/session-successor.js';
 import type { EvalResult } from '../events/predicate-eval.js';
-export interface FollowSuccessor {
+interface FollowSuccessor {
     sessions: SuccessorRegistry;
     session: Session;
     verdict: EvalResult;
@@ -24,7 +24,7 @@ export interface FollowSuccessor {
     /** Re-ask the declared consequence on `next`, with whatever budget is left. */
     reevaluate: (next: Session, budgetMs: number) => Promise<EvalResult>;
 }
-export interface FollowedOutcome {
+interface FollowedOutcome {
     session: Session;
     verdict: EvalResult;
     /** True when the wait moved to a new document, so the caller must reset its event cursor. */
@@ -39,3 +39,4 @@ export interface FollowedOutcome {
  * `awaitDocumentSuccessor` refuses to guess — a wrong follow drives somebody else's app.
  */
 export declare function followLostObservation(input: FollowSuccessor): Promise<FollowedOutcome>;
+export {};

package/dist/tools/act-preflight.js

@@ -10,9 +10,10 @@
  * produce: it sends somebody to fix code that is not broken. "Nothing was acted on" is a far better
  * outcome than "unknown".
  */
+import { isGlobalPressCall } from '@reticlehq/core';
+import { unevaluablePredicateReason } from '../events/predicate-precheck.js';
 import { SessionReplacedError } from '../session/pending-commands.js';
 import { assertNativeInputSupported } from './act-danger.js';
-import { unevaluablePredicateReason } from '../events/predicate-precheck.js';
 /**
  * Refuse a sequence whose steps cannot be addressed.
  *
@@ -21,8 +22,9 @@ import { unevaluablePredicateReason } from '../events/predicate-precheck.js';
  * a stale-ref diagnosis for a missing locator — and the caller went looking for a re-render.
  *
  * `target` is the same locator `reticle_act` / `reticle_act_and_wait` take; the handler resolves it
- * with `resolveActTarget` before dispatch. This check only asks that every step names one of the
- * two, and it runs before the first step, so a typo in step three cannot leave one and two applied.
+ * with `resolveActTarget` before dispatch. This check asks that every step names one of the two,
+ * except a document-key press (Escape, Tab, a modifier shortcut), which is not aimed at an element.
+ * It runs before the first step, so a typo in step three cannot leave one and two applied.
  */
 /**
  * Keys an agent reaches for when it means "and prove this happened".
@@ -55,9 +57,12 @@ export function assertSequenceSteps(steps) {
             return;
         if (step['target'] !== undefined)
             return;
+        if (isGlobalPressCall(step))
+            return;
         throw new Error(`step ${String(i)} has no \`ref\` or \`target\`. ` +
             'Sequence steps take `ref` (from reticle_query/reticle_snapshot) or `target` ' +
             '(e.g. { testid } or { label }), the same locator reticle_act accepts. ' +
+            'A press of Escape, Tab, or a modifier shortcut is a document key and needs neither. ' +
             'Nothing was acted on — the whole sequence is refused so a bad step cannot leave the earlier ones half-applied.');
     });
 }

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

@@ -10,5 +10,9 @@ import { type TargetResolution } from './resolve-target.js';
  *
  * `ref` wins when both are given, because it is the more specific instruction and silently
  * preferring the query would act on something the caller did not name.
+ *
+ * A document-key press (Escape, Tab, a modifier shortcut) is the one action that is not aimed at
+ * an element. It resolves to `{ kind: 'global' }` rather than refusing, so dismissing a dialog
+ * does not cost a snapshot.
  */
 export declare function resolveActTarget(session: Session, args: Record<string, unknown>): Promise<TargetResolution>;

package/dist/tools/act-target.js

@@ -7,10 +7,16 @@
  * dispatch out of the file that opens the window would have weakened a real invariant to satisfy a
  * line count. This resolves a TARGET and dispatches only QUERY, so that guard is untouched.
  */
-import { ReticleCommand } from '@reticlehq/core';
+import { ReticleCommand, isGlobalPressCall } from '@reticlehq/core';
 import { normalizeQueryArgs } from './query-shape.js';
 import { resolveTargetRef } from './resolve-target.js';
 import { asRecord, asString } from './tools-helpers.js';
+/**
+ * A press of Escape, Tab, or a modifier shortcut is a document key. Requiring a locator for it
+ * forced a snapshot just to name an element the keystroke is not about.
+ */
+const MISSING_ACT_TARGET = 'pass `ref` (from reticle_query/reticle_snapshot) or `target` (e.g. { testid } or { role, name }). ' +
+    'A press of Escape, Tab, or a modifier shortcut is a document key and needs neither.';
 /**
  * Resolve an action's element: an explicit `ref`, or a `target` query resolved in the SAME call.
  *
@@ -21,6 +27,10 @@ import { asRecord, asString } from './tools-helpers.js';
  *
  * `ref` wins when both are given, because it is the more specific instruction and silently
  * preferring the query would act on something the caller did not name.
+ *
+ * A document-key press (Escape, Tab, a modifier shortcut) is the one action that is not aimed at
+ * an element. It resolves to `{ kind: 'global' }` rather than refusing, so dismissing a dialog
+ * does not cost a snapshot.
  */
 export async function resolveActTarget(session, args) {
     const ref = asString(args['ref']);
@@ -28,10 +38,9 @@ export async function resolveActTarget(session, args) {
         return { kind: 'ref', ref };
     const target = args['target'];
     if (target === undefined) {
-        return {
-            kind: 'error',
-            message: 'pass `ref` (from reticle_query/reticle_snapshot) or `target` (e.g. { testid } or { role, name }).',
-        };
+        if (isGlobalPressCall(args))
+            return { kind: 'global', ref: '' };
+        return { kind: 'error', message: MISSING_ACT_TARGET };
     }
     const q = normalizeQueryArgs(asRecord(target));
     const out = await session.command(ReticleCommand.QUERY, {

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

@@ -4,7 +4,6 @@
  * native-input attempt itself lives in real-input-attempt.ts for the same reason.
  */
 import type { Session } from '../session/session.js';
-import { z } from 'zod';
 import { type ToolDef, type ToolDeps } from './tool-kit.js';
 /**
  * Single dispatch point for every ACT and ACT_SEQUENCE command.
@@ -18,5 +17,4 @@ import { type ToolDef, type ToolDeps } from './tool-kit.js';
  * base64 to the browser as if it were an inline content call.
  */
 export declare function actCommand(deps: ToolDeps, session: Session, actArgs: Record<string, unknown>, timeoutMs?: number): Promise<import('@reticlehq/core').CommandResult>;
-export declare const actionTypeEnum: z.ZodEnum<[string, ...string[]]>;
 export declare const ACT_TOOLS: ToolDef[];