@trusty-squire/mcp 1.1.16-rc.4 → 1.1.16-rc.6

package/README.md

@@ -85,9 +85,9 @@ operator does not add a broad secret scanner or claim to defeat that page.
 npx @trusty-squire/mcp connect
 ```
 
-`connect` signs you in with Google or GitHub, detects your coding agent, and merges the `squire` MCP server into its existing configuration. On an enrolled machine, sign-in opens a tab in Trusty Squire's shared browser. When that browser is on the machine's own screen and you are running `connect` there, you finish sign-in in the window in front of you — no URL and no virtual display. Otherwise — the shared browser started without a screen and sits on a private Linux display, or you are running `connect` over SSH or a TTY with no screen of your own — the ceremony prints a single-use noVNC URL; open that URL on another device. The URL shows and controls the whole display that browser runs on until the ceremony ends: other sessions' tabs, and on a machine with its own screen, everything else on that screen. macOS and Windows draw their windows natively, so the shared browser's tab is on the screen in front of you there and nothing is exposed over noVNC. If the display cannot be shown, connect stops with an explanation instead of waiting indefinitely. On a first connect where no broker can serve, connect launches its own sign-in browser, using a visible desktop when one still answers or a login-scoped Xvfb + noVNC stack on headless Linux (including SSH/TTY sessions with an inherited virtual display, and a display that has stopped answering since startup).
+`connect` signs you in with Google or GitHub, detects your coding agent, and merges the `squire` MCP server into its existing configuration. Sign-in opens a tab in Trusty Squire's shared browser — the broker's browser, which is the only browser this product launches, on a first connect as much as on an enrolled machine. When that browser is on the machine's own screen and you are running `connect` there, you finish sign-in in the window in front of you — no URL and no virtual display. Otherwise — the shared browser started without a screen and sits on a private Linux display, or you are running `connect` over SSH or a TTY with no screen of your own — the ceremony prints a single-use noVNC URL; open that URL on another device. The URL shows and controls the whole display that browser runs on until the ceremony ends: other sessions' tabs, and on a machine with its own screen, everything else on that screen. macOS and Windows draw their windows natively, so the shared browser's tab is on the screen in front of you there and nothing is exposed over noVNC. If the display cannot be shown, connect stops with an explanation instead of waiting indefinitely. Nothing falls back to a browser of its own.
 
-Ceremony completion, timeout, failure, or interruption tears down its quick tunnel and local exposure helpers. The shared browser and its display remain with the broker; a self-launched ceremony also closes its own browser and display. Operators may set both `TS_LOGIN_PUBLIC_HOSTNAME` and `TS_LOGIN_LOCAL_PORT` to reuse an externally managed named tunnel, which Trusty Squire never creates or stops. If that fixed local port is busy, login reports it and uses a one-off quick tunnel instead. Restart the agent and ask for the finished website outcome. Trusty Squire is free to start.
+Ceremony completion, timeout, failure, or interruption tears down its quick tunnel and local exposure helpers. Those helpers also hold a bound of their own — the sign-in link's lifetime plus a short grace, counted from the moment they are stood up — so a `connect` that is abandoned, wedged, or never waits still tears the display down and exits non-zero instead of leaving a tunnel published. The shared browser and its display remain with the broker. Operators may set both `TS_LOGIN_PUBLIC_HOSTNAME` and `TS_LOGIN_LOCAL_PORT` to reuse an externally managed named tunnel, which Trusty Squire never creates or stops. If that fixed local port is busy, login reports it and uses a one-off quick tunnel instead. Restart the agent and ask for the finished website outcome. Trusty Squire is free to start.
 
 `connect` is also the only way to sign in again: `--force-relogin` switches the bound account and `--force-relogin=google` or `--force-relogin=github` refreshes one provider session. It re-checks provider sessions before reporting success; when the shared browser keeps the profile busy, that check uses committed cookies, which can outlive a server-side session. Use `--force-relogin` to refresh a stale session. The detailed [provider-probe and ceremony contract](docs/browser-broker.md) describes completion and failure handling.
 
@@ -127,7 +127,7 @@ Each report carries seven fields:
 - `browser_location` — where the ceremony browser actually opened, reported by the code that placed it: `{kind:"host_screen",display?}` (the screen you are at), `{kind:"virtual",url}` (a display nobody is sitting at — `url` is the noVNC address that reaches it, reported on a non-terminal line the moment the browser lands there, while the tunnel is up), `{kind:"unreachable",reason}` (nothing here could be shown the page — also the answer when a ceremony ran but no path ever reported a placement, with `reason` naming the failure), `{kind:"none"}` (no browser was opened), or `{kind:"unknown",reason}` (a browser opened that Squire did not place — `--skip-browser` hands the link to the machine's default browser). Squire decides this; callers do not detect screens.
 - `reason` — only what the five fields above cannot say: `provider_session_missing`, `requested_provider_missing`, `account_mismatch`, `profile_unverifiable`, `install_expired`, `cached_cookie_evidence`, `run_failed`. `null` otherwise.
 
-Connect never waits longer than the sign-in link lives — the wait is the link's lifetime counted from the moment connect received it, so a skewed machine clock cannot shorten or overrun it. A `sign_in_url` it hands back is still open; a wait that reached that deadline, or a link the server reported lapsed, is `no-browser` with `reason: "install_expired"` and no URL at all.
+Connect never waits longer than the sign-in link lives — the wait is the link's lifetime counted from the moment connect received it, so a skewed machine clock cannot shorten or overrun it. A `sign_in_url` it hands back is still open; a wait that reached that deadline, or a link the server reported lapsed, is `no-browser` with `reason: "install_expired"` and no URL at all. A ceremony display that outlives its own bound answers the same way, on a terminal line written before connect exits — so a run that wedged before it ever reached that wait still ends the machine channel.
 
 Supported targets: `claude-code`, `cursor`, `codex`, `opencode`, `goose`, `cline`, `continue`, and `hermes`.
 
@@ -190,6 +190,12 @@ grant; host scoping, auditing, and revocation still apply. When a grant reaches
 an explicit hourly limit, the proxy returns `429 rate_limited` with
 `scope: "grant"`, `Retry-After`, and window/reset metadata.
 
+The proxy passes the provider's response through as it arrives and forwards the
+upstream response headers (cookies, hop-by-hop headers, and the upstream
+content-length removed), so a streaming completion — `stream: true`,
+`text/event-stream` — reaches the app event by event rather than in one block
+once generation has finished. The body is not buffered and carries no size cap.
+
 The result contains a host-scoped egress `base_url` and a `token`, not the Clerk secret key. The token is returned once through the MCP result and remains valid until revoked. That means the scoped grant token can enter agent context; it is not the provider key. Move it directly into backend-only deployment secret storage, never browser code, logs, or source control. If you need zero grant-token exposure to the model, use `use_credential` for agent-initiated requests instead. Trusty Squire removes the grant authorization at the boundary and injects the vaulted provider credential into the upstream request.
 
 ## Security and threat model

package/dist/bot/act/act.d.ts

@@ -5,6 +5,19 @@ import { type ObserveDetail } from "../observe/observe.js";
 import { type CompactV2TargetAuthorization } from "./targets.js";
 import type { Observation, ProvisionAction } from "../provision-session.js";
 import type { Session } from "../session/model.js";
+export type ActExecutorOptions = {
+    drive?: boolean;
+};
+export type DriveActResult = {
+    kind: "ok";
+    combobox: boolean;
+    needsUser?: NonNullable<Observation["needs_user"]>;
+} | {
+    kind: "stale";
+    reason: string;
+} | {
+    kind: "unsupported";
+};
 export declare function runSerializedGoogleIdentityOperation<T>(session: Session, operation: (browser: BrowserController) => Promise<T>, options?: {
     deadline?: OAuthActionDeadline;
 }): Promise<{
@@ -17,9 +30,11 @@ export interface InternalActResult {
     outcome: {
         selectedOption?: string;
     };
+    combobox?: boolean;
 }
-export declare function actInternally(sessionId: string, action: ProvisionAction, detail?: ObserveDetail, compactV2Authorization?: CompactV2TargetAuthorization, operationPage?: Page): Promise<InternalActResult>;
+export declare function actInternally(sessionId: string, action: ProvisionAction, detail?: ObserveDetail, compactV2Authorization?: CompactV2TargetAuthorization, operationPage?: Page, options?: ActExecutorOptions): Promise<InternalActResult>;
 export declare function act(sessionId: string, action: ProvisionAction, detail?: ObserveDetail, outputFormat?: "compact" | "full", compactMapEmitted?: boolean): Promise<Observation>;
+export declare function dispatchDriveAct(sessionId: string, action: ProvisionAction): Promise<DriveActResult>;
 export declare function compactV2SelectionFailureReason(error: unknown): string;
 export declare function settleAfterDriveAction(page?: Page, combobox?: boolean): Promise<void>;
 export declare function settleAfterStateChange(browser: BrowserController, page?: Page, options?: {

package/dist/bot/act/act.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../../src/bot/act/act.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAGL,KAAK,iBAAiB,EAEvB,MAAM,eAAe,CAAC;AACvB,OAAO,EAWL,KAAK,mBAAmB,EAIzB,MAAM,mBAAmB,CAAC;AAY3B,OAAO,EAOL,KAAK,aAAa,EAMnB,MAAM,uBAAuB,CAAC;AAU/B,OAAO,EAiBL,KAAK,4BAA4B,EAClC,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AA4EnD,wBAAsB,oCAAoC,CAAC,CAAC,EAC1D,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,CAAC,CAAC,EACrD,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,mBAAmB,CAAA;CAAO,GAC/C,OAAO,CAAC;IAAE,OAAO,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC,CAOpD;AA+GD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,WAAW,CAAC;IACzB,aAAa,CAAC,EAAE,IAAI,CAAC;IACrB,OAAO,EAAE;QACP,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAqED,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,EACvB,MAAM,GAAE,aAAyB,EACjC,sBAAsB,CAAC,EAAE,4BAA4B,EACrD,aAAa,CAAC,EAAE,IAAI,GACnB,OAAO,CAAC,iBAAiB,CAAC,CAgD5B;AAED,wBAAsB,GAAG,CACvB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,EACvB,MAAM,GAAE,aAAyB,EACjC,YAAY,GAAE,SAAS,GAAG,MAAe,EACzC,iBAAiB,UAAO,GACvB,OAAO,CAAC,WAAW,CAAC,CAwGtB;AAsjBD,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtE;AA+FD,wBAAsB,sBAAsB,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCzF;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,iBAAiB,EAC1B,IAAI,CAAC,EAAE,IAAI,EACX,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAChD,OAAO,CAAC,IAAI,CAAC,CAUf"}
+{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../../src/bot/act/act.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAS,IAAI,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAIL,KAAK,iBAAiB,EAEvB,MAAM,eAAe,CAAC;AACvB,OAAO,EAWL,KAAK,mBAAmB,EAIzB,MAAM,mBAAmB,CAAC;AAY3B,OAAO,EAOL,KAAK,aAAa,EAMnB,MAAM,uBAAuB,CAAC;AAU/B,OAAO,EAiBL,KAAK,4BAA4B,EAClC,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAuBnD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAIF,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC,CAAA;CAAE,GACrF;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AA4E5B,wBAAsB,oCAAoC,CAAC,CAAC,EAC1D,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,CAAC,CAAC,EACrD,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,mBAAmB,CAAA;CAAO,GAC/C,OAAO,CAAC;IAAE,OAAO,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC,CAOpD;AAqHD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,WAAW,CAAC;IACzB,aAAa,CAAC,EAAE,IAAI,CAAC;IACrB,OAAO,EAAE;QACP,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAqED,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,EACvB,MAAM,GAAE,aAAyB,EACjC,sBAAsB,CAAC,EAAE,4BAA4B,EACrD,aAAa,CAAC,EAAE,IAAI,EACpB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,iBAAiB,CAAC,CA4D5B;AAED,wBAAsB,GAAG,CACvB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,EACvB,MAAM,GAAE,aAAyB,EACjC,YAAY,GAAE,SAAS,GAAG,MAAe,EACzC,iBAAiB,UAAO,GACvB,OAAO,CAAC,WAAW,CAAC,CAwGtB;AAyxBD,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,cAAc,CAAC,CAyEzB;AAED,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtE;AA+FD,wBAAsB,sBAAsB,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCzF;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,iBAAiB,EAC1B,IAAI,CAAC,EAAE,IAAI,EACX,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAChD,OAAO,CAAC,IAAI,CAAC,CAUf"}

package/dist/bot/act/act.js

@@ -1,4 +1,4 @@
-import { BrowserClickDispatchError, clickDispatchStatusForError, } from "../browser.js";
+import { BrowserClickDispatchError, DRIVE_DISPATCH_PACING, clickDispatchStatusForError, } from "../browser.js";
 import { loginWithOAuth, oauthActionDeadline, oauthActionRemainingMs, oauthAutomatedActionTimeoutMs, oauthHumanHandoffTimeoutMs, oauthLoginLeaseCooldownMs, resetOAuthActionDeadline, settleAfterOAuth, withOAuthActionLease, withinOAuthActionDeadline, OAuthAwaitingHumanError, OAuthFailedError, OAuthOnboardingRequiredError, } from "../oauth-login.js";
 import { compactV2AuditUrl, safeStageV2 } from "../compact-observation-v2.js";
 import { ProvenPreDispatchMutationError } from "../mutation-dispatch-evidence.js";
@@ -11,6 +11,10 @@ import { substituteCardTokens } from "../card-secret-tokens.js";
 import { clickScreenshot, ScreenshotClickError } from "../screenshot-click.js";
 import { composeOperatorSignals, currentOperatorRequestSignal, operatorMutationDispatchPhase, } from "../request-cancellation.js";
 import { AmbiguousProvisionTargetError, compactV2AuthorizationForTarget, frameTargetFor, isRequiredShippingAddressLine1, parseLocatorTarget, preparedOAuthLoginTarget, resolveAuthorizedCompactV2Target, resolveTarget, staleTargetError, TargetStaleError, throwCompactV2StaleRef, CompactV2ActionFailureError, CompactV2StaleRefError, CompactV2UnresolvedLabelError, ProvisionTargetMissingError, ProvisionTargetNotAllowedError, } from "./targets.js";
+import { resolveIdentityScope, resolveLiveControlIdentity, } from "./identity.js";
+import { evaluateBound } from "../drive-evaluate.js";
+import { clickCrossOriginFrameTarget, commitDriveListOption, selectDriveOption, overlayOptionLabels, waitForOpenedOverlay, waitForOverlayOptionsToChange, } from "../drive-act.js";
+const DRIVE_DISPATCH = { drive: true };
 async function withOAuthActionBoundary(session, provider, run, outputFormat) {
     if (provider === "google") {
         const gate = await googleSessionGateForSession(session.id);
@@ -73,10 +77,15 @@ export async function runSerializedGoogleIdentityOperation(session, operation, o
         : await withinOAuthActionDeadline(operation(browser), options.deadline);
     return { browser, result };
 }
-async function runSerializedOAuthBoundary(session, authorizedElement, authorizedElements, provider, deadline, compactAuthorization, bindPreparedTargetAtDispatch = false) {
-    const authorizedRef = provisionElementRefs(authorizedElements).get(authorizedElement);
-    if (authorizedRef === undefined) {
-        throw new Error("OAuth action target was not present in the authorized action map");
+async function runSerializedOAuthBoundary(session, authorizedElement, authorizedElements, provider, deadline, compactAuthorization, bindPreparedTargetAtDispatch = false, driveResolved = false) {
+    // A drive ref is authorized by its own in-page identity record (the caller
+    // already re-proved the node is still the observed control), not by the
+    // tools' action map. Only the tools path needs the map-membership proof.
+    if (!driveResolved) {
+        const authorizedRef = provisionElementRefs(authorizedElements).get(authorizedElement);
+        if (authorizedRef === undefined) {
+            throw new Error("OAuth action target was not present in the authorized action map");
+        }
     }
     const expectedGoogleAccountEmail = session.userEmail ?? undefined;
     const completed = await runSerializedGoogleIdentityOperation(session, async (browser) => {
@@ -206,13 +215,18 @@ function oauthOnboardingRequiredObservation(session, error) {
     };
     return compactV2PublicObservation(session, { stage: "form", guidance, oauth, url });
 }
-export async function actInternally(sessionId, action, detail = "compact", compactV2Authorization, operationPage) {
+export async function actInternally(sessionId, action, detail = "compact", compactV2Authorization, operationPage, options) {
     const session = sessionForCall(sessionId);
     const capturedOperationPage = operationPage ?? (session === undefined ? undefined : operationPageForSession(session));
     const oauthProvider = action.kind === "oauth_login" || action.kind === "oauth_click" ? action.provider : undefined;
     try {
         const execute = async (deadline) => {
-            const run = async () => await executeAct(sessionId, action, detail, true, compactV2Authorization, deadline, capturedOperationPage, false);
+            const run = async () => {
+                const act = async () => await executeAct(sessionId, action, detail, true, compactV2Authorization, deadline, capturedOperationPage, false, undefined, "full", true, options);
+                return session === undefined || options?.drive !== true
+                    ? await act()
+                    : await session.browser.withDispatchPacing(DRIVE_DISPATCH_PACING, act);
+            };
             return (action.kind === "click" ||
                 action.kind === "js_click" ||
                 action.kind === "oauth_login" ||
@@ -240,7 +254,7 @@ export async function actInternally(sessionId, action, detail = "compact", compa
             return { observation: oauthOnboardingRequiredObservation(session, error), outcome: {} };
         }
         if (session?.compactV2Active === true && !(error instanceof ProvisionTargetMissingError)) {
-            throw new CompactV2ActionFailureError(compactV2ActionFailureReason(error, action.kind));
+            throw new CompactV2ActionFailureError(compactV2ActionFailureReason(error, action.kind), clickDispatchStatusForError(error));
         }
         throw error;
     }
@@ -341,10 +355,90 @@ function actDriverTarget(el) {
         return { kind: "frame", frame, selector: el.selector };
     return { kind: "selector", selector: el.selector };
 }
+function actsThroughOverlay(el, picker) {
+    if (picker)
+        return true;
+    const role = (el.role ?? "").toLowerCase();
+    const type = (el.type ?? "").toLowerCase();
+    return (role === "combobox" ||
+        role === "searchbox" ||
+        type === "search" ||
+        type === "date" ||
+        type === "datetime-local" ||
+        type === "month");
+}
+function submitsOnEnter(el, ariaLabel) {
+    const role = (el.role ?? "").toLowerCase();
+    const type = (el.type ?? "").toLowerCase();
+    return (role === "searchbox" ||
+        type === "search" ||
+        el.name === "q" ||
+        /search/i.test(`${ariaLabel} ${el.placeholder ?? ""}`));
+}
+function scopeForElement(page, el) {
+    if (el.framePath === undefined || el.framePath === null || el.framePath.length === 0)
+        return page;
+    let frame = page.mainFrame();
+    for (const part of el.framePath.split("/")) {
+        const child = frame.childFrames()[Number(part)];
+        if (child === undefined)
+            return page;
+        frame = child;
+    }
+    return frame;
+}
+// The occlusion guard the drive used to carry in its own dispatch: a cookie
+// banner or sticky footer over the target swallows the click while the page
+// still reports a dispatch, so the caller records a step that never landed.
+// Absent a box (still loading) it says nothing and the actionability waits rule.
+async function clickTargetOccluded(scope, selector) {
+    return await evaluateBound(scope, (sel) => {
+        const element = document.querySelector(sel);
+        if (element === null)
+            return false;
+        // The snapshot keeps offscreen fillables so the model can name them, and
+        // the dispatch scrolls before clicking — so measure where the click will
+        // actually land, not where the element sits right now. "instant" is
+        // load-bearing: a page with scroll-behavior:smooth would animate and the
+        // rect below would still be the pre-scroll one.
+        const before = element.getBoundingClientRect();
+        const inView = before.width > 0 &&
+            before.height > 0 &&
+            before.bottom > 0 &&
+            before.top < innerHeight &&
+            before.right > 0 &&
+            before.left < innerWidth;
+        if (!inView) {
+            element.scrollIntoView({ block: "center", inline: "nearest", behavior: "instant" });
+        }
+        const rect = element.getBoundingClientRect();
+        if (rect.width <= 0 || rect.height <= 0)
+            return false;
+        const hit = document.elementFromPoint(rect.x + rect.width / 2, rect.y + rect.height / 2);
+        return hit !== null && hit !== element && !element.contains(hit) && !hit.contains(element);
+    }, selector).catch(() => false);
+}
 // Re-resolve against FRESH elements — never trust a stale index. Shared by the
 // type_secret / select / click-group ref paths; `internalLabel`/`noMatchPrefix`
 // keep each caller's error wording, `withVisibleCandidates` its candidate list.
 async function resolveFreshActTarget(session, browser, compactV2ActionPage, compactV2Authorization, resolutionTarget, internalAccess, internalLabel, noMatchPrefix, actionTarget, withVisibleCandidates) {
+    const driveIdentity = session.drive?.identities?.get(resolutionTarget);
+    const livePage = compactV2ActionPage ?? browser.page;
+    if (driveIdentity !== undefined && livePage !== null) {
+        const live = await resolveLiveControlIdentity(livePage, resolutionTarget, driveIdentity);
+        if (live !== null) {
+            return { el: live, fresh: session.lastElements, driveIdentity };
+        }
+        if (session.compactV2Active) {
+            if (!internalAccess)
+                throwCompactV2StaleRef();
+            throw new CompactV2StaleRefError("stale_ref");
+        }
+        const stale = staleTargetError(session, actionTarget, session.lastElements);
+        if (stale !== null)
+            throw stale;
+        throw new CompactV2StaleRefError("stale_ref");
+    }
     const fresh = (await browser.extractBrowserUseObservation(compactV2ActionPage)).elements;
     retainSessionElements(session, fresh);
     // resolveTarget recomputes identities (incl. volatile positional-group
@@ -354,7 +448,7 @@ async function resolveFreshActTarget(session, browser, compactV2ActionPage, comp
         ? resolveTarget(fresh, resolutionTarget)
         : resolveAuthorizedCompactV2Target(session, fresh, compactV2Authorization);
     if (el !== null)
-        return { el, fresh };
+        return { el, fresh, driveIdentity: undefined };
     if (session.compactV2Active) {
         if (!internalAccess)
             throwCompactV2StaleRef();
@@ -373,15 +467,18 @@ async function resolveFreshActTarget(session, browser, compactV2ActionPage, comp
         : "";
     throw new Error(`${prefix}no element matched target "${actionTarget}".${visible}`);
 }
-async function executeAct(sessionId, action, detail, internalAccess, internalAuthorization, oauthDeadline, operationPage, preparedOAuthDispatch = false, onScreenshotDispatched, outputFormat = "full", compactMapEmitted = true) {
+async function executeAct(sessionId, action, detail, internalAccess, internalAuthorization, oauthDeadline, operationPage, preparedOAuthDispatch = false, onScreenshotDispatched, outputFormat = "full", compactMapEmitted = true, options) {
     const session = sessionForCall(sessionId);
     if (session === undefined)
         throw new Error(`unknown provision session ${sessionId}`);
     let browser = session.browser;
     const compactV2ActionPage = operationPage ?? operationPageForSession(session);
     const driveSettle = session.drive !== null && action.kind !== "oauth_login" && action.kind !== "oauth_click";
+    const skipToolSettle = options?.drive === true;
     let settleMs = 0;
     const settle = async (combobox = false) => {
+        if (skipToolSettle)
+            return;
         const started = Date.now();
         await settleAfterStateChange(browser, compactV2ActionPage, {
             drive: driveSettle,
@@ -390,6 +487,7 @@ async function executeAct(sessionId, action, detail, internalAccess, internalAut
         settleMs += Date.now() - started;
     };
     const actStarted = Date.now();
+    let actedCombobox = false;
     let actionPageAfter = compactV2ActionPage;
     let completedAction = action;
     let resolutionTarget;
@@ -529,7 +627,10 @@ async function executeAct(sessionId, action, detail, internalAccess, internalAut
             }
             case "select": {
                 const el = (await resolveFreshActTarget(session, browser, compactV2ActionPage, compactV2Authorization, resolutionTarget, internalAccess, "select", "select", action.target, true)).el;
-                const committedText = await browser.select(actDriverTarget(el), action.text, compactV2ActionPage);
+                const driveSelectPage = compactV2ActionPage ?? browser.page;
+                const committedText = options?.drive === true && driveSelectPage !== null && driveSelectPage !== undefined
+                    ? await selectDriveOptionOrRefuse(scopeForElement(driveSelectPage, el), el.selector, action.text ?? "")
+                    : await browser.select(actDriverTarget(el), action.text, compactV2ActionPage);
                 session.committedSelectValues.set(compactV2CommittedSelectKey(session, el.selector), compactV2CommittedSelectValue(session, committedText));
                 completedAction = { ...action, text: committedText };
                 await settle();
@@ -629,18 +730,79 @@ async function executeAct(sessionId, action, detail, internalAccess, internalAut
                     break;
                 }
                 // Re-resolve against FRESH elements every act — never trust a stale index.
-                const { el, fresh } = await resolveFreshActTarget(session, browser, compactV2ActionPage, compactV2Authorization, resolutionTarget, internalAccess, action.kind, "", action.target, true);
+                const { el, fresh, driveIdentity } = await resolveFreshActTarget(session, browser, compactV2ActionPage, compactV2Authorization, resolutionTarget, internalAccess, action.kind, "", action.target, true);
+                actedCombobox = actsThroughOverlay(el, driveIdentity?.picker === true);
+                const ariaLabelAttribute = driveIdentity === undefined ? (el.ariaLabel ?? "") : (driveIdentity.ariaLabel ?? "");
                 // Preserve frame identity (origin + path) for the frame-scoped fill.
                 if (action.kind === "click" || action.kind === "js_click") {
+                    const clickPage = compactV2ActionPage ?? browser.page;
+                    // Only the drive's extra dispatch arms consume a frame scope; the
+                    // tools reach a frame through actDriverTarget's frame target, so
+                    // walking the positional frame path for them would be dead work.
+                    const clickScope = options?.drive !== true || clickPage === null || clickPage === undefined
+                        ? undefined
+                        : scopeForElement(clickPage, el);
+                    if (action.kind === "click" &&
+                        clickScope !== undefined &&
+                        (await clickTargetOccluded(clickScope, el.selector))) {
+                        throw new BrowserClickDispatchError("not_dispatched", "click target is occluded by an overlay");
+                    }
+                    // One adoption arm/grace around whichever dispatch runs: an option row
+                    // or a cross-origin coordinate click can open a target=_blank tab
+                    // just as an ordinary click can, and paying the grace per candidate
+                    // would charge every click for the branches that declined.
+                    const commitsListOption = action.kind === "click" &&
+                        clickPage !== null &&
+                        clickPage !== undefined &&
+                        clickScope !== undefined;
+                    const crossOriginScope = action.kind === "click" && clickScope !== undefined && "parentFrame" in clickScope
+                        ? clickScope
+                        : undefined;
                     actionPageAfter =
                         (await adoptTabOpenedByClick(session, browser, async () => {
+                            if (commitsListOption &&
+                                clickPage !== null &&
+                                clickPage !== undefined &&
+                                clickScope !== undefined &&
+                                (await commitDriveListOption(clickPage, clickScope, el.selector))) {
+                                return;
+                            }
+                            if (crossOriginScope !== undefined &&
+                                clickPage !== null &&
+                                clickPage !== undefined &&
+                                (await clickCrossOriginFrameTarget(clickPage, crossOriginScope, el.selector))) {
+                                return;
+                            }
                             await actClick({ ...actDriverTarget(el), method: action.kind });
                         })) ?? actionPageAfter;
                 }
                 else if (action.kind === "type") {
                     clearCommittedSelectValue(session, el.selector);
                     const actTarget = actDriverTarget(el);
-                    await actType(actTarget, typedText, false);
+                    if (options?.drive === true && actedCombobox && compactV2ActionPage !== undefined) {
+                        // The click may remount the field into an overlay that takes focus,
+                        // so the text goes to whatever is focused — after an explicit
+                        // select-all, because insertText alone APPENDS to a committed value.
+                        // The suggestion baseline is read AFTER the overlay opens; reading
+                        // it before would make the refresh wait return on the stale rows.
+                        await actClick({ ...actTarget, method: "click" });
+                        await waitForOpenedOverlay(compactV2ActionPage).catch(() => undefined);
+                        const overlayBefore = await overlayOptionLabels(compactV2ActionPage);
+                        await compactV2ActionPage.keyboard.press("ControlOrMeta+a");
+                        await compactV2ActionPage.keyboard.insertText(typedText ?? "");
+                        await waitForOverlayOptionsToChange(compactV2ActionPage, overlayBefore);
+                        if (submitsOnEnter(el, ariaLabelAttribute)) {
+                            await compactV2ActionPage.keyboard.press("Enter").catch(() => undefined);
+                        }
+                    }
+                    else {
+                        await actType(actTarget, typedText, false);
+                        if (options?.drive === true && submitsOnEnter(el, ariaLabelAttribute)) {
+                            await (compactV2ActionPage ?? browser.page)?.keyboard
+                                .press("Enter")
+                                .catch(() => undefined);
+                        }
+                    }
                     // #635 fix (not a gate on typing): Shopify only enables delivery-rate
                     // selection after the required address line is committed by
                     // blur/change, not merely after the raw keystrokes land.
@@ -690,24 +852,48 @@ async function executeAct(sessionId, action, detail, internalAccess, internalAut
                 }
                 // Atomic OAuth deliberately accepts only the observed stable ref. A raw
                 // locator would lose the same stale-reference guarantees as every other
-                // action before the provider transition begins.
-                const fresh = (await browser.extractBrowserUseObservation(compactV2ActionPage)).elements;
-                retainSessionElements(session, fresh);
-                const el = compactV2Authorization === undefined
-                    ? resolveTarget(fresh, resolutionTarget)
-                    : resolveAuthorizedCompactV2Target(session, fresh, compactV2Authorization);
-                if (el === null) {
-                    if (session.compactV2Active) {
-                        if (!internalAccess)
-                            throwCompactV2StaleRef();
+                // action before the provider transition begins. Resolve it by the
+                // identity it was OBSERVED under: a drive ref carries the drive's own
+                // record, a tools ref the tools' authorization/fresh inventory. A
+                // drive session never populates the tools' compact-v2 index, so mixing
+                // the two namespaces is what lost the handoff target.
+                const driveResolved = internalAccess && session.drive?.identities?.get(resolutionTarget) !== undefined;
+                let fresh;
+                let el;
+                if (driveResolved) {
+                    const livePage = compactV2ActionPage ?? browser.page;
+                    const identity = session.drive.identities.get(resolutionTarget);
+                    fresh = session.lastElements;
+                    el =
+                        livePage === null
+                            ? null
+                            : await resolveLiveControlIdentity(livePage, resolutionTarget, identity);
+                    if (el === null) {
+                        if (session.compactV2Active)
+                            throw new CompactV2StaleRefError("stale_ref");
                         throw new Error("oauth_login: internal live target changed");
                     }
-                    throw new Error(`oauth_login: no element matched target "${action.target}". Re-observe and use the OAuth control ref.`);
+                }
+                else {
+                    fresh = (await browser.extractBrowserUseObservation(compactV2ActionPage)).elements;
+                    retainSessionElements(session, fresh);
+                    el =
+                        compactV2Authorization === undefined
+                            ? resolveTarget(fresh, resolutionTarget)
+                            : resolveAuthorizedCompactV2Target(session, fresh, compactV2Authorization);
+                    if (el === null) {
+                        if (session.compactV2Active) {
+                            if (!internalAccess)
+                                throwCompactV2StaleRef();
+                            throw new Error("oauth_login: internal live target changed");
+                        }
+                        throw new Error(`oauth_login: no element matched target "${action.target}". Re-observe and use the OAuth control ref.`);
+                    }
                 }
                 if (oauthDeadline === undefined) {
                     throw new Error("OAuth action deadline was not established");
                 }
-                browser = await runSerializedOAuthBoundary(session, el, fresh, action.provider, oauthDeadline, compactV2Authorization, preparedOAuthDispatch);
+                browser = await runSerializedOAuthBoundary(session, el, driveResolved ? [el] : fresh, action.provider, oauthDeadline, compactV2Authorization, preparedOAuthDispatch, driveResolved);
                 const completedPage = browser.completedOAuthPage() ?? undefined;
                 rememberOAuthCompletionSourcePage(session, completedPage);
                 actionPageAfter = completedPage ?? actionPageAfter;
@@ -755,6 +941,7 @@ async function executeAct(sessionId, action, detail, internalAccess, internalAut
     if (session.drive !== null) {
         const observeMs = Date.now() - observeStarted;
         session.drive.lastActProfile = {
+            ...session.drive.lastActProfile,
             act_ms: Math.max(0, Date.now() - actStarted - settleMs - observeMs),
             settle_ms: settleMs,
             observe_ms: observeMs,
@@ -782,8 +969,104 @@ async function executeAct(sessionId, action, detail, internalAccess, internalAut
         outcome: {
             ...(completedAction.kind === "select" ? { selectedOption: completedAction.text } : {}),
         },
+        combobox: actedCombobox,
     };
 }
+async function selectDriveOptionOrRefuse(scope, selector, text) {
+    const { outcome, committed } = await selectDriveOption(scope, selector, text);
+    if (outcome === "ok")
+        return committed;
+    if (outcome === "missing")
+        throw new CompactV2StaleRefError("stale_ref");
+    throw new CompactV2ActionFailureError(outcome);
+}
+async function guardDriveOauthTarget(sessionId, target) {
+    const session = sessionForCall(sessionId);
+    const identity = session?.drive?.identities?.get(target);
+    const page = session?.browser.page ?? null;
+    if (session === undefined || identity === undefined || page === null) {
+        // No drive identity record: this target came from a fallback observation,
+        // so it is the tools' to resolve, not the drive's to dispatch.
+        return { kind: "unsupported" };
+    }
+    const scope = await resolveIdentityScope(page, target, identity);
+    if (scope === null)
+        return { kind: "stale", reason: "stale_ref" };
+    if (await clickTargetOccluded(scope, identity.selector)) {
+        return { kind: "stale", reason: "occluded" };
+    }
+    // Clean and still the control the drive observed: DISPATCH it. An OAuth
+    // handoff is an ordinary action; refusing it here and falling through to the
+    // tools path is what let a drive ref lose its target to the tools' index.
+    return { kind: "ok", combobox: false };
+}
+export async function dispatchDriveAct(sessionId, action) {
+    // "unsupported" means the shared executor has no drive verb for this action
+    // and the caller should fall back to the tools path. A DISPATCH failure is a
+    // different thing — the act did not land on the control, which is stale.
+    if (action.kind !== "click" &&
+        action.kind !== "type" &&
+        action.kind !== "select" &&
+        action.kind !== "scroll" &&
+        action.kind !== "oauth_login") {
+        return { kind: "unsupported" };
+    }
+    // An OAuth handoff is a drive action like any other. The drive guard proves
+    // the control is still the one it observed and refuses an occluded target
+    // BEFORE the OAuth deadline is spent, then the shared executor dispatches it
+    // by that identity — never by the tools' index, which a drive session never
+    // populated. A target with no drive identity record is the tools' to resolve.
+    if (action.kind === "oauth_login") {
+        const guard = await guardDriveOauthTarget(sessionId, action.target);
+        if (guard.kind !== "ok")
+            return guard;
+    }
+    else if (action.kind !== "scroll" &&
+        sessionForCall(sessionId)?.drive?.identities?.get(action.target) === undefined) {
+        return { kind: "unsupported" };
+    }
+    try {
+        const result = await actInternally(sessionId, action, "none", undefined, undefined, DRIVE_DISPATCH);
+        // An OAuth act can end on a wall (no live provider session, a 2FA hand-off)
+        // WITHOUT dispatching: the executor returns that as an observation. The
+        // drive must surface it — dropping it here would re-observe the unchanged
+        // page and look like the action did nothing.
+        return {
+            kind: "ok",
+            combobox: result.combobox === true,
+            ...(result.observation.needs_user === undefined
+                ? {}
+                : { needsUser: result.observation.needs_user }),
+        };
+    }
+    catch (error) {
+        if (error instanceof CompactV2StaleRefError)
+            return { kind: "stale", reason: "stale_ref" };
+        if (error instanceof TargetStaleError)
+            return { kind: "stale", reason: "stale" };
+        const message = error instanceof Error ? error.message : String(error);
+        // A tracked click that reached the element and only then failed did land —
+        // telling the drive it never executed invites a second submit. The evidence
+        // is a CLICK's own dispatch listener, so it says nothing about a type whose
+        // focusing click landed before the keystrokes were written.
+        const dispatchStatus = error instanceof CompactV2ActionFailureError
+            ? error.dispatchStatus
+            : clickDispatchStatusForError(error);
+        if (action.kind === "click" && dispatchStatus === "dispatched") {
+            return { kind: "ok", combobox: false };
+        }
+        // A select that could not take the value was refused by the CONTROL; the
+        // drive must not blame the ref and retire it. A ref that went stale before
+        // the select was ever attempted stays stale.
+        if (action.kind === "select" && !/stale_ref|reobserve_required/i.test(message)) {
+            return { kind: "stale", reason: message === "not_select" ? "not_select" : "option_missing" };
+        }
+        return {
+            kind: "stale",
+            reason: /occluded|intercepts pointer/i.test(message) ? "occluded" : "stale_ref",
+        };
+    }
+}
 export function compactV2SelectionFailureReason(error) {
     return compactV2ActionFailureReason(error, "select");
 }