@reticlehq/server 3.4.0 → 3.6.0

package/dist/memory/project/sync-status.d.ts

@@ -0,0 +1,39 @@
+import type { CloudSyncState } from '../cloud/sync-cycle.js';
+export declare const SyncStatus: {
+    readonly ON_PLATFORM: "on-platform";
+    readonly PENDING: "pending";
+    readonly REFUSED: "refused";
+    readonly LOCAL_ONLY: "local-only";
+};
+export type SyncStatus = (typeof SyncStatus)[keyof typeof SyncStatus];
+export interface SyncSummary {
+    linked: boolean;
+    /** Runs on this machine. */
+    runs: number;
+    onPlatform: number;
+    pending: number;
+    /** The runs the platform refused in their current form, with its reason. */
+    refused: {
+        runId: string;
+        reason: string;
+    }[];
+    /** Refusals beyond the ones named. */
+    refusedMore: number;
+    lastPushAt?: number;
+    /** Why the last cycle failed, when it did. */
+    lastError?: string;
+}
+export declare function summarizeSync(input: {
+    linked: boolean;
+    runs: readonly {
+        runId: string;
+        payload: unknown;
+    }[];
+    state: CloudSyncState;
+}): SyncSummary;
+/** This project's summary, read from its `.reticle`. Never throws: an unreadable record is empty. */
+export declare function readSyncSummary(reticleRoot: string, linked: boolean): SyncSummary;
+/** One status for the whole project: the worst thing true of it. */
+export declare function overallStatus(summary: SyncSummary): SyncStatus;
+/** The summary in one sentence an agent can repeat to a person. */
+export declare function describeSync(summary: SyncSummary, now: number): string;

package/dist/memory/project/sync-status.js

@@ -0,0 +1,90 @@
+/**
+ * Where this project's work stands with the Reticle platform, run by run.
+ *
+ * Read from the sync cycle's own record (`.reticle/cloud-state.json`): the content hash of every run
+ * the platform ACCEPTED, and the reason for every run it REFUSED. A run whose current content matches
+ * an accepted hash is on the platform; one whose current content was refused is refused, with the
+ * platform's own sentence; anything else is waiting for the next cycle. On a machine that is not
+ * linked, everything is local only.
+ *
+ * Nothing here talks to the network. It answers "did my work go up?" from what the machine already
+ * knows, so it can ride on every verdict without costing a request.
+ */
+import { diskSource, readCloudState } from '../cloud/sync-disk.js';
+import { hashPayload } from '../cloud/sync-hash.js';
+export const SyncStatus = {
+    ON_PLATFORM: 'on-platform',
+    PENDING: 'pending',
+    REFUSED: 'refused',
+    LOCAL_ONLY: 'local-only',
+};
+/** How many refusals a summary names before it only counts them. */
+const MAX_NAMED_REFUSALS = 3;
+export function summarizeSync(input) {
+    const { linked, runs, state } = input;
+    let onPlatform = 0;
+    let pending = 0;
+    const refused = [];
+    if (linked) {
+        for (const run of runs) {
+            const hash = hashPayload(run.payload);
+            const refusal = state.refusedRuns?.[run.runId];
+            if (state.sentRunHashes?.[run.runId] === hash)
+                onPlatform += 1;
+            else if (refusal !== undefined && refusal.payloadHash === hash)
+                refused.push({ runId: run.runId, reason: refusal.reason });
+            else
+                pending += 1;
+        }
+    }
+    return {
+        linked,
+        runs: runs.length,
+        onPlatform,
+        pending,
+        refused: refused.slice(0, MAX_NAMED_REFUSALS),
+        refusedMore: Math.max(0, refused.length - MAX_NAMED_REFUSALS),
+        ...(state.lastPushAt === undefined ? {} : { lastPushAt: state.lastPushAt }),
+        ...(state.lastError === undefined || 0 === state.lastError.length
+            ? {}
+            : { lastError: state.lastError }),
+    };
+}
+/** This project's summary, read from its `.reticle`. Never throws: an unreadable record is empty. */
+export function readSyncSummary(reticleRoot, linked) {
+    let runs = [];
+    try {
+        runs = diskSource(reticleRoot).runs();
+    }
+    catch {
+        runs = [];
+    }
+    return summarizeSync({ linked, runs, state: readCloudState(reticleRoot) });
+}
+/** One status for the whole project: the worst thing true of it. */
+export function overallStatus(summary) {
+    if (!summary.linked)
+        return SyncStatus.LOCAL_ONLY;
+    if (0 < summary.refused.length)
+        return SyncStatus.REFUSED;
+    if (0 < summary.pending || summary.lastError !== undefined)
+        return SyncStatus.PENDING;
+    return SyncStatus.ON_PLATFORM;
+}
+/** The summary in one sentence an agent can repeat to a person. */
+export function describeSync(summary, now) {
+    if (!summary.linked)
+        return `${String(summary.runs)} run(s) exist only on this machine; nothing is synced until the project is linked (npx @reticlehq/server connect).`;
+    const ago = summary.lastPushAt === undefined
+        ? 'nothing pushed yet'
+        : `last push ${String(Math.max(0, Math.round((now - summary.lastPushAt) / 1000)))}s ago`;
+    const parts = [`${String(summary.onPlatform)} of ${String(summary.runs)} run(s) on the platform`];
+    if (0 < summary.pending)
+        parts.push(`${String(summary.pending)} waiting for the next push`);
+    const named = summary.refused.map((r) => `${r.runId}: ${r.reason}`);
+    if (0 < named.length)
+        parts.push(`refused by the platform: ${named.join('; ')}${0 < summary.refusedMore ? ` (+${String(summary.refusedMore)} more)` : ''}`);
+    if (summary.lastError !== undefined)
+        parts.push(`the last push failed: ${summary.lastError}`);
+    return `${parts.join('; ')} (${ago}).`;
+}

package/dist/memory/recall/memory-tools.js

@@ -30,6 +30,8 @@ const ADVICE = {
     [MemoryUnavailable.NOT_LINKED]: 'this project is not linked to a Reticle workspace, so there is no shared memory to read. Run `npx @reticlehq/server login` in the project to link it.',
     [MemoryUnavailable.DISABLED]: 'this project is linked but memory sync is turned off in .reticle/cloud.json, so nothing is being shared. Enable `sync.memory` to use it.',
     [MemoryUnavailable.UNREACHABLE]: 'the workspace could not be reached, or refused the key. Nothing is wrong with this project — try again, or check the link with `reticle status`.',
+    [MemoryUnavailable.UNVERIFIED]: 'the server answered, but the answer could not be shown to be about THIS project, so none of it is being reported. This is not an empty corpus: do NOT conclude this project knows nothing. Check the link with `reticle status`, and retry once the workspace is reachable.',
+    [MemoryUnavailable.UNREADABLE]: 'the workspace answered about THIS project, but the body was a shape this build cannot read entries out of. Retrying will not change it — this is not an empty corpus and not a link problem. Check the workspace version, and that `reticle memory` from the same terminal returns a `{ projectId, entries }` body.',
 };
 export const MEMORY_TOOLS = [
     {

package/dist/memory/recall/project-memory.d.ts

@@ -7,6 +7,25 @@ export declare const MemoryUnavailable: {
     readonly DISABLED: "memory-sync-disabled";
     /** The server was reached and said no, or could not be reached at all. */
     readonly UNREACHABLE: "unreachable";
+    /**
+     * The server answered, and the answer could not be shown to be about THIS project: its envelope
+     * named another one, or named none at all.
+     *
+     * Its own reason rather than an empty list, because the two are opposite facts about the corpus.
+     * "This project knows nothing" is something an agent can act on; "we cannot tell whose knowledge
+     * this is" is something it must not, and an empty list reports the first while meaning the second.
+     */
+    readonly UNVERIFIED: "unverified";
+    /**
+     * The server answered about THIS project, and the body is a shape this build cannot read entries
+     * out of — no `entries` field, or one that is not a list.
+     *
+     * Apart from `UNREACHABLE` on purpose. That reason's advice is "try again, or check the link", and
+     * neither applies: the workspace WAS reached, its answer IS this project's, and the shape will be
+     * the same on the second attempt. Sending an agent to retry it costs a round trip and teaches it
+     * to distrust a link that is fine, which is what a reason is for.
+     */
+    readonly UNREADABLE: "unreadable";
 };
 export type MemoryUnavailable = (typeof MemoryUnavailable)[keyof typeof MemoryUnavailable];
 export interface KnownThing {

package/dist/memory/recall/project-memory.js

@@ -13,6 +13,7 @@
  */
 import { cloudFetch } from '../cloud/cloud-sync.js';
 import { resolveProjectCloud } from '../cloud/cloud-config.js';
+import { isReadableMemoryScope, memoryReadUrl, scopedMemoryEntries, scopeOfMemoryResponse, } from '../cloud/memory-scope.js';
 /** Named so a read from the tool surface is distinguishable from the CLI's and from replay's. */
 const MCP_AGENT_ID = 'reticle-mcp';
 /** Why a lookup returned nothing. Each one is a different thing for the agent to do next. */
@@ -23,6 +24,25 @@ export const MemoryUnavailable = {
     DISABLED: 'memory-sync-disabled',
     /** The server was reached and said no, or could not be reached at all. */
     UNREACHABLE: 'unreachable',
+    /**
+     * The server answered, and the answer could not be shown to be about THIS project: its envelope
+     * named another one, or named none at all.
+     *
+     * Its own reason rather than an empty list, because the two are opposite facts about the corpus.
+     * "This project knows nothing" is something an agent can act on; "we cannot tell whose knowledge
+     * this is" is something it must not, and an empty list reports the first while meaning the second.
+     */
+    UNVERIFIED: 'unverified',
+    /**
+     * The server answered about THIS project, and the body is a shape this build cannot read entries
+     * out of — no `entries` field, or one that is not a list.
+     *
+     * Apart from `UNREACHABLE` on purpose. That reason's advice is "try again, or check the link", and
+     * neither applies: the workspace WAS reached, its answer IS this project's, and the shape will be
+     * the same on the second attempt. Sending an agent to retry it costs a round trip and teaches it
+     * to distrust a link that is fine, which is what a reason is for.
+     */
+    UNREADABLE: 'unreadable',
 };
 /** Defensive: the wire is somebody else's server, so every field is checked before it is trusted. */
 const asKnown = (raw) => {
@@ -58,9 +78,15 @@ export async function readProjectMemory(fs, root, home, env, opts) {
         return { ok: false, reason: MemoryUnavailable.NOT_LINKED };
     if (!cloud.policy.memory)
         return { ok: false, reason: MemoryUnavailable.DISABLED };
-    const query = opts.subject === undefined ? '' : `?subject=${encodeURIComponent(opts.subject)}`;
+    // Scoped to the LINKED project, not to whatever the key happens to cover. A workspace can hold
+    // more than one repo, and a read that named no project could be answered with another one's
+    // established knowledge — indistinguishable from this project's, and acted on. See memory-scope.
+    const url = memoryReadUrl(cloud.config.url, {
+        projectId: cloud.projectId,
+        subject: opts.subject,
+    });
     try {
-        const res = await cloudFetch(`${cloud.config.url}/v1/memory${query}`, {
+        const res = await cloudFetch(url, {
             method: 'GET',
             headers: {
                 authorization: `Bearer ${cloud.config.apiKey}`,
@@ -75,10 +101,23 @@ export async function readProjectMemory(fs, root, home, env, opts) {
         // property yields the function, and every downstream field is undefined — a silent "the project
         // knows nothing" that is indistinguishable from the honest empty case. It cost a live drive to
         // find once already.
-        const body = (await res.json());
-        const entries = body?.entries;
-        if (!Array.isArray(entries))
-            return { ok: false, reason: MemoryUnavailable.UNREACHABLE };
+        const body = await res.json();
+        // The envelope first, and it decides everything. The platform names the project on the response
+        // and NOT on each entry, so an entry-level filter alone keeps a whole sibling workspace while
+        // looking like it did something — see `memory-scope.ts`. A response that names another project,
+        // or names none, is UNVERIFIED: not empty, and not this project's.
+        const entries = scopedMemoryEntries(body, cloud.projectId);
+        if (entries === undefined) {
+            return {
+                ok: false,
+                reason: isReadableMemoryScope(scopeOfMemoryResponse(body, cloud.projectId))
+                    ? MemoryUnavailable.UNREADABLE // scoped fine, but no readable `entries` — a shape we do not know
+                    : MemoryUnavailable.UNVERIFIED,
+            };
+        }
+        // The entry-level pass is redundant against the envelope check above and kept for a server that
+        // labels entries instead. `total` is counted AFTER it, so a truncated list still tells the truth
+        // about how many of THIS project's statements there were.
         const known = entries.map(asKnown).filter((k) => k !== null);
         return {
             ok: true,

package/dist/portal/bridge/bridge.d.ts

@@ -66,10 +66,11 @@ interface BridgeOptions {
      */
     server?: http.Server;
     /**
-     * The SDK-upgrade sentence to attach when a HELLO is skewed. Injected so the daemon can name
-     * this project's packages and package manager; tests that omit it get the no-project fallback.
+     * The SDK-upgrade sentence to attach when a HELLO is skewed, for the project that HELLO named.
+     * Injected so the daemon can name that project's packages and package manager; tests that omit
+     * it get the no-project fallback.
      */
-    sdkFix?: () => string;
+    sdkFix?: (projectId?: string) => string;
 }
 /**
  * The browser-facing half of the relay: a localhost WebSocket server. Each connection
@@ -109,7 +110,9 @@ export declare class Bridge {
      * Register a handler for the panel's harness switch. Optional for the same reason as the above: a
      * bridge built without one ignores the request rather than refusing it.
      */
-    attachHarnessRequest(handler: (enabled: boolean) => void): void;
+    attachHarnessRequest(handler: (enabled: boolean, session: Session) => void): void;
+    /** Register a handler for the panel's Sign in. Optional, like the above: without one it is ignored. */
+    attachSigninRequest(handler: () => void): void;
     /** Register a handler to run when a session connects. Additive — every handler runs. */
     attachSessionCreate(handler: (session: Session) => void): void;
     close(): Promise<void>;

package/dist/portal/bridge/bridge.js

@@ -11,7 +11,7 @@ import { tokensMatch } from './token-auth.js';
 import { pairingTokenSource } from './pairing-token.js';
 import { log } from '../../log.js';
 import { getSessionMetrics } from '../../telemetry/session-metrics.js';
-import { sessionReplacedReason } from '../session/facts/session-replaced.js';
+import { SESSION_PARKED_REASON, sessionReplacedReason, } from '../session/facts/session-replaced.js';
 import { describeSkew, sdkFix, SkewPair } from '../../command/version/version-skew.js';
 import { noteVersionSkew } from '../../command/version/version-nudge.js';
 import { protocolSkewReason } from './protocol-skew.js';
@@ -147,6 +147,10 @@ function harnessRequest(event) {
         return false;
     return undefined;
 }
+/** True when this event is the panel's Sign in. Pure boundary narrowing, like the above. */
+function isSigninRequest(event) {
+    return event.type === EventType.HUMAN_CONTROL && event.data['kind'] === HumanControlKind.SIGNIN;
+}
 /** True when this event is the panel's "sync now" button. Pure boundary narrowing, like the above. */
 function isSyncRequest(event) {
     return event.type === EventType.HUMAN_CONTROL && event.data['kind'] === HumanControlKind.SYNC;
@@ -273,6 +277,7 @@ export class Bridge {
     /** Wired by the daemon: push to the dashboard now, because somebody asked in the panel. */
     #onSyncRequest;
     #onHarnessRequest;
+    #onSigninRequest;
     constructor(options) {
         const host = options.host ?? LOOPBACK_HOST;
         if ((options.token?.length ?? 0) > TRANSPORT_LIMITS.MAX_TOKEN_LENGTH) {
@@ -543,6 +548,11 @@ export class Bridge {
                         socket.close(WS_CLOSE.AUTH_FAILED[0], reason);
                         return;
                     }
+                    // A window the agent detached stays detached across its own reloads. See SessionManager.park.
+                    if (this.sessions.isParked(parsed.sessionId)) {
+                        socket.close(1008, SESSION_PARKED_REASON);
+                        return;
+                    }
                     const existing = this.sessions.get(parsed.sessionId);
                     if (existing === undefined && this.sessions.count() >= this.#maxSessions) {
                         socket.close(...WS_CLOSE.SESSION_LIMIT);
@@ -608,6 +618,9 @@ export class Bridge {
                     // The daemon is the single judge of skew, and HELLO is where the page announces itself.
                     // Reported on the session (reticle_sessions) AND queued for the next tool result, because an
                     // agent driving a flow never calls reticle_sessions and would never learn.
+                    // Read only if the page IS skewed: the fix reads the project's package.json and lockfile,
+                    // and a compatible page (nearly every HELLO) should not pay for that on connect.
+                    const fixForThisProject = () => this.#sdkFix(parsed.projectId);
                     const skew = describeSkew({
                         what: 'the page',
                         version: parsed.sdkVersion,
@@ -618,7 +631,9 @@ export class Bridge {
                         ...(parsed.contractParts === undefined
                             ? {}
                             : { contractParts: parsed.contractParts }),
-                        fix: this.#sdkFix(),
+                        get fix() {
+                            return fixForThisProject();
+                        },
                     }, {
                         version: SERVER_VERSION,
                         contract: CONTRACT_FINGERPRINT,
@@ -690,7 +705,10 @@ export class Bridge {
                     // The switch is written through to the platform by the daemon, for the same reason: the
                     // Session has no cloud credential and should not grow one.
                     else if (harness !== undefined)
-                        this.#onHarnessRequest?.(harness);
+                        this.#onHarnessRequest?.(harness, session);
+                    // Signing in writes `~/.reticle`, which only the daemon may do; the panel only asks.
+                    else if (isSigninRequest(parsed.event))
+                        this.#onSigninRequest?.();
                     // Pass the raw frame's byte length so the buffer doesn't re-serialize every event for accounting.
                     else
                         session.pushEvent(parsed.event, Buffer.byteLength(text, 'utf8'));
@@ -833,6 +851,10 @@ export class Bridge {
     attachHarnessRequest(handler) {
         this.#onHarnessRequest = handler;
     }
+    /** Register a handler for the panel's Sign in. Optional, like the above: without one it is ignored. */
+    attachSigninRequest(handler) {
+        this.#onSigninRequest = handler;
+    }
     /** Register a handler to run when a session connects. Additive — every handler runs. */
     attachSessionCreate(handler) {
         this.#onSessionCreate.push(handler);

package/dist/portal/bridge/pairing-token.d.ts

@@ -33,6 +33,15 @@ export declare function pairingTokenSource(input: {
     explicit: boolean;
     env: NodeJS.ProcessEnv;
 }): 'explicit' | 'env:RETICLE_TOKEN' | 'env:RETICLE_PAIRING_TOKEN_DIR' | 'default';
+/**
+ * The pairing token this machine was told to use, or undefined when it was told nothing.
+ *
+ * `RETICLE_TOKEN` first, then the token file in `RETICLE_PAIRING_TOKEN_DIR`, the precedence
+ * `pairingTokenSource` names. A command that mints its own one-shot token for a hosted preview asks
+ * this first: in a container the app's plugin bakes the directory token in, and a fresh token made
+ * the daemon refuse the only app it was started to verify (#1251).
+ */
+export declare function configuredPairingToken(env: NodeJS.ProcessEnv, deps: PairingTokenDeps): Promise<string | undefined>;
 export declare function pairingTokenPath(dir: string): string;
 /** Production IO adapter: 0600 file + 0700 dir so only the owner can read the secret. */
 export declare function nodePairingTokenDeps(): PairingTokenDeps;

package/dist/portal/bridge/pairing-token.js

@@ -41,6 +41,23 @@ export function pairingTokenSource(input) {
         return `env:${PAIRING_TOKEN_DIR_ENV}`;
     return 'default';
 }
+/**
+ * The pairing token this machine was told to use, or undefined when it was told nothing.
+ *
+ * `RETICLE_TOKEN` first, then the token file in `RETICLE_PAIRING_TOKEN_DIR`, the precedence
+ * `pairingTokenSource` names. A command that mints its own one-shot token for a hosted preview asks
+ * this first: in a container the app's plugin bakes the directory token in, and a fresh token made
+ * the daemon refuse the only app it was started to verify (#1251).
+ */
+export async function configuredPairingToken(env, deps) {
+    const token = env[ReticleEnv.TOKEN]?.trim();
+    if (token !== undefined && 0 < token.length)
+        return token;
+    const dir = env[PAIRING_TOKEN_DIR_ENV];
+    if (dir === undefined || 0 === dir.length)
+        return undefined;
+    return readOrCreatePairingToken(dir, deps);
+}
 export function pairingTokenPath(dir) {
     return join(dir, ReticleDir.PAIRING_TOKEN_FILE);
 }

package/dist/portal/input/real-input.d.ts

@@ -11,7 +11,7 @@
  */
 import { type ScriptCoverage } from './js-coverage.js';
 import type { Browser, Page } from 'playwright';
-import { ActionType, DriveErrorCode } from '@reticlehq/core';
+import { ActionType, DriveErrorCode, InputMode, InputModeReason } from '@reticlehq/core';
 import { type MockRule } from './network-mock.js';
 import { type NetworkDetail } from './network-detail.js';
 /** Viewport CSS-px box as returned by the INSPECT command (getBoundingClientRect). */
@@ -21,28 +21,72 @@ export interface ElementBox {
     width: number;
     height: number;
 }
-/** Args forwarded from reticle_act (fill value, type text, drag drop-target box). */
-export interface RealInputArgs {
+/**
+ * Args forwarded from reticle_act (fill value, type text, press key, drag drop-target box).
+ *
+ * A `type`, not an `interface`: only the alias form gets an implicit index signature, so the core
+ * arg readers take it as a plain record without a cast at every call site.
+ */
+export type RealInputArgs = {
     value?: string;
     text?: string;
+    /** For press: the key name, e.g. Escape or Tab. `text` also carries it; `key` is the fallback. */
+    key?: string;
+    /** For press: modifier names (Meta/Control/Shift/Alt; aliases like `cmd` accepted). */
+    modifiers?: string[];
+    /**
+     * For press: several keys held down TOGETHER, pressed in order and released in reverse. Read but
+     * never forwarded — a chord with a non-modifier key has no `page.keyboard.press` spelling, so the
+     * caller routes such a press to the synthetic dispatcher before it reaches here.
+     */
+    keys?: string[];
+    /**
+     * For press: how long to keep the key down between keydown and keyup. The same argument the
+     * synthetic path has always honoured, so a hold-to-confirm key driven through the driver holds
+     * for exactly as long as one driven in the page.
+     */
+    holdMs?: number;
     /** For drag: the resolved box of the drop-target ref (toRef). */
     toBox?: ElementBox;
     steps?: number;
-}
-interface RealInputResult {
+};
+/** What a provider reports for one driven gesture. Exported so a fake can build it by name. */
+export interface RealInputResult {
     /** True if a native gesture was actually driven. */
     performed: boolean;
-    /** Center used, for diagnostics/tests. */
-    center: {
+    /** Center used, for diagnostics/tests. ABSENT for a key press: see `undriven`. */
+    center?: {
         cx: number;
         cy: number;
     };
+    /**
+     * Which path this result came from. `real` whenever a gesture was actually driven, so a caller
+     * reading it on a `performed: true` result learns nothing it did not already know — it is here
+     * for the `performed: false` case, where the caller is about to take the synthetic path and
+     * saying `real` would describe a gesture that never ran.
+     */
+    inputMode: InputMode;
+    /**
+     * How long the key was ACTUALLY held, for a real press that was asked to hold. Absent for every
+     * other gesture, and for a press with no `holdMs` — the same rule the synthetic path uses, where
+     * an absent `heldMs` means "this action does not hold" rather than "it held for no time".
+     *
+     * Measured rather than echoed back: `holdMs: 1200` against a 1200ms animation is a race by
+     * construction, and a throttled tab stretches the wait. A caller needs to tell "held 1200" from
+     * "held 1204", and can only do that with the achieved number.
+     */
+    heldMs?: number;
 }
 /** Options for a page screenshot — full-page scroll capture and/or a clip box. */
 export interface ScreenshotOpts {
     fullPage?: boolean;
     /** Restrict the capture to one element/region (viewport CSS px). */
     clip?: ElementBox;
+    /**
+     * A live picture, as a JPEG at this quality: what a person is watching, taken as it is. The
+     * baseline tweaks (hiding the HUD, stopping animations) would make their window flicker each second.
+     */
+    jpegQuality?: number;
 }
 /** The capability surface reticle_act depends on. A FAKE implementing this is injected in tests. */
 export interface RealInputProvider {
@@ -117,17 +161,40 @@ export declare function boxCenter(box: ElementBox): {
     cy: number;
 };
 /**
- * Which actions are driven by native pointer input. fill/type stay synthetic unless a
- * provider explicitly runs them.
+ * Which actions are driven by a native pointer. `press` is excluded on purpose — a key has no
+ * pointer, and widening this would change what every existing caller of it means.
  */
 export declare function isPointerAction(action: ActionType): boolean;
+/**
+ * The routing question `tryRealInput` asks: does this action have a real-input path at all? Wider
+ * than `isPointerAction` by `press`, which needs no coordinates.
+ */
+export declare function isRealInputAction(action: ActionType): boolean;
 type SleepFn = (ms: number) => Promise<void>;
 type ConnectFn = (url: string) => Promise<Browser>;
+/**
+ * The `press`es this module will NOT drive: a chord that only the in-page dispatcher can express.
+ *
+ * `args.keys` asks for several keys held down TOGETHER, pressed in order and released in reverse.
+ * That is not a `page.keyboard.press` chord — a non-modifier key cannot appear before the last `+`
+ * — and a real keyboard cannot aim a key at a named element. `args.code` is the third: the driver
+ * presses by KEY name and offers no way to send a physical `code` that disagrees with it, so
+ * `{ text: 'z', code: 'KeyY' }` would strike a different key than the one asked for. All three are
+ * routed to the synthetic path by the caller, which reports the reason rather than pretending a
+ * different gesture happened.
+ *
+ * Ordered by how specifically the caller asked: `keys` then `code` name the KEY, `ref` names only
+ * the target. Two can apply at once, and the earlier one is the more unusual request — the reason
+ * should name that, not the generic "you passed a ref".
+ */
+export declare function unspellablePressReason(ref: string, args: Record<string, unknown>): InputModeReason | undefined;
 /**
  * Shared gesture executor: drive a native gesture on an already-resolved Page. Used by both the
  * CDP-attached and the launched (drive) providers so the pointer logic lives in one place.
  */
-export declare function performGesture(page: Page, action: ActionType, box: ElementBox, args: RealInputArgs, sleep: SleepFn): Promise<RealInputResult>;
+export declare function performGesture(page: Page, action: ActionType, box: ElementBox, args: RealInputArgs, sleep: SleepFn, 
+/** Injected so a test can assert the achieved hold deterministically; defaults to the real clock. */
+now?: () => number): Promise<RealInputResult>;
 /**
  * Capture a PNG from a Playwright page. Shared by the CDP + launched providers so the
  * screenshot path lives in one place (mirrors performGesture). Returns the raw PNG bytes.
@@ -137,6 +204,8 @@ interface CdpProviderOptions {
     cdpUrl: string;
     /** Injected so the settle delay is deterministic in tests; defaults to a real Node timer. */
     sleep?: SleepFn;
+    /** Injected so a measured hold is deterministic in tests; defaults to the real clock. */
+    now?: () => number;
     /** Injected connector so unit tests can stub Playwright without import. */
     connect?: ConnectFn;
     /**
@@ -193,6 +262,8 @@ export interface LaunchedProviderOptions {
     headless: boolean;
     /** Injected so the settle delay is deterministic in tests; defaults to a real Node timer. */
     sleep?: SleepFn;
+    /** Injected so a measured hold is deterministic in tests; defaults to the real clock. */
+    now?: () => number;
     /** Injected launcher so unit tests can stub Playwright; defaults to dynamic import('playwright'). */
     launch?: LaunchFn;
     /** When set, re-invoke the page's reticle.connect with these after load (drive-a-hosted-preview). */