harnery 0.40.0 → 0.42.0

package/dist/commands/browse.js

@@ -1,10 +1,15 @@
+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 { chromium } from "playwright";
 import { PNG } from "pngjs";
 import { resolveBinName } from "../core/config.js";
+import { splitBatchSteps } from "../lib/browser/batch-steps.js";
 import { CAPTURE_FIDELITY_MISMATCH_THRESHOLD, compareBand, cropNativePng, decideFidelity, pngDimensions, } from "../lib/browser/capture-fidelity.js";
-import { Browser, browserProxyFromEnv, browserProxyGateFromEnv, captureDevOverlay, DEFAULT_CRITIQUE_RUBRIC, extractObservedIp, parseAssertSpec, runCritique, tilesFromFullPage, WEBRTC_PROXY_ONLY_ARG, writeNetscapeCookieFile, wslHeadedLaunchArgs, } from "../lib/browser/index.js";
+import { createPageDriver, createRng, DEFAULT_COLLECT_LIMITS, PACING_LIMITS, parseProbability, parseRange, presetNames, randomSeed, resolveCollectSpec, runCollect, scrollPacingFromEnv, } from "../lib/browser/collect/index.js";
+import { Browser, browserProxyFromEnv, browserProxyGateFromEnv, captureDevOverlay, chromeMajorFromExecutable, DEFAULT_CRITIQUE_RUBRIC, extractObservedIp, installedChromeChannel, installedChromePath, parseAssertSpec, resolveUserAgent, runCritique, tilesFromFullPage, WEBRTC_PROXY_ONLY_ARG, writeNetscapeCookieFile, wslHeadedLaunchArgs, } from "../lib/browser/index.js";
+import { isWSL } from "../lib/browser/launch-args.js";
 import { allocateTileBudget, validatePageReviewAllocation, } from "../lib/browser/page-review-budget.js";
 import { PAGE_REVIEW_CAPTURE_PLAN_SCHEMA, } from "../lib/browser/page-review-contracts.js";
 import { findPackTile, gateHitsFromEnvelope, readPackContext, tileId, writePackContext, writePackExpandedTile, } from "../lib/browser/page-review-pack.js";
@@ -17,7 +22,9 @@ import { startBrowserSessionServer, } from "../lib/browser/session-control.js";
 import { captureThumbnailFingerprint, registerCaptureThumbnail, } from "../lib/browser/thumbnail-association.js";
 import { reviewCandidateRects } from "../lib/browser/tiling.js";
 import { diffAgainstBaseline, saveBaseline, } from "../lib/browser/visual-diff.js";
-import { applyExtraCookies, CookieJar } from "../lib/cookies/index.js";
+import { harvestDomain, harvestWindowsChromeCookies, stopWindowsChromeProfile, windowsChromePath, windowsLocalAppData, windowsPlainProfile, wslPathToWindows, } from "../lib/browser/windows-chrome.js";
+import { applyExtraCookies, CookieJar, mergeCookies } from "../lib/cookies/index.js";
+import { commandPaceGate } from "../lib/pace/index.js";
 /**
  * `harn browse <url>`: Playwright-backed page navigation with shared
  * cookie jar + persistent profile + diagnostics capture for LLM
@@ -70,26 +77,66 @@ export function registerBrowseCommand(program, emitParam, context, binName = res
         .option("--capture-evaluate <js>", "In trio mode, evaluate JS inside the exact screenshot viewport immediately before capture; result is written as captureEval")
         .option("--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, previous = []) => [...previous, value], [])
+        .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")
+        .option("--viewport <preset|WxH>", "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>", "Emulate prefers-color-scheme for the whole session: light | dark. " +
         "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")
-        .option("--headed", "Headed mode for one-off (no auth-flow framing)")
+        .option("--control-file <path>", "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("--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.", (value, prev = []) => [...prev, value], [])
+        "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, prev = []) => [...prev, value], [])
         .option("--proxy-from-env", "Pass HTTP(S)_PROXY to Playwright as an authenticated browser proxy. " +
         "Credentials stay in the child environment, never command arguments. " +
         "When the host also injects the HARNERY_BROWSER_PROXY_* gate variables, " +
         "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("--export-cookies <path>", "Write live profile cookies as an owner-only Netscape cookies.txt file on close")
@@ -296,7 +343,8 @@ async function runBrowse(url, opts, context) {
         : 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) {
@@ -322,30 +370,58 @@ async function runBrowse(url, opts, context) {
     }
     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(`Login close signal already exists at ${loginCloseFile}. Remove the stale file before launching.`);
     }
+    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,
         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;
     let controlServer = null;
@@ -382,6 +458,10 @@ async function runBrowse(url, opts, context) {
         if (opts.batch) {
             batchResult = await runBatch(browser, opts.batch, Number.parseInt(opts.timeout, 10));
         }
+        if (collectPlan) {
+            await runCollectMode(browser, collectPlan);
+            return;
+        }
         let evalResult;
         if (opts.evaluate) {
             evalResult = await browser.evaluate(opts.evaluate);
@@ -772,11 +852,11 @@ async function runBrowse(url, opts, context) {
             const lifecycleAbort = new AbortController();
             const closeWaits = [];
             if (loginCloseFile) {
-                emit.log(`[--login] Headed Chromium is open. Drive the visible window now. Create ${loginCloseFile} to close cleanly.`, "info");
+                emit.log(`[--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.", "info");
+                emit.log("[--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));
             }
             if (controlServer) {
@@ -912,6 +992,137 @@ async function runBrowse(url, opts, context) {
             process.exitCode = receivedSignal === "SIGINT" ? 130 : 143;
     }
 }
+function parsePositiveInt(raw, flag) {
+    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) {
+    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 = {
+        ...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, plan) {
+    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;
+    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;
+}
 async function runBatch(browser, batch, defaultTimeoutMs) {
     const result = { clipboardReads: [] };
     const steps = splitBatchSteps(batch);
@@ -982,27 +1193,6 @@ async function runBatch(browser, batch, defaultTimeoutMs) {
     }
     return result;
 }
-function splitBatchSteps(input) {
-    const steps = [];
-    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
 // ---------------------------------------------------------------------------
@@ -2035,15 +2225,50 @@ function summarizeDiagnostics(diag) {
 }
 /**
  * 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, headed) {
+    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;
+    }
+    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) {
+    if (channel === "chrome") {
+        const exe = installedChromePath();
+        return exe ? chromeMajorFromExecutable(exe) : undefined;
+    }
+    try {
+        return chromeMajorFromExecutable(chromium.executablePath());
+    }
+    catch {
+        return undefined;
+    }
+}
 function resolveLaunchArgs(opts, headed, proxyEnabled) {
     const args = [];
-    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();
@@ -2067,6 +2292,124 @@ async function verifyBrowserProxyGate(browser, gate) {
     }
     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) {
+    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, profileDir, loginCloseFile, userAgent, emit) {
+    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((resolveExit) => {
+        child.once("exit", () => resolveExit());
+        child.once("error", () => resolveExit());
+    });
+    const lifecycleAbort = new AbortController();
+    const waits = [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() {
+    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, storePath, loginCloseFile, emit) {
+    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((resolveExit) => {
+        child.once("exit", () => resolveExit());
+        child.once("error", () => resolveExit());
+    });
+    const lifecycleAbort = new AbortController();
+    const waits = [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, signal) {
     while (!existsSync(path) && !signal?.aborted) {
         await new Promise((resolve) => setTimeout(resolve, 250));

package/dist/commands/checkpoint.js

@@ -1,3 +1,4 @@
+import { ADAPTERS, normalizeAdapter } from "../core/adapter.js";
 import { monorepoRoot, resolveOwner } from "../core/agents/index.js";
 import { readLiveCoordinationRow } from "../core/agents/state/live-coordination-view.js";
 import { checkpointContext, readContextState, readLatestCapsule, } from "../core/context/index.js";
@@ -58,7 +59,7 @@ export function registerCheckpointCommand(program, emit, context) {
         .description("Create a durable context-continuity capsule for the current work")
         .option("--session <id>", "Session id (defaults to the current agent heartbeat)")
         .option("--instance <id>", "Agent instance id (defaults to the current owner)")
-        .option("--adapter <id>", "claude-code, codex, or cursor (inferred from heartbeat)")
+        .option("--adapter <id>", `${ADAPTERS.join(", ")} (inferred from heartbeat)`)
         .option("--reason <reason>", "manual, pressure, pre_compact, or session_end", "manual")
         .option("--note <text>", "Short continuation note for the recovered agent")
         .option("--json", "Structured JSON output")
@@ -68,7 +69,7 @@ export function registerCheckpointCommand(program, emit, context) {
             const reason = parseCheckpointReason(opts.reason);
             const identity = resolveContinuityIdentity(context, opts);
             if (!identity.adapter) {
-                throw new Error("could not infer the adapter; pass --adapter claude-code|codex|cursor");
+                throw new Error(`could not infer the adapter; pass --adapter ${ADAPTERS.join("|")}`);
             }
             const result = checkpointContext(identity.coordRoot, {
                 sessionId: identity.sessionId,
@@ -135,18 +136,13 @@ function resolveContinuityIdentity(context, opts) {
     return { coordRoot, instanceId, sessionId, adapter };
 }
 function adapterFromPlatform(platform) {
-    if (platform === "claude-code")
-        return "claude-code";
-    if (platform === "cursor")
-        return "cursor";
-    if (platform === "codex")
-        return "codex";
-    return null;
+    return normalizeAdapter(platform);
 }
 function parseAdapter(value) {
-    if (value === "claude-code" || value === "codex" || value === "cursor")
-        return value;
-    throw new Error(`invalid adapter "${value}"; expected claude-code, codex, or cursor`);
+    const adapter = normalizeAdapter(value);
+    if (adapter)
+        return adapter;
+    throw new Error(`invalid adapter "${value}"; expected one of ${ADAPTERS.join(", ")}`);
 }
 function parseCheckpointReason(value) {
     if (value === "manual" ||

package/dist/commands/claude-desktop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude-desktop.d.ts","sourceRoot":"","sources":["../../src/commands/claude-desktop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAU1E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,QAAQ,CAAC,EAAE,qBAAqB,GAC/B,IAAI,CA8JN"}
+{"version":3,"file":"claude-desktop.d.ts","sourceRoot":"","sources":["../../src/commands/claude-desktop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAiB1E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,QAAQ,CAAC,EAAE,qBAAqB,GAC/B,IAAI,CAoNN"}