harnery 0.40.0 → 0.42.0

package/src/commands/browse.ts

@@ -1,10 +1,13 @@
+import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, resolve } from "node:path";
 import type { Command } from "commander";
+import { chromium } from "playwright";
 import { PNG } from "pngjs";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
 import { resolveBinName } from "../core/config.ts";
+import { splitBatchSteps } from "../lib/browser/batch-steps.ts";
 import {
   CAPTURE_FIDELITY_MISMATCH_THRESHOLD,
   compareBand,
@@ -13,6 +16,22 @@ import {
   type FidelityProbe,
   pngDimensions,
 } from "../lib/browser/capture-fidelity.ts";
+import {
+  type CollectLimits,
+  createPageDriver,
+  createRng,
+  DEFAULT_COLLECT_LIMITS,
+  PACING_LIMITS,
+  parseProbability,
+  parseRange,
+  presetNames,
+  type ResolvedCollectSpec,
+  randomSeed,
+  resolveCollectSpec,
+  runCollect,
+  type ScrollPacing,
+  scrollPacingFromEnv,
+} from "../lib/browser/collect/index.ts";
 import {
   type AssertResult,
   Browser,
@@ -24,15 +43,19 @@ import {
   type CritiqueResult,
   type CritiqueTile,
   captureDevOverlay,
+  chromeMajorFromExecutable,
   DEFAULT_CRITIQUE_RUBRIC,
   type DevOverlayResult,
   type Diagnostics,
   extractObservedIp,
+  installedChromeChannel,
+  installedChromePath,
   type LayoutAxis,
   type LayoutLintResult,
   type OverflowResult,
   parseAssertSpec,
   type RuntsResult,
+  resolveUserAgent,
   runCritique,
   type StandaloneHtmlResult,
   type TargetSizeProfile,
@@ -44,6 +67,7 @@ import {
   writeNetscapeCookieFile,
   wslHeadedLaunchArgs,
 } from "../lib/browser/index.ts";
+import { isWSL } from "../lib/browser/launch-args.ts";
 import {
   allocateTileBudget,
   validatePageReviewAllocation,
@@ -107,7 +131,17 @@ import {
   type SaveBaselineResult,
   saveBaseline,
 } from "../lib/browser/visual-diff.ts";
-import { applyExtraCookies, CookieJar } from "../lib/cookies/index.ts";
+import {
+  harvestDomain,
+  harvestWindowsChromeCookies,
+  stopWindowsChromeProfile,
+  windowsChromePath,
+  windowsLocalAppData,
+  windowsPlainProfile,
+  wslPathToWindows,
+} from "../lib/browser/windows-chrome.ts";
+import { applyExtraCookies, CookieJar, mergeCookies } from "../lib/cookies/index.ts";
+import { commandPaceGate } from "../lib/pace/index.ts";
 
 /**
  * `harn browse <url>`: Playwright-backed page navigation with shared
@@ -160,15 +194,38 @@ interface BrowseOpts {
   evaluate?: string;
   captureEvaluate?: string;
   batch?: string;
+  // Scroll-and-collect mode (--collect [preset])
+  collect?: string | boolean;
+  collectItem?: string;
+  collectKey?: string;
+  collectKeyPattern?: string;
+  collectField?: string[];
+  collectExpand?: string | boolean;
+  collectMaxItems?: string;
+  collectMaxScrolls?: string;
+  collectMaxSeconds?: string;
+  collectIdle?: string;
+  collectStep?: string;
+  collectPause?: string;
+  collectReadChance?: string;
+  collectReadPause?: string;
+  collectBackChance?: string;
+  collectSeed?: string;
+  collectFormat?: string;
+  collectOut?: string;
   networkHar?: string;
   login?: boolean;
+  attached?: boolean;
   loginCloseFile?: string;
   controlFile?: string;
   headed?: boolean;
   browserArg?: string[];
+  browserChannel?: string;
+  userAgent?: string;
   proxyFromEnv?: boolean;
   exportCookies?: string;
   cookies?: boolean;
+  pace?: boolean;
   store?: string;
   profile?: string;
   viewport?: string;
@@ -334,13 +391,73 @@ export function registerBrowseCommand(
       "--batch <steps>",
       "Run multiple steps in one session, semicolon-separated. Each step is one of: " +
         "`click <selector>`, `fill <selector=>value>`, `press <key>`, `wait <selector|ms>`, `eval <js>`, `reload`. " +
-        'Example: `--batch "click button; wait 1500; reload; wait 3000"`. `reload` preserves sessionStorage + cookies, which is how to repro sessionStorage-restored UI state.',
+        'Example: `--batch "click button; wait 1500; reload; wait 3000"`. `reload` preserves sessionStorage + cookies, which is how to repro sessionStorage-restored UI state. ' +
+        "An `eval` step keeps semicolons inside JS quotes and (), [], {}; `\\;` is always a literal semicolon.",
+    )
+    .option(
+      "--collect [preset]",
+      "Scroll an infinite feed like a reader and collect every item that passes through the DOM, " +
+        `de-duplicated, as JSON. Presets: ${presetNames().join(", ")} (default generic). ` +
+        "Skips the trio, checks and --evaluate; runs after --wait-for and --batch.",
+    )
+    .option("--collect-item <css>", "Item selector (overrides the preset's).")
+    .option(
+      "--collect-key <extractor>",
+      "Dedupe key extractor, <selector>[@attr] inside the item. Default: the preset key, else the " +
+        "first permalink-like link, else a hash of the item text.",
+    )
+    .option("--collect-key-pattern <regex>", "Regex a link must match to count as a permalink key.")
+    .option(
+      "--collect-field <name=extractor>",
+      "Add or override a field: name=<selector>[@attr]. name[]= collects every match. Empty selector " +
+        "or :scope is the item itself; no @attr reads visible text (repeatable).",
+      (value: string, previous: string[] = []) => [...previous, value],
+      [] as string[],
+    )
+    .option(
+      "--collect-expand [selector]",
+      "Click 'show more' buttons inside visible items before harvesting (preset selector by default). " +
+        "At most 3 per step and 50 per run; links and action buttons are never clicked.",
+    )
+    .option("--collect-max-items <n>", "Stop after this many unique items.")
+    .option("--collect-max-scrolls <n>", "Stop after this many scroll steps (default 60).", "60")
+    .option("--collect-max-seconds <n>", "Stop after this much wall time (default 300).", "300")
+    .option(
+      "--collect-idle <n>",
+      "Stop after this many steps with no new items and no page growth (default 5).",
+      "5",
+    )
+    .option(
+      "--collect-step <min-max>",
+      "Scroll distance per step as a viewport fraction (default 0.6-1.1; env HARNERY_COLLECT_STEP).",
+    )
+    .option(
+      "--collect-pause <min-max>",
+      "Pause after each step in ms (default 1200-3500; env HARNERY_COLLECT_PAUSE_MS).",
+    )
+    .option(
+      "--collect-read-chance <p>",
+      "Chance of a longer reading pause per step (default 0.12).",
+    )
+    .option("--collect-read-pause <min-max>", "Reading pause in ms (default 4000-9000).")
+    .option(
+      "--collect-back-chance <p>",
+      "Chance a step starts with a small scroll back up (default 0.08).",
     )
+    .option(
+      "--collect-seed <n>",
+      "Seed for the scroll schedule; the envelope reports the seed used.",
+    )
+    .option(
+      "--collect-format <format>",
+      "json (envelope, default) or jsonl (one item per line).",
+      "json",
+    )
+    .option("--collect-out <path>", "Write the collection to this file instead of stdout.")
     .option("--network-har <path>", "Record network traffic to a HAR file (finalized on close)")
     .option(
       "--viewport <preset|WxH>",
-      "Viewport: mobile (390x844), tablet (820x1180), desktop (1280x800), hd (1920x1080), or explicit '1920x1080'",
-      "desktop",
+      "Viewport: mobile (390x844), tablet (820x1180), desktop (1280x800), hd (1920x1080), or explicit '1920x1080'. Default: real window in headed mode, desktop in headless mode",
     )
     .option(
       "--color-scheme <scheme>",
@@ -348,23 +465,52 @@ export function registerBrowseCommand(
         "Renders theme-aware pages in that scheme without page-specific toggles. " +
         "Absent = browser default (unchanged behavior).",
     )
-    .option("--login", "Headed mode for one-time auth flow (cookies persist in profile)")
+    .option(
+      "--login",
+      "Open the URL in the installed Google Chrome with nothing attached (no DevTools protocol, no " +
+        "Playwright) so a person can sign in; under WSL this is the Windows host's Chrome. Sign in, then " +
+        "close the window or create the --login-close-file; later browse and browse-session runs reuse " +
+        "the cookies. Sites cannot tell this window from the person's own browser.",
+    )
+    .option(
+      "--attached",
+      "With --login: open an automation-controlled Chrome that this process and --control-file can drive. " +
+        "Sites can detect it and may lock the account, so use it only for agent-driven headed sessions on " +
+        "sites you own. Never use it to sign in to a third-party account.",
+    )
     .option(
       "--login-close-file <path>",
       "With --login, wait for this file instead of terminal Enter, then remove it and close cleanly",
     )
     .option(
       "--control-file <path>",
-      "With --login, publish an owner-only descriptor for repeated browse-session control",
+      "With --login --attached, publish an owner-only descriptor for repeated browse-session control",
+    )
+    .option(
+      "--headed",
+      "Automation-controlled headed window for one-off visual checks. Not for signing in; use --login.",
+    )
+    .option(
+      "--browser-channel <name>",
+      "Browser to launch: chrome | chrome-beta | msedge | chromium. Headed launches (--login, --headed) " +
+        "default to the installed Google Chrome with the automation signals removed, because the bundled " +
+        '"Chrome for Testing" build advertises itself and sign-in flows refuse clicks; chromium forces the ' +
+        "bundled build. HARNERY_BROWSER_CHANNEL sets the default machine-wide.",
+    )
+    .option(
+      "--user-agent <ua|auto|native>",
+      "User agent to present. Default: a normal Windows (or macOS on a Mac) Chrome user agent at the launched " +
+        "Chrome's major version, stored at ~/.cache/harnery/user-agent.json and reused by every surface; never " +
+        "Linux, never HeadlessChrome. A string rewrites the store, auto refreshes it, native uses the browser's own. " +
+        "HARNERY_BROWSER_UA overrides for one environment.",
     )
-    .option("--headed", "Headed mode for one-off (no auth-flow framing)")
     .option(
       "--browser-arg <flag>",
       "Extra Chromium launch flag, passed straight to the browser (repeatable). " +
         "e.g. --browser-arg --disable-gpu. Also settable machine-wide via the " +
-        "HARNERY_BROWSER_ARGS env var (whitespace-separated). Under WSL, headed " +
-        "launches auto-add --disable-gpu to fix blank-window paint; opt out with " +
-        "HARNERY_BROWSER_NO_WSL_DEFAULTS=1.",
+        "HARNERY_BROWSER_ARGS env var (whitespace-separated). Under WSL, set " +
+        "HARNERY_BROWSER_WSL_DISABLE_GPU=1 to add --disable-gpu when a headed window paints blank; " +
+        "it is off by default because software WebGL is a bot tell.",
       (value: string, prev: string[] = []) => [...prev, value],
       [] as string[],
     )
@@ -376,6 +522,11 @@ export function registerBrowseCommand(
         "the expected IP is verified before the requested URL opens.",
     )
     .option("--no-cookies", "Skip cookie-jar attach and persist")
+    .option(
+      "--no-pace",
+      "Skip the human-pace gap (3 to 9 s) between page loads of the same site for this run. " +
+        "HARNERY_PACE=off disables it machine-wide; local and private hosts never wait.",
+    )
     .option("--store <path>", `Cookie store path (default ${DEFAULT_STORE})`)
     .option("--profile <dir>", `Persistent Chromium profile dir (default ${DEFAULT_PROFILE})`)
     .option(
@@ -856,7 +1007,8 @@ async function runBrowse(
       ? null
       : new CookieJar({ path: opts.store ?? DEFAULT_STORE, source: "harn-browse" });
   if (jar) applyExtraCookies(url, jar, context?.extraCookies);
-  const headed = opts.login || opts.headed;
+  const loginMode = resolveLoginMode(opts);
+  const headed = loginMode === "attached" || opts.headed;
   const viewport = parseViewport(opts.viewport ?? "desktop");
   const deviceScaleFactor = parseDeviceScaleFactor(opts.deviceScaleFactor);
   if (opts.reviewPackAllocation && !opts.reviewPack) {
@@ -888,12 +1040,6 @@ async function runBrowse(
   }
   const proxy = opts.proxyFromEnv ? browserProxyFromEnv() : undefined;
   const proxyGate = opts.proxyFromEnv ? browserProxyGateFromEnv() : null;
-  if (opts.loginCloseFile && !opts.login) {
-    throw new Error("--login-close-file requires --login.");
-  }
-  if (opts.controlFile && !opts.login) {
-    throw new Error("--control-file requires --login.");
-  }
   const loginCloseFile = opts.loginCloseFile ? resolve(opts.loginCloseFile) : null;
   if (loginCloseFile && existsSync(loginCloseFile)) {
     throw new Error(
@@ -901,20 +1047,58 @@ async function runBrowse(
     );
   }
 
+  const collectPlan = opts.collect ? buildCollectPlan(opts) : null;
+
+  const pace = commandPaceGate(opts.pace !== false, (message) => emit.log(message, "info"));
+  if (loginMode === "plain") {
+    const plainExecutable = installedChromePath();
+    const plainUa = resolveUserAgent({
+      requested: opts.userAgent,
+      env: process.env.HARNERY_BROWSER_UA,
+      chromeMajor: plainExecutable ? chromeMajorFromExecutable(plainExecutable) : undefined,
+    });
+    await pace?.before(url);
+    if (useWindowsPlainLogin()) {
+      await runWindowsPlainLogin(url, opts.store ?? DEFAULT_STORE, loginCloseFile, emit);
+      return;
+    }
+    await runPlainLogin(url, opts.profile ?? DEFAULT_PROFILE, loginCloseFile, plainUa, emit);
+    return;
+  }
+
+  const channel = resolveBrowserChannel(opts, Boolean(headed));
+  const userAgent = resolveUserAgent({
+    requested: opts.userAgent,
+    env: process.env.HARNERY_BROWSER_UA,
+    chromeMajor: launchedChromeMajor(channel),
+  });
   const browser = new Browser({
     profileDir: opts.profile ?? DEFAULT_PROFILE,
     headed,
     jar,
-    viewport,
+    viewport: headed && !opts.viewport ? null : viewport,
     ...(deviceScaleFactor !== undefined ? { deviceScaleFactor } : {}),
     ...(colorScheme ? { colorScheme } : {}),
     navigationTimeout: Number.parseInt(opts.timeout, 10),
     waitUntil: opts.waitUntil as BrowseOpts["waitUntil"] as never,
     recordHarPath: opts.networkHar ? resolve(opts.networkHar) : undefined,
     extraHeaders: context?.extraHeaders,
+    pace,
     launchArgs: resolveLaunchArgs(opts, Boolean(headed), Boolean(proxy)),
+    ...(channel ? { channel } : {}),
+    hideAutomation: Boolean(headed),
+    ...(userAgent ? { userAgent } : {}),
     proxy,
   });
+  if (userAgent) emit.log(`Presenting as: ${userAgent}`, "debug");
+  if (headed) {
+    emit.log(
+      channel && channel !== "chromium"
+        ? `Headed session uses the installed ${channel} channel with automation signals hidden.`
+        : "Headed session uses Playwright's bundled Chromium (no Google Chrome found); automation signals hidden.",
+      "info",
+    );
+  }
 
   // Print mode: --snapshot / --html / --json all suppress file writes.
   const printMode = opts.snapshot || opts.html || opts.json;
@@ -955,6 +1139,11 @@ async function runBrowse(
       batchResult = await runBatch(browser, opts.batch, Number.parseInt(opts.timeout, 10));
     }
 
+    if (collectPlan) {
+      await runCollectMode(browser, collectPlan);
+      return;
+    }
+
     let evalResult: unknown;
     if (opts.evaluate) {
       evalResult = await browser.evaluate<unknown>(opts.evaluate);
@@ -1409,13 +1598,13 @@ async function runBrowse(
       const closeWaits: Promise<void>[] = [];
       if (loginCloseFile) {
         emit.log(
-          `[--login] Headed Chromium is open. Drive the visible window now. Create ${loginCloseFile} to close cleanly.`,
+          `[--login --attached] Automation-controlled Chrome is open. Drive the visible window now. Create ${loginCloseFile} to close cleanly.`,
           "info",
         );
         closeWaits.push(waitForLoginCloseFile(loginCloseFile, lifecycleAbort.signal));
       } else {
         emit.log(
-          "[--login] Headed Chromium is open. Walk through your auth flow now. Press Enter here to close + persist cookies into the profile.",
+          "[--login --attached] Automation-controlled Chrome is open. Drive the visible window now. Press Enter here to close + persist cookies into the profile.",
           "info",
         );
         closeWaits.push(waitForTerminalEnter(lifecycleAbort.signal));
@@ -1612,9 +1801,161 @@ async function runBrowse(
 }
 
 // ---------------------------------------------------------------------------
-// Batch mode parser. Each step is `<verb> <args>`; verbs are click, fill,
-// press, wait, eval. Steps are separated by `;` (escape with `\;` if a value
-// genuinely contains a semicolon, rare for the supported verbs).
+// Scroll-and-collect mode (--collect). Extends browse rather than adding a
+// sibling command so it reuses the exact session path: persistent profile,
+// cookie jar, browser channel, user agent, proxy, page-load pace gate,
+// --wait-for and --batch setup steps.
+// ---------------------------------------------------------------------------
+
+interface CollectPlan {
+  spec: ResolvedCollectSpec;
+  limits: CollectLimits;
+  pacing: ScrollPacing;
+  seed: number;
+  format: "json" | "jsonl";
+  out: string | null;
+}
+
+function parsePositiveInt(raw: string, flag: string): number {
+  if (!/^\d+$/.test(raw.trim()) || Number.parseInt(raw, 10) < 1) {
+    throw new Error(`${flag} must be a positive integer (got "${raw}").`);
+  }
+  return Number.parseInt(raw, 10);
+}
+
+function buildCollectPlan(opts: BrowseOpts): CollectPlan {
+  if (opts.login) throw new Error("--collect cannot run with --login.");
+  if (opts.snapshot || opts.html || opts.json) {
+    throw new Error("--collect prints its own JSON; drop --snapshot, --html and --json.");
+  }
+  const presetName = typeof opts.collect === "string" ? opts.collect : "generic";
+  const spec = resolveCollectSpec(presetName, {
+    item: opts.collectItem,
+    key: opts.collectKey,
+    keyPattern: opts.collectKeyPattern,
+    fields: opts.collectField,
+    expand: opts.collectExpand,
+  });
+  const limits: CollectLimits = {
+    ...DEFAULT_COLLECT_LIMITS,
+    maxItems:
+      opts.collectMaxItems === undefined
+        ? null
+        : parsePositiveInt(opts.collectMaxItems, "--collect-max-items"),
+    maxScrolls: parsePositiveInt(opts.collectMaxScrolls ?? "60", "--collect-max-scrolls"),
+    maxMs: parsePositiveInt(opts.collectMaxSeconds ?? "300", "--collect-max-seconds") * 1_000,
+    idleSteps: parsePositiveInt(opts.collectIdle ?? "5", "--collect-idle"),
+    expandPerStep: spec.expand ? 3 : 0,
+  };
+  const pacing = scrollPacingFromEnv();
+  const msBounds = { min: 0, max: PACING_LIMITS.maxPauseMs };
+  if (opts.collectStep) {
+    pacing.step = parseRange(opts.collectStep, "--collect-step", {
+      min: 0.05,
+      max: PACING_LIMITS.maxStepFraction,
+    });
+  }
+  if (opts.collectPause)
+    pacing.pauseMs = parseRange(opts.collectPause, "--collect-pause", msBounds);
+  if (opts.collectReadPause) {
+    pacing.readPauseMs = parseRange(opts.collectReadPause, "--collect-read-pause", msBounds);
+  }
+  if (opts.collectReadChance !== undefined) {
+    pacing.readChance = parseProbability(opts.collectReadChance, "--collect-read-chance");
+  }
+  if (opts.collectBackChance !== undefined) {
+    pacing.backChance = parseProbability(opts.collectBackChance, "--collect-back-chance");
+  }
+  let seed = randomSeed();
+  if (opts.collectSeed !== undefined) {
+    if (!/^\d+$/.test(opts.collectSeed.trim())) {
+      throw new Error(`--collect-seed must be a non-negative integer (got "${opts.collectSeed}").`);
+    }
+    seed = Number(BigInt(opts.collectSeed.trim()) % 4294967296n);
+  }
+  const format = opts.collectFormat ?? "json";
+  if (format !== "json" && format !== "jsonl") {
+    throw new Error(`--collect-format must be json or jsonl (got "${format}").`);
+  }
+  return {
+    spec,
+    limits,
+    pacing,
+    seed,
+    format,
+    out: opts.collectOut ? resolve(opts.collectOut) : null,
+  };
+}
+
+async function runCollectMode(browser: Browser, plan: CollectPlan): Promise<void> {
+  const page = browser.currentPage;
+  const rng = createRng(plan.seed);
+  let interrupted = false;
+  const onSignal = () => {
+    interrupted = true;
+  };
+  process.on("SIGINT", onSignal);
+  process.on("SIGTERM", onSignal);
+  let result: Awaited<ReturnType<typeof runCollect>>;
+  try {
+    emit.log(
+      `collect: preset ${plan.spec.preset}, item ${plan.spec.item}, seed ${plan.seed}`,
+      "info",
+    );
+    const driver = createPageDriver(page, plan.spec, {
+      rng,
+      log: (message) => emit.log(message, "warn"),
+    });
+    result = await runCollect(driver, {
+      limits: plan.limits,
+      pacing: plan.pacing,
+      rng,
+      shouldStop: () => interrupted,
+      onStep: ({ step, items, added }) =>
+        emit.log(`collect: step ${step}, ${items} items (+${added})`, "debug"),
+    });
+  } finally {
+    process.removeListener("SIGINT", onSignal);
+    process.removeListener("SIGTERM", onSignal);
+  }
+  const { items, stats } = result;
+  emit.log(
+    `collect: ${items.length} items in ${stats.steps} steps, stopped on ${stats.stopReason}` +
+      (stats.stopDetail ? ` (${stats.stopDetail})` : ""),
+    "info",
+  );
+  const envelope = {
+    url: page.url(),
+    preset: plan.spec.preset,
+    itemSelector: plan.spec.item,
+    seed: plan.seed,
+    stopReason: stats.stopReason,
+    stats,
+    items,
+  };
+  if (plan.format === "jsonl") {
+    const body = items.map((item) => JSON.stringify(item)).join("\n");
+    if (plan.out) {
+      mkdirSync(dirname(plan.out), { recursive: true });
+      writeFileSync(plan.out, body ? `${body}\n` : "");
+      emit.file(plan.out, { items: items.length, stopReason: stats.stopReason, stats });
+    } else if (body) {
+      process.stdout.write(`${body}\n`);
+    }
+  } else if (plan.out) {
+    mkdirSync(dirname(plan.out), { recursive: true });
+    writeFileSync(plan.out, `${JSON.stringify(envelope, null, 2)}\n`);
+    emit.file(plan.out, { items: items.length, stopReason: stats.stopReason, stats });
+  } else {
+    emit.data(envelope);
+  }
+  if (interrupted) process.exitCode = 130;
+}
+
+// ---------------------------------------------------------------------------
+// Batch mode runner. Each step is `<verb> <args>`; see splitBatchSteps for
+// the separator rule (eval steps keep semicolons inside JS quotes and
+// brackets; `\;` is always a literal semicolon).
 // ---------------------------------------------------------------------------
 
 interface BatchResult {
@@ -1694,27 +2035,6 @@ async function runBatch(
   return result;
 }
 
-function splitBatchSteps(input: string): string[] {
-  const steps: string[] = [];
-  let buf = "";
-  for (let i = 0; i < input.length; i++) {
-    const ch = input[i];
-    if (ch === "\\" && input[i + 1] === ";") {
-      buf += ";";
-      i++;
-      continue;
-    }
-    if (ch === ";") {
-      steps.push(buf);
-      buf = "";
-      continue;
-    }
-    buf += ch;
-  }
-  if (buf.trim()) steps.push(buf);
-  return steps;
-}
-
 // ---------------------------------------------------------------------------
 // Print mode (--snapshot / --html / --json): stdout, no file writes
 // ---------------------------------------------------------------------------
@@ -2967,15 +3287,57 @@ function summarizeDiagnostics(diag: Diagnostics): Record<string, unknown> {
 
 /**
  * Merge Chromium launch flags from three sources, in order, de-duped:
- *   1. WSLg headed default (`--disable-gpu`) — auto-applied for headed launches
- *      under WSL so the window actually paints. Opt out with
- *      HARNERY_BROWSER_NO_WSL_DEFAULTS=1.
+ *   1. WSLg `--disable-gpu`, only when HARNERY_BROWSER_WSL_DISABLE_GPU=1. It
+ *      was the default for headed launches, but software WebGL (SwiftShader)
+ *      is a bot tell that sign-in flows screen for, and current WSLg exposes
+ *      the host GPU through D3D12, so the flag is now opt-in for machines
+ *      that still paint a blank headed window without it.
  *   2. HARNERY_BROWSER_ARGS env (whitespace-separated) — a machine-wide default.
  *   3. --browser-arg flags on this invocation (repeatable).
  */
+const BROWSER_CHANNELS = new Set(["chrome", "chrome-beta", "msedge", "chromium"]);
+
+/**
+ * Pick the browser channel: `--browser-channel`, then `HARNERY_BROWSER_CHANNEL`,
+ * then (headed only) the installed Google Chrome when one exists. Headless runs
+ * keep the bundled Chromium unless told otherwise, so QA renders stay stable.
+ */
+function resolveBrowserChannel(
+  opts: BrowseOpts,
+  headed: boolean,
+): "chrome" | "chrome-beta" | "msedge" | "chromium" | undefined {
+  const requested = (opts.browserChannel ?? process.env.HARNERY_BROWSER_CHANNEL)?.trim();
+  if (requested) {
+    if (!BROWSER_CHANNELS.has(requested)) {
+      throw new Error(
+        `Unknown --browser-channel "${requested}". Use chrome, chrome-beta, msedge, or chromium.`,
+      );
+    }
+    return requested as "chrome" | "chrome-beta" | "msedge" | "chromium";
+  }
+  return headed ? installedChromeChannel() : undefined;
+}
+
+/**
+ * Major version of the Chrome that will launch: the installed Chrome for the
+ * `chrome` channel, else Playwright's bundled Chromium. Unknown when neither
+ * answers `--version`; the user-agent store then keeps its last value.
+ */
+function launchedChromeMajor(channel: string | undefined): number | undefined {
+  if (channel === "chrome") {
+    const exe = installedChromePath();
+    return exe ? chromeMajorFromExecutable(exe) : undefined;
+  }
+  try {
+    return chromeMajorFromExecutable(chromium.executablePath());
+  } catch {
+    return undefined;
+  }
+}
+
 function resolveLaunchArgs(opts: BrowseOpts, headed: boolean, proxyEnabled: boolean): string[] {
   const args: string[] = [];
-  if (headed && !process.env.HARNERY_BROWSER_NO_WSL_DEFAULTS) {
+  if (headed && process.env.HARNERY_BROWSER_WSL_DISABLE_GPU === "1") {
     args.push(...wslHeadedLaunchArgs());
   }
   const envArgs = process.env.HARNERY_BROWSER_ARGS?.trim();
@@ -3005,6 +3367,166 @@ async function verifyBrowserProxyGate(
   emit.log(`browser proxy gate: ${observedIp} · expected IP confirmed`, "info");
 }
 
+/**
+ * How a `browse` run handles sign-in. `--login` opens the installed Google
+ * Chrome with nothing attached, because sites can detect an
+ * automation-controlled browser and disable the account that signed in with
+ * it. The attached window is reachable only through an explicit `--attached`.
+ */
+export function resolveLoginMode(
+  opts: Pick<BrowseOpts, "login" | "attached" | "controlFile" | "loginCloseFile">,
+): "none" | "plain" | "attached" {
+  if (opts.attached && !opts.login) throw new Error("--attached requires --login.");
+  if (opts.loginCloseFile && !opts.login) throw new Error("--login-close-file requires --login.");
+  if (opts.controlFile && !(opts.login && opts.attached)) {
+    throw new Error(
+      "--control-file requires --login --attached. A sign-in to a third-party account uses plain " +
+        "--login, which nothing can drive.",
+    );
+  }
+  if (!opts.login) return "none";
+  return opts.attached ? "attached" : "plain";
+}
+
+/**
+ * `--login`: spawn the installed Google Chrome directly on the shared
+ * persistent profile, with no DevTools protocol attached. Playwright enables
+ * its runtime hooks in every frame it drives, and sign-in verification vendors
+ * (X's is the reported case) detect that and fail the flow with no explanation.
+ * The person signs in here; cookies land in the same profile that later
+ * `browse` and `browse-session` runs open, so read-only captures inherit the
+ * session without ever repeating the sign-in under automation.
+ */
+async function runPlainLogin(
+  url: string,
+  profileDir: string,
+  loginCloseFile: string | null,
+  userAgent: string | undefined,
+  emit: { log: (message: string, level: "info" | "warn" | "error" | "debug") => void },
+): Promise<void> {
+  const executable = installedChromePath();
+  if (!executable) {
+    throw new Error(
+      "--login needs an installed Google Chrome at a standard path; none was found on this machine. " +
+        "Install Google Chrome; do not fall back to --attached for a third-party sign-in.",
+    );
+  }
+  mkdirSync(profileDir, { recursive: true });
+  const child = spawn(
+    executable,
+    [
+      `--user-data-dir=${profileDir}`,
+      "--no-first-run",
+      "--no-default-browser-check",
+      ...(userAgent ? [`--user-agent=${userAgent}`] : []),
+      url,
+    ],
+    { stdio: "ignore" },
+  );
+  const exited = new Promise<void>((resolveExit) => {
+    child.once("exit", () => resolveExit());
+    child.once("error", () => resolveExit());
+  });
+  const lifecycleAbort = new AbortController();
+  const waits: Promise<void>[] = [exited];
+  if (loginCloseFile) {
+    emit.log(
+      `[--login] Plain Google Chrome is open with nothing attached. Sign in, then close the window or create ${loginCloseFile}.`,
+      "info",
+    );
+    waits.push(waitForLoginCloseFile(loginCloseFile, lifecycleAbort.signal));
+  } else {
+    emit.log(
+      "[--login] Plain Google Chrome is open with nothing attached. Sign in, then close the window or press Enter here.",
+      "info",
+    );
+    waits.push(waitForTerminalEnter(lifecycleAbort.signal));
+  }
+  await Promise.race(waits);
+  lifecycleAbort.abort();
+  if (child.exitCode === null && child.signalCode === null) {
+    child.kill("SIGTERM");
+    await Promise.race([exited, new Promise((r) => setTimeout(r, 5000))]);
+  }
+  emit.log(`[--login] Chrome closed; cookies persisted in ${profileDir}.`, "info");
+}
+
+/**
+ * Under WSL, `--login` opens the Windows host's Google Chrome when one
+ * is installed. Some sign-in flows reject every browser running inside WSL,
+ * even a plain Linux Chrome, while the Windows desktop Chrome signs in
+ * normally. `HARNERY_BROWSER_WSL_PLAIN=linux` keeps the Linux Chrome.
+ */
+function useWindowsPlainLogin(): boolean {
+  if (!isWSL()) return false;
+  if ((process.env.HARNERY_BROWSER_WSL_PLAIN ?? "").toLowerCase() === "linux") return false;
+  return windowsChromePath() !== undefined;
+}
+
+/**
+ * The WSL form of `--login`: the person signs in through the Windows
+ * Chrome on a dedicated Windows profile with nothing attached. When the window
+ * closes, the profile's cookies for the sign-in site are read and merged into
+ * the shared cookie store, which later `browse` runs attach.
+ */
+async function runWindowsPlainLogin(
+  url: string,
+  storePath: string,
+  loginCloseFile: string | null,
+  emit: { log: (message: string, level: "info" | "warn" | "error" | "debug") => void },
+): Promise<void> {
+  const chromeLinux = windowsChromePath();
+  const localAppData = windowsLocalAppData();
+  if (!chromeLinux || !localAppData) {
+    throw new Error(
+      "--login under WSL needs the Windows Google Chrome and %LOCALAPPDATA%; neither was readable.",
+    );
+  }
+  const chromeWindows = wslPathToWindows(chromeLinux);
+  const profileWindows = windowsPlainProfile(localAppData);
+  const child = spawn(
+    chromeLinux,
+    [`--user-data-dir=${profileWindows}`, "--no-first-run", "--no-default-browser-check", url],
+    { stdio: "ignore" },
+  );
+  const exited = new Promise<void>((resolveExit) => {
+    child.once("exit", () => resolveExit());
+    child.once("error", () => resolveExit());
+  });
+  const lifecycleAbort = new AbortController();
+  const waits: Promise<void>[] = [exited];
+  const how = loginCloseFile ? `create ${loginCloseFile}` : "press Enter here";
+  emit.log(
+    `[--login] Windows Google Chrome is open with nothing attached (profile ${profileWindows}). Sign in, then close the window or ${how}.`,
+    "info",
+  );
+  waits.push(
+    loginCloseFile
+      ? waitForLoginCloseFile(loginCloseFile, lifecycleAbort.signal)
+      : waitForTerminalEnter(lifecycleAbort.signal),
+  );
+  await Promise.race(waits);
+  lifecycleAbort.abort();
+  stopWindowsChromeProfile(profileWindows);
+  await Promise.race([exited, new Promise((r) => setTimeout(r, 5000))]);
+  const domain = harvestDomain(url);
+  const cookies = harvestWindowsChromeCookies({ chromeWindows, profileWindows, domain });
+  if (cookies.length === 0) {
+    emit.log(
+      `[--login] No ${domain} cookies were found in the Windows profile; the sign-in may not have completed.`,
+      "warn",
+    );
+    return;
+  }
+  const jar = new CookieJar({ path: storePath, source: "harn-browse" });
+  jar.save(mergeCookies(jar.load(), cookies));
+  const names = [...new Set(cookies.map((cookie) => cookie.name))].sort().join(", ");
+  emit.log(
+    `[--login] Copied ${cookies.length} ${domain} cookies into ${storePath}: ${names}.`,
+    "info",
+  );
+}
+
 async function waitForLoginCloseFile(path: string, signal?: AbortSignal): Promise<void> {
   while (!existsSync(path) && !signal?.aborted) {
     await new Promise((resolve) => setTimeout(resolve, 250));