browse 0.8.4 → 0.8.5-alpha-8b83bb7

package/README.md

@@ -57,10 +57,14 @@ Every driver command accepts the same flags to pick where the browser runs. Mix
 | `--auto-connect` | Auto-discover and attach to a local Chrome with remote debugging enabled |
 | `--cdp <url\|port>` | Attach directly to a CDP endpoint (port, `http(s)://`, or `ws(s)://`) |
 | `--target-id <id>` | Select a specific CDP target when attaching to an existing browser |
+| `--chrome-arg <flag>` | Append a Chrome launch arg on top of the defaults (repeatable, managed-local only) |
+| `--ignore-default-chrome-arg <flag>` | Drop a specific Chrome default launch arg (repeatable, managed-local only) |
+| `--no-default-chrome-args` | Launch without any of Chrome's default args (managed-local only) |
 
 ```bash
 browse open https://example.com                 # default target
 browse open https://example.com --local --headed
+browse open https://example.com --local --headed --chrome-arg=--no-focus-on-navigate
 browse open https://example.com --remote
 browse open https://example.com --auto-connect
 browse open https://example.com --cdp 9222

package/dist/commands/screenshot.js

@@ -1,13 +1,17 @@
+import { closeSync, openSync, statSync, unlinkSync } from "node:fs";
+import { resolve } from "node:path";
 import { Flags } from "@oclif/core";
 import { BrowseCommand } from "../base.js";
 import { driverCommandFlags, parseClip, runDriverCommandFromFlags, } from "../lib/driver/command-cli.js";
 export default class Screenshot extends BrowseCommand {
     static description = "Capture a screenshot of the active browser page.";
     static examples = [
+        "browse screenshot",
         "browse screenshot --path page.png",
-        "browse screenshot --full-page --path page.png",
+        "browse screenshot --full-page",
         "browse screenshot --type jpeg --quality 80",
         "browse screenshot --clip 0,0,800,600 --path clipped.png",
+        "browse screenshot --base64",
     ];
     static flags = {
         ...driverCommandFlags,
@@ -15,6 +19,10 @@ export default class Screenshot extends BrowseCommand {
             description: "Whether CSS animations run during capture.",
             options: ["allow", "disabled"],
         }),
+        base64: Flags.boolean({
+            description: "Print base64 to stdout instead of writing a file (legacy default).",
+            exclusive: ["path"],
+        }),
         caret: Flags.string({
             description: "Whether text caret is hidden during capture.",
             options: ["hide", "initial"],
@@ -28,7 +36,7 @@ export default class Screenshot extends BrowseCommand {
         }),
         path: Flags.string({
             char: "p",
-            description: "Write the screenshot to a file. Without this flag, base64 is printed.",
+            description: "Write the screenshot to this file. Defaults to screenshot-<timestamp>.png (or .jpeg with --type jpeg) in the current directory.",
             helpValue: "<path>",
         }),
         quality: Flags.integer({
@@ -42,14 +50,77 @@ export default class Screenshot extends BrowseCommand {
     };
     async run() {
         const { flags } = await this.parse(Screenshot);
-        await runDriverCommandFromFlags("screenshot", {
-            animations: flags.animations,
-            caret: flags.caret,
-            clip: parseClip(flags.clip),
-            fullPage: flags["full-page"],
-            path: flags.path,
-            quality: flags.quality,
-            type: flags.type,
-        }, flags);
+        const defaultPath = getDefaultPathFromFlags(flags);
+        try {
+            await runDriverCommandFromFlags("screenshot", {
+                animations: flags.animations,
+                caret: flags.caret,
+                clip: parseClip(flags.clip),
+                fullPage: flags["full-page"],
+                path: flags.path ?? defaultPath,
+                quality: flags.quality,
+                type: flags.type,
+            }, flags);
+        }
+        catch (error) {
+            if (defaultPath)
+                removeIfEmpty(defaultPath);
+            throw error;
+        }
+    }
+}
+// Generous upper bound on filename-collision retries; far beyond any real
+// same-second burst, it just guarantees the loop below always terminates.
+const MAX_RESERVE_ATTEMPTS = 1000;
+/**
+ * Resolves the file the screenshot should be written to, or undefined when the
+ * driver should return base64 (explicit --path is handled separately; --base64
+ * opts out of a file entirely).
+ */
+function getDefaultPathFromFlags(flags) {
+    if (flags.path || flags.base64)
+        return undefined;
+    return reserveDefaultScreenshotPath(flags.type);
+}
+/**
+ * Picks the next free screenshot-<timestamp>[-<counter>].<type> name in the
+ * current directory and reserves it. "Reserve" = create the file with an
+ * exclusive open (`wx` → O_CREAT|O_EXCL), which atomically fails with EEXIST if
+ * the name already exists, so two concurrent runs can never claim the same
+ * file. On EEXIST we advance the counter and try the next name.
+ */
+function reserveDefaultScreenshotPath(type) {
+    const now = new Date();
+    const pad = (value) => String(value).padStart(2, "0");
+    const stamp = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}` +
+        `-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+    const extension = type === "jpeg" ? "jpeg" : "png";
+    for (let counter = 1; counter <= MAX_RESERVE_ATTEMPTS; counter += 1) {
+        const suffix = counter === 1 ? "" : `-${counter}`;
+        const candidate = resolve(`screenshot-${stamp}${suffix}.${extension}`);
+        try {
+            // Exclusive create reserves the name; close immediately since the driver
+            // (re)writes the file. The empty placeholder is cleaned up on failure.
+            closeSync(openSync(candidate, "wx"));
+            return candidate;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+    }
+    throw new Error(`Could not reserve a screenshot filename after ${MAX_RESERVE_ATTEMPTS} attempts; pass --path to choose one.`);
+}
+// Removes the reserved placeholder when the screenshot failed before the driver
+// wrote to it. `path` is always a file we created via openSync above, so the
+// isFile guard is just defensive against an unexpected directory/symlink.
+function removeIfEmpty(path) {
+    try {
+        const stats = statSync(path);
+        if (stats.isFile() && stats.size === 0)
+            unlinkSync(path);
+    }
+    catch {
+        // Best effort: leave the placeholder behind rather than mask the error.
     }
 }

package/dist/hooks/command-not-found.js

@@ -0,0 +1,45 @@
+import { Errors } from "@oclif/core";
+import { suggestCommand } from "../lib/command-suggestions.js";
+import { captureCommandNotFound } from "../lib/telemetry.js";
+function toSpaced(commandId) {
+    return commandId.replaceAll(":", " ");
+}
+const hook = async function ({ config, id }) {
+    let attempted = "";
+    let suggestion = null;
+    try {
+        const commandIds = config.commands
+            .filter((command) => !command.hidden)
+            .map((command) => command.id);
+        const result = suggestCommand(id, commandIds);
+        attempted = result.attempted;
+        suggestion = result.suggestion;
+        if (suggestion &&
+            !config.findCommand(suggestion) &&
+            !config.findTopic(suggestion)) {
+            // Guards against alias targets drifting out of the command tree.
+            suggestion = null;
+        }
+        const displayAttempted = toSpaced(attempted || (id.split(":")[0] ?? id));
+        const didYouMean = suggestion
+            ? ` Did you mean "${config.bin} ${toSpaced(suggestion)}"?`
+            : "";
+        process.stderr.write(`"${config.bin} ${displayAttempted}" is not a ${config.bin} command.${didYouMean} Run ${config.bin} --help for all commands.\n`);
+    }
+    catch {
+        // Suggestions are best-effort and must never mask the not-found error.
+    }
+    try {
+        // Awaited so the event is delivered before the process exits; the
+        // transport aborts after a short timeout, so this cannot hang the CLI.
+        await captureCommandNotFound(config.version, attempted || null, suggestion);
+    }
+    catch {
+        // Best-effort telemetry should never affect CLI behavior.
+    }
+    // Re-throw oclif's standard not-found error. Returning normally from a
+    // command_not_found hook makes oclif treat the invocation as handled
+    // (exit 0), so this throw preserves the default error and exit code 2.
+    throw new Errors.CLIError(`command ${id} not found`);
+};
+export default hook;

package/dist/lib/command-suggestions.js

@@ -0,0 +1,112 @@
+/**
+ * Suggestion engine for unknown commands.
+ *
+ * oclif's spaced-topic parsing glues unknown leading argv tokens into the
+ * attempted command id (e.g. `browse opne https://example.com` arrives as
+ * `opne:https://example.com`), so the id may contain user-provided values.
+ * Everything here works on a sanitized token prefix and never returns raw
+ * argv content beyond the tokens that matched a known command shape.
+ */
+import { distance } from "fastest-levenshtein";
+/**
+ * Old Commander-era syntax (and common agent guesses) mapped to the current
+ * command tree. Keys and values are colon-separated oclif ids; values may
+ * also be topics (e.g. `cloud:contexts`, which prints topic help).
+ */
+export const aliasSuggestions = new Map([
+    ["sessions", "cloud:sessions:list"],
+    ["sessions:list", "cloud:sessions:list"],
+    ["sessions:create", "cloud:sessions:create"],
+    ["sessions:get", "cloud:sessions:get"],
+    ["projects", "cloud:projects:list"],
+    ["projects:list", "cloud:projects:list"],
+    ["contexts", "cloud:contexts"],
+    ["extensions", "cloud:extensions"],
+    ["search", "cloud:search"],
+    ["fetch", "cloud:fetch"],
+    ["goto", "open"],
+    ["navigate", "open"],
+]);
+const safeTokenPattern = /^[A-Za-z][A-Za-z0-9_-]*$/;
+const maxCommandTokens = 4;
+const maxSuggestionDistance = 5;
+/**
+ * Extracts the leading command-shaped tokens from an attempted id, stopping
+ * at the first token that does not look like a command word (URLs, selectors,
+ * flags, and other argument-like values).
+ */
+export function extractCommandTokens(id) {
+    const tokens = [];
+    for (const token of id.split(":")) {
+        if (tokens.length >= maxCommandTokens || !safeTokenPattern.test(token)) {
+            break;
+        }
+        tokens.push(token.toLowerCase());
+    }
+    return tokens;
+}
+function tokenThreshold(token) {
+    return Math.max(2, Math.floor(token.length / 3));
+}
+/**
+ * Segment-aligned fuzzy distance between a token prefix and a command id.
+ * Only command ids with the same number of segments are considered, and every
+ * token must be within its own edit-distance threshold of the corresponding
+ * segment. This means a trailing token can only ever be retained in the
+ * attempted command when it itself looks like a typo of a real command
+ * segment — free-form user values can never ride along.
+ */
+function prefixDistance(tokens, commandId) {
+    const segments = commandId.split(":");
+    if (segments.length !== tokens.length) {
+        return null;
+    }
+    let total = 0;
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i] ?? "";
+        const segmentDistance = distance(token, segments[i] ?? "");
+        if (segmentDistance > tokenThreshold(token)) {
+            return null;
+        }
+        total += segmentDistance;
+    }
+    return total > maxSuggestionDistance ? null : total;
+}
+/**
+ * Computes a suggestion for an unknown command id. Explicit aliases win over
+ * fuzzy matches, and longer token prefixes win over shorter ones so that
+ * `auth status` resolves before `auth`. Returns only the matched prefix as
+ * `attempted` (or the first token when nothing matches) so user-provided
+ * values never escape into messaging or telemetry.
+ */
+export function suggestCommand(id, commandIds) {
+    const tokens = extractCommandTokens(id);
+    if (tokens.length === 0) {
+        return { attempted: "", suggestion: null };
+    }
+    for (let length = tokens.length; length >= 1; length--) {
+        const attempted = tokens.slice(0, length).join(":");
+        const alias = aliasSuggestions.get(attempted);
+        if (alias) {
+            return { attempted, suggestion: alias };
+        }
+    }
+    let best;
+    for (let length = tokens.length; length >= 1; length--) {
+        const prefix = tokens.slice(0, length);
+        for (const commandId of commandIds) {
+            const prefixDist = prefixDistance(prefix, commandId);
+            if (prefixDist !== null && (!best || prefixDist < best.distance)) {
+                best = {
+                    attempted: prefix.join(":"),
+                    suggestion: commandId,
+                    distance: prefixDist,
+                };
+            }
+        }
+    }
+    if (best) {
+        return { attempted: best.attempted, suggestion: best.suggestion };
+    }
+    return { attempted: tokens[0] ?? "", suggestion: null };
+}

package/dist/lib/driver/command-cli.js

@@ -1,15 +1,18 @@
 import { Flags } from "@oclif/core";
-import { autoConnectFlag, cdpFlag, headedFlag, headlessFlag, localFlag, remoteFlag, sessionFlag, sessionName, targetIdFlag, } from "./flags.js";
+import { autoConnectFlag, cdpFlag, chromeArgFlag, headedFlag, headlessFlag, ignoreDefaultChromeArgFlag, localFlag, noDefaultChromeArgsFlag, remoteFlag, sessionFlag, sessionName, targetIdFlag, } from "./flags.js";
 import { getDriverStatus } from "./daemon/client.js";
-import { resolveConnectionTarget } from "./mode.js";
+import { hasChromeArgFlags, resolveConnectionTarget, } from "./mode.js";
 import { outputJson } from "../output.js";
 import { runDriverCommandWithTarget } from "./runtime.js";
 export const driverCommandFlags = {
     "auto-connect": autoConnectFlag,
     cdp: cdpFlag,
+    "chrome-arg": chromeArgFlag,
     headed: headedFlag,
     headless: headlessFlag,
+    "ignore-default-chrome-arg": ignoreDefaultChromeArgFlag,
     local: localFlag,
+    "no-default-chrome-args": noDefaultChromeArgsFlag,
     remote: remoteFlag,
     session: sessionFlag,
     "target-id": targetIdFlag,
@@ -52,6 +55,7 @@ export function hasExplicitDriverTarget(flags) {
         flags.remote ||
         flags["auto-connect"] ||
         flags.cdp ||
+        hasChromeArgFlags(flags) ||
         flags["target-id"] ||
         flags.headed ||
         flags.headless);
@@ -60,6 +64,7 @@ function hasModeOnlyFlag(flags) {
     return Boolean((flags.local || flags.remote) &&
         !flags["auto-connect"] &&
         !flags.cdp &&
+        !hasChromeArgFlags(flags) &&
         !flags["target-id"] &&
         !flags.headed &&
         !flags.headless &&

package/dist/lib/driver/commands/selectors.js

@@ -1,3 +1,4 @@
+import { DriverError } from "../errors.js";
 export function emptyRefMaps() {
     return { urlMap: {}, xpathMap: {} };
 }
@@ -24,7 +25,7 @@ export function resolveSelector(selector, refMaps) {
         return selector;
     const xpath = refMaps.xpathMap[ref];
     if (!xpath) {
-        throw new Error(`Unknown ref "${ref}" - run browse snapshot first to populate refs (have ${Object.keys(refMaps.xpathMap).length} refs).`);
+        throw new DriverError(`Unknown ref "${ref}" - run browse snapshot first to populate refs (have ${Object.keys(refMaps.xpathMap).length} refs).`, { code: "stale_ref" });
     }
     return xpath;
 }

package/dist/lib/driver/daemon/client.js

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { promises as fs } from "node:fs";
 import net from "node:net";
-import { fail } from "../../errors.js";
+import { CommandFailure, fail } from "../../errors.js";
 import { targetsCompatible } from "../mode.js";
 import { cleanupDaemonFiles, ensureRuntimeDir, getLockPath, getPidPath, getSocketPath, PRIVATE_FILE_MODE, } from "./paths.js";
 import { isProcessAlive } from "./process.js";
@@ -15,7 +15,7 @@ export async function ensureDriverDaemon({ session, target, }) {
     }
     const locked = await acquireLock(session);
     if (!locked) {
-        fail(`Timed out waiting for driver daemon lock for session "${session}".`);
+        fail(`Timed out waiting for driver daemon lock for session "${session}".`, 1, { resultCode: "daemon_lock_timeout" });
     }
     try {
         const afterLock = await tryDriverStatus(session);
@@ -24,7 +24,7 @@ export async function ensureDriverDaemon({ session, target, }) {
             return;
         }
         if (await isDaemonPidAlive(session)) {
-            fail(`Driver daemon session "${session}" is running but not responding. Run browse stop --session ${session} --force to clean it up.`);
+            fail(`Driver daemon session "${session}" is running but not responding. Run browse stop --session ${session} --force to clean it up.`, 1, { resultCode: "daemon_unresponsive" });
         }
         spawnDaemon(session, target);
         await waitForSocketReady(getSocketPath(session), 30_000);
@@ -123,7 +123,7 @@ async function sendDriverRequest(session, request) {
             return new Error(`Driver daemon session "${session}" closed ${detail}.`);
         };
         const timeout = setTimeout(() => {
-            failRequest(new Error(`Timed out waiting for driver daemon session "${session}".`));
+            failRequest(new CommandFailure(`Timed out waiting for driver daemon session "${session}".`, 1, { resultCode: "daemon_socket_timeout" }));
         }, 35_000);
         socket.on("connect", () => {
             socket.write(`${JSON.stringify(request)}\n`);
@@ -136,7 +136,12 @@ async function sendDriverRequest(session, request) {
             try {
                 const response = ResponseSchema.parse(JSON.parse(buffer.slice(0, newline)));
                 if (response.type === "error") {
-                    failRequest(new Error(response.error));
+                    failRequest(new CommandFailure(response.error, 1, {
+                        ...(response.code ? { resultCode: response.code } : {}),
+                        ...(response.httpStatus !== undefined
+                            ? { httpStatus: response.httpStatus }
+                            : {}),
+                    }));
                     return;
                 }
                 completeRequest(response.data);
@@ -161,7 +166,9 @@ async function sendDriverRequest(session, request) {
 function spawnDaemon(session, target) {
     const entrypoint = process.argv[1];
     if (!entrypoint) {
-        fail("Unable to locate browse CLI entrypoint for daemon startup.");
+        fail("Unable to locate browse CLI entrypoint for daemon startup.", 1, {
+            resultCode: "daemon_spawn_failed",
+        });
     }
     const child = spawn(process.execPath, [
         entrypoint,

package/dist/lib/driver/daemon/protocol.js

@@ -32,7 +32,9 @@ export const SuccessResponseSchema = z.object({
     type: z.literal("success"),
 });
 export const ErrorResponseSchema = z.object({
+    code: z.string().optional(),
     error: z.string(),
+    httpStatus: z.number().optional(),
     id: z.string().optional(),
     type: z.literal("error"),
 });

package/dist/lib/driver/daemon/server.js

@@ -1,5 +1,6 @@
 import net from "node:net";
 import readline from "node:readline";
+import { DriverError } from "../errors.js";
 import { DriverSessionManager } from "../session-manager.js";
 import { cleanupDaemonFiles, ensureRuntimeDir, getPidPath, getSocketPath, writePrivateFile, } from "./paths.js";
 import { parseRequest, serializeResponse, } from "./protocol.js";
@@ -83,7 +84,7 @@ async function handleLine(line, socket, manager) {
         request = parseRequest(line);
     }
     catch (error) {
-        await writeResponse(socket, { error: formatError(error), type: "error" });
+        await writeResponse(socket, { ...formatError(error), type: "error" });
         return false;
     }
     try {
@@ -124,7 +125,7 @@ async function handleLine(line, socket, manager) {
     }
     catch (error) {
         await writeResponse(socket, {
-            error: formatError(error),
+            ...formatError(error),
             id: request.id,
             type: "error",
         });
@@ -161,5 +162,15 @@ function endSocket(socket) {
     });
 }
 function formatError(error) {
-    return error instanceof Error ? error.message : String(error);
+    const message = error instanceof Error ? error.message : String(error);
+    if (error instanceof DriverError) {
+        return {
+            code: error.code,
+            error: message,
+            ...(error.httpStatus !== undefined
+                ? { httpStatus: error.httpStatus }
+                : {}),
+        };
+    }
+    return { error: message };
 }

package/dist/lib/driver/errors.js

@@ -0,0 +1,16 @@
+/**
+ * Typed driver error. The daemon serializes `code`/`httpStatus` into error
+ * responses so the client can record a telemetry result code and agents get
+ * a stable, machine-readable failure reason alongside the human message.
+ */
+export class DriverError extends Error {
+    code;
+    httpStatus;
+    constructor(message, options) {
+        super(message, options.cause === undefined ? {} : { cause: options.cause });
+        this.name = "DriverError";
+        this.code = options.code;
+        if (options.httpStatus !== undefined)
+            this.httpStatus = options.httpStatus;
+    }
+}

package/dist/lib/driver/flags.js

@@ -27,6 +27,19 @@ export const targetIdFlag = Flags.string({
     description: "Select a specific CDP target when attaching to an existing browser.",
     helpValue: "<target-id>",
 });
+export const chromeArgFlag = Flags.string({
+    description: "Add a Chrome launch arg for managed local sessions. Repeatable.",
+    helpValue: "<flag>",
+    multiple: true,
+});
+export const ignoreDefaultChromeArgFlag = Flags.string({
+    description: "Drop one of Chrome's default launch args for managed local sessions. Repeatable.",
+    helpValue: "<flag>",
+    multiple: true,
+});
+export const noDefaultChromeArgsFlag = Flags.boolean({
+    description: "Launch managed local Chrome without any of its default launch args.",
+});
 export function sessionName(value) {
     return value ?? process.env.BROWSE_SESSION ?? "default";
 }

package/dist/lib/driver/mode.js

@@ -1,3 +1,4 @@
+import { isDeepStrictEqual } from "node:util";
 import { fail } from "../errors.js";
 import { getRemote } from "./remote-binding.js";
 import { resolveWsTarget } from "./resolve-ws.js";
@@ -11,10 +12,25 @@ function resolveHeadless(flags) {
         return true;
     return true;
 }
+export function hasChromeArgFlags(flags) {
+    return chromeArgFlagsInUse(flags).length > 0;
+}
+function chromeArgFlagsInUse(flags) {
+    const names = [];
+    if (flags["chrome-arg"]?.length)
+        names.push("--chrome-arg");
+    if (flags["ignore-default-chrome-arg"]?.length)
+        names.push("--ignore-default-chrome-arg");
+    if (flags["no-default-chrome-args"])
+        names.push("--no-default-chrome-args");
+    return names;
+}
 export async function resolveConnectionTarget(flags) {
+    const chromeArgFlags = chromeArgFlagsInUse(flags);
     if (flags.cdp) {
         failOnConflictingFlags("--cdp", [
             flags["auto-connect"] ? "--auto-connect" : null,
+            ...chromeArgFlags,
             flags.local ? "--local" : null,
             flags.remote ? "--remote" : null,
             flags.headed ? "--headed" : null,
@@ -31,6 +47,7 @@ export async function resolveConnectionTarget(flags) {
     }
     if (flags["auto-connect"]) {
         failOnConflictingFlags("--auto-connect", [
+            ...chromeArgFlags,
             flags.local ? "--local" : null,
             flags.remote ? "--remote" : null,
             flags.headed ? "--headed" : null,
@@ -43,36 +60,76 @@ export async function resolveConnectionTarget(flags) {
     }
     if (flags.remote) {
         failOnConflictingFlags("--remote", [
+            ...chromeArgFlags,
             flags.headed ? "--headed" : null,
             flags.headless ? "--headless" : null,
         ]);
         return (await getRemote()).resolveExplicitRemoteTarget(flags);
     }
     if (flags.local) {
-        return { kind: "managed-local", headless: resolveHeadless(flags) };
+        return managedLocalTarget(resolveHeadless(flags), resolveChromeArgs(flags));
     }
     const autoRemote = (await getRemote()).autoSelectRemoteTarget();
     if (autoRemote) {
         failOnConflictingFlags("remote mode", [
+            ...chromeArgFlags,
             flags.headed ? "--headed" : null,
             flags.headless ? "--headless" : null,
         ]);
         return autoRemote;
     }
-    return { kind: "managed-local", headless: resolveHeadless(flags) };
+    return managedLocalTarget(resolveHeadless(flags), resolveChromeArgs(flags));
+}
+function managedLocalTarget(headless, chromeArgs) {
+    return {
+        ...(chromeArgs.args?.length ? { chromeArgs: chromeArgs.args } : {}),
+        ...(chromeArgs.ignoreDefaultArgs !== undefined
+            ? { ignoreDefaultArgs: chromeArgs.ignoreDefaultArgs }
+            : {}),
+        kind: "managed-local",
+        headless,
+    };
 }
 function failOnConflictingFlags(flag, candidates) {
     const conflicts = candidates.filter((candidate) => Boolean(candidate));
     if (conflicts.length > 0)
         fail(`${flag} cannot be combined with ${conflicts.join(", ")}.`);
 }
+function resolveChromeArgs(flags) {
+    const args = flags["chrome-arg"]?.filter((arg) => arg.length > 0);
+    const ignoreDefaults = flags["ignore-default-chrome-arg"]?.filter((arg) => arg.length > 0);
+    const noDefaults = flags["no-default-chrome-args"] === true;
+    if (noDefaults && ignoreDefaults?.length) {
+        fail("--no-default-chrome-args cannot be combined with --ignore-default-chrome-arg.");
+    }
+    const resolved = {};
+    if (args?.length)
+        resolved.args = args;
+    if (noDefaults) {
+        resolved.ignoreDefaultArgs = true;
+    }
+    else if (ignoreDefaults?.length) {
+        resolved.ignoreDefaultArgs = ignoreDefaults;
+    }
+    return resolved;
+}
 export function targetsCompatible(left, right) {
     if (left.kind !== right.kind)
         return false;
     if (left.kind === "managed-local" && right.kind === "managed-local")
-        return left.headless === right.headless;
+        return (left.headless === right.headless &&
+            chromeArgsEqual(left.chromeArgs, right.chromeArgs) &&
+            ignoreDefaultArgsEqual(left.ignoreDefaultArgs, right.ignoreDefaultArgs));
     if (left.kind === "cdp" && right.kind === "cdp") {
         return left.endpoint === right.endpoint && left.targetId === right.targetId;
     }
     return true;
 }
+function chromeArgsEqual(left, right) {
+    return isDeepStrictEqual(left ?? [], right ?? []);
+}
+function ignoreDefaultArgsEqual(left, right) {
+    if (left === true || right === true)
+        return left === right;
+    return chromeArgsEqual(Array.isArray(left) ? left : undefined, Array.isArray(right) ? right : undefined);
+}

package/dist/lib/driver/remote.disabled.js

@@ -13,6 +13,21 @@ export function autoSelectRemoteTarget() {
 export function remoteStagehandOptions() {
     throw new Error(DISABLED_MESSAGE);
 }
+export function classifyRemoteInitError(error) {
+    // Remote targets cannot be selected in a local-only build, so this is only
+    // reachable if a remote error somehow surfaces anyway; preserve it as-is.
+    return {
+        code: "remote_session_create_failed",
+        message: error instanceof Error ? error.message : String(error),
+    };
+}
+export function driverInitHints() {
+    // Key-free variants: a local-only artifact must not mention the API key.
+    return {
+        chromeNotFound: "No Chrome or Chromium found on this machine. Install one (Linux: apt install chromium \u00b7 macOS: brew install --cask google-chrome, or Chromium with CHROME_PATH set) or attach to a running browser with --cdp <port>.",
+        repeatedInitFailure: " (failing repeatedly — check your browser setup or run browse doctor)",
+    };
+}
 export function remoteDoctorCheck() {
     return { ok: true, message: "remote disabled (local-only build)" };
 }