@zenrows/cli 1.6.1 → 1.7.0

package/README.md

@@ -84,11 +84,12 @@ unclaimed Zenrows Free plan account**, stores the key in `.zenrows/secrets.json`
 (no secret — just the accountId, Free-period info, and a claim link).
 
 When you (or your agent) want to keep the usage and history, **claim** the
-account — this sets an email + password; the same key keeps working:
+account — this confirms an email (Google, GitHub or a 6-digit code); the same
+key keeps working:
 
 ```bash
 zenrows account status # show account + Free period + claim link
-zenrows account claim  # open the claim URL in the browser
+zenrows account claim  # open the claim URL (fresh one if the stored link is near its 30-day expiry)
 zenrows usage          # plan usage, credits & concurrency (does not count against your limit)
 ```
 
@@ -187,7 +188,10 @@ to open. `--max-items` and `--max-pages` cap the crawl (API default 100 each),
 and `--max-pages` bounds the cost, since each page is one fetch. The local policy `max_pages_per_run` caps `--max-pages` (default
 1000). `--output-format html` uses up the page budget: each kept page is one
 more fetch, and `--max-pages` counts it. `--include-patterns` /
-`--exclude-patterns` are repeatable substring filters on the URL. `get` and
+`--exclude-patterns` are repeatable substring filters on the URL. A crawl whose
+pages held nothing new to follow ends `completed` with no results and exits 0.
+When patterns were set, it prints a note (under `--json`, in `note`) to check
+them against the URLs the start page links to. `get` and
 `list` read one page and take `--cursor` and `--limit`. `results` follows every
 page (`--limit` is the page size); on a running crawl it returns the URLs kept
 so far, with `partial: true`. `download` reports the crawl's `status` (`null`

package/agent-plugin/skills/zenrows/SKILL.md

@@ -21,7 +21,8 @@ You do **not** need an API key in the plugin package.
 - **stdio** (`npx -y @zenrows/mcp`): on first cloud call the server can
   auto-create a **free, unclaimed** Zenrows Free plan account and persist the
   key locally. When the Free plan nears its limit (or the user asks), surface
-  the **claim URL** so a human can claim the account (email + password). The
+  the **claim URL** so a human can claim the account (confirming an email
+  with Google, GitHub or a 6-digit code). Claim links expire after 30 days. The
   same key keeps working after claim. Never handle payment or upgrades —
   only show the claim link.
 - **Remote** (`https://mcp.zenrows.com/mcp`): the client runs **OAuth**

package/dist/src/cli/commands/account.js

@@ -1,11 +1,14 @@
 /**
  * `zenrows account <status|claim>` — inspect the auto-provisioned Zenrows
  * account and surface the human-facing claim link. Never handles payment or
- * upgrades; it only reports status and opens the claim URL.
+ * upgrades; it only reports status and opens the claim URL, asking the API for
+ * a fresh one when the stored link is missing or close to its 30-day expiry.
  */
 import { fetchAccountStatus, readAccount, writeAccount } from "../../core/agent-account.js";
 import { authState, ENV_KEY, resolveApiKey } from "../../core/auth.js";
+import { refreshClaimState, usableClaimUrl } from "../../core/claim-link.js";
 import { loadConfig } from "../../core/config.js";
+import { ToolkitError } from "../../core/errors.js";
 import { log } from "../../core/logger.js";
 import { openUrl } from "../../core/open-url.js";
 import { fetchUsage } from "../../core/usage.js";
@@ -17,11 +20,39 @@ export const account = {
     async run(argv, ctx) {
         const { values, positionals } = parse(argv, { "no-open": { type: "boolean" } });
         const sub = positionals[0] ?? "status";
-        let acct = readAccount();
         const auth = authState();
-        // Claiming happens in the browser, out-of-band from the CLI. If we hold an
-        // unclaimed record and a key, ask the backend whether it has since been
-        // claimed and refresh account.json. Best-effort — stay on local state offline.
+        if (sub === "claim") {
+            const state = await refreshClaimState({ force: true });
+            if (state.status === "none") {
+                log.info("No agent-created account to claim. Use `zenrows login --api-key` if you already have a key.");
+                return 0;
+            }
+            if (state.status === "claimed") {
+                log.success("This account is already claimed. Nothing to do: the same API key keeps working.");
+                if (ctx.json)
+                    log.out(JSON.stringify({ ok: true, claimed: true }, null, 2));
+                return 0;
+            }
+            if (!state.claimUrl) {
+                throw new ToolkitError({
+                    code: "FETCH_FAILED",
+                    message: "No valid claim link is available.",
+                    likely_cause: auth.hasKey
+                        ? "The stored claim link expired and a fresh one could not be requested."
+                        : "The stored claim link expired, and no API key is configured to request a fresh one.",
+                    next_action: "Check connectivity and run `zenrows account claim` again.",
+                    suggested_commands: ["zenrows account claim"],
+                });
+            }
+            log.info("Claim this Zenrows account: open the link and confirm your email (Google, GitHub or a 6-digit code).");
+            log.info(state.claimUrl);
+            if (!values["no-open"])
+                await openUrl(state.claimUrl);
+            if (ctx.json)
+                log.out(JSON.stringify({ ok: true, claimUrl: state.claimUrl, refreshed: state.refreshed }, null, 2));
+            return 0;
+        }
+        let acct = readAccount();
         if (acct && acct.unclaimed && auth.hasKey) {
             const key = resolveApiKey().key;
             if (key) {
@@ -33,30 +64,9 @@ export const account = {
                     }
                 }
                 catch {
-                    // endpoint unavailable / offline — keep the local record
                 }
             }
         }
-        if (sub === "claim") {
-            if (!acct) {
-                log.info("No agent-created account to claim. Use `zenrows login --api-key` if you already have a key.");
-                return 0;
-            }
-            if (!acct.unclaimed) {
-                log.success("This account is already claimed.");
-                if (ctx.json)
-                    log.out(JSON.stringify({ ok: true, claimed: true }, null, 2));
-                return 0;
-            }
-            log.info("Claim this Zenrows account (set your email + password):");
-            log.info(acct.claimUrl);
-            if (!values["no-open"])
-                await openUrl(acct.claimUrl);
-            if (ctx.json)
-                log.out(JSON.stringify({ ok: true, claimUrl: acct.claimUrl }, null, 2));
-            return 0;
-        }
-        // status — cycle dates from subscriptions/self/details
         let periodEndsAt;
         if (auth.hasKey) {
             const key = resolveApiKey().key;
@@ -86,7 +96,7 @@ export const account = {
             if (periodEndsAt)
                 log.dim(`Billing period ends: ${periodEndsAt}`);
             if (acct.unclaimed)
-                log.dim(`Claim it: ${acct.claimUrl}`);
+                log.dim(`Claim it: ${usableClaimUrl(acct) ?? "run `zenrows account claim` for a fresh link"}`);
         }
         else {
             if (auth.hasKey) {

package/dist/src/cli/commands/batch.js

@@ -20,6 +20,7 @@ import { createJob, downloadResults, getJob, listResults, rerunJob, stopJob, wai
 import { asNumber, asString, parse } from "../command.js";
 import { ToolkitError, isKeyCapReached, keyCapReached } from "../../core/errors.js";
 import { printError, writeOut } from "../output.js";
+import { refreshClaimAdvice } from "../../core/claim-link.js";
 export const batch = {
     name: "batch",
     summary: "Run JSONL batch jobs on Zenrows Batch.",
@@ -74,7 +75,9 @@ export const batch = {
                     });
             }
         }
-        catch (err) {
+        catch (caught) {
+            // A quota error's claim advice is built from local state; check it is still current.
+            const err = await refreshClaimAdvice(caught);
             printError(err, ctx.json);
             return 1;
         }

package/dist/src/cli/commands/browser.js

@@ -23,6 +23,7 @@ import { newRunId, writeRun } from "../../core/artifacts.js";
 import { ToolkitError } from "../../core/errors.js";
 import { parse, asString, asNumber } from "../command.js";
 import { printError, writeOut } from "../output.js";
+import { refreshClaimAdvice } from "../../core/claim-link.js";
 import { createSession, sessionCall, closeSession, decodeBinary, connectUrl, normalizeSelectValue, } from "../../core/browser-api.js";
 const VERBS = {
     navigate: { verb: "navigate", opts: { url: { type: "string" } }, required: ["url"], body: (v) => ({ url: asString(v.url) }) },
@@ -155,7 +156,9 @@ export const browser = {
                     });
             }
         }
-        catch (err) {
+        catch (caught) {
+            // A quota error's claim advice is built from local state; check it is still current.
+            const err = await refreshClaimAdvice(caught);
             printError(err, ctx.json);
             return err instanceof ToolkitError && err.code === "POLICY_BROWSER_DISABLED" ? 2 : 1;
         }

package/dist/src/cli/commands/crawl.js

@@ -18,6 +18,7 @@ import { asNumber, asString, parse } from "../command.js";
 import { ToolkitError, isKeyCapReached, keyCapReached, quotaExhausted } from "../../core/errors.js";
 import { readAccount } from "../../core/agent-account.js";
 import { printError, writeOut, writeOutStream } from "../output.js";
+import { refreshClaimAdvice, storedClaimHint } from "../../core/claim-link.js";
 /** The API's default for `max_pages` (and `max_items`) when the flag is unset. */
 const DEFAULT_MAX_PAGES = 100;
 /** Largest `depth` / `max_items` / `max_pages` the API takes. */
@@ -62,7 +63,8 @@ export const crawl = {
         "                                    a crawl still running then is printed, not stopped",
         "  --json                            print structured output: create/get/wait/stop print",
         "                                    {ok, crawl_id, status, crawl}; get adds results and next_cursor;",
-        "                                    a wait that runs out adds note",
+        "                                    a wait that runs out, or a completed crawl with patterns",
+        "                                    and 0 results, adds note",
     ].join("\n"),
     async run(argv, ctx) {
         const [sub, ...rest] = argv;
@@ -94,7 +96,9 @@ export const crawl = {
                     });
             }
         }
-        catch (err) {
+        catch (caught) {
+            // A quota error's claim advice is built from local state; check it is still current.
+            const err = await refreshClaimAdvice(caught);
             printError(err, ctx.json);
             return 1;
         }
@@ -461,13 +465,13 @@ export function crawlFailure(c) {
     }
     if (code === "insufficient_credits") {
         const acct = readAccount();
-        const quota = quotaExhausted(where, acct?.unclaimed ? acct.claimUrl : undefined, { status: null, detail }).toJSON();
+        const quota = quotaExhausted(where, storedClaimHint(acct), { status: null, detail }).toJSON();
         return new ToolkitError({ ...quota, ...ids, code: "CRAWL_INSUFFICIENT_CREDITS", suggested_commands: [...(quota.suggested_commands ?? []), getCmd] });
     }
     const why = [code, c.error?.detail].filter(Boolean).join(": ");
     const next = {
-        seed_unreachable: "The start URL could not be fetched (the site may be blocking it). Check it with `zenrows fetch <url>`.",
-        no_items_found: "Nothing matched. Loosen --include-patterns / --exclude-patterns, raise or drop --depth, or check the start page with `zenrows fetch <url>`.",
+        seed_unreachable: "The start URL could not be fetched or returned an empty page (the site may be blocking it). Check it with `zenrows fetch <url>`.",
+        no_items_found: "The crawl read the start page but found no data it could use, so it had nothing to follow. Start from a listing or product page.",
     };
     return new ToolkitError({
         code: "CRAWL_FAILED",
@@ -478,6 +482,18 @@ export function crawlFailure(c) {
         ...ids,
     });
 }
+/**
+ * Set only when a crawl with patterns completed and kept nothing. The API ends a
+ * crawl whose pages held nothing new to follow `completed`, and does not count
+ * the links the patterns rejected, so the patterns are the first thing to check.
+ */
+function noMatchNote(c) {
+    const crawl = c;
+    const patterns = [...(crawl.include_patterns ?? []), ...(crawl.exclude_patterns ?? [])];
+    if (crawl.status !== "completed" || crawl.coverage?.items_found !== 0 || !patterns.length)
+        return undefined;
+    return "The crawl completed with no results. Check --include-patterns / --exclude-patterns against the URLs the start page links to.";
+}
 /**
  * Print a crawl (or a stop answer), structured under --json, and return the exit
  * code: 1 when it ended `failed`, or `stopped` because credits ran out or the
@@ -487,6 +503,7 @@ export function crawlFailure(c) {
  */
 function printCrawl(c, json, headline, extra = {}) {
     const err = crawlFailure(c);
+    const note = extra.note ?? noMatchNote(c);
     const crawlFields = { ...c };
     // A wait polls with one result to stay cheap; that page is not "the results".
     delete crawlFields.results;
@@ -498,6 +515,7 @@ function printCrawl(c, json, headline, extra = {}) {
             status: c.status,
             crawl: crawlFields,
             ...extra,
+            note,
             ...(err ? { error: err.toJSON() } : {}),
         }, null, 2));
         return err ? 1 : 0;
@@ -515,6 +533,8 @@ function printCrawl(c, json, headline, extra = {}) {
     }
     if (extra.note)
         log.dim(`  next: zenrows crawl wait ${c.crawl_id}`);
+    else if (note)
+        log.warn(`  ${note}`);
     if (err)
         printError(err, false);
     return err ? 1 : 0;

package/dist/src/cli/commands/extract.js

@@ -17,6 +17,7 @@ import { runExtract } from "../../adapters/extract.js";
 import { formatRequestCost } from "../../core/http.js";
 import { parse, asString, asNumber } from "../command.js";
 import { printError, writeOut } from "../output.js";
+import { refreshClaimAdvice } from "../../core/claim-link.js";
 export const extract = {
     name: "extract",
     summary: "Turn a protected page into structured data (Extract / Autoparse / CSS / Markdown).",
@@ -175,7 +176,9 @@ export const extract = {
             await maybeNudgeClaim(config, {});
             return 0;
         }
-        catch (err) {
+        catch (caught) {
+            // A quota error's claim advice is built from local state; check it is still current.
+            const err = await refreshClaimAdvice(caught);
             writeRun({
                 runId,
                 command: "zenrows extract",

package/dist/src/cli/commands/fetch.js

@@ -16,6 +16,7 @@ import { runFetch } from "../../adapters/protected-fetch.js";
 import { formatRequestCost } from "../../core/http.js";
 import { parse, asString, asNumber } from "../command.js";
 import { printError, writeOut } from "../output.js";
+import { refreshClaimAdvice } from "../../core/claim-link.js";
 export const fetch_ = {
     name: "fetch",
     summary: "Retrieve a protected page (Fetch).",
@@ -152,7 +153,9 @@ export const fetch_ = {
             await maybeNudgeClaim(config, {});
             return 0;
         }
-        catch (err) {
+        catch (caught) {
+            // A quota error's claim advice is built from local state; check it is still current.
+            const err = await refreshClaimAdvice(caught);
             writeRun({
                 runId,
                 command: "zenrows fetch",

package/dist/src/cli/commands/signup.js

@@ -21,12 +21,13 @@ export const signup = {
         if (values.agent) {
             const account = readAccount();
             if (account) {
-                log.info("An agent account already exists. Claim it: " + account.claimUrl);
+                log.info("An agent account already exists. Claim it with: zenrows account claim");
                 return 0;
             }
             const res = await signupAgent();
             saveApiKey(res.apiKey);
-            writeAccount({ accountId: res.accountId, unclaimed: true, claimUrl: res.claimUrl, createdAt: new Date().toISOString() });
+            const now = new Date().toISOString();
+            writeAccount({ accountId: res.accountId, unclaimed: true, claimUrl: res.claimUrl, createdAt: now, claimUrlIssuedAt: now });
             log.success("Created a Zenrows Free plan account.");
             log.dim(`Claim it anytime: ${res.claimUrl}`);
             if (ctx.json)

package/dist/src/cli/index.js

@@ -8,6 +8,7 @@
  */
 import { CLI_VERSION } from "../core/config.js";
 import { ToolkitError } from "../core/errors.js";
+import { refreshClaimAdvice } from "../core/claim-link.js";
 import { log, ANSI, c } from "../core/logger.js";
 import { makeAssetCommand } from "./asset-command.js";
 import { printError } from "./output.js";
@@ -82,7 +83,7 @@ export async function main(rawArgv) {
         return await cmd.run(argv, ctx);
     }
     catch (err) {
-        printError(err, json);
+        printError(await refreshClaimAdvice(err), json);
         // Any error exits 1 — the exit code doesn't encode error kind. Machine
         // consumers read the precise `error.code` from the --json output instead.
         return 1;

package/dist/src/core/agent-account.js

@@ -5,13 +5,13 @@
  * It never holds the API key (that lives in secrets.json, 0600) — only the
  * accountId, the human-facing claim URL, and claim metadata.
  */
-import { chmodSync, existsSync, unlinkSync } from "node:fs";
+import { existsSync, unlinkSync } from "node:fs";
 import { attributionEnabled, getOrCreateTelemetryId, loadConfig, CLI_USER_AGENT, CLI_VERSION } from "./config.js";
 import { agentClientHeader } from "./agent-client.js";
 import { ToolkitError } from "./errors.js";
 import { AGENT_SIGNUP_API_URL, WELL_KNOWN_PROTECTED_RESOURCE } from "./open-url.js";
 import { detectClient } from "./provenance.js";
-import { findWorkspace, readJson, workspacePaths, writeJson } from "./workspace.js";
+import { findWorkspace, readJson, workspacePaths, writePrivateJson } from "./workspace.js";
 /** Env var to override the signup endpoint (highest priority; for local testing). */
 export const SIGNUP_URL_ENV = "ZENROWS_AGENT_SIGNUP_URL";
 /** Env var to override the discovery base origin (for local testing). */
@@ -49,7 +49,9 @@ export async function discoverSignupUrl(projectRoot, opts = {}) {
             return null;
         const json = (await res.json());
         const endpoint = json?.agent_auth?.signup_endpoint;
-        if (typeof endpoint === "string" && endpoint.trim())
+        // The key is later sent to URLs derived from this one, so only a Zenrows
+        // https endpoint is accepted from a document fetched over the network.
+        if (typeof endpoint === "string" && isZenrowsHttpsUrl(endpoint.trim()))
             return endpoint.trim();
         return null;
     }
@@ -89,7 +91,7 @@ export async function signupCandidates(projectRoot, opts = {}) {
 export async function resolveSignupUrl(projectRoot, opts = {}) {
     return (await signupCandidates(projectRoot, opts))[0];
 }
-function accountPath(projectRoot) {
+export function accountPath(projectRoot) {
     const ws = projectRoot ? workspacePaths(projectRoot) : (findWorkspace() ?? workspacePaths());
     return ws.account;
 }
@@ -98,14 +100,8 @@ export function readAccount(projectRoot) {
 }
 export function writeAccount(acct, projectRoot) {
     const file = accountPath(projectRoot);
-    writeJson(file, acct);
-    try {
-        // account.json holds the single-use claim token — restrict to owner-only.
-        chmodSync(file, 0o600);
-    }
-    catch {
-        // best-effort on platforms without POSIX permissions
-    }
+    // account.json holds the single-use claim token: owner-only from creation.
+    writePrivateJson(file, acct);
 }
 /** Remove local agent account metadata (used by `zenrows logout`). */
 export function clearAccount(projectRoot) {
@@ -201,7 +197,108 @@ function signupError(status, body) {
  * `signupUrl` override applies here too (local/staging testing).
  */
 export async function resolveAccountUrl(projectRoot, opts = {}) {
-    return (await resolveSignupUrl(projectRoot, opts)).replace(/\/signup\/?$/, "/account");
+    return siblingOfSignup(await resolveSignupUrl(projectRoot, opts), "account");
+}
+/**
+ * `…/agent/signup` → `…/agent/<name>`. A signup URL that does not end in
+ * `/signup` gives no safe sibling, so the built-in endpoint's sibling is used
+ * rather than sending the key somewhere unexpected.
+ */
+export function siblingOfSignup(signupUrl, name) {
+    const re = /\/signup\/?$/;
+    // These two endpoints receive the API key. A signup URL from the environment
+    // or a project's config (which a cloned repository could ship) is only
+    // trusted when it is Zenrows or this machine; anything else gets the
+    // built-in endpoint.
+    const base = re.test(signupUrl) && isAgentKeyDestination(signupUrl) ? signupUrl : AGENT_SIGNUP_API_URL;
+    return base.replace(re, `/${name}`);
+}
+/**
+ * Where the CLI may send the API key for the agent account endpoints: a
+ * Zenrows https URL, or http(s) on loopback (local testing). No userinfo.
+ */
+export function isAgentKeyDestination(value) {
+    if (isZenrowsHttpsUrl(value))
+        return true;
+    try {
+        const u = new URL(value);
+        const host = u.hostname.toLowerCase();
+        return ((u.protocol === "https:" || u.protocol === "http:") &&
+            u.username === "" &&
+            u.password === "" &&
+            (host === "127.0.0.1" || host === "localhost" || host === "[::1]"));
+    }
+    catch {
+        return false;
+    }
+}
+/** True for an https URL on zenrows.com or a subdomain, with no userinfo. */
+export function isZenrowsHttpsUrl(value) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        const u = new URL(value);
+        const host = u.hostname.toLowerCase();
+        return (u.protocol === "https:" &&
+            u.username === "" &&
+            u.password === "" &&
+            (host === "zenrows.com" || host.endsWith(".zenrows.com")));
+    }
+    catch {
+        return false;
+    }
+}
+/** The fresh-claim-link endpoint, derived from the signup URL like the status one. */
+export async function resolveClaimUrl(projectRoot, opts = {}) {
+    return siblingOfSignup(await resolveSignupUrl(projectRoot, opts), "claim");
+}
+/**
+ * Mint a fresh claim link for the account behind `apiKey`. Each call
+ * invalidates the previous link and the endpoint is rate-limited per key, so
+ * callers only ask when the link they hold is missing or near expiry.
+ * A 409 `already_claimed` means a person owns the account. Throws ToolkitError
+ * on any other failure.
+ */
+export async function requestClaimLink(apiKey, opts = {}) {
+    const url = opts.url ?? (await resolveClaimUrl(opts.projectRoot, { fetchImpl: opts.fetchImpl }));
+    const doFetch = opts.fetchImpl ?? fetch;
+    const res = await doFetch(url, {
+        method: "POST",
+        headers: { "X-API-Key": apiKey, Accept: "application/json", "User-Agent": CLI_USER_AGENT, ...agentClientHeader() },
+    });
+    const body = await res.text();
+    if (res.status === 200) {
+        let json = null;
+        try {
+            json = JSON.parse(body);
+        }
+        catch {
+            // not JSON: reported below
+        }
+        if (!json || typeof json.claimUrl !== "string") {
+            throw new ToolkitError({
+                code: "FETCH_FAILED",
+                message: "The claim-link endpoint answered HTTP 200 without a claim link (unexpected response body).",
+                likely_cause: body.slice(0, 240),
+                next_action: "Retry later.",
+            });
+        }
+        return {
+            status: "unclaimed",
+            claimUrl: json.claimUrl,
+            ...(typeof json.expiresAt === "string" ? { expiresAt: json.expiresAt } : {}),
+        };
+    }
+    if (res.status === 409 && /already_claimed/.test(body))
+        return { status: "claimed" };
+    if (res.status === 409 && /not_agent_account/.test(body))
+        return { status: "not_agent" };
+    throw new ToolkitError({
+        code: res.status === 401 || res.status === 403 ? "AUTH_INVALID" : "FETCH_FAILED",
+        message: `Claim link request failed (HTTP ${res.status}).`,
+        likely_cause: body.slice(0, 240),
+        next_action: res.status === 429 ? "Too many claim links requested for this key; retry in an hour." : "Retry later.",
+    });
 }
 /**
  * Ask the backend whether the account behind `apiKey` has been claimed
@@ -209,7 +306,7 @@ export async function resolveAccountUrl(projectRoot, opts = {}) {
  * `X-API-Key` header. Throws ToolkitError on failure.
  */
 export async function fetchAccountStatus(apiKey, opts = {}) {
-    const url = opts.url ?? (await resolveAccountUrl());
+    const url = opts.url ?? (await resolveAccountUrl(opts.projectRoot, { fetchImpl: opts.fetchImpl }));
     const doFetch = opts.fetchImpl ?? fetch;
     const res = await doFetch(url, {
         method: "GET",

package/dist/src/core/auth.js

@@ -4,11 +4,11 @@
  * Resolution order: explicit secrets file → ZENROWS_API_KEY env var.
  * The key is never printed in full and never written into run artifacts.
  */
-import { chmodSync, existsSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { ToolkitError } from "./errors.js";
 import { registerSecret } from "./logger.js";
 import { mask } from "./redact.js";
-import { findWorkspace, readJson, workspacePaths, writeJson } from "./workspace.js";
+import { findWorkspace, readJson, workspacePaths, writePrivateJson } from "./workspace.js";
 export const ENV_KEY = "ZENROWS_API_KEY";
 function secretsPath(projectRoot) {
     const ws = projectRoot ? workspacePaths(projectRoot) : (findWorkspace() ?? workspacePaths());
@@ -49,20 +49,14 @@ export function saveApiKey(apiKey, projectRoot) {
         });
     }
     const file = secretsPath(projectRoot);
-    writeJson(file, { apiKey: trimmed });
-    try {
-        chmodSync(file, 0o600);
-    }
-    catch {
-        // best-effort on platforms without POSIX permissions
-    }
+    writePrivateJson(file, { apiKey: trimmed });
     registerSecret(trimmed);
 }
 export function clearApiKey(projectRoot) {
     const file = secretsPath(projectRoot);
     if (!existsSync(file))
         return false;
-    writeJson(file, {});
+    writePrivateJson(file, {});
     return true;
 }
 /** Throw AUTH_MISSING if no key is configured. */

package/dist/src/core/batch-api.js

@@ -17,6 +17,7 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { ToolkitError, isKeyCapReached, keyCapReached, quotaExhausted } from "./errors.js";
+import { storedClaimHint } from "./claim-link.js";
 import { readAccount } from "./agent-account.js";
 import { registerSecret } from "./logger.js";
 import { CLI_USER_AGENT } from "./config.js";
@@ -163,7 +164,7 @@ function problemToError(status, body, method, path) {
         // a claim link (unclaimed Free plan) or dashboard/upgrade pointer, not a
         // generic "fix the problem and retry".
         const acct = readAccount();
-        return quotaExhausted(`${method} ${path}`, acct?.unclaimed ? acct.claimUrl : undefined, {
+        return quotaExhausted(`${method} ${path}`, storedClaimHint(acct), {
             status: 402,
             detail: problem.detail || problem.title || undefined,
         });

package/dist/src/core/browser-api.js

@@ -12,6 +12,7 @@
  * them (`closeSession`) — the `browser run` command does so in a `finally`.
  */
 import { ToolkitError, isKeyCapReached, keyCapReached, quotaExhausted } from "./errors.js";
+import { storedClaimHint } from "./claim-link.js";
 import { readAccount } from "./agent-account.js";
 import { registerSecret } from "./logger.js";
 import { CLI_USER_AGENT } from "./config.js";
@@ -116,7 +117,7 @@ export function browserProblemToError(status, body, method, path) {
     if (status === 402) {
         // Out of credits — same exhausted state as the scraper/batch 402.
         const acct = readAccount();
-        return quotaExhausted(`${method} ${path}`, acct?.unclaimed ? acct.claimUrl : undefined, {
+        return quotaExhausted(`${method} ${path}`, storedClaimHint(acct), {
             status: 402,
             detail: parsed.error || parsed.detail || parsed.title || undefined,
         });

package/dist/src/core/claim-link.js

@@ -0,0 +1,237 @@
+import { randomBytes } from "node:crypto";
+import { linkSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { accountPath, fetchAccountStatus, isZenrowsHttpsUrl, readAccount, requestClaimLink, writeAccount } from "./agent-account.js";
+import { resolveApiKey } from "./auth.js";
+import { CLAIM_LINK_REFRESH, CLAIM_NEXT_ACTION_PREFIX, ToolkitError, quotaNextAction } from "./errors.js";
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** The backend's claim-link lifetime. A link this old no longer works. */
+export const CLAIM_LINK_TTL_MS = 30 * DAY_MS;
+/** Ask for a fresh link once the held one is this old, before it lapses. */
+export const CLAIM_LINK_REFRESH_AGE_MS = 25 * DAY_MS;
+/** On error paths, check claim status at most this often. */
+export const CLAIM_CHECK_THROTTLE_MS = 6 * 60 * 60 * 1000;
+/** Each claim request gives up after this long, so an error is never held up for long. */
+const CLAIM_REQUEST_TIMEOUT_MS = 5000;
+/** Only an https link on zenrows.com (or a subdomain), with no userinfo, is shown or opened. */
+export function isTrustedClaimUrl(value) {
+    return isZenrowsHttpsUrl(value);
+}
+/** Age of the held link in ms, or Infinity when its issue time is unknown. */
+function linkAgeMs(acct, now) {
+    const issued = new Date(acct.claimUrlIssuedAt ?? acct.createdAt).getTime();
+    return Number.isNaN(issued) ? Infinity : now.getTime() - issued;
+}
+/** The held link if it is trusted and not yet expired, else undefined. No network. */
+export function usableClaimUrl(acct, now = new Date()) {
+    if (!isTrustedClaimUrl(acct.claimUrl))
+        return undefined;
+    return linkAgeMs(acct, now) < CLAIM_LINK_TTL_MS ? acct.claimUrl : undefined;
+}
+/** The claim hint for an error from local state alone. No network. */
+export function storedClaimHint(acct, now = new Date()) {
+    if (!acct?.unclaimed)
+        return undefined;
+    return usableClaimUrl(acct, now) ?? CLAIM_LINK_REFRESH;
+}
+/**
+ * Bring the stored claim state up to date, as far as the network allows, and
+ * report it. Steps: ask whether the account was claimed; if not, and the held
+ * link is missing, untrusted or 25+ days old, mint a fresh one and store it.
+ * Network failures are swallowed: the held link is still offered while it is
+ * under 30 days old. Unless `force` is set, the network is skipped entirely
+ * when the last check was under 6 hours ago. Throws only for a forced call
+ * whose fresh-link request failed with no usable link to fall back on.
+ */
+export async function refreshClaimState(opts = {}) {
+    const { projectRoot } = opts;
+    const now = opts.now ?? new Date();
+    const first = readAccount(projectRoot);
+    if (!first)
+        return { status: "none" };
+    if (!first.unclaimed)
+        return { status: "claimed" };
+    if (!opts.force && throttled(first, now))
+        return offlineState(first, now);
+    const key = opts.apiKey ?? resolveApiKey(projectRoot).key;
+    if (!key)
+        return offlineState(first, now);
+    // Several `zenrows` processes can hit a 402 at once. Only the one holding the
+    // lock talks to the claim endpoints; the others use what is stored.
+    const release = acquireClaimLock(projectRoot);
+    if (!release)
+        return offlineState(readAccount(projectRoot) ?? first, now);
+    try {
+        return await refreshLocked(key, opts, now);
+    }
+    finally {
+        release();
+    }
+}
+async function refreshLocked(key, opts, now) {
+    const { projectRoot } = opts;
+    // Re-read under the lock: another process may have just finished a refresh.
+    let acct = readAccount(projectRoot);
+    if (!acct)
+        return { status: "none" };
+    if (!acct.unclaimed)
+        return { status: "claimed" };
+    if (!opts.force && throttled(acct, now))
+        return offlineState(acct, now);
+    // Take the 6-hour slot before any network call, so a failing backend is not
+    // retried by every command that follows.
+    acct = { ...acct, lastClaimCheckAt: now.toISOString() };
+    writeAccount(acct, projectRoot);
+    const base = opts.fetchImpl ?? fetch;
+    const fetchImpl = ((url, init) => base(url, { ...init, signal: AbortSignal.timeout(CLAIM_REQUEST_TIMEOUT_MS) }));
+    try {
+        const remote = await fetchAccountStatus(key, { url: opts.accountUrl, fetchImpl, projectRoot });
+        if (remote.claimed === true)
+            return markClaimed(acct, projectRoot);
+    }
+    catch {
+        // Status unknown: carry on and judge the held link on its own.
+    }
+    // Re-read before minting: minting replaces the link everyone else holds.
+    acct = readAccount(projectRoot) ?? acct;
+    if (!acct.unclaimed)
+        return { status: "claimed" };
+    if (!needsNewLink(acct, now))
+        return offlineState(acct, now);
+    let fresh;
+    try {
+        fresh = await requestClaimLink(key, { url: opts.claimUrl, fetchImpl, projectRoot });
+    }
+    catch (err) {
+        if (opts.force && !usableClaimUrl(acct, now)) {
+            if (err instanceof ToolkitError)
+                throw err;
+            throw new ToolkitError({
+                code: "BACKEND_UNAVAILABLE",
+                message: "Could not reach Zenrows to get a fresh claim link.",
+                likely_cause: err instanceof Error ? err.message : String(err),
+                next_action: "The stored claim link has expired. Check connectivity and run `zenrows account claim` again.",
+                suggested_commands: ["zenrows account claim"],
+            });
+        }
+        return offlineState(acct, now);
+    }
+    // Both 409s are final: a person owns the account, so there is nothing to claim.
+    if (fresh.status === "claimed" || fresh.status === "not_agent")
+        return markClaimed(acct, projectRoot);
+    if (!isTrustedClaimUrl(fresh.claimUrl)) {
+        if (opts.force && !usableClaimUrl(acct, now)) {
+            throw new ToolkitError({
+                code: "FETCH_FAILED",
+                message: "The claim-link endpoint returned a URL outside zenrows.com; it was not used.",
+                likely_cause: "The signup/claim endpoint override points at an unexpected server.",
+                next_action: "Check ZENROWS_AGENT_SIGNUP_URL / `signupUrl` in the zenrows config, then retry.",
+            });
+        }
+        return offlineState(acct, now);
+    }
+    const latest = readAccount(projectRoot) ?? acct;
+    writeAccount({ ...latest, claimUrl: fresh.claimUrl, claimUrlIssuedAt: now.toISOString() }, projectRoot);
+    return { status: "unclaimed", claimUrl: fresh.claimUrl, refreshed: true };
+}
+function throttled(acct, now) {
+    if (!acct.lastClaimCheckAt)
+        return false;
+    const last = new Date(acct.lastClaimCheckAt).getTime();
+    return !Number.isNaN(last) && now.getTime() - last < CLAIM_CHECK_THROTTLE_MS;
+}
+function needsNewLink(acct, now) {
+    return !isTrustedClaimUrl(acct.claimUrl) || linkAgeMs(acct, now) >= CLAIM_LINK_REFRESH_AGE_MS;
+}
+function offlineState(acct, now) {
+    if (!acct.unclaimed)
+        return { status: "claimed" };
+    return { status: "unclaimed", claimUrl: usableClaimUrl(acct, now), refreshed: false };
+}
+/** A lock older than this is from a process that died mid-refresh. */
+const CLAIM_LOCK_STALE_MS = 60 * 1000;
+/**
+ * Create `account.json.lock` exclusively, holding a random token. Returns a
+ * release function, or null when another live process holds the lock.
+ *
+ * A lock older than CLAIM_LOCK_STALE_MS is taken over by renaming it aside
+ * first (only one process can rename it away). If what was renamed turns out
+ * to be live, it is put back and this process gives up. Release deletes the
+ * lock only while it still holds this process's token.
+ */
+function acquireClaimLock(projectRoot) {
+    const lock = `${accountPath(projectRoot)}.lock`;
+    const token = randomBytes(16).toString("hex");
+    const release = () => {
+        try {
+            if (readFileSync(lock, "utf8") === token)
+                unlinkSync(lock);
+        }
+        catch {
+        }
+    };
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            writeFileSync(lock, token, { flag: "wx", mode: 0o600 });
+            return readFileSync(lock, "utf8") === token ? release : null;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                return null;
+            try {
+                if (Date.now() - statSync(lock).mtimeMs < CLAIM_LOCK_STALE_MS)
+                    return null;
+                const aside = `${lock}.${token}.stale`;
+                renameSync(lock, aside);
+                if (Date.now() - statSync(aside).mtimeMs < CLAIM_LOCK_STALE_MS) {
+                    // Another process replaced the stale lock between our checks: restore it.
+                    try {
+                        linkSync(aside, lock);
+                    }
+                    catch {
+                    }
+                    unlinkSync(aside);
+                    return null;
+                }
+                unlinkSync(aside);
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    return null;
+}
+/** Test-only: the lock path, so tests can simulate other processes. */
+export function _claimLockPath(projectRoot) {
+    return `${accountPath(projectRoot)}.lock`;
+}
+function markClaimed(acct, projectRoot) {
+    writeAccount({ ...acct, unclaimed: false }, projectRoot);
+    return { status: "claimed" };
+}
+/** The error hint for a refreshed state. */
+export function claimHintFor(state) {
+    if (state.status !== "unclaimed")
+        return undefined;
+    return state.claimUrl ?? CLAIM_LINK_REFRESH;
+}
+/**
+ * Bring a quota error's claim advice up to date before it is shown. Errors are
+ * built synchronously from `account.json`; this runs the throttled refresh and
+ * rewrites `next_action` if the account was claimed or the link changed. Never
+ * throws: on any failure the error is returned as it was.
+ */
+export async function refreshClaimAdvice(err, opts = {}) {
+    try {
+        if (!(err instanceof ToolkitError) || !err.next_action.startsWith(CLAIM_NEXT_ACTION_PREFIX))
+            return err;
+        const state = await refreshClaimState({ ...opts, force: false });
+        const next = quotaNextAction(claimHintFor(state));
+        if (next === err.next_action)
+            return err;
+        return new ToolkitError({ ...err.toJSON(), next_action: next });
+    }
+    catch {
+        return err;
+    }
+}

package/dist/src/core/config.js

@@ -14,7 +14,7 @@ export const CONFIG_VERSION = "0.1.0";
  * entrypoint) so core modules — telemetry, signup provenance — can read it
  * without an import cycle. `VERSION` in `cli/index.ts` re-exports this.
  */
-export const CLI_VERSION = "1.6.1"; // x-release-please-version
+export const CLI_VERSION = "1.7.0"; // x-release-please-version
 /** The User-Agent on every request to a Zenrows API. The gateway reads the version from it. */
 export const CLI_USER_AGENT = `zenrows-cli/${CLI_VERSION}`;
 /** Env var to override the Fetch and Extract API base (local/staging testing). */

package/dist/src/core/crawl-api.js

@@ -15,6 +15,7 @@
  */
 import { Readable } from "node:stream";
 import { ToolkitError, isKeyCapReached, keyCapReached, quotaExhausted } from "./errors.js";
+import { storedClaimHint } from "./claim-link.js";
 import { readAccount } from "./agent-account.js";
 import { registerSecret } from "./logger.js";
 import { CLI_USER_AGENT, loadConfig } from "./config.js";
@@ -245,7 +246,7 @@ function classifyProblem(status, problem, body, request, serverCode, retryAfter)
             return new ToolkitError({ ...keyCapReached(request, { status, detail }).toJSON(), code: "CRAWL_KEY_CAP_REACHED" });
         }
         const acct = readAccount();
-        const quota = quotaExhausted(request, acct?.unclaimed ? acct.claimUrl : undefined, { status, detail });
+        const quota = quotaExhausted(request, storedClaimHint(acct), { status, detail });
         return new ToolkitError({ ...quota.toJSON(), code: "CRAWL_INSUFFICIENT_CREDITS" });
     }
     if (status === 409) {

package/dist/src/core/ensure-key.js

@@ -15,6 +15,7 @@ export async function ensureApiKey(policy, opts = {}) {
         claimUrl: res.claimUrl,
         createdAt: new Date().toISOString(),
     };
+    account.claimUrlIssuedAt = account.createdAt;
     writeAccount(account, opts.projectRoot);
     opts.onProvision?.(account);
     return res.apiKey;

package/dist/src/core/errors.js

@@ -49,26 +49,36 @@ export class ToolkitError extends Error {
  * credits stopped: its status call succeeded, so there is no HTTP error to cite,
  * only `url` (the crawl).
  */
-export function quotaExhausted(url, claimUrl, opts = {}) {
-    // Say that the allowance comes back. Without it this reads as a permanent paywall,
-    // which is how the API's own AUTH004 text reads ("Purchase a new subscription to
-    // continue") and why exhausted clients retry-loop instead of waiting or upgrading —
-    // one account spent seven days at ~3 req/s against this wall. `zenrows usage` prints
-    // the exact `period_ends_at`, so the date is one command away rather than guessed here.
-    const renewLine = "Credits renew at the end of the billing period — run `zenrows usage` for the date.";
-    const claimLine = claimUrl
-        ? `You are on the Zenrows Free plan. Claim your account to keep your usage and add credits: ${claimUrl}. ${renewLine}`
-        : `You are out of Zenrows credits. ${renewLine} To carry on now, add a credit pack (${BILLING_TOPUP_URL} opens the purchase directly) or upgrade your plan: ${PLANS_URL}`;
+export function quotaExhausted(url, claim, opts = {}) {
     const detail = opts.detail ? `${opts.detail.replace(/\.\s*$/, "")}. ` : "";
     const where = opts.status === null ? `Stopped ${url}` : `HTTP ${opts.status ?? 429} for ${url}`;
     return new ToolkitError({
         code: "POLICY_MAX_CREDITS_EXCEEDED",
         message: "Zenrows request quota exhausted.",
         likely_cause: `${detail}${where}`,
-        next_action: claimLine,
+        next_action: quotaNextAction(claim),
         suggested_commands: ["zenrows usage"],
     });
 }
+export const CLAIM_LINK_REFRESH = Symbol("claim-link-refresh");
+/** Start of `next_action` on a quota error for an unclaimed account. */
+export const CLAIM_NEXT_ACTION_PREFIX = "You are on the Zenrows Free plan.";
+/** The `next_action` of a quota error for the given claim state. */
+export function quotaNextAction(claim) {
+    // Say that the allowance comes back. Without it this reads as a permanent paywall,
+    // which is how the API's own AUTH004 text reads ("Purchase a new subscription to
+    // continue") and why exhausted clients retry-loop instead of waiting or upgrading.
+    // `zenrows usage` prints the exact `period_ends_at`, so the date is one command away
+    // rather than guessed here.
+    const renewLine = "Credits renew at the end of the billing period — run `zenrows usage` for the date.";
+    if (claim === CLAIM_LINK_REFRESH) {
+        return `${CLAIM_NEXT_ACTION_PREFIX} Claim your account to keep your usage and add credits: run \`zenrows account claim\` for a fresh claim link. ${renewLine}`;
+    }
+    if (claim) {
+        return `${CLAIM_NEXT_ACTION_PREFIX} Claim your account to keep your usage and add credits: ${claim}. ${renewLine}`;
+    }
+    return `You are out of Zenrows credits. ${renewLine} To carry on now, add a credit pack (${BILLING_TOPUP_URL} opens the purchase directly) or upgrade your plan: ${PLANS_URL}`;
+}
 /** Where an account manages its API keys and their credit caps. */
 export const API_KEYS_SETTINGS_URL = "https://app.zenrows.com/settings/api-keys";
 /**

package/dist/src/core/http.js

@@ -6,6 +6,7 @@
  * from any logged URL.
  */
 import { ToolkitError, isKeyCapReached, keyCapReached, quotaExhausted } from "./errors.js";
+import { storedClaimHint, usableClaimUrl } from "./claim-link.js";
 import { readAccount } from "./agent-account.js";
 import { ENV_KEY, resolveApiKey } from "./auth.js";
 import { registerSecret } from "./logger.js";
@@ -143,7 +144,7 @@ export async function scrape(apiBase, apiKey, params, opts = {}) {
                     message: "The auto-provisioned Free plan key was rejected by the Zenrows API.",
                     likely_cause: `${cause}. The signup endpoint issued this key, but the scraping API did not accept it.`,
                     next_action: "If you are testing against a local/staging backend, ensure `apiBase` (zenrows config) points at the same environment that issued the key. Otherwise re-provision with `zenrows signup --agent`, or claim the account: " +
-                        acct.claimUrl,
+                        (usableClaimUrl(acct) ?? "run `zenrows account claim` for a link"),
                     suggested_commands: ["zenrows status", "zenrows signup --agent"],
                 });
             }
@@ -184,7 +185,7 @@ export async function scrape(apiBase, apiKey, params, opts = {}) {
         // out of credits. This is NOT scraped content — surface it as a credits
         // error (claim link for an unclaimed Free plan, dashboard/upgrade otherwise).
         const acct = readAccount();
-        throw quotaExhausted(redacted, acct?.unclaimed ? acct.claimUrl : undefined, {
+        throw quotaExhausted(redacted, storedClaimHint(acct), {
             status: 402,
             detail: zrErrorDetail(body) ?? undefined,
         });
@@ -196,7 +197,7 @@ export async function scrape(apiBase, apiKey, params, opts = {}) {
         // limit; otherwise advise a brief retry.
         if (isQuotaError(body)) {
             const acct = readAccount();
-            throw quotaExhausted(redacted, acct?.unclaimed ? acct.claimUrl : undefined);
+            throw quotaExhausted(redacted, storedClaimHint(acct));
         }
         const detail = zrErrorDetail(body) ?? snippet(body);
         throw new ToolkitError({

package/dist/src/core/nudge.js

@@ -1,5 +1,6 @@
 import { readAccount, writeAccount } from "./agent-account.js";
 import { resolveApiKey } from "./auth.js";
+import { usableClaimUrl } from "./claim-link.js";
 import { log } from "./logger.js";
 import { fetchUsage } from "./usage.js";
 /** How high usage must be (percent) before we nudge. */
@@ -15,7 +16,8 @@ export function nudgeMessage(account, usagePercent, _now) {
     if (!account.unclaimed)
         return null;
     if (typeof usagePercent === "number" && usagePercent >= USAGE_NUDGE_PERCENT) {
-        return `You've used ${usagePercent}% of your Zenrows Free plan — claim your account to keep your usage & history: ${account.claimUrl}`;
+        const link = usableClaimUrl(account, _now) ?? "run `zenrows account claim` for a claim link";
+        return `You've used ${usagePercent}% of your Zenrows Free plan — claim your account to keep your usage & history: ${link}`;
     }
     return null;
 }

package/dist/src/core/provenance.js

@@ -10,17 +10,25 @@
 function hasPrefix(env, prefix) {
     return Object.keys(env).some((k) => k.startsWith(prefix));
 }
+/**
+ * Variables the agent itself sets in the shells it runs commands in, so they
+ * mean the agent is driving this command (the same signals as agent-client.ts).
+ * Variables that only show the agent is installed or configured (CODEX_HOME,
+ * ANTHROPIC_API_KEY, OPENAI_API_KEY, other CLAUDE_* settings) are not used.
+ */
+const CLAUDE_VARS = ["CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT", "CLAUDE_CODE_CHILD_SESSION"];
+const CODEX_VARS = ["CODEX_SANDBOX", "CODEX_SANDBOX_NETWORK_DISABLED", "CODEX_THREAD_ID"];
 /** Detect the host agent brand + runtime, best-effort, from env vars. */
 export function detectClient(env = process.env) {
     const term = env.TERM_PROGRAM;
     let client = "unknown";
-    if (env.CLAUDECODE || hasPrefix(env, "CLAUDE_CODE") || hasPrefix(env, "CLAUDE_")) {
+    if (CLAUDE_VARS.some((v) => env[v])) {
         client = "claude-code";
     }
     else if (env.CURSOR_TRACE_ID || hasPrefix(env, "CURSOR_") || term === "cursor") {
         client = "cursor";
     }
-    else if (hasPrefix(env, "OPENAI_") || hasPrefix(env, "CODEX_")) {
+    else if (CODEX_VARS.some((v) => env[v])) {
         client = "openai-codex";
     }
     else if (hasPrefix(env, "WINDSURF")) {

package/dist/src/core/usage.js

@@ -7,6 +7,7 @@
  * safe to poll. The API key is registered as a secret so it is redacted in logs.
  */
 import { ToolkitError, quotaExhausted } from "./errors.js";
+import { storedClaimHint } from "./claim-link.js";
 import { isQuotaError, zrErrorDetail } from "./http.js";
 import { readAccount } from "./agent-account.js";
 import { ENV_KEY, resolveApiKey } from "./auth.js";
@@ -63,7 +64,7 @@ export async function fetchUsage(apiBase, apiKey, opts = {}) {
         // scraper 402. Surface it as a credits error (claim link for an unclaimed
         // Free plan account, dashboard/upgrade otherwise) instead of a generic "retry".
         const acct = readAccount();
-        throw quotaExhausted(url, acct?.unclaimed ? acct.claimUrl : undefined, {
+        throw quotaExhausted(url, storedClaimHint(acct), {
             status: res.status,
             detail: zrErrorDetail(body) ?? undefined,
         });

package/dist/src/core/workspace.js

@@ -5,7 +5,7 @@
  * assets, traces, and logs. Secrets live in `.zenrows/secrets.json`, which is
  * gitignored and never written into run artifacts.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 export const WORKSPACE_DIRNAME = ".zenrows";
 /** Subdirectories created inside `.zenrows/`. */
@@ -96,3 +96,31 @@ export function writeJson(file, value) {
     mkdirSync(dirname(file), { recursive: true });
     writeFileSync(file, JSON.stringify(value, null, 2) + "\n");
 }
+/**
+ * Write a file only its owner may read (secrets, account metadata). The data
+ * goes to a temp file created 0600 and is renamed into place, so the target is
+ * never readable by others, not even for a moment, and a reader never sees a
+ * half-written file. A directory this creates is 0700.
+ */
+export function writePrivateJson(file, value) {
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        writeFileSync(tmp, JSON.stringify(value, null, 2) + "\n", { mode: 0o600, flag: "wx" });
+        try {
+            chmodSync(tmp, 0o600); // the umask can only remove bits, but be explicit
+        }
+        catch {
+            // best-effort on platforms without POSIX permissions
+        }
+        renameSync(tmp, file);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+        }
+        throw err;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenrows/cli",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "Open-source CLI, MCP, skills, templates, workflows, recipes, and evals layer for giving AI agents reliable access to protected web data through Zenrows cloud infrastructure.",
   "type": "module",
   "license": "MIT",

package/skills/crawl/SKILL.md

@@ -39,6 +39,10 @@ zenrows crawl results <id> --out urls.jsonl  # same, as JSONL
 - `--include-patterns` / `--exclude-patterns` are substring matches on the
   normalized URL and repeat:
   `--include-patterns /product/ --exclude-patterns ?add-to-cart`.
+- A crawl whose pages held nothing new to follow (no link, only links to other
+  sites, or only links the patterns reject) ends `completed` with no results
+  and exits 0. When patterns were set, it prints a note (under `--json`, in
+  `note`) to check them against the URLs the start page links to.
 - `create` returns at once. `--follow` (or `zenrows crawl wait <id>`) polls
   until the crawl ends or `--timeout` seconds run out (default 600). When the
   time runs out, the command exits 0 and prints the crawl with status
@@ -85,7 +89,10 @@ credit cap; the pages fetched before that stay readable. `failed`, and a
 `stopped` crawl with an `error`, exit non-zero: `CRAWL_INSUFFICIENT_CREDITS` or
 `CRAWL_KEY_CAP_REACHED` when credits ended it (the same codes a refused
 `create` gets, also when an older deployment reports it `failed`), else
-`CRAWL_FAILED`. `server_code` carries the API's `error.code`.
+`CRAWL_FAILED`. `server_code` carries the API's `error.code`:
+`seed_unreachable` when the start URL could not be fetched or returned an empty
+page, `no_items_found` when the crawl read the start page but found no data it
+could use.
 `stop` on a crawl that already ended prints the status it ended with.
 
 With `--json`, `create`, `get`, `wait` and `stop` print

package/skills/zenrows/SKILL.md

@@ -22,7 +22,9 @@ key locally — no human step required. To opt out, pass `--no-signup` or set
 
 When the Free plan nears its limit (or the user asks), tell the human they can **claim** the
 account to keep their usage and history: run `zenrows account claim` (or open the claim URL
-shown on quota errors). Claiming sets an email + password; the same key keeps working.
+shown on quota errors). It prints a valid link, requesting a fresh one when the stored link is
+near its 30-day expiry. Claiming confirms an email (Google, GitHub or a 6-digit code); the same
+key keeps working.
 Never attempt to handle payment or upgrades — only surface the claim link.
 
 ## The decision tree (follow this exactly)