camoufox-cli 0.4.0__tar.gz → 0.6.0__tar.gz

camoufox_cli-0.6.0/.claude/worktrees/busy-darwin-6b67a6/.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "camoufox-cli",
+  "owner": {
+    "name": "Benn Huang"
+  },
+  "metadata": {
+    "description": "Anti-detect browser automation CLI & Skills for AI agents, powered by Camoufox",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "camoufox-cli",
+      "description": "Anti-detect browser automation skill with fingerprint spoofing for AI agents",
+      "source": "./",
+      "skills": [
+        "./skills/camoufox-cli"
+      ]
+    }
+  ]
+}

{camoufox_cli-0.4.0 → camoufox_cli-0.6.0/.claude/worktrees/busy-darwin-6b67a6}/README.md

@@ -40,6 +40,10 @@ On Linux, install system dependencies with:
 camoufox-cli install --with-deps
 ```
 
+The browser is downloaded from GitHub releases. If the anonymous GitHub API
+rate limit is exhausted (common on shared server/CI IPs), the installer
+automatically falls back to scraping github.com release pages.
+
 ### Agent Skill
 
 ```bash
@@ -158,6 +162,33 @@ camoufox-cli cookies export file.json     # Export cookies
 --locale <tag>         Force browser locale (e.g. "en-US" or "en-US,zh-CN")
 ```
 
+## Config File
+
+Tired of repeating the same flags on every call? Put defaults in `~/.camoufox-cli/config.json` (override the path with `$CAMOUFOX_CLI_CONFIG`):
+
+```json
+{
+  "default": {
+    "persistent": true,
+    "timeout": 3600,
+    "proxy": "http://user:pass@host:8080"
+  },
+  "sessions": {
+    "<your-session-name>": {
+      "proxy": "socks5://127.0.0.1:1080",
+      "locale": "zh-CN"
+    }
+  }
+}
+```
+
+- **`default`** applies to every session.
+- **`sessions` is optional.** You never pre-register sessions — the name is just whatever you pass to `--session`. A `sessions.<name>` block only kicks in when you happen to run `--session <name>`, layering its keys on top of `default`; any other session (or no `--session` at all) just uses `default`. Above, `camoufox-cli --session <your-session-name> open <url>` swaps in that block's proxy + locale, while every other session keeps the `default` proxy.
+- **Command-line flags always win** over the file, which in turn wins over built-in defaults.
+- Settable keys: `proxy`, `locale`, `geoip`, `persistent` (`true` / `false` / path string), `headed`, `timeout`, `json`. `session` is command-line only (it selects which block to apply), and per-command options like `--full` or `-i` are never read from config.
+- A broken config never blocks a command — it's ignored with a warning on stderr.
+- Config is read when a session's daemon **first launches**. If one is already running for that session, run `camoufox-cli --session <name> close` first for changes to take effect.
+
 ## Persistent Identity
 
 Without `--persistent`, every launch gets a fresh random fingerprint. With `--persistent`, a `camoufox-cli.json` file is written next to the browser's user data. Fingerprint, OS, and canvas/font seeds are generated on the first launch and frozen afterwards; locale and proxy-derived timezone/geolocation are also saved but track whatever you pass on the command line. Every subsequent launch with the same path reloads the identity, so sites see the same device on every visit.

{camoufox_cli-0.4.0 → camoufox_cli-0.6.0/.claude/worktrees/busy-darwin-6b67a6}/js/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "camoufox-cli",
-  "version": "0.1.7",
+  "version": "0.5.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "camoufox-cli",
-      "version": "0.1.7",
+      "version": "0.5.0",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {

{camoufox_cli-0.4.0 → camoufox_cli-0.6.0/.claude/worktrees/busy-darwin-6b67a6}/js/package.json

@@ -1,6 +1,6 @@
 {
   "name": "camoufox-cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Anti-detect headless browser automation CLI & Skills for AI agents, powered by Camoufox",
   "type": "module",
   "bin": {

{camoufox_cli-0.4.0 → camoufox_cli-0.6.0/.claude/worktrees/busy-darwin-6b67a6}/js/src/browser.ts

@@ -4,10 +4,13 @@ import { execFileSync } from "node:child_process";
 import { mkdirSync } from "node:fs";
 import { Camoufox, launchOptions } from "camoufox-js";
 import { firefox, type Browser, type BrowserContext, type Page } from "playwright-core";
+import { ensureMmdb } from "./install.js";
 import { loadOrCreate, toLaunchOptions } from "./identity.js";
 import { parseProxySettings } from "./proxy.js";
 import { RefRegistry } from "./refs.js";
 
+const MAX_HISTORY = 200;
+
 function ensureBrowserInstalled(): void {
   try {
     execFileSync("npx", ["camoufox-js", "path"], { stdio: "pipe" });
@@ -42,6 +45,12 @@ export class BrowserManager {
 
     ensureBrowserInstalled();
 
+    if (this.proxy && this.geoip) {
+      // Geoip resolution lazily downloads the GeoIP db via the rate-limited
+      // GitHub API; fetch it through the resilient path first.
+      await ensureMmdb();
+    }
+
     const launchOpts: Record<string, unknown> = { headless };
     let proxySettings: { server: string; username?: string; password?: string } | null = null;
     if (this.proxy) {
@@ -147,6 +156,9 @@ export class BrowserManager {
   pushHistory(url: string): void {
     this.history = this.history.slice(0, this.historyIndex + 1);
     this.history.push(url);
+    if (this.history.length > MAX_HISTORY) {
+      this.history = this.history.slice(-MAX_HISTORY);
+    }
     this.historyIndex = this.history.length - 1;
   }
 

{camoufox_cli-0.4.0 → camoufox_cli-0.6.0/.claude/worktrees/busy-darwin-6b67a6}/js/src/cli.ts

@@ -7,6 +7,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { execFileSync, spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { loadDefaults } from "./config.js";
 
 const SOCKET_PREFIX = "/tmp/camoufox-cli-";
 
@@ -105,42 +106,46 @@ export interface Flags {
 }
 
 export function parseArgs(argv: string[]): { flags: Flags; command: Record<string, unknown> } {
-  const flags: Flags = { session: "default", headed: false, timeout: 1800, json: false, persistent: null, proxy: null, geoip: true, locale: null };
+  // Flag precedence: command line > config file (per-session block, then the
+  // `default` block) > built-in defaults. Only flags explicitly passed on the
+  // command line are collected here, so they always win over config.
+  const builtin: Flags = { session: "default", headed: false, timeout: 1800, json: false, persistent: null, proxy: null, geoip: true, locale: null };
+  const cli: Partial<Flags> = {};
   const rest: string[] = [];
 
   let i = 0;
   while (i < argv.length) {
     switch (argv[i]) {
       case "--session":
-        flags.session = argv[++i] ?? (process.stderr.write("Error: --session requires a value\n"), process.exit(1), "");
+        cli.session = argv[++i] ?? (process.stderr.write("Error: --session requires a value\n"), process.exit(1), "");
         break;
       case "--headed":
-        flags.headed = true;
+        cli.headed = true;
         break;
       case "--timeout":
-        flags.timeout = parseInt(argv[++i] ?? "1800", 10);
+        cli.timeout = parseInt(argv[++i] ?? "1800", 10);
         break;
       case "--json":
-        flags.json = true;
+        cli.json = true;
         break;
       case "--persistent": {
         // Optional value: if next arg looks like a path, use it; otherwise use default
         const next = argv[i + 1];
         if (next && (next.includes("/") || next.startsWith(".") || next.startsWith("~"))) {
-          flags.persistent = argv[++i];
+          cli.persistent = argv[++i];
         } else {
-          flags.persistent = "";
+          cli.persistent = "";
         }
         break;
       }
       case "--proxy":
-        flags.proxy = argv[++i] ?? null;
+        cli.proxy = argv[++i] ?? null;
         break;
       case "--no-geoip":
-        flags.geoip = false;
+        cli.geoip = false;
         break;
       case "--locale":
-        flags.locale = argv[++i] ?? (process.stderr.write("Error: --locale requires a value\n"), process.exit(1), "");
+        cli.locale = argv[++i] ?? (process.stderr.write("Error: --locale requires a value\n"), process.exit(1), "");
         break;
       default:
         rest.push(argv[i]);
@@ -153,6 +158,10 @@ export function parseArgs(argv: string[]): { flags: Flags; command: Record<strin
     process.exit(1);
   }
 
+  // session selects which config block applies, so it comes only from the CLI.
+  const session = cli.session ?? builtin.session;
+  const flags: Flags = { ...builtin, ...loadDefaults(session), ...cli };
+
   const command = buildCommand(rest[0], rest);
   return { flags, command };
 }
@@ -372,7 +381,8 @@ async function main() {
   // Client-side: install
   if (action === "install") {
     process.stderr.write("[camoufox-cli] Downloading browser...\n");
-    execFileSync("npx", ["camoufox-js", "fetch"], { stdio: "inherit" });
+    const { installBrowser } = await import("./install.js");
+    await installBrowser();
     process.stderr.write("[camoufox-cli] Browser installed.\n");
     if ((command.params as any)?.with_deps) {
       installSystemDeps();
@@ -480,7 +490,12 @@ Flags:
   --persistent [path]  Persistent identity — freeze fingerprint/OS/locale + store cookies/state (default: ~/.camoufox-cli/profiles/<session>)
   --proxy <url>        Proxy server (e.g. http://host:port or https://host:443)
   --no-geoip           Disable automatic GeoIP spoofing (auto-enabled with --proxy)
-  --locale <tag>       Force browser locale (e.g. "en-US" or "en-US,zh-CN")`;
+  --locale <tag>       Force browser locale (e.g. "en-US" or "en-US,zh-CN")
+
+Config file:
+  ~/.camoufox-cli/config.json sets defaults for the flags above (override the
+  path with $CAMOUFOX_CLI_CONFIG). Command-line flags always take precedence.
+  Use a "default" block plus optional per-session blocks under "sessions".`;
 
 const isDirectRun = (() => {
   try {

camoufox_cli-0.6.0/.claude/worktrees/busy-darwin-6b67a6/js/src/config.ts

@@ -0,0 +1,140 @@
+/**
+ * Optional config file support.
+ *
+ * A JSON file at ~/.camoufox-cli/config.json (override with the
+ * CAMOUFOX_CLI_CONFIG env var) supplies default values for daemon-launch
+ * flags, so common settings (proxy, locale, persistent…) don't have to be
+ * repeated on every invocation.
+ *
+ * Precedence: command-line flag > config `sessions.<name>` block >
+ * config `default` block > built-in default.
+ *
+ * Only flags that affect daemon launch are honored. `session` itself is never
+ * read from config — it selects which block to apply, so it can only come from
+ * the command line. Per-command flags (--full, -i, …) are never read.
+ *
+ * The config only takes effect when a session's daemon first launches; an
+ * already-running daemon is reused as-is (see ensureDaemon).
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export interface ConfigDefaults {
+  headed?: boolean;
+  timeout?: number;
+  json?: boolean;
+  persistent?: string | null;
+  proxy?: string | null;
+  geoip?: boolean;
+  locale?: string | null;
+}
+
+// Flags a config file may set, grouped by the value type each one expects.
+// "session" is intentionally absent — it selects which block to apply, so it
+// must come from the command line.
+const BOOL_KEYS = new Set(["headed", "geoip", "json"]);
+const STR_KEYS = new Set(["proxy", "locale"]);
+const ALLOWED_KEYS = new Set([...BOOL_KEYS, ...STR_KEYS, "timeout", "persistent"]);
+const INVALID = Symbol("invalid");
+
+/** Resolved config path, read at call time so the env var can be overridden (incl. by tests). */
+export function configPath(): string {
+  return process.env.CAMOUFOX_CLI_CONFIG || path.join(os.homedir(), ".camoufox-cli", "config.json");
+}
+
+/**
+ * Return config-derived flag defaults for `session`.
+ *
+ * Merges the top-level `default` block with the `sessions.<session>` block
+ * (the latter wins). Returns `{}` when the file is absent or malformed — a
+ * broken config never blocks a command, it is only ignored with a warning on
+ * stderr.
+ */
+export function loadDefaults(session: string): ConfigDefaults {
+  const p = configPath();
+  if (!fs.existsSync(p)) return {};
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch (e: any) {
+    process.stderr.write(`[camoufox-cli] Ignoring config ${p}: ${e.message}\n`);
+    return {};
+  }
+
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    process.stderr.write(`[camoufox-cli] Ignoring config ${p}: top level must be a JSON object\n`);
+    return {};
+  }
+
+  const obj = raw as Record<string, unknown>;
+  const merged: Record<string, unknown> = {};
+  Object.assign(merged, clean(obj.default, p));
+
+  const sessions = obj.sessions;
+  if (typeof sessions === "object" && sessions !== null && !Array.isArray(sessions)) {
+    Object.assign(merged, clean((sessions as Record<string, unknown>)[session], p));
+  } else if (sessions !== undefined) {
+    process.stderr.write(`[camoufox-cli] Ignoring config ${p}: "sessions" must be an object\n`);
+  }
+
+  return normalize(merged);
+}
+
+/** Keep only allowed keys from a block, warning on anything else. */
+function clean(block: unknown, p: string): Record<string, unknown> {
+  if (block === undefined || block === null) return {};
+  if (typeof block !== "object" || Array.isArray(block)) {
+    process.stderr.write(`[camoufox-cli] Ignoring config ${p}: blocks must be objects\n`);
+    return {};
+  }
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(block as Record<string, unknown>)) {
+    if (ALLOWED_KEYS.has(key)) out[key] = value;
+    else if (key === "session") process.stderr.write(`[camoufox-cli] Ignoring "session" in config — set it with --session on the command line\n`);
+    else process.stderr.write(`[camoufox-cli] Ignoring unknown config key: ${key}\n`);
+  }
+  return out;
+}
+
+/**
+ * Validate/coerce each config value to the type its flag expects.
+ *
+ * A value of the wrong type is dropped with a warning rather than passed
+ * through, so a malformed config is always ignored, never fatal: a non-string
+ * proxy/locale/persistent would crash daemon launch, a non-numeric timeout
+ * would fail silently, and a non-bool toggle (e.g. the string "false") would
+ * be silently truthy.
+ */
+function normalize(flags: Record<string, unknown>): ConfigDefaults {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(flags)) {
+    const coerced = coerce(key, value);
+    if (coerced === INVALID) {
+      process.stderr.write(`[camoufox-cli] Ignoring invalid ${key} in config: ${JSON.stringify(value)}\n`);
+    } else {
+      out[key] = coerced;
+    }
+  }
+  return out as ConfigDefaults;
+}
+
+/** Return the normalized value if it fits the flag's type, else the INVALID sentinel. */
+function coerce(key: string, value: unknown): unknown {
+  if (BOOL_KEYS.has(key)) return typeof value === "boolean" ? value : INVALID;
+  // null is accepted as "unset" (falls back to the built-in default).
+  if (STR_KEYS.has(key)) return value === null || typeof value === "string" ? value : INVALID;
+  if (key === "timeout") {
+    // a finite number only — excludes bool, string and null
+    return typeof value === "number" && Number.isFinite(value) ? Math.trunc(value) : INVALID;
+  }
+  if (key === "persistent") {
+    // true -> "" (default profile path, resolved in main); false -> null
+    // (disabled); null/string kept as-is; anything else invalid.
+    if (typeof value === "boolean") return value ? "" : null;
+    return value === null || typeof value === "string" ? value : INVALID;
+  }
+  return value; // unreachable: clean already filtered to known keys
+}

camoufox_cli-0.6.0/.claude/worktrees/busy-darwin-6b67a6/js/src/install.ts

@@ -0,0 +1,126 @@
+/**
+ * Browser installation with resilient GitHub release discovery.
+ *
+ * Anonymous GitHub API requests are limited to 60/hour per IP, which makes
+ * installs flaky on servers behind shared egress IPs (CI runners, cloud
+ * hosts). Mitigations:
+ *
+ * - If the API fails, release assets are discovered by paging through
+ *   github.com release pages, which are not behind the API rate limit.
+ * - The GeoIP database is downloaded from a fixed releases/latest/download
+ *   URL (no API involved) at install time and before geoip launches, so
+ *   upstream's lazy API-based download never triggers.
+ */
+
+import { existsSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { DefaultAddons, maybeDownloadAddons } from "camoufox-js/dist/addons.js";
+import { downloadMMDB } from "camoufox-js/dist/locale.js";
+import { CamoufoxFetcher, INSTALL_DIR, installedVerStr, webdl } from "camoufox-js/dist/pkgman.js";
+
+const HEADERS = { "User-Agent": "camoufox-cli" };
+const MMDB_URL = "https://github.com/P3TERX/GeoLite.mmdb/releases/latest/download/GeoLite2-City.mmdb";
+
+async function assetsViaApi(repo: string): Promise<any[]> {
+  const resp = await fetch(`https://api.github.com/repos/${repo}/releases`, { headers: HEADERS });
+  if (!resp.ok) throw new Error(`GitHub API responded with ${resp.status}`);
+  const releases = (await resp.json()) as any[];
+  return releases.flatMap((release) => release.assets ?? []);
+}
+
+/**
+ * Discover release assets by paging through github.com release pages,
+ * newest release first. Lazy: stops requesting once the caller stops.
+ */
+export async function* assetsViaWeb(repo: string): AsyncGenerator<any> {
+  const escaped = repo.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const tagRe = new RegExp(`/${escaped}/releases/tag/([^"<]+)`, "g");
+  const linkRe = new RegExp(`href="(/${escaped}/releases/download/[^"]+)"`, "g");
+
+  const seen = new Set<string>();
+  for (let pageNum = 1; ; pageNum++) {
+    const listing = await fetch(`https://github.com/${repo}/releases?page=${pageNum}`, { headers: HEADERS });
+    if (!listing.ok) throw new Error(`github.com responded with ${listing.status}`);
+    const tags = [...new Set([...(await listing.text()).matchAll(tagRe)].map((m) => m[1]))]
+      .filter((tag) => !seen.has(tag));
+    if (tags.length === 0) return;
+    for (const tag of tags) seen.add(tag);
+    for (const tag of tags) {
+      const page = await fetch(`https://github.com/${repo}/releases/expanded_assets/${tag}`, { headers: HEADERS });
+      if (!page.ok) continue;
+      for (const m of (await page.text()).matchAll(linkRe)) {
+        yield {
+          name: decodeURIComponent(m[1].split("/").pop()!),
+          browser_download_url: `https://github.com${m[1]}`,
+        };
+      }
+    }
+  }
+}
+
+/** Yield all release assets of a repo, newest release first. */
+export async function* iterReleaseAssets(repo: string): AsyncGenerator<any> {
+  let assets: any[];
+  try {
+    assets = await assetsViaApi(repo);
+  } catch (e) {
+    process.stderr.write(`[camoufox-cli] GitHub API failed (${e}), falling back to github.com pages...\n`);
+    yield* assetsViaWeb(repo);
+    return;
+  }
+  yield* assets;
+}
+
+class ResilientFetcher extends CamoufoxFetcher {
+  async getAsset(): Promise<any> {
+    for await (const asset of iterReleaseAssets(this.githubRepo)) {
+      const data = this.checkAsset(asset);
+      if (data) return data;
+    }
+    this.missingAssetError();
+  }
+}
+
+/**
+ * Download the GeoIP database if missing, without hitting the GitHub API.
+ * Failures are non-fatal: upstream still lazily downloads on first use.
+ */
+export async function ensureMmdb(): Promise<void> {
+  const mmdbFile = join(INSTALL_DIR.toString(), "GeoLite2-City.mmdb");
+  if (existsSync(mmdbFile)) return;
+  try {
+    const buf = await webdl(MMDB_URL, "Downloading GeoIP database", true);
+    writeFileSync(mmdbFile, buf);
+    return;
+  } catch {
+    rmSync(mmdbFile, { force: true });
+  }
+  try {
+    await downloadMMDB(); // upstream API-based path, as a last resort
+  } catch (e) {
+    rmSync(mmdbFile, { force: true });
+    process.stderr.write(`[camoufox-cli] GeoIP database download failed (${e}).\n`);
+  }
+}
+
+/** Download and install the Camoufox browser, GeoIP database and addons. */
+export async function installBrowser(): Promise<void> {
+  const fetcher = new ResilientFetcher();
+  await fetcher.init();
+
+  let installed: string | null = null;
+  try {
+    installed = installedVerStr();
+  } catch {
+    installed = null;
+  }
+  if (installed === fetcher.verstr) {
+    process.stderr.write(`[camoufox-cli] Camoufox v${installed} is already up to date.\n`);
+  } else {
+    await fetcher.install();
+  }
+
+  await ensureMmdb();
+  maybeDownloadAddons(DefaultAddons);
+}

{camoufox_cli-0.4.0 → camoufox_cli-0.6.0/.claude/worktrees/busy-darwin-6b67a6}/js/tests/cli.test.ts

@@ -1,5 +1,9 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
 import { buildCommand, getSocketPath, parseArgs } from "../src/cli.js";
+import { loadDefaults } from "../src/config.js";
 
 // buildCommand calls process.exit on error; mock it to throw instead
 beforeEach(() => {
@@ -7,6 +11,8 @@ beforeEach(() => {
     throw new Error(`process.exit(${code})`);
   });
   vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+  // Isolate from any real ~/.camoufox-cli/config.json on the dev's machine.
+  process.env.CAMOUFOX_CLI_CONFIG = path.join(os.tmpdir(), "camoufox-cli-absent-dir", "config.json");
 });
 
 describe("buildCommand", () => {
@@ -298,3 +304,152 @@ describe("getSocketPath", () => {
     expect(getSocketPath("my-session")).toBe("/tmp/camoufox-cli-my-session.sock");
   });
 });
+
+describe("config file", () => {
+  let dir: string;
+  let cfg: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), "camoufox-cli-test-"));
+    cfg = path.join(dir, "config.json");
+    process.env.CAMOUFOX_CLI_CONFIG = cfg;
+  });
+
+  afterEach(() => {
+    delete process.env.CAMOUFOX_CLI_CONFIG;
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  const write = (obj: unknown) => fs.writeFileSync(cfg, JSON.stringify(obj));
+
+  // --- loadDefaults ---
+  it("absent file -> {}", () => {
+    expect(loadDefaults("default")).toEqual({});
+  });
+
+  it("default block", () => {
+    write({ default: { timeout: 60, headed: true } });
+    const out = loadDefaults("default");
+    expect(out.timeout).toBe(60);
+    expect(out.headed).toBe(true);
+  });
+
+  it("session overrides default", () => {
+    write({ default: { locale: "en-US", timeout: 60 }, sessions: { work: { locale: "zh-CN" } } });
+    const out = loadDefaults("work");
+    expect(out.locale).toBe("zh-CN"); // session block wins
+    expect(out.timeout).toBe(60); // inherited from default block
+  });
+
+  it("unknown session uses default block", () => {
+    write({ default: { locale: "en-US" }, sessions: { work: { locale: "zh-CN" } } });
+    expect(loadDefaults("other").locale).toBe("en-US");
+  });
+
+  it("session key excluded", () => {
+    write({ default: { session: "ignored", proxy: "http://h:1" } });
+    const out = loadDefaults("default") as any;
+    expect(out.session).toBeUndefined();
+    expect(out.proxy).toBe("http://h:1");
+  });
+
+  it("unknown key ignored", () => {
+    write({ default: { bogus: 1, headed: true } });
+    const out = loadDefaults("default") as any;
+    expect(out.bogus).toBeUndefined();
+    expect(out.headed).toBe(true);
+  });
+
+  it("persistent true -> empty-string sentinel", () => {
+    write({ default: { persistent: true } });
+    expect(loadDefaults("default").persistent).toBe("");
+  });
+
+  it("persistent false -> null", () => {
+    write({ default: { persistent: false } });
+    expect(loadDefaults("default").persistent).toBeNull();
+  });
+
+  it("persistent path kept", () => {
+    write({ default: { persistent: "/tmp/p" } });
+    expect(loadDefaults("default").persistent).toBe("/tmp/p");
+  });
+
+  it("invalid persistent dropped", () => {
+    // A number would crash daemon launch; it must be dropped, not passed through.
+    write({ default: { persistent: 123, headed: true } });
+    const out = loadDefaults("default") as any;
+    expect(out.persistent).toBeUndefined();
+    expect(out.headed).toBe(true);
+  });
+
+  it("persistent null disables", () => {
+    write({ default: { persistent: null } });
+    expect(loadDefaults("default").persistent).toBeNull();
+  });
+
+  it("invalid timeout dropped", () => {
+    write({ default: { timeout: "abc", headed: true } });
+    const out = loadDefaults("default") as any;
+    expect(out.timeout).toBeUndefined();
+    expect(out.headed).toBe(true);
+  });
+
+  it("timeout bool dropped", () => {
+    write({ default: { timeout: true } });
+    expect("timeout" in loadDefaults("default")).toBe(false);
+  });
+
+  it("timeout float truncated", () => {
+    write({ default: { timeout: 3600.9 } });
+    expect(loadDefaults("default").timeout).toBe(3600);
+  });
+
+  it("invalid proxy dropped", () => {
+    // A non-string proxy would crash daemon launch; it must be dropped.
+    write({ default: { proxy: 123, locale: "en-US" } });
+    const out = loadDefaults("default") as any;
+    expect(out.proxy).toBeUndefined();
+    expect(out.locale).toBe("en-US");
+  });
+
+  it("bool field wrong type dropped", () => {
+    write({ default: { headed: "false", geoip: "no" } });
+    const out = loadDefaults("default") as any;
+    expect(out.headed).toBeUndefined();
+    expect(out.geoip).toBeUndefined();
+  });
+
+  it("malformed json ignored", () => {
+    fs.writeFileSync(cfg, "{not valid json");
+    expect(loadDefaults("default")).toEqual({});
+  });
+
+  it("non-object top level ignored", () => {
+    write([1, 2, 3]);
+    expect(loadDefaults("default")).toEqual({});
+  });
+
+  // --- parseArgs integration (precedence: CLI > config > built-in) ---
+  it("config supplies defaults", () => {
+    write({ default: { proxy: "http://h:1", headed: true } });
+    const { flags } = parseArgs(["open", "https://example.com"]);
+    expect(flags.proxy).toBe("http://h:1");
+    expect(flags.headed).toBe(true);
+  });
+
+  it("CLI overrides config", () => {
+    write({ default: { timeout: 60 } });
+    const { flags } = parseArgs(["--timeout", "999", "open", "x"]);
+    expect(flags.timeout).toBe(999);
+  });
+
+  it("session block applies", () => {
+    write({ sessions: { work: { locale: "zh-CN" } } });
+    const { flags } = parseArgs(["--session", "work", "open", "x"]);
+    expect(flags.locale).toBe("zh-CN");
+    // A different session doesn't pick up the "work" block.
+    const { flags: f2 } = parseArgs(["open", "x"]);
+    expect(f2.locale).toBeNull();
+  });
+});