harnery 0.40.0 → 0.41.0

package/src/core/workflow/workspaces/leases.ts

@@ -16,6 +16,7 @@ import {
 } from "node:fs";
 import { hostname } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
+import { stateDirMode, stateFileMode } from "../../storage/modes.ts";
 
 const MAX_LEASE_BYTES = 8 * 1024;
 const MAX_CONTENTION_OBSERVATION_ATTEMPTS = 8;
@@ -202,11 +203,11 @@ function validateInput(input: AcquireNoClobberLeaseInput): void {
 }
 
 function ensureLeaseDirectory(leaseDir: string, onCreate?: () => void): void {
-  mkdirSync(dirname(leaseDir), { recursive: true, mode: 0o700 });
+  mkdirSync(dirname(leaseDir), { recursive: true, mode: stateDirMode() });
   let created = false;
   onCreate?.();
   try {
-    mkdirSync(leaseDir, { mode: 0o700 });
+    mkdirSync(leaseDir, { mode: stateDirMode() });
     created = true;
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
@@ -226,7 +227,7 @@ function createRecoveryClaim(
   observed: { owner: NoClobberLeaseOwner; bytes: string },
 ): void {
   const temporary = join(leaseDir, `recovery-claim-${claimant.owner_id}`);
-  mkdirSync(temporary, { mode: 0o700 });
+  mkdirSync(temporary, { mode: stateDirMode() });
   const claim: RecoveryClaim = {
     schema_version: 1,
     claimant,
@@ -385,7 +386,7 @@ function leaseHandle(
 }
 
 function writeExclusive(path: string, bytes: string): void {
-  const fd = openSync(path, "wx", 0o600);
+  const fd = openSync(path, "wx", stateFileMode());
   try {
     writeFileSync(fd, bytes, "utf8");
     fsyncSync(fd);

package/src/core/workflow/workspaces/local-git.ts

@@ -8,6 +8,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { stateDirMode, stateFileMode } from "../../storage/modes.ts";
 import { WorkspaceAttestationError } from "./attestation-error.ts";
 import {
   git,
@@ -323,7 +324,7 @@ function claimedParentSegment(claim: WorkspaceClaim): string {
 function hideWorkspaceParentFromGit(parent: string): void {
   const ignoreFile = join(parent, ".gitignore");
   if (existsSync(ignoreFile)) return;
-  writeFileSync(ignoreFile, "*\n", { mode: 0o600 });
+  writeFileSync(ignoreFile, "*\n", { mode: stateFileMode() });
 }
 
 function reconcileAllocation(
@@ -1908,7 +1909,7 @@ function capabilityDigestForClaim(claim: WorkspaceClaim): string {
 
 function acquireRepositoryLease(coordRoot: string, claim: WorkspaceClaim): () => void {
   const leaseDir = join(resolve(coordRoot), ".harnery", "workspaces", PROVIDER_ID, ".leases");
-  mkdirSync(leaseDir, { recursive: true, mode: 0o700 });
+  mkdirSync(leaseDir, { recursive: true, mode: stateDirMode() });
   // Mutual exclusion keys on the Git common directory alone. `git worktree add`,
   // `prune`, and the shared-`config` migration all write to the common directory's
   // administrative area, and once worktrees and submodules are allowed, several

package/src/core/workflow/workspaces/paths.ts

@@ -9,6 +9,7 @@ import {
   statSync,
 } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
+import { stateDirMode } from "../../storage/modes.ts";
 import type { FilesystemIdentity, ValidatedFilesystemPath } from "./types.ts";
 
 const WINDOWS_AMBIGUOUS = /[<>:"|?*]|[ .]$/;
@@ -152,7 +153,7 @@ export function openContainedDirectory(
           );
         }
       } else {
-        mkdirSync(candidate, { mode: 0o700 });
+        mkdirSync(candidate, { mode: stateDirMode() });
       }
       const childFd = openSync(
         candidate,

package/src/core/workflow/workspaces/state.ts

@@ -10,6 +10,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { stateDirMode, stateFileMode } from "../../storage/modes.ts";
 import {
   canonicalJson,
   fsyncParentDirectory,
@@ -192,7 +193,7 @@ export function appendWorkspaceEvent(
     throw new Error("workspace provider event is invalid or too large");
   }
   const path = workspaceEventsPath(coordRoot, claim.provider_id, claim.binding_id);
-  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  mkdirSync(dirname(path), { recursive: true, mode: stateDirMode() });
   const existed = existsSync(path);
   const prior = readWorkspaceEvents(coordRoot, claim.provider_id, claim.binding_id);
   const basis = {
@@ -213,14 +214,14 @@ export function appendWorkspaceEvent(
   const line = `${canonicalJson(record)}\n`;
   if (Buffer.byteLength(line) > WORKSPACE_EVENT_BYTES)
     throw new Error("workspace provider event is too large");
-  const fd = openSync(path, "a", 0o600);
+  const fd = openSync(path, "a", stateFileMode());
   try {
     writeFileSync(fd, line, "utf8");
     fsyncSync(fd);
   } finally {
     closeSync(fd);
   }
-  chmodSync(path, 0o600);
+  chmodSync(path, stateFileMode());
   if (!existed) fsyncParentDirectory(path);
   return record;
 }
@@ -295,7 +296,7 @@ export function appendCleanupAttempt(
   input: Omit<WorkspaceCleanupAttempt, "seq" | "previous_sha256" | "record_sha256">,
 ): WorkspaceCleanupAttempt {
   const path = join(workflowRunDir(coordRoot, runId), "cleanup", "attempts.jsonl");
-  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  mkdirSync(dirname(path), { recursive: true, mode: stateDirMode() });
   const existed = existsSync(path);
   const prior = readCleanupAttempts(coordRoot, runId);
   const basis = {
@@ -311,14 +312,14 @@ export function appendCleanupAttempt(
   if (Buffer.byteLength(line) > WORKSPACE_EVENT_BYTES) {
     throw new Error("workspace cleanup attempt is too large");
   }
-  const fd = openSync(path, "a", 0o600);
+  const fd = openSync(path, "a", stateFileMode());
   try {
     writeFileSync(fd, line, "utf8");
     fsyncSync(fd);
   } finally {
     closeSync(fd);
   }
-  chmodSync(path, 0o600);
+  chmodSync(path, stateFileMode());
   if (!existed) fsyncParentDirectory(path);
   return attempt;
 }
@@ -329,7 +330,7 @@ export function appendIntegrationAttempt(
   input: Omit<IntegrationApplyAttempt, "seq" | "previous_sha256" | "record_sha256">,
 ): IntegrationApplyAttempt {
   const path = join(workflowRunDir(coordRoot, runId), "integration", "attempts.jsonl");
-  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  mkdirSync(dirname(path), { recursive: true, mode: stateDirMode() });
   const existed = existsSync(path);
   const prior = readIntegrationAttempts(coordRoot, runId);
   const basis = {
@@ -372,14 +373,14 @@ function appendChainedRecord(
   if (Buffer.byteLength(line) > WORKSPACE_EVENT_BYTES) {
     throw new Error(`${label} is too large`);
   }
-  const fd = openSync(path, "a", 0o600);
+  const fd = openSync(path, "a", stateFileMode());
   try {
     writeFileSync(fd, line, "utf8");
     fsyncSync(fd);
   } finally {
     closeSync(fd);
   }
-  chmodSync(path, 0o600);
+  chmodSync(path, stateFileMode());
 }
 
 function readChainedRecords<

package/src/lazy-commands.ts

@@ -256,7 +256,17 @@ function selectedCommand(
     if (token === "--") return undefined;
     if (token.startsWith("-")) {
       const option = findRootOption(program, token);
-      if (option?.required || (option?.optional && !args[index + 1]?.startsWith("-"))) index++;
+      // `--format=json` carries its value inline, so the next token is the
+      // command, not the value. Skipping it here consumed the command name and
+      // the wrong bundle (or none) was materialized, which surfaced downstream
+      // as empty output or a bogus "too many arguments" error.
+      const inlineValue = token.includes("=");
+      if (
+        !inlineValue &&
+        (option?.required || (option?.optional && !args[index + 1]?.startsWith("-")))
+      ) {
+        index++;
+      }
       continue;
     }
     if (token === "help") return state.byName.get(args[index + 1] ?? "");

package/src/lib/agent-browser/client.ts

@@ -1,6 +1,7 @@
 import { type SpawnSyncOptions, spawnSync } from "node:child_process";
 import { writeFileSync } from "node:fs";
 import type { CookieJar, Cookie as JarCookie } from "../cookies/index.ts";
+import { PaceGate, pacePolicyFromEnv } from "../pace/index.ts";
 
 /**
  * Thin wrapper over Vercel Labs' `agent-browser` Rust CLI.
@@ -34,6 +35,11 @@ export interface AgentBrowserOptions {
    * agent-browser session. Defaults to a tmp file derived from the jar.
    */
   stateFilePath?: string;
+  /**
+   * Human-pace gate applied before every `open`. Unset resolves the default
+   * from the `HARNERY_PACE*` environment; `null` disables pacing.
+   */
+  pace?: PaceGate | null;
 }
 
 export interface ExecResult {
@@ -48,11 +54,21 @@ const DEFAULT_TIMEOUT_MS = 60_000;
 export class AgentBrowser {
   private readonly opts: AgentBrowserOptions;
   private cookiesSeeded = false;
+  private paceGate: PaceGate | null | undefined;
 
   constructor(opts: AgentBrowserOptions = {}) {
     this.opts = opts;
   }
 
+  /** Block for the human-pace slot before a page load. Synchronous like the rest of this client. */
+  private paceBefore(url: string): void {
+    if (this.paceGate === undefined) {
+      this.paceGate =
+        this.opts.pace === undefined ? new PaceGate(pacePolicyFromEnv()) : this.opts.pace;
+    }
+    this.paceGate?.beforeSync(url);
+  }
+
   /**
    * Run an `agent-browser` subcommand. Returns a structured result.
    * Throws only on spawn failure (e.g., binary not found); non-zero exit
@@ -132,6 +148,7 @@ export class AgentBrowser {
 
   open(url: string, timeoutMs?: number): ExecResult {
     this.seedCookies();
+    this.paceBefore(url);
     return this.execOrThrow(["open", url], timeoutMs);
   }
 
@@ -183,6 +200,7 @@ export class AgentBrowser {
       // Naive shell-like splitting; agent-browser's own argv parser handles
       // the actual command; we just split on whitespace for the wrapper.
       const args = trimmed.split(/\s+/);
+      if (args[0] === "open" && args[1]) this.paceBefore(args[1]);
       results.push(this.exec(args));
     }
     return results;

package/src/lib/browser/client.ts

@@ -16,6 +16,7 @@ import {
   CookieStoreParseError,
   type Cookie as JarCookie,
 } from "../cookies/index.ts";
+import { PaceGate, pacePolicyFromEnv } from "../pace/index.ts";
 import { type AssertResult, type AssertSpec, buildAssertCheck } from "./asserts.js";
 import { stitchPngRows } from "./capture-fidelity.js";
 import {
@@ -33,6 +34,8 @@ import {
   type LayoutLintRequest,
   type LayoutLintResult,
 } from "./geometry.js";
+import { browserIdentity, installDocumentIdentity } from "./identity.js";
+import { AUTOMATION_DEFAULT_ARGS_TO_DROP, automationDisguiseArgs } from "./launch-args.js";
 import {
   buildClearLayoutAnnotationsScript,
   buildLayoutAnnotateScript,
@@ -91,7 +94,7 @@ export interface BrowserOptions {
   /** Cookie jar to seed/sync with. Pass `null` to skip jar entirely. */
   jar?: CookieJar | null;
   /** Viewport. Default 1280x800. */
-  viewport?: { width: number; height: number };
+  viewport?: { width: number; height: number } | null;
   /**
    * Device scale factor (DPR) for the context. Unset keeps Playwright's
    * default of 1, so screenshots are CSS-pixel sized. A higher value renders
@@ -128,6 +131,13 @@ export interface BrowserOptions {
    * via this callback (e.g., a Cloudflare-bypass header for specific zones).
    */
   extraHeaders?: (url: string) => Record<string, string>;
+  /**
+   * Human-pace gate applied before every page load: `navigate`, `reload`, and
+   * the session tab verbs. Unset resolves the default from the `HARNERY_PACE*`
+   * environment (on, 3 to 9 seconds between loads of one site). `null`
+   * disables pacing for this client.
+   */
+  pace?: PaceGate | null;
   /**
    * Extra Chromium command-line flags, passed through to Playwright's
    * `launchPersistentContext` `args`. Used for environment-specific
@@ -136,6 +146,28 @@ export interface BrowserOptions {
    * defaults only.
    */
   launchArgs?: string[];
+  /**
+   * Playwright browser channel. `"chrome"` launches the operator's installed
+   * Google Chrome instead of the bundled "Chrome for Testing" build. Unset or
+   * `"chromium"` keeps the bundled browser.
+   */
+  channel?: "chrome" | "chrome-beta" | "msedge" | "chromium";
+  /**
+   * Drop Playwright's `--enable-automation` default, disable Blink's
+   * AutomationControlled feature, and run with the Chromium sandbox on (no
+   * `--no-sandbox`), so pages do not see `navigator.webdriver`, the automation
+   * infobar, or the unsupported-flag banner. Headed sessions set this; sites
+   * that screen for automation otherwise refuse clicks a person makes in the
+   * window.
+   */
+  hideAutomation?: boolean;
+  /**
+   * User agent to present. Set by `browse` from `lib/browser/user-agent`
+   * (never Linux, never HeadlessChrome). Applied both as the Playwright
+   * context override and as `--user-agent` so workers and frames agree.
+   * Unset keeps the browser's native string.
+   */
+  userAgent?: string;
   /** Authenticated browser proxy passed directly to Playwright. */
   proxy?: { server: string; username?: string; password?: string };
 }
@@ -306,6 +338,7 @@ export class Browser {
   private consoleEvents: ConsoleEvent[] = [];
   private pageErrors: PageErrorEvent[] = [];
   private failedRequests: FailedRequest[] = [];
+  private identityReady = new WeakMap<Page, Promise<void>>();
 
   constructor(private opts: BrowserOptions = {}) {
     this.profileDir = opts.profileDir ?? DEFAULT_PROFILE;
@@ -326,20 +359,54 @@ export class Browser {
    */
   private async openOnce(): Promise<void> {
     const jarCookies = this.opts.jar?.list() ?? [];
+    const launchIdentity = this.opts.userAgent ? browserIdentity(this.opts.userAgent) : undefined;
+    const launchArgs = [
+      ...new Set([
+        ...(this.opts.headed && this.opts.viewport == null ? ["--window-size=1536,864"] : []),
+        ...(this.opts.launchArgs ?? []),
+        ...(this.opts.hideAutomation ? automationDisguiseArgs() : []),
+        ...(this.opts.userAgent ? [`--user-agent=${this.opts.userAgent}`] : []),
+      ]),
+    ];
 
     // Hold a launch slot only across the spawn itself, not the browser's life.
     await acquireLaunchSlot();
     try {
       this.context = await chromium.launchPersistentContext(this.profileDir, {
         headless: !this.opts.headed,
-        viewport: this.opts.viewport ?? { width: 1280, height: 800 },
+        // Service-worker-owned navigations bypass Playwright request routes.
+        ...(this.getPaceGate()?.policy.enabled ? { serviceWorkers: "block" as const } : {}),
+        viewport:
+          this.opts.viewport !== undefined
+            ? this.opts.viewport
+            : this.opts.headed
+              ? null
+              : { width: 1280, height: 800 },
         ...(this.opts.deviceScaleFactor !== undefined
           ? { deviceScaleFactor: this.opts.deviceScaleFactor }
           : {}),
         ...(this.opts.colorScheme ? { colorScheme: this.opts.colorScheme } : {}),
+        ...(this.opts.userAgent ? { userAgent: this.opts.userAgent } : {}),
+        ...(launchIdentity
+          ? {
+              extraHTTPHeaders: {
+                "sec-ch-ua-platform": JSON.stringify(launchIdentity.userAgentMetadata.platform),
+                "sec-ch-ua-mobile": "?0",
+                "sec-ch-ua": launchIdentity.userAgentMetadata.brands
+                  .map(
+                    ({ brand, version }) => `${JSON.stringify(brand)};v=${JSON.stringify(version)}`,
+                  )
+                  .join(", "),
+              },
+            }
+          : {}),
         ...(this.opts.launchTimeout !== undefined ? { timeout: this.opts.launchTimeout } : {}),
-        ...(this.opts.launchArgs && this.opts.launchArgs.length > 0
-          ? { args: this.opts.launchArgs }
+        ...(launchArgs.length > 0 ? { args: launchArgs } : {}),
+        ...(this.opts.channel && this.opts.channel !== "chromium"
+          ? { channel: this.opts.channel }
+          : {}),
+        ...(this.opts.hideAutomation
+          ? { ignoreDefaultArgs: [...AUTOMATION_DEFAULT_ARGS_TO_DROP], chromiumSandbox: true }
           : {}),
         ...(this.opts.proxy ? { proxy: this.opts.proxy } : {}),
         ...(this.opts.recordHarPath
@@ -350,18 +417,55 @@ export class Browser {
       releaseLaunchSlot();
     }
     this.context.setDefaultNavigationTimeout(this.opts.navigationTimeout ?? 30_000);
+    const identity = this.opts.userAgent
+      ? browserIdentity(this.opts.userAgent, this.context.browser()?.version())
+      : undefined;
+    if (identity) await this.context.addInitScript(installDocumentIdentity, identity);
 
     if (jarCookies.length > 0) {
       await this.context.addCookies(jarCookies.map(toPWCookie));
     }
 
-    // Caller-injected extraHeaders callback (e.g., for Cloudflare-bypass
-    // or custom auth headers). Per-request route handler so headers only
-    // attach when the callback returns non-empty.
+    // Gate actual document requests, including links, forms, script navigation,
+    // and the first request of a popup. Method-level waits miss those loads.
+    // Redirect hops are part of the original load, not additional reservations.
     const headersCb = this.opts.extraHeaders;
-    if (headersCb) {
+    if (this.getPaceGate()?.policy.enabled || headersCb || this.opts.userAgent) {
       await this.context.route("**/*", async (route, request) => {
-        const extra = headersCb(request.url());
+        let mainDocument = false;
+        if (request.isNavigationRequest() && !request.redirectedFrom()) {
+          try {
+            mainDocument = request.frame() === request.frame().page().mainFrame();
+          } catch {
+            // A popup's first request can precede creation of its Page/Frame.
+            mainDocument = true;
+          }
+        }
+        if (mainDocument) {
+          try {
+            await this.getPaceGate()?.before(request.url());
+          } catch {
+            await route.abort("failed");
+            return;
+          }
+        }
+        const extra = { ...headersCb?.(request.url()) };
+        // Popup request headers are already computed before its CDP session is
+        // available. Keep negotiated hints consistent on that first request too.
+        if (identity) {
+          const metadata = identity.userAgentMetadata;
+          extra["sec-ch-ua-platform"] = JSON.stringify(metadata.platform);
+          extra["sec-ch-ua-mobile"] = "?0";
+          extra["sec-ch-ua"] = metadata.brands
+            .map(({ brand, version }) => `${JSON.stringify(brand)};v=${JSON.stringify(version)}`)
+            .join(", ");
+          for (const [header, value] of Object.entries({
+            "sec-ch-ua-platform-version": metadata.platformVersion,
+            "sec-ch-ua-arch": metadata.architecture,
+            "sec-ch-ua-bitness": metadata.bitness,
+          }))
+            if (header in request.headers()) extra[header] = JSON.stringify(value);
+        }
         if (Object.keys(extra).length === 0) return route.continue();
         const headers = { ...request.headers(), ...extra };
         return route.continue({ headers });
@@ -370,6 +474,7 @@ export class Browser {
 
     const pages = this.context.pages();
     const firstPage = pages[0] ?? (await this.context.newPage());
+    await Promise.all(this.context.pages().map((page) => this.preparePageIdentity(page)));
     for (const page of this.context.pages()) this.trackPage(page, page === firstPage);
     this.context.on("page", (page) => this.trackPage(page, true));
   }
@@ -491,6 +596,10 @@ export class Browser {
         type: "unknown",
       });
       this.attachDiagnosticListeners(page);
+      void this.preparePageIdentity(page).catch((error) => {
+        if (!page.isClosed())
+          this.pageErrors.push({ message: `Browser identity setup failed: ${String(error)}` });
+      });
       page.on("domcontentloaded", () => this.recordDocumentNavigation(page));
       page.once("close", () => {
         this.pageRecency.delete(page);
@@ -501,6 +610,23 @@ export class Browser {
     if (makeActive) this.setActivePage(page);
   }
 
+  private preparePageIdentity(page: Page): Promise<void> {
+    if (!this.opts.userAgent || !this.context) return Promise.resolve();
+    let ready = this.identityReady.get(page);
+    if (!ready) {
+      const context = this.context;
+      const userAgent = this.opts.userAgent;
+      ready = (async () => {
+        const identity = browserIdentity(userAgent, context.browser()?.version());
+        if (!identity) return;
+        const session = await context.newCDPSession(page);
+        await session.send("Emulation.setUserAgentOverride", identity);
+      })();
+      this.identityReady.set(page, ready);
+    }
+    return ready;
+  }
+
   private setActivePage(page: Page): void {
     if (page.isClosed()) return;
     this.page = page;
@@ -569,8 +695,19 @@ export class Browser {
     };
   }
 
+  private paceGate: PaceGate | null | undefined;
+
+  private getPaceGate(): PaceGate | null {
+    if (this.paceGate === undefined) {
+      this.paceGate =
+        this.opts.pace === undefined ? new PaceGate(pacePolicyFromEnv()) : this.opts.pace;
+    }
+    return this.paceGate;
+  }
+
   async navigate(url: string): Promise<NavigateResult> {
     const page = this.currentPage;
+    await this.preparePageIdentity(page);
     const response = await page.goto(url, { waitUntil: this.opts.waitUntil ?? "load" });
     return {
       url: page.url(),
@@ -1381,6 +1518,7 @@ export class Browser {
     const page = await this.context.newPage();
     this.trackPage(page, true);
     try {
+      await this.preparePageIdentity(page);
       await page.goto(url, { waitUntil: this.opts.waitUntil ?? "load" });
       this.sessionRevision++;
       return await this.describeTab(page);

package/src/lib/browser/identity.ts

@@ -0,0 +1,64 @@
+/** Keep Chromium's UA, navigator.platform and client hints in one profile. */
+export function browserIdentity(userAgent: string, browserVersion?: string) {
+  const chrome = /(?:Chrome|Chromium)\/(\d+)\.([\d.]+)/.exec(userAgent);
+  const windows = userAgent.includes("Windows NT");
+  const mac = userAgent.includes("Macintosh");
+  // A custom non-Chromium or non-desktop UA is an explicit caller choice.
+  if (!chrome || (!windows && !mac)) return undefined;
+  const major = chrome[1]!;
+  const fullVersion = browserVersion?.startsWith(`${major}.`)
+    ? browserVersion
+    : `${major}.${chrome[2]}`;
+  const brand = userAgent.includes("Edg/") ? "Microsoft Edge" : "Google Chrome";
+  return {
+    userAgent,
+    platform: windows ? "Win32" : "MacIntel",
+    userAgentMetadata: {
+      brands: [
+        { brand: "Chromium", version: major },
+        { brand, version: major },
+      ],
+      fullVersionList: [
+        { brand: "Chromium", version: fullVersion },
+        { brand, version: fullVersion },
+      ],
+      platform: windows ? "Windows" : "macOS",
+      platformVersion: windows ? "10.0.0" : "10.15.7",
+      architecture: "x86",
+      bitness: "64",
+      model: "",
+      mobile: false,
+      wow64: false,
+    },
+  };
+}
+
+/** Initial popup documents exist before Playwright can attach a page session. */
+export function installDocumentIdentity(identity: NonNullable<ReturnType<typeof browserIdentity>>) {
+  const metadata = identity.userAgentMetadata;
+  const basics = { brands: metadata.brands, mobile: metadata.mobile, platform: metadata.platform };
+  Object.defineProperty(Navigator.prototype, "platform", {
+    configurable: true,
+    get: () => identity.platform,
+  });
+  if (!("userAgentData" in navigator)) return;
+  const nativeData = (navigator as Navigator & { userAgentData: object }).userAgentData;
+  const data = Object.create(Object.getPrototypeOf(nativeData));
+  for (const [name, value] of Object.entries(basics)) {
+    Object.defineProperty(data, name, { enumerable: true, get: () => value });
+  }
+  Object.defineProperty(data, "toJSON", { value: () => ({ ...basics }) });
+  Object.defineProperty(data, "getHighEntropyValues", {
+    value: async (hints: string[]) => {
+      const result: Record<string, unknown> = { ...basics };
+      for (const hint of hints) {
+        if (Object.hasOwn(metadata, hint)) result[hint] = metadata[hint as keyof typeof metadata];
+      }
+      return result;
+    },
+  });
+  Object.defineProperty(Navigator.prototype, "userAgentData", {
+    configurable: true,
+    get: () => data,
+  });
+}

package/src/lib/browser/index.ts

@@ -76,7 +76,14 @@ export type {
   OverlapResult,
 } from "./geometry.js";
 export { buildLayoutLintCheck } from "./geometry.js";
-export { isWSL, wslHeadedLaunchArgs } from "./launch-args.js";
+export {
+  AUTOMATION_DEFAULT_ARGS_TO_DROP,
+  automationDisguiseArgs,
+  installedChromeChannel,
+  installedChromePath,
+  isWSL,
+  wslHeadedLaunchArgs,
+} from "./launch-args.js";
 export type {
   OverflowElement,
   OverflowResult,
@@ -237,6 +244,13 @@ export {
   snappedBandRects,
   type VisualAtom,
 } from "./tiling.js";
+export {
+  chromeMajorFromExecutable,
+  hostFamily,
+  normalUserAgent,
+  readStoredUserAgent,
+  resolveUserAgent,
+} from "./user-agent.js";
 export type {
   CheckVisibilityOptions,
   VisibilityResult,

package/src/lib/browser/launch-args.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 
 /**
  * Chromium launch-arg helpers for environment-specific workarounds.
@@ -31,3 +31,55 @@ export function isWSL(): boolean {
 export function wslHeadedLaunchArgs(): string[] {
   return isWSL() ? ["--disable-gpu"] : [];
 }
+
+/**
+ * Playwright's bundled browser is "Chrome for Testing", launched with
+ * `--enable-automation`. Both are visible to the page: the User-Agent brand
+ * list carries "Chrome for Testing" and `navigator.webdriver` reads true, so
+ * sign-in flows on sites that screen for automation (X, some banks, some
+ * Cloudflare-fronted apps) silently refuse clicks in a headed window that a
+ * person is driving. Headed sessions therefore launch the operator's real
+ * Google Chrome when one is installed and drop the automation signals.
+ */
+
+/** Default Chromium args Playwright adds that a headed session must not carry. */
+export const AUTOMATION_DEFAULT_ARGS_TO_DROP: readonly string[] = ["--enable-automation"];
+
+/** Launch flags that stop Blink from reporting the automation state to pages. */
+export function automationDisguiseArgs(): string[] {
+  return ["--disable-blink-features=AutomationControlled"];
+}
+
+const CHROME_PATHS: Record<string, string[]> = {
+  linux: ["/usr/bin/google-chrome", "/usr/bin/google-chrome-stable", "/opt/google/chrome/chrome"],
+  darwin: ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"],
+  win32: [
+    "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+    "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+  ],
+};
+
+/**
+ * `"chrome"` when a stable Google Chrome install is present at a well-known
+ * path for this platform, else `undefined` (use Playwright's bundled
+ * Chromium). Playwright resolves the `chrome` channel to the same install, so
+ * the check only has to answer whether asking for it can succeed.
+ */
+export function installedChromeChannel(
+  platform: NodeJS.Platform = process.platform,
+  exists: (path: string) => boolean = existsSync,
+): "chrome" | undefined {
+  return installedChromePath(platform, exists) ? "chrome" : undefined;
+}
+
+/**
+ * Filesystem path of the installed stable Google Chrome for this platform, or
+ * `undefined`. Used to spawn Chrome with nothing attached for sign-in flows
+ * whose verification vendors detect the DevTools protocol itself.
+ */
+export function installedChromePath(
+  platform: NodeJS.Platform = process.platform,
+  exists: (path: string) => boolean = existsSync,
+): string | undefined {
+  return (CHROME_PATHS[platform] ?? []).find((candidate) => exists(candidate));
+}