mcp-scraper 0.2.12 → 0.2.14

package/dist/bin/api-server.cjs

@@ -7099,6 +7099,20 @@ async function migrate() {
     await db.execute(`ALTER TABLE users ADD COLUMN concurrency_stripe_sub_id TEXT`);
   } catch {
   }
+  await db.execute(`
+    CREATE TABLE IF NOT EXISTS concurrency_locks (
+      id          TEXT PRIMARY KEY,
+      user_id     INTEGER NOT NULL REFERENCES users(id),
+      operation   TEXT NOT NULL,
+      status      TEXT NOT NULL DEFAULT 'active',
+      acquired_at TEXT NOT NULL DEFAULT (datetime('now')),
+      expires_at  TEXT NOT NULL,
+      released_at TEXT,
+      metadata    TEXT
+    )
+  `);
+  await db.execute(`CREATE INDEX IF NOT EXISTS concurrency_locks_user_status ON concurrency_locks(user_id, status, expires_at)`);
+  await db.execute(`CREATE INDEX IF NOT EXISTS concurrency_locks_operation ON concurrency_locks(operation, status, expires_at)`);
   await db.execute(`
     CREATE TABLE IF NOT EXISTS ledger (
       id          INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -8672,6 +8686,19 @@ var init_site_audit_routes = __esm({
 function browserActiveCostMc(activeMs) {
   return Math.round(activeMs * MC_PER_BROWSER_MS);
 }
+function concurrencySlotBillingInfo() {
+  const billingUrl = process.env.CONCURRENCY_BILLING_URL ?? "https://mcpscraper.dev/billing";
+  return {
+    product: "Extra concurrency slot",
+    price_label: CONCURRENCY_SLOT_PRICE_LABEL,
+    unit_amount_usd: CONCURRENCY_SLOT_PRICE_USD,
+    currency: CONCURRENCY_SLOT_PRICE_CURRENCY,
+    interval: CONCURRENCY_SLOT_PRICE_INTERVAL,
+    billing_url: billingUrl,
+    terminal_command: CONCURRENCY_SLOT_TERMINAL_COMMAND,
+    terminal_command_with_api_key_env: `MCP_SCRAPER_API_KEY=sk_live_your_key ${CONCURRENCY_SLOT_TERMINAL_COMMAND}`
+  };
+}
 function mcToCredits(mc) {
   return mc / MC_PER_CREDIT;
 }
@@ -8688,7 +8715,7 @@ function insufficientBalanceResponse(balanceMc, requiredMc) {
     topup_url: topupUrl
   };
 }
-var MC_COSTS, MC_PER_BROWSER_MS, BROWSER_OPEN_MIN_BALANCE_MC, MC_PER_CREDIT, CREDIT_COST_CATALOG, CONCURRENCY_PRICE_ID, FREE_SIGNUP_MC, FREE_MONTHLY_REFRESH_MC, BALANCE_PRICE_IDS, BALANCE_PACK_LABELS, LedgerOperation;
+var MC_COSTS, MC_PER_BROWSER_MS, BROWSER_OPEN_MIN_BALANCE_MC, MC_PER_CREDIT, CREDIT_COST_CATALOG, CONCURRENCY_PRICE_ID, CONCURRENCY_SLOT_PRICE_USD, CONCURRENCY_SLOT_PRICE_CURRENCY, CONCURRENCY_SLOT_PRICE_INTERVAL, CONCURRENCY_SLOT_PRICE_LABEL, CONCURRENCY_SLOT_TERMINAL_COMMAND, FREE_SIGNUP_MC, FREE_MONTHLY_REFRESH_MC, BALANCE_PRICE_IDS, BALANCE_PACK_LABELS, LedgerOperation;
 var init_rates = __esm({
   "src/api/rates.ts"() {
     "use strict";
@@ -8815,6 +8842,11 @@ var init_rates = __esm({
       }
     ];
     CONCURRENCY_PRICE_ID = "price_1Ta1NRS8aAcsk3TGwsRnYbix";
+    CONCURRENCY_SLOT_PRICE_USD = 5;
+    CONCURRENCY_SLOT_PRICE_CURRENCY = "usd";
+    CONCURRENCY_SLOT_PRICE_INTERVAL = "month";
+    CONCURRENCY_SLOT_PRICE_LABEL = "$5/month";
+    CONCURRENCY_SLOT_TERMINAL_COMMAND = "npx -y -p mcp-scraper@latest mcp-scraper-cli billing concurrency checkout";
     FREE_SIGNUP_MC = 5e5;
     FREE_MONTHLY_REFRESH_MC = 25e4;
     BALANCE_PRICE_IDS = {
@@ -10383,6 +10415,187 @@ var init_server_schemas = __esm({
   }
 });
 
+// src/api/concurrency-gates.ts
+function concurrencyLimitForUser(user) {
+  return 1 + Math.max(0, Number(user.extra_concurrency_slots ?? 0));
+}
+function concurrencyLimitExceededResponse(gate) {
+  const upgrade = concurrencySlotBillingInfo();
+  const message = `You have ${gate.active} active operation${gate.active !== 1 ? "s" : ""}. Your account allows ${gate.limit} concurrent operation${gate.limit !== 1 ? "s" : ""}. Wait for one to finish, or add an extra concurrency slot for ${upgrade.price_label} at ${upgrade.billing_url}. Terminal upgrade: ${upgrade.terminal_command}`;
+  return {
+    error: message,
+    message,
+    error_code: "concurrency_limit_exceeded",
+    error_type: "concurrency_limit",
+    retryable: true,
+    active: gate.active,
+    limit: gate.limit,
+    operation: gate.operation,
+    upgrade,
+    upgrade_url: upgrade.billing_url,
+    upgrade_command: upgrade.terminal_command
+  };
+}
+function isConcurrencyLimitBypassed(user) {
+  const raw = process.env.CONCURRENCY_LIMIT_BYPASS_EMAILS ?? process.env.HARVEST_LIMIT_BYPASS_EMAILS ?? "";
+  return raw.split(",").map((email) => email.trim()).filter(Boolean).includes(user.email);
+}
+function lockTtlModifier(ttlSeconds) {
+  const ttl = Number.isFinite(ttlSeconds) ? Math.max(30, Math.min(Math.trunc(Number(ttlSeconds)), MAX_LOCK_TTL_SECONDS)) : DEFAULT_LOCK_TTL_SECONDS;
+  return `+${ttl} seconds`;
+}
+function safeMetadata(metadata) {
+  if (!metadata) return null;
+  try {
+    return JSON.stringify(metadata).slice(0, 4e3);
+  } catch {
+    return null;
+  }
+}
+async function ensureConcurrencyGateSchema() {
+  if (!schemaReady) {
+    schemaReady = (async () => {
+      const db = getDb();
+      await db.execute(`
+        CREATE TABLE IF NOT EXISTS concurrency_locks (
+          id          TEXT PRIMARY KEY,
+          user_id     INTEGER NOT NULL REFERENCES users(id),
+          operation   TEXT NOT NULL,
+          status      TEXT NOT NULL DEFAULT 'active',
+          acquired_at TEXT NOT NULL DEFAULT (datetime('now')),
+          expires_at  TEXT NOT NULL,
+          released_at TEXT,
+          metadata    TEXT
+        )
+      `);
+      await db.execute(`CREATE INDEX IF NOT EXISTS concurrency_locks_user_status ON concurrency_locks(user_id, status, expires_at)`);
+      await db.execute(`CREATE INDEX IF NOT EXISTS concurrency_locks_operation ON concurrency_locks(operation, status, expires_at)`);
+    })();
+  }
+  return schemaReady;
+}
+async function expireConcurrencyLocksForUser(userId) {
+  await ensureConcurrencyGateSchema();
+  await getDb().execute({
+    sql: `UPDATE concurrency_locks
+          SET status = 'expired', released_at = datetime('now')
+          WHERE user_id = ? AND status = 'active' AND expires_at <= datetime('now')`,
+    args: [userId]
+  });
+}
+async function countActiveUsageForUser(userId) {
+  await ensureConcurrencyGateSchema();
+  await expireConcurrencyLocksForUser(userId);
+  const res = await getDb().execute({
+    sql: `SELECT
+            (
+              SELECT COUNT(*)
+              FROM jobs
+              WHERE user_id = ?
+                AND (status = 'pending' OR (status = 'running' AND started_at > datetime('now', '-10 minutes')))
+            ) +
+            (
+              SELECT COUNT(*)
+              FROM concurrency_locks
+              WHERE user_id = ? AND status = 'active' AND expires_at > datetime('now')
+            ) AS n`,
+    args: [userId, userId]
+  });
+  return Number(res.rows[0]?.n ?? 0);
+}
+async function reuseExistingConcurrencyGate(userId, lockId, ttlSeconds) {
+  if (!/^cl_[a-f0-9]{24,32}$/.test(lockId)) return false;
+  await ensureConcurrencyGateSchema();
+  await expireConcurrencyLocksForUser(userId);
+  const res = await getDb().execute({
+    sql: `UPDATE concurrency_locks
+          SET expires_at = datetime('now', ?)
+          WHERE id = ?
+            AND user_id = ?
+            AND status = 'active'
+            AND expires_at > datetime('now')`,
+    args: [lockTtlModifier(ttlSeconds), lockId, userId]
+  });
+  return Number(res.rowsAffected ?? 0) > 0;
+}
+async function acquireConcurrencyGate(user, operation, options = {}) {
+  await ensureConcurrencyGateSchema();
+  const limit = concurrencyLimitForUser(user);
+  if (isConcurrencyLimitBypassed(user)) {
+    return { ok: true, lockId: null, active: 0, limit, operation, bypassed: true };
+  }
+  if (options.reuseLockId && await reuseExistingConcurrencyGate(user.id, options.reuseLockId, options.ttlSeconds)) {
+    return { ok: true, lockId: null, active: await countActiveUsageForUser(user.id), limit, operation, reused: true };
+  }
+  await expireConcurrencyLocksForUser(user.id);
+  const lockId = `cl_${(0, import_node_crypto2.randomUUID)().replace(/-/g, "").slice(0, 24)}`;
+  const res = await getDb().execute({
+    sql: `INSERT INTO concurrency_locks (id, user_id, operation, status, expires_at, metadata)
+          SELECT ?, ?, ?, 'active', datetime('now', ?), ?
+          WHERE (
+            (
+              SELECT COUNT(*)
+              FROM jobs
+              WHERE user_id = ?
+                AND (status = 'pending' OR (status = 'running' AND started_at > datetime('now', '-10 minutes')))
+            ) +
+            (
+              SELECT COUNT(*)
+              FROM concurrency_locks
+              WHERE user_id = ? AND status = 'active' AND expires_at > datetime('now')
+            )
+          ) < ?`,
+    args: [
+      lockId,
+      user.id,
+      operation,
+      lockTtlModifier(options.ttlSeconds),
+      safeMetadata(options.metadata),
+      user.id,
+      user.id,
+      limit
+    ]
+  });
+  const active = await countActiveUsageForUser(user.id);
+  if (Number(res.rowsAffected ?? 0) > 0) {
+    return { ok: true, lockId, active, limit, operation };
+  }
+  return { ok: false, active, limit, operation, retryAfterSeconds: DEFAULT_RETRY_AFTER_SECONDS };
+}
+async function releaseConcurrencyGate(lockId) {
+  if (!lockId) return;
+  await ensureConcurrencyGateSchema();
+  await getDb().execute({
+    sql: `UPDATE concurrency_locks
+          SET status = 'released', released_at = datetime('now')
+          WHERE id = ? AND status = 'active'`,
+    args: [lockId]
+  });
+}
+async function extendConcurrencyGate(lockId, ttlSeconds = DEFAULT_LOCK_TTL_SECONDS) {
+  if (!lockId) return;
+  await ensureConcurrencyGateSchema();
+  await getDb().execute({
+    sql: `UPDATE concurrency_locks
+          SET expires_at = datetime('now', ?)
+          WHERE id = ? AND status = 'active' AND expires_at > datetime('now')`,
+    args: [lockTtlModifier(ttlSeconds), lockId]
+  });
+}
+var import_node_crypto2, DEFAULT_LOCK_TTL_SECONDS, DEFAULT_RETRY_AFTER_SECONDS, MAX_LOCK_TTL_SECONDS, schemaReady;
+var init_concurrency_gates = __esm({
+  "src/api/concurrency-gates.ts"() {
+    "use strict";
+    import_node_crypto2 = require("crypto");
+    init_db();
+    init_rates();
+    DEFAULT_LOCK_TTL_SECONDS = 15 * 60;
+    DEFAULT_RETRY_AFTER_SECONDS = 30;
+    MAX_LOCK_TTL_SECONDS = 24 * 60 * 60;
+    schemaReady = null;
+  }
+});
+
 // src/api/youtube-routes.ts
 function buildTranscriptMarkdown(result) {
   const lines = [];
@@ -10444,6 +10657,7 @@ var init_youtube_routes = __esm({
     init_errors();
     init_api_auth();
     init_server_schemas();
+    init_concurrency_gates();
     youtubeApp = new import_hono2.Hono();
     youtubeApp.post("/harvest", createApiKeyAuth(), async (c) => {
       const raw = await c.req.json().catch(() => ({}));
@@ -10457,9 +10671,16 @@ var init_youtube_routes = __esm({
         return c.json({ error: "channel mode requires channelHandle (@handle or UC... ID)" }, 400);
       }
       const user = c.get("user");
-      const { ok: ytOk, balance_mc: ytBal } = await debitMc(user.id, MC_COSTS.yt_channel, LedgerOperation.YT_CHANNEL, query ?? channelHandle ?? "");
-      if (!ytOk) return c.json(insufficientBalanceResponse(ytBal, MC_COSTS.yt_channel), 402);
+      const gate = await acquireConcurrencyGate(user, "youtube_harvest", {
+        reuseLockId: c.req.header("x-mcp-scraper-concurrency-lock"),
+        metadata: { mode, query, channelHandle }
+      });
+      if (!gate.ok) return c.json(concurrencyLimitExceededResponse(gate), 429, { "Retry-After": String(gate.retryAfterSeconds) });
+      let debited = false;
       try {
+        const { ok: ytOk, balance_mc: ytBal } = await debitMc(user.id, MC_COSTS.yt_channel, LedgerOperation.YT_CHANNEL, query ?? channelHandle ?? "");
+        if (!ytOk) return c.json(insufficientBalanceResponse(ytBal, MC_COSTS.yt_channel), 402);
+        debited = true;
         const normalizedChannelUrl = mode === "channel" ? buildYouTubeChannelVideosUrl(channelHandle.trim()) : void 0;
         const result = await ytHarvest({
           mode,
@@ -10484,13 +10705,15 @@ var init_youtube_routes = __esm({
           return c.json({ error: msg }, 400);
         }
         if (err instanceof CaptchaError || msg.includes("CAPTCHA") || msg.includes("blocked")) {
-          await creditMc(user.id, MC_COSTS.yt_channel, LedgerOperation.YT_CHANNEL_REFUND, "failed call");
+          if (debited) await creditMc(user.id, MC_COSTS.yt_channel, LedgerOperation.YT_CHANNEL_REFUND, "failed call");
           await logRequestEvent({ userId: user.id, source: "youtube_harvest", status: "failed", query: mode === "search" ? query?.trim() ?? "" : channelHandle?.trim() ?? "", error: msg });
           return c.json({ error: msg }, 503);
         }
-        await creditMc(user.id, MC_COSTS.yt_channel, LedgerOperation.YT_CHANNEL_REFUND, "failed call");
+        if (debited) await creditMc(user.id, MC_COSTS.yt_channel, LedgerOperation.YT_CHANNEL_REFUND, "failed call");
         await logRequestEvent({ userId: user.id, source: "youtube_harvest", status: "failed", query: mode === "search" ? query?.trim() ?? "" : channelHandle?.trim() ?? "", error: msg });
         return c.json({ error: msg }, 500);
+      } finally {
+        await releaseConcurrencyGate(gate.lockId);
       }
     });
     youtubeApp.post("/transcribe", createApiKeyAuth(), async (c) => {
@@ -10502,9 +10725,16 @@ var init_youtube_routes = __esm({
       const user = c.get("user");
       const holdMins = 5;
       const holdMc = MC_COSTS.yt_transcription * holdMins;
-      const { ok: trOk, balance_mc: trBal } = await debitMc(user.id, holdMc, LedgerOperation.TRANSCRIPTION_HOLD, id);
-      if (!trOk) return c.json(insufficientBalanceResponse(trBal, holdMc), 402);
+      const gate = await acquireConcurrencyGate(user, "youtube_transcribe", {
+        reuseLockId: c.req.header("x-mcp-scraper-concurrency-lock"),
+        metadata: { videoId: id }
+      });
+      if (!gate.ok) return c.json(concurrencyLimitExceededResponse(gate), 429, { "Retry-After": String(gate.retryAfterSeconds) });
+      let debited = false;
       try {
+        const { ok: trOk, balance_mc: trBal } = await debitMc(user.id, holdMc, LedgerOperation.TRANSCRIPTION_HOLD, id);
+        if (!trOk) return c.json(insufficientBalanceResponse(trBal, holdMc), 402);
+        debited = true;
         const result = await fetchCaptions(id);
         const lastChunk = result.chunks?.[result.chunks.length - 1];
         const chunkSecs = lastChunk && Number.isFinite(lastChunk.timestamp[1]) ? lastChunk.timestamp[1] : 0;
@@ -10529,10 +10759,12 @@ var init_youtube_routes = __esm({
           html: buildTranscriptHtml(result)
         });
       } catch (err) {
-        await creditMc(user.id, holdMc, LedgerOperation.TRANSCRIPTION_REFUND, "failed call");
+        if (debited) await creditMc(user.id, holdMc, LedgerOperation.TRANSCRIPTION_REFUND, "failed call");
         const msg = err instanceof Error ? err.message : String(err);
         await logRequestEvent({ userId: user.id, source: "youtube_transcribe", status: "failed", query: id, error: msg });
         return c.json({ error: msg }, 500);
+      } finally {
+        await releaseConcurrencyGate(gate.lockId);
       }
     });
   }
@@ -10549,6 +10781,7 @@ var init_screenshot_routes = __esm({
     init_screenshot();
     init_api_auth();
     init_url_utils();
+    init_concurrency_gates();
     ScreenshotBodySchema = import_zod14.z.object({
       url: import_zod14.z.string().trim().min(1, "url is required"),
       device: import_zod14.z.string().trim().optional(),
@@ -10564,6 +10797,7 @@ var init_screenshot_routes = __esm({
       }
       const body = parsed.data;
       const urlCheck = await validatePublicHttpUrl(body.url, { field: "url", requireHttps: false });
+      let targetUrl = urlCheck.parsed?.href;
       if (urlCheck.error) {
         if (!body.allowLocal) {
           return c.json({ error_code: "invalid_request", message: urlCheck.error }, 400);
@@ -10577,25 +10811,17 @@ var init_screenshot_routes = __esm({
         if (parsedFallback.protocol !== "http:" && parsedFallback.protocol !== "https:") {
           return c.json({ error: "url must use http or https" }, 400);
         }
-        const device2 = body.device === "mobile" ? "mobile" : "desktop";
-        try {
-          const buf = await captureScreenshot(parsedFallback.href, browserServiceApiKey(), device2);
-          return new Response(new Uint8Array(buf), {
-            status: 200,
-            headers: {
-              "Content-Type": "image/png",
-              "Content-Length": String(buf.length),
-              "Cache-Control": "no-store"
-            }
-          });
-        } catch (err) {
-          const msg = err instanceof Error ? err.message : String(err);
-          return c.json({ error: msg }, 502);
-        }
+        targetUrl = parsedFallback.href;
       }
       const device = body.device === "mobile" ? "mobile" : "desktop";
+      const user = c.get("user");
+      const gate = await acquireConcurrencyGate(user, "screenshot", {
+        reuseLockId: c.req.header("x-mcp-scraper-concurrency-lock"),
+        metadata: { url: targetUrl, device }
+      });
+      if (!gate.ok) return c.json(concurrencyLimitExceededResponse(gate), 429, { "Retry-After": String(gate.retryAfterSeconds) });
       try {
-        const buf = await captureScreenshot(urlCheck.parsed.href, browserServiceApiKey(), device);
+        const buf = await captureScreenshot(targetUrl, browserServiceApiKey(), device);
         return new Response(new Uint8Array(buf), {
           status: 200,
           headers: {
@@ -10607,6 +10833,8 @@ var init_screenshot_routes = __esm({
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         return c.json({ error: msg }, 502);
+      } finally {
+        await releaseConcurrencyGate(gate.lockId);
       }
     });
   }
@@ -11978,6 +12206,7 @@ var init_facebook_ad_routes = __esm({
     import_client3 = require("@fal-ai/client");
     init_api_auth();
     init_url_utils();
+    init_concurrency_gates();
     FacebookAdBodySchema = import_zod15.z.object({
       url: import_zod15.z.string().trim().optional(),
       libraryId: import_zod15.z.string().trim().optional(),
@@ -12016,10 +12245,17 @@ var init_facebook_ad_routes = __esm({
       const libraryId = FacebookAdExtractor.resolveLibraryId(raw2);
       if (!libraryId) return c.json({ error: "Could not resolve a valid Facebook Ad Library ID from the provided input" }, 400);
       const fbUser = c.get("user");
-      const { ok: adOk, balance_mc: adBal } = await debitMc(fbUser.id, MC_COSTS.fb_ad, LedgerOperation.FB_AD, raw2);
-      if (!adOk) return c.json(insufficientBalanceResponse(adBal, MC_COSTS.fb_ad), 402);
+      const gate = await acquireConcurrencyGate(fbUser, "facebook_ad", {
+        reuseLockId: c.req.header("x-mcp-scraper-concurrency-lock"),
+        metadata: { libraryId }
+      });
+      if (!gate.ok) return c.json(concurrencyLimitExceededResponse(gate), 429, { "Retry-After": String(gate.retryAfterSeconds) });
       const driver = new BrowserDriver();
+      let debited = false;
       try {
+        const { ok: adOk, balance_mc: adBal } = await debitMc(fbUser.id, MC_COSTS.fb_ad, LedgerOperation.FB_AD, raw2);
+        if (!adOk) return c.json(insufficientBalanceResponse(adBal, MC_COSTS.fb_ad), 402);
+        debited = true;
         await driver.launch(kernelLaunchOpts());
         const extractor = new FacebookAdExtractor(driver);
         const result = await extractor.extract(libraryId, { openModal: body.openModal !== false });
@@ -12033,7 +12269,7 @@ var init_facebook_ad_routes = __esm({
         });
         return c.json(result);
       } catch (err) {
-        await creditMc(fbUser.id, MC_COSTS.fb_ad, LedgerOperation.FB_AD_REFUND, "failed call");
+        if (debited) await creditMc(fbUser.id, MC_COSTS.fb_ad, LedgerOperation.FB_AD_REFUND, "failed call");
         const msg = err instanceof Error ? err.message : String(err);
         await logRequestEvent({ userId: fbUser.id, source: "facebook_ad", status: "failed", query: raw2, error: msg });
         if (msg.toLowerCase().includes("blocked") || msg.toLowerCase().includes("captcha")) {
@@ -12042,24 +12278,26 @@ var init_facebook_ad_routes = __esm({
         return c.json({ error: msg }, 500);
       } finally {
         await driver.close();
+        await releaseConcurrencyGate(gate.lockId);
       }
     });
     facebookAdApp.post("/page-intel", createApiKeyAuth(), async (c) => {
       const raw = await c.req.json().catch(() => ({}));
       const parsed = FacebookPageIntelBodySchema.safeParse(raw);
-      if (!parsed.success) {
-        return c.json(invalidRequest(parsed.error.issues[0]?.message ?? "Invalid request"), 400);
-      }
+      if (!parsed.success) return c.json(invalidRequest(parsed.error.issues[0]?.message ?? "Invalid request"), 400);
       const body = parsed.data;
       const maxAds = Math.min(200, Math.max(1, body.maxAds ?? 50));
       const country = body.country?.trim().toUpperCase() ?? "US";
       const listingUrl = buildPageIntelUrl(body, country);
       const fbUser = c.get("user");
-      const { ok: fbOk, balance_mc: fbBal } = await debitMc(fbUser.id, MC_COSTS.fb_ad, LedgerOperation.FB_AD, body.pageId ?? body.query ?? body.libraryId ?? "");
-      if (!fbOk) return c.json(insufficientBalanceResponse(fbBal, MC_COSTS.fb_ad), 402);
+      const gate = await acquireConcurrencyGate(fbUser, "facebook_page_intel", { reuseLockId: c.req.header("x-mcp-scraper-concurrency-lock"), metadata: { pageId: body.pageId, query: body.query, libraryId: body.libraryId, country } });
+      if (!gate.ok) return c.json(concurrencyLimitExceededResponse(gate), 429, { "Retry-After": String(gate.retryAfterSeconds) });
       const driver = new BrowserDriver();
-      let refunded = false;
+      let refunded = false, debited = false;
       try {
+        const { ok: fbOk, balance_mc: fbBal } = await debitMc(fbUser.id, MC_COSTS.fb_ad, LedgerOperation.FB_AD, body.pageId ?? body.query ?? body.libraryId ?? "");
+        if (!fbOk) return c.json(insufficientBalanceResponse(fbBal, MC_COSTS.fb_ad), 402);
+        debited = true;
         await driver.launch(await kernelLaunchOptsResidential());
         await driver.navigateTo(listingUrl);
         const extractor = new FacebookAdExtractor(driver);
@@ -12074,7 +12312,7 @@ var init_facebook_ad_routes = __esm({
         return c.json(result);
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        if (!refunded) await creditMc(fbUser.id, MC_COSTS.fb_ad, LedgerOperation.FB_AD_REFUND, "failed call");
+        if (debited && !refunded) await creditMc(fbUser.id, MC_COSTS.fb_ad, LedgerOperation.FB_AD_REFUND, "failed call");
         await logRequestEvent({ userId: fbUser.id, source: "facebook_page_intel", status: "failed", query: body.pageId ?? body.query ?? body.libraryId ?? "", error: msg });
         if (msg.toLowerCase().includes("blocked") || msg.toLowerCase().includes("captcha")) {
           return c.json({ error: msg }, 503);
@@ -12082,6 +12320,7 @@ var init_facebook_ad_routes = __esm({
         return c.json({ error: msg }, 500);
       } finally {
         await driver.close();
+        await releaseConcurrencyGate(gate.lockId);
       }
     });
     facebookAdApp.post("/transcribe", createApiKeyAuth(), async (c) => {
@@ -12097,10 +12336,17 @@ var init_facebook_ad_routes = __esm({
       }
       const videoUrl = urlCheck.parsed.href;
       const fbUser = c.get("user");
-      const { ok, balance_mc } = await debitMc(fbUser.id, MC_COSTS.fb_transcribe, LedgerOperation.FB_TRANSCRIBE, videoUrl);
-      if (!ok) return c.json(insufficientBalanceResponse(balance_mc, MC_COSTS.fb_transcribe), 402);
+      const gate = await acquireConcurrencyGate(fbUser, "facebook_transcribe", {
+        reuseLockId: c.req.header("x-mcp-scraper-concurrency-lock"),
+        metadata: { videoUrl }
+      });
+      if (!gate.ok) return c.json(concurrencyLimitExceededResponse(gate), 429, { "Retry-After": String(gate.retryAfterSeconds) });
       import_client3.fal.config({ credentials: process.env.FAL_KEY });
+      let debited = false;
       try {
+        const { ok, balance_mc } = await debitMc(fbUser.id, MC_COSTS.fb_transcribe, LedgerOperation.FB_TRANSCRIBE, videoUrl);
+        if (!ok) return c.json(insufficientBalanceResponse(balance_mc, MC_COSTS.fb_transcribe), 402);
+        debited = true;
         const startMs = Date.now();
         const result = await import_client3.fal.subscribe("fal-ai/wizper", {
           input: { audio_url: videoUrl, task: "transcribe", language: "en" },
@@ -12123,9 +12369,11 @@ var init_facebook_ad_routes = __esm({
         return c.json({ text, chunks, durationMs, markdown: lines.join("\n") });
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        await creditMc(fbUser.id, MC_COSTS.fb_transcribe, LedgerOperation.FB_TRANSCRIBE_REFUND, "failed call");
+        if (debited) await creditMc(fbUser.id, MC_COSTS.fb_transcribe, LedgerOperation.FB_TRANSCRIBE_REFUND, "failed call");
         await logRequestEvent({ userId: fbUser.id, source: "facebook_transcribe", status: "failed", query: videoUrl, error: msg });
         return c.json({ error: msg }, 500);
+      } finally {
+        await releaseConcurrencyGate(gate.lockId);
       }
     });
     facebookAdApp.post("/search", createApiKeyAuth(), async (c) => {
@@ -12139,11 +12387,18 @@ var init_facebook_ad_routes = __esm({
       const maxResults = Math.min(20, Math.max(1, body.maxResults ?? 10));
       const searchUrl = `https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=${country}&q=${encodeURIComponent(body.query.trim())}&search_type=keyword_unordered`;
       const fbUser = c.get("user");
-      const { ok, balance_mc } = await debitMc(fbUser.id, MC_COSTS.fb_search, LedgerOperation.FB_SEARCH, body.query.trim());
-      if (!ok) return c.json(insufficientBalanceResponse(balance_mc, MC_COSTS.fb_search), 402);
+      const gate = await acquireConcurrencyGate(fbUser, "facebook_search", {
+        reuseLockId: c.req.header("x-mcp-scraper-concurrency-lock"),
+        metadata: { query: body.query.trim(), country }
+      });
+      if (!gate.ok) return c.json(concurrencyLimitExceededResponse(gate), 429, { "Retry-After": String(gate.retryAfterSeconds) });
       const driver = new BrowserDriver();
       let searchRefunded = false;
+      let debited = false;
       try {
+        const { ok, balance_mc } = await debitMc(fbUser.id, MC_COSTS.fb_search, LedgerOperation.FB_SEARCH, body.query.trim());
+        if (!ok) return c.json(insufficientBalanceResponse(balance_mc, MC_COSTS.fb_search), 402);
+        debited = true;
         await driver.launch(await kernelLaunchOptsResidential());
         const page = driver.getPage();
         const collated = await collectAdLibraryResults(page, searchUrl, Math.max(maxResults * 4, 40));
@@ -12204,7 +12459,7 @@ var init_facebook_ad_routes = __esm({
         return c.json(searchResult);
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        if (!searchRefunded) await creditMc(fbUser.id, MC_COSTS.fb_search, LedgerOperation.FB_SEARCH_REFUND, "failed call");
+        if (debited && !searchRefunded) await creditMc(fbUser.id, MC_COSTS.fb_search, LedgerOperation.FB_SEARCH_REFUND, "failed call");
         await logRequestEvent({ userId: fbUser.id, source: "facebook_search", status: "failed", query: body.query.trim(), error: msg });
         if (msg.toLowerCase().includes("blocked") || msg.toLowerCase().includes("captcha")) {
           return c.json({ error: msg }, 503);
@@ -12212,6 +12467,7 @@ var init_facebook_ad_routes = __esm({
         return c.json({ error: msg }, 500);
       } finally {
         await driver.close();
+        await releaseConcurrencyGate(gate.lockId);
       }
     });
     ALLOWED_MEDIA_HOSTS = ["fbcdn.net", "cdninstagram.com", "scontent.facebook.com", "scontent.cdninstagram.com"];
@@ -13215,6 +13471,7 @@ var init_maps_routes = __esm({
     init_errors();
     init_browser_service_env();
     init_maps_search_rotation();
+    init_concurrency_gates();
     mapsApp = new import_hono5.Hono();
     mapsApp.post("/search", createApiKeyAuth(), async (c) => {
       const user = c.get("user");
@@ -13226,14 +13483,21 @@ var init_maps_routes = __esm({
       if (!parsed.success) {
         return c.json({ error: parsed.error.issues[0]?.message ?? "Invalid request" }, 400);
       }
-      const { ok, balance_mc } = await debitMc(
-        user.id,
-        MC_COSTS.maps_search,
-        LedgerOperation.MAPS_SEARCH,
-        [parsed.data.query, parsed.data.location].filter(Boolean).join(" ")
-      );
-      if (!ok) return c.json(insufficientBalanceResponse(balance_mc, MC_COSTS.maps_search), 402);
+      const gate = await acquireConcurrencyGate(user, "maps_search", {
+        reuseLockId: c.req.header("x-mcp-scraper-concurrency-lock"),
+        metadata: { query: parsed.data.query, location: parsed.data.location }
+      });
+      if (!gate.ok) return c.json(concurrencyLimitExceededResponse(gate), 429, { "Retry-After": String(gate.retryAfterSeconds) });
+      let debited = false;
       try {
+        const { ok, balance_mc } = await debitMc(
+          user.id,
+          MC_COSTS.maps_search,
+          LedgerOperation.MAPS_SEARCH,
+          [parsed.data.query, parsed.data.location].filter(Boolean).join(" ")
+        );
+        if (!ok) return c.json(insufficientBalanceResponse(balance_mc, MC_COSTS.maps_search), 402);
+        debited = true;
         const result = await runMapsSearchWithRotation({
           ...parsed.data,
           configuredKernelProxyId: browserServiceProxyId()
@@ -13249,7 +13513,7 @@ var init_maps_routes = __esm({
         });
         return c.json(result);
       } catch (err) {
-        await creditMc(user.id, MC_COSTS.maps_search, LedgerOperation.REFUND, "failed maps_search call");
+        if (debited) await creditMc(user.id, MC_COSTS.maps_search, LedgerOperation.REFUND, "failed maps_search call");
         const msg = err instanceof Error ? err.message : String(err);
         await logRequestEvent({
           userId: user.id,
@@ -13261,6 +13525,8 @@ var init_maps_routes = __esm({
           result: err instanceof MapsSearchRotationError ? { attempts: err.attempts } : void 0
         });
         return mapsErrorResponse(c, err, "maps_search_failed");
+      } finally {
+        await releaseConcurrencyGate(gate.lockId);
       }
     });
     mapsApp.post("/place", createApiKeyAuth(), async (c) => {
@@ -13273,17 +13539,24 @@ var init_maps_routes = __esm({
       if (!parsed.success) {
         return c.json({ error: parsed.error.issues[0]?.message ?? "Invalid request" }, 400);
       }
-      const { ok, balance_mc } = await debitMc(
-        user.id,
-        MC_COSTS.maps_place,
-        LedgerOperation.MAPS_PLACE,
-        `${parsed.data.businessName} ${parsed.data.location}`
-      );
-      if (!ok) return c.json(insufficientBalanceResponse(balance_mc, MC_COSTS.maps_place), 402);
+      const gate = await acquireConcurrencyGate(user, "maps_place", {
+        reuseLockId: c.req.header("x-mcp-scraper-concurrency-lock"),
+        metadata: { businessName: parsed.data.businessName, location: parsed.data.location }
+      });
+      if (!gate.ok) return c.json(concurrencyLimitExceededResponse(gate), 429, { "Retry-After": String(gate.retryAfterSeconds) });
       const driver = new BrowserDriver();
       const extractor = new MapsExtractor(driver);
       let reviewDebitMc = 0;
+      let debited = false;
       try {
+        const { ok, balance_mc } = await debitMc(
+          user.id,
+          MC_COSTS.maps_place,
+          LedgerOperation.MAPS_PLACE,
+          `${parsed.data.businessName} ${parsed.data.location}`
+        );
+        if (!ok) return c.json(insufficientBalanceResponse(balance_mc, MC_COSTS.maps_place), 402);
+        debited = true;
         const result = await extractor.extract(parsed.data);
         const reviewCount = Array.isArray(result.reviews) ? result.reviews.length : 0;
         if (reviewCount > 0) {
@@ -13311,7 +13584,7 @@ var init_maps_routes = __esm({
         });
         return c.json(result);
       } catch (err) {
-        await creditMc(user.id, MC_COSTS.maps_place, LedgerOperation.REFUND, "failed maps_place call");
+        if (debited) await creditMc(user.id, MC_COSTS.maps_place, LedgerOperation.REFUND, "failed maps_place call");
         if (reviewDebitMc > 0) {
           await creditMc(
             user.id,
@@ -13332,6 +13605,7 @@ var init_maps_routes = __esm({
         return mapsErrorResponse(c, msg, "maps_place_failed");
       } finally {
         await driver.close();
+        await releaseConcurrencyGate(gate.lockId);
       }
     });
   }
@@ -13969,6 +14243,8 @@ function formatCreditsInfo(raw, input) {
   const costs = d.costs ?? [];
   const matched = d.matched_cost;
   const ledger = d.ledger ?? [];
+  const concurrencyRaw = d.concurrency;
+  const upgradeRaw = concurrencyRaw?.upgrade;
   const costRows = costs.map((c) => {
     const notes = c.notes ? ` ${c.notes}` : "";
     return `| ${c.label} | ${c.credits} | ${c.unit}${notes} |`;
@@ -13984,10 +14260,20 @@ function formatCreditsInfo(raw, input) {
 ${matched.notes}` : ""}` : input.item ? `
 ## Matched Cost
 No exact cost match found for "${input.item}". See the full cost table below.` : "";
+  const concurrencySection = concurrencyRaw ? [
+    `
+## Concurrency`,
+    `**Current limit:** ${concurrencyRaw.current_limit ?? "unknown"} concurrent operation${concurrencyRaw.current_limit === 1 ? "" : "s"}`,
+    `**Extra slots:** ${concurrencyRaw.current_extra_slots ?? "unknown"}`,
+    `**Extra concurrency slot:** ${upgradeRaw?.price_label ?? "$5/month"}`,
+    `**Upgrade in terminal:** \`${upgradeRaw?.terminal_command ?? "npx -y -p mcp-scraper@latest mcp-scraper-cli billing concurrency checkout"}\``,
+    `**Billing URL:** ${upgradeRaw?.billing_url ?? "https://mcpscraper.dev/billing"}`
+  ].join("\n") : "";
   const full = [
     `# Credits`,
     `**Balance:** ${balance ?? "unknown"} credits`,
     matchedSection,
+    concurrencySection,
     costs.length ? `
 ## Cost Table
 | Item | Credits | Unit |
@@ -14016,7 +14302,22 @@ ${ledgerRows}` : ""
         operation: String(row.operation ?? ""),
         credits: row.amount_mc / 1e3,
         description: row.description ?? null
-      }))
+      })),
+      concurrency: concurrencyRaw && upgradeRaw ? {
+        currentExtraSlots: Number(concurrencyRaw.current_extra_slots ?? 0),
+        currentLimit: Number(concurrencyRaw.current_limit ?? 1),
+        hasSubscription: concurrencyRaw.has_subscription === true,
+        upgrade: {
+          product: String(upgradeRaw.product ?? "Extra concurrency slot"),
+          priceLabel: String(upgradeRaw.price_label ?? "$5/month"),
+          unitAmountUsd: Number(upgradeRaw.unit_amount_usd ?? 5),
+          currency: String(upgradeRaw.currency ?? "usd"),
+          interval: String(upgradeRaw.interval ?? "month"),
+          billingUrl: String(upgradeRaw.billing_url ?? "https://mcpscraper.dev/billing"),
+          terminalCommand: String(upgradeRaw.terminal_command ?? "npx -y -p mcp-scraper@latest mcp-scraper-cli billing concurrency checkout"),
+          terminalCommandWithApiKeyEnv: String(upgradeRaw.terminal_command_with_api_key_env ?? "MCP_SCRAPER_API_KEY=sk_live_your_key npx -y -p mcp-scraper@latest mcp-scraper-cli billing concurrency checkout")
+        }
+      } : null
     }
   };
 }
@@ -14095,7 +14396,7 @@ function formatDirectoryWorkflow(raw, input) {
   const csvPath = d.csvPath ?? null;
   const totalResultCount = d.totalResultCount ?? cities.reduce((sum, city) => sum + city.resultCount, 0);
   const durationMs = d.durationMs;
-  const marketRows = cities.map((city) => {
+  const marketRows2 = cities.map((city) => {
     const zips = city.zips?.length ? city.zips.slice(0, 8).join(" ") + (city.zips.length > 8 ? ` +${city.zips.length - 8}` : "") : "\u2014";
     return `| ${cell(city.city)} | ${city.population.toLocaleString()} | ${city.zips?.length ?? 0} | ${city.resultCount} | ${city.status} | ${cell(zips)} |`;
   }).join("\n");
@@ -14116,7 +14417,7 @@ ${warnings.map((w) => `- ${w}`).join("\n")}` : "";
 ## Markets
 | City | Population | ZIPs | Maps Results | Status | ZIP Sample |
 |---|---:|---:|---:|---|---|
-${marketRows}`,
+${marketRows2}`,
     businessRows ? `
 ## Top Candidates By City
 | City | # | Name | Category | Rating | Website | Maps |
@@ -14811,6 +15112,7 @@ var init_directory_routes = __esm({
     init_directory_workflow();
     init_location_db();
     init_browser_service_env();
+    init_concurrency_gates();
     directoryApp = new import_hono6.Hono();
     directoryApp.post("/run", createApiKeyAuth(), async (c) => {
       const user = c.get("user");
@@ -14826,18 +15128,27 @@ var init_directory_routes = __esm({
       if (!kernelApiKey && parsed.data.proxyMode !== "none") {
         return c.json({ error: "Browser service API key is required for directory workflow Maps searches unless proxyMode is none" }, 503);
       }
-      const plan = await resolveDirectoryMarkets(parsed.data);
-      const requiredMc = plan.markets.length * MC_COSTS.maps_search;
-      if (requiredMc > 0) {
-        const debit = await debitMc(
-          user.id,
-          requiredMc,
-          LedgerOperation.MAPS_SEARCH,
-          `directory_workflow ${parsed.data.query} ${parsed.data.state} ${plan.markets.length} cities`
-        );
-        if (!debit.ok) return c.json(insufficientBalanceResponse(debit.balance_mc, requiredMc), 402);
-      }
+      const gate = await acquireConcurrencyGate(user, "directory_workflow", {
+        reuseLockId: c.req.header("x-mcp-scraper-concurrency-lock"),
+        ttlSeconds: 30 * 60,
+        metadata: { query: parsed.data.query, state: parsed.data.state }
+      });
+      if (!gate.ok) return c.json(concurrencyLimitExceededResponse(gate), 429, { "Retry-After": String(gate.retryAfterSeconds) });
+      let debited = false;
+      let requiredMc = 0;
       try {
+        const plan = await resolveDirectoryMarkets(parsed.data);
+        requiredMc = plan.markets.length * MC_COSTS.maps_search;
+        if (requiredMc > 0) {
+          const debit = await debitMc(
+            user.id,
+            requiredMc,
+            LedgerOperation.MAPS_SEARCH,
+            `directory_workflow ${parsed.data.query} ${parsed.data.state} ${plan.markets.length} cities`
+          );
+          if (!debit.ok) return c.json(insufficientBalanceResponse(debit.balance_mc, requiredMc), 402);
+          debited = true;
+        }
         const result = await runDirectoryWorkflowFromPlan(parsed.data, plan);
         const failedCities = result.cities.filter((city) => city.status === "failed").length;
         if (failedCities > 0) {
@@ -14854,7 +15165,7 @@ var init_directory_routes = __esm({
         });
         return c.json(result);
       } catch (err) {
-        if (requiredMc > 0) {
+        if (debited && requiredMc > 0) {
           await creditMc(user.id, requiredMc, LedgerOperation.REFUND, "failed directory_workflow call");
         }
         const message = err instanceof Error ? err.message : String(err);
@@ -14867,6 +15178,8 @@ var init_directory_routes = __esm({
           error: message
         });
         return c.json({ error: message, error_code: "directory_workflow_failed", retryable: true }, 500);
+      } finally {
+        await releaseConcurrencyGate(gate.lockId);
       }
     });
   }
@@ -15015,18 +15328,21 @@ var init_http_client2 = __esm({
   "src/workflows/http-client.ts"() {
     "use strict";
     WorkflowHttpClient = class {
-      constructor(apiUrl, apiKey, fetchImpl = fetch) {
+      constructor(apiUrl, apiKey, fetchImpl = fetch, extraHeaders = {}) {
         this.apiUrl = apiUrl;
         this.apiKey = apiKey;
         this.fetchImpl = fetchImpl;
+        this.extraHeaders = extraHeaders;
       }
       apiUrl;
       apiKey;
       fetchImpl;
+      extraHeaders;
       async post(path6, body, timeoutMs = 18e4) {
         const res = await this.fetchImpl(`${this.apiUrl.replace(/\/$/, "")}${path6}`, {
           method: "POST",
           headers: {
+            ...this.extraHeaders,
             "Content-Type": "application/json",
             "x-api-key": this.apiKey
           },
@@ -15646,6 +15962,718 @@ ${summary}
   }
 });
 
+// src/workflows/workflows/seo-workflow-utils.ts
+function normalizeDomain2(value) {
+  if (!value) return null;
+  try {
+    const url = new URL(value.includes("://") ? value : `https://${value}`);
+    return url.hostname.replace(/^www\./, "").toLowerCase();
+  } catch {
+    return value.replace(/^https?:\/\//, "").replace(/^www\./, "").split("/")[0]?.toLowerCase() || null;
+  }
+}
+function domainFromUrl2(url) {
+  return normalizeDomain2(url) ?? "";
+}
+function numberFrom2(value) {
+  if (value === null || value === void 0 || value === "") return null;
+  const parsed = Number(String(value).replace(/[^\d.]/g, ""));
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function median2(values) {
+  const nums = values.filter((v) => v !== null).sort((a, b) => a - b);
+  if (!nums.length) return null;
+  return nums[Math.floor(nums.length / 2)] ?? null;
+}
+function textTerms(text, limit = 12) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const token of text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/)) {
+    if (token.length < 4 || STOP_WORDS.has(token)) continue;
+    counts.set(token, (counts.get(token) ?? 0) + 1);
+  }
+  return [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, limit).map(([term, count]) => `${term} (${count})`).join("; ");
+}
+function classifyQuestion(question) {
+  const q = question.toLowerCase();
+  if (/\b(cost|price|pricing|charge|expensive|cheap)\b/.test(q)) return "cost";
+  if (/\b(best|top|recommended|reviews?|compare|versus|vs)\b/.test(q)) return "comparison";
+  if (/\b(how|steps?|process|way to)\b/.test(q)) return "process";
+  if (/\b(why|worth|important|benefit)\b/.test(q)) return "why";
+  if (/\b(near me|city|local|nearby)\b/.test(q)) return "local";
+  if (/\b(can|does|do|is|are|should|will)\b/.test(q)) return "decision";
+  return "definition";
+}
+function questionRows(paa) {
+  return (paa?.flat ?? []).filter((row) => row.question).map((row, index) => {
+    const url = row.source_cite ?? "";
+    const domain = normalizeDomain2(row.source_site ?? "") ?? domainFromUrl2(url);
+    return {
+      position: index + 1,
+      intent: classifyQuestion(row.question ?? ""),
+      question: row.question ?? "",
+      answer_excerpt: (row.answer ?? "").slice(0, 320),
+      source_title: row.source_title ?? "",
+      source_domain: domain,
+      source_url: url
+    };
+  });
+}
+function sourceDomainRows(rows) {
+  const byDomain = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const domain = String(row.source_domain ?? row.domain ?? "");
+    if (!domain) continue;
+    const entry = byDomain.get(domain) ?? { questions: 0, urls: /* @__PURE__ */ new Set(), intents: /* @__PURE__ */ new Map() };
+    entry.questions += row.question ? 1 : 0;
+    if (row.source_url || row.url) entry.urls.add(String(row.source_url ?? row.url));
+    if (row.intent) entry.intents.set(String(row.intent), (entry.intents.get(String(row.intent)) ?? 0) + 1);
+    byDomain.set(domain, entry);
+  }
+  return [...byDomain.entries()].map(([domain, entry]) => ({
+    domain,
+    question_mentions: entry.questions,
+    source_url_count: entry.urls.size,
+    top_intents: [...entry.intents.entries()].sort((a, b) => b[1] - a[1]).map(([intent, count]) => `${intent} (${count})`).join("; ")
+  })).sort((a, b) => Number(b.question_mentions) - Number(a.question_mentions) || String(a.domain).localeCompare(String(b.domain)));
+}
+function splitSentences(text) {
+  return (text ?? "").replace(/\s+/g, " ").split(/(?<=[.!?])\s+/).map((sentence) => sentence.trim()).filter((sentence) => sentence.length > 20).slice(0, 20);
+}
+function classifySentence(sentence) {
+  const s = sentence.toLowerCase();
+  if (/\bis\b|\bare\b|\bmeans\b|\brefers to\b/.test(s)) return "definition";
+  if (/\binclude\b|\bconsider\b|\bfactors?\b|\bcriteria\b/.test(s)) return "criteria";
+  if (/\bfirst\b|\bthen\b|\bsteps?\b|\bprocess\b/.test(s)) return "process";
+  if (/\bvs\b|\bthan\b|\bcompare\b|\bdifference\b/.test(s)) return "comparison";
+  if (/\bcost\b|\bprice\b|\baverage\b|\brange\b/.test(s)) return "cost";
+  return "claim";
+}
+function pageSummaryRow(page, source) {
+  return {
+    position: source.position ?? "",
+    domain: source.domain,
+    url: source.url,
+    serp_title: source.title ?? "",
+    page_title: page.title ?? "",
+    h1: page.h1 ?? "",
+    meta_description: page.metaDescription ?? "",
+    word_count: page.wordCount ?? "",
+    heading_count: page.headings?.length ?? 0,
+    schema_types: (page.schemaTypes ?? []).join("; ")
+  };
+}
+async function mapLimit3(items, limit, fn) {
+  const out = new Array(items.length);
+  let next = 0;
+  async function worker() {
+    while (next < items.length) {
+      const index = next;
+      next += 1;
+      out[index] = await fn(items[index], index);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(Math.max(1, limit), items.length) }, () => worker()));
+  return out;
+}
+var STOP_WORDS;
+var init_seo_workflow_utils = __esm({
+  "src/workflows/workflows/seo-workflow-utils.ts"() {
+    "use strict";
+    STOP_WORDS = /* @__PURE__ */ new Set([
+      "about",
+      "after",
+      "also",
+      "because",
+      "been",
+      "best",
+      "both",
+      "from",
+      "have",
+      "into",
+      "more",
+      "most",
+      "near",
+      "only",
+      "over",
+      "than",
+      "that",
+      "their",
+      "them",
+      "then",
+      "there",
+      "these",
+      "they",
+      "this",
+      "what",
+      "when",
+      "where",
+      "which",
+      "while",
+      "with",
+      "your",
+      "will",
+      "would",
+      "should",
+      "could",
+      "does",
+      "were",
+      "cost",
+      "costs"
+    ]);
+  }
+});
+
+// src/workflows/workflows/comparison-briefs.ts
+function businessRowsFromMaps(location2, query, results) {
+  return results.map((result) => ({
+    source_query: query,
+    source_location: location2,
+    city: location2.split(",")[0]?.trim() ?? location2,
+    state: location2.split(",")[1]?.trim() ?? "",
+    population: "",
+    result_position: result.position,
+    business_name: result.name,
+    review_stars: result.rating ?? "",
+    review_count: result.reviewCount ?? "",
+    category: result.category ?? "",
+    address: result.address ?? "",
+    phone: result.phone ?? "",
+    website_url: result.websiteUrl ?? "",
+    place_url: result.placeUrl ?? "",
+    cid: result.cid ?? "",
+    cid_decimal: result.cidDecimal ?? "",
+    result_status: "ok",
+    error: ""
+  }));
+}
+function marketRows(rows) {
+  const byLocation = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const key = String(row.source_location ?? row.location ?? "");
+    if (!key) continue;
+    const list = byLocation.get(key) ?? [];
+    list.push(row);
+    byLocation.set(key, list);
+  }
+  return [...byLocation.entries()].map(([location2, list]) => {
+    const counts = list.map((row) => numberFrom2(row.review_count));
+    const ratings = list.map((row) => numberFrom2(row.review_stars));
+    const topThree = list.slice(0, 3).map((row) => numberFrom2(row.review_count)).filter((v) => v !== null);
+    const categories = /* @__PURE__ */ new Map();
+    for (const row of list) {
+      const category = String(row.category ?? "");
+      if (category) categories.set(category, (categories.get(category) ?? 0) + 1);
+    }
+    return {
+      source_location: location2,
+      result_count: list.filter((row) => row.business_name).length,
+      median_review_count: median2(counts) ?? "",
+      median_rating: median2(ratings) ?? "",
+      top_three_average_review_count: topThree.length ? Math.round(topThree.reduce((a, b) => a + b, 0) / topThree.length) : "",
+      top_categories: [...categories.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([cat, count]) => `${cat} (${count})`).join("; "),
+      websites_present: list.filter((row) => row.website_url).length
+    };
+  });
+}
+function comparisonRows(rows) {
+  const benchmarkByLocation = /* @__PURE__ */ new Map();
+  for (const market of marketRows(rows)) {
+    benchmarkByLocation.set(String(market.source_location), numberFrom2(market.top_three_average_review_count) ?? 0);
+  }
+  return rows.filter((row) => row.business_name).map((row) => {
+    const reviews = numberFrom2(row.review_count) ?? 0;
+    const benchmark = benchmarkByLocation.get(String(row.source_location)) ?? 0;
+    const websiteMissing = !row.website_url;
+    const rank = numberFrom2(row.result_position) ?? 999;
+    return {
+      source_location: row.source_location,
+      result_position: row.result_position,
+      business_name: row.business_name,
+      category: row.category,
+      review_stars: row.review_stars,
+      review_count: row.review_count,
+      review_gap_to_top3_average: benchmark ? Math.max(0, benchmark - reviews) : "",
+      website_url: row.website_url,
+      place_url: row.place_url,
+      comparison_note: rank <= 3 ? "visible leader" : websiteMissing ? "ranking without website" : reviews < benchmark ? "review-light competitor" : "visible competitor"
+    };
+  });
+}
+function organicRows(serp, targetDomain) {
+  return (serp?.organicResults ?? []).map((result) => {
+    const url = result.url ?? "";
+    const domain = normalizeDomain2(result.domain ?? "") ?? domainFromUrl2(url);
+    return {
+      position: result.position ?? "",
+      title: result.title ?? "",
+      url,
+      domain,
+      snippet: result.snippet ?? "",
+      is_target: targetDomain ? domain === targetDomain : false
+    };
+  });
+}
+function pageGapRows(targetPage, competitorPages) {
+  const targetHeadingText = new Set((targetPage?.headings ?? []).map((h) => h.text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").trim()));
+  const targetTerms = new Set((targetPage?.headings ?? []).flatMap((h) => h.text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/).filter(Boolean)));
+  const rows = [];
+  for (const { source, page } of competitorPages) {
+    for (const heading of page.headings ?? []) {
+      if (heading.level > 3 || !heading.text) continue;
+      const normalized = heading.text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").trim();
+      const terms = normalized.split(/\s+/).filter((term) => term.length > 3);
+      const overlap = terms.filter((term) => targetTerms.has(term)).length;
+      const covered = targetHeadingText.has(normalized) || overlap >= Math.max(2, Math.ceil(terms.length / 2));
+      if (covered && targetPage) continue;
+      rows.push({
+        source_position: source.position ?? "",
+        source_domain: normalizeDomain2(source.domain ?? "") ?? domainFromUrl2(source.url),
+        source_url: source.url ?? "",
+        heading_level: heading.level,
+        competitor_heading: heading.text,
+        target_coverage: targetPage ? "not found in target headings" : "no target page extracted",
+        terms: textTerms(heading.text, 6)
+      });
+    }
+  }
+  return rows.slice(0, 150);
+}
+async function extractPages(ctx, sources, warnings, labelPrefix) {
+  return mapLimit3(sources.filter((source) => source.url), 2, async (source, index) => {
+    try {
+      const page = await ctx.client.post("/extract-url", { url: source.url }, 18e4);
+      await ctx.artifacts.writeJson(`${labelPrefix} ${index + 1}`, `raw/extract-url/${labelPrefix.toLowerCase()}-${index + 1}.json`, page);
+      return { source, page };
+    } catch (err) {
+      warnings.push(`Page extraction failed for ${source.url}: ${err instanceof Error ? err.message : String(err)}`);
+      return null;
+    }
+  }).then((items) => items.filter((item) => item !== null));
+}
+var import_zod22, ProxyModeSchema, MapComparisonInputSchema, SerpComparisonInputSchema, PaaExpansionBriefInputSchema, AiOverviewLanguageInputSchema, mapComparisonWorkflowDefinition, serpComparisonWorkflowDefinition, paaExpansionBriefWorkflowDefinition, aiOverviewLanguageWorkflowDefinition;
+var init_comparison_briefs = __esm({
+  "src/workflows/workflows/comparison-briefs.ts"() {
+    "use strict";
+    import_zod22 = require("zod");
+    init_report_renderer();
+    init_directory();
+    init_seo_workflow_utils();
+    ProxyModeSchema = import_zod22.z.enum(["location", "configured", "none"]);
+    MapComparisonInputSchema = import_zod22.z.object({
+      query: import_zod22.z.string().min(1),
+      location: import_zod22.z.string().optional(),
+      state: import_zod22.z.string().optional(),
+      minPopulation: import_zod22.z.number().int().min(0).default(1e5),
+      maxCities: import_zod22.z.number().int().min(1).max(100).default(5),
+      maxResultsPerCity: import_zod22.z.number().int().min(1).max(50).default(20),
+      hydrateTop: import_zod22.z.number().int().min(0).max(10).default(5),
+      maxReviews: import_zod22.z.number().int().min(0).max(500).default(25),
+      concurrency: import_zod22.z.number().int().min(1).max(5).default(5),
+      proxyMode: ProxyModeSchema.default("location"),
+      returnPartial: import_zod22.z.boolean().default(true)
+    }).refine((input) => input.location || input.state, {
+      message: "Either location or state is required for map-comparison"
+    });
+    SerpComparisonInputSchema = import_zod22.z.object({
+      keyword: import_zod22.z.string().min(1),
+      domain: import_zod22.z.string().optional(),
+      url: import_zod22.z.string().url().optional(),
+      location: import_zod22.z.string().optional(),
+      maxResults: import_zod22.z.number().int().min(1).max(20).default(10),
+      maxQuestions: import_zod22.z.number().int().min(1).max(200).default(40),
+      extractTop: import_zod22.z.number().int().min(0).max(10).default(5),
+      includePaa: import_zod22.z.boolean().default(true),
+      includeAiOverview: import_zod22.z.boolean().default(true),
+      returnPartial: import_zod22.z.boolean().default(true)
+    });
+    PaaExpansionBriefInputSchema = import_zod22.z.object({
+      keyword: import_zod22.z.string().min(1),
+      location: import_zod22.z.string().optional(),
+      maxQuestions: import_zod22.z.number().int().min(1).max(300).default(80),
+      depth: import_zod22.z.number().int().min(1).max(6).default(3),
+      returnPartial: import_zod22.z.boolean().default(true)
+    });
+    AiOverviewLanguageInputSchema = import_zod22.z.object({
+      keyword: import_zod22.z.string().min(1),
+      domain: import_zod22.z.string().optional(),
+      url: import_zod22.z.string().url().optional(),
+      location: import_zod22.z.string().optional(),
+      maxQuestions: import_zod22.z.number().int().min(1).max(200).default(40),
+      extractTop: import_zod22.z.number().int().min(0).max(8).default(3),
+      returnPartial: import_zod22.z.boolean().default(true)
+    });
+    mapComparisonWorkflowDefinition = {
+      id: "map-comparison",
+      title: "Maps Comparison",
+      description: "Compare Google Maps competitors by rank, reviews, stars, categories, websites, and profile/review signals.",
+      inputSchema: MapComparisonInputSchema,
+      async run(input, ctx) {
+        await ctx.artifacts.writeManifest("running", {}, [], []);
+        const warnings = [];
+        let rows;
+        let directory = null;
+        let mapsSearch = null;
+        if (input.location) {
+          mapsSearch = await ctx.client.post("/maps/search", {
+            query: input.query,
+            location: input.location,
+            maxResults: input.maxResultsPerCity,
+            proxyMode: input.proxyMode
+          }, 24e4);
+          rows = businessRowsFromMaps(input.location, input.query, mapsSearch.results);
+          await ctx.artifacts.writeJson("Maps search raw JSON", "raw/maps-search.json", mapsSearch);
+        } else {
+          directory = await ctx.client.post("/directory/run", {
+            query: input.query,
+            state: input.state,
+            minPopulation: input.minPopulation,
+            maxCities: input.maxCities,
+            maxResultsPerCity: input.maxResultsPerCity,
+            concurrency: input.concurrency,
+            proxyMode: input.proxyMode,
+            saveCsv: true
+          }, 9e5);
+          rows = directoryRows(directory);
+          await ctx.artifacts.writeJson("Directory raw JSON", "raw/directory-workflow.json", directory);
+          await ctx.artifacts.writeCsv("Directory CSV", "exports/directory.csv", DIRECTORY_CSV_HEADERS, rows);
+          warnings.push(...directory.warnings);
+        }
+        const compareRows = comparisonRows(rows);
+        const selected = compareRows.slice(0, input.hydrateTop * Math.max(1, input.location ? 1 : input.maxCities));
+        const hydrated = await mapLimit3(selected, 3, async (row, index) => {
+          try {
+            const detail = await ctx.client.post("/maps/place", {
+              businessName: row.business_name,
+              location: row.source_location,
+              includeReviews: input.maxReviews > 0,
+              maxReviews: Math.max(1, input.maxReviews)
+            }, 18e4);
+            await ctx.artifacts.writeJson(`${row.business_name} profile`, `raw/maps-place-intel/${index + 1}-${String(row.business_name).toLowerCase().replace(/[^a-z0-9]+/g, "-")}.json`, detail);
+            return { row, detail, error: "" };
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            warnings.push(`Profile hydration failed for ${row.business_name}: ${message}`);
+            return { row, detail: null, error: message };
+          }
+        });
+        const profileRows = hydrated.map(({ row, detail, error }) => ({
+          source_location: row.source_location,
+          result_position: row.result_position,
+          business_name: row.business_name,
+          category: detail?.category ?? row.category,
+          review_stars: detail?.rating ?? row.review_stars,
+          review_count: detail?.reviewCount ?? row.review_count,
+          website_url: detail?.website ?? row.website_url,
+          review_topics: (detail?.reviewTopics ?? []).map((t) => `${t.label} (${t.count})`).join("; "),
+          about_attributes: (detail?.aboutAttributes ?? []).map((a) => `${a.section}: ${a.attribute}`).join("; "),
+          reviews_status: detail?.reviewsStatus ?? "",
+          error
+        }));
+        const markets = marketRows(rows);
+        await ctx.artifacts.writeCsv("Maps results CSV", "maps-results.csv", ["source_query", "source_location", "city", "state", "population", "result_position", "business_name", "review_stars", "review_count", "category", "address", "phone", "website_url", "place_url", "cid", "cid_decimal", "result_status", "error"], rows);
+        await ctx.artifacts.writeCsv("Comparison CSV", "map-comparison.csv", ["source_location", "result_position", "business_name", "category", "review_stars", "review_count", "review_gap_to_top3_average", "website_url", "place_url", "comparison_note"], compareRows);
+        await ctx.artifacts.writeCsv("Profile insights CSV", "profile-insights.csv", ["source_location", "result_position", "business_name", "category", "review_stars", "review_count", "website_url", "review_topics", "about_attributes", "reviews_status", "error"], profileRows);
+        await ctx.artifacts.writeJson("Maps comparison evidence", "evidence.json", { input, directory, mapsSearch, rows, compareRows, profileRows, markets, warnings });
+        await ctx.artifacts.writeText("Brief", "brief.md", [
+          `# Maps Comparison: ${input.query}`,
+          "",
+          `Markets: ${markets.map((row) => row.source_location).join(", ")}`,
+          "",
+          "## How to Use",
+          "- Compare rank position against review count and category patterns.",
+          "- Treat review gaps and missing websites as opportunity signals, not guarantees.",
+          "- Use profile topics and attributes as evidence for local content and GBP improvements."
+        ].join("\n"));
+        const summary = `${compareRows.length} Maps competitors compared across ${markets.length} market(s); ${profileRows.filter((row) => !row.error).length} profiles hydrated.`;
+        const reportPath = await ctx.artifacts.writeHtml("HTML report", "report.html", renderWorkflowReport({
+          title: "Maps Comparison",
+          subtitle: `${input.query}${input.location ? ` \xB7 ${input.location}` : input.state ? ` \xB7 ${input.state}` : ""}`,
+          summary,
+          warnings,
+          tables: [
+            { title: "Market Benchmarks", columns: ["source_location", "result_count", "median_review_count", "median_rating", "top_three_average_review_count", "top_categories", "websites_present"], rows: markets },
+            { title: "Competitor Comparison", columns: ["source_location", "result_position", "business_name", "category", "review_stars", "review_count", "review_gap_to_top3_average", "comparison_note"], rows: compareRows.slice(0, 120) },
+            { title: "Profile Insights", columns: ["source_location", "business_name", "review_topics", "about_attributes", "error"], rows: profileRows }
+          ]
+        }));
+        const status = warnings.length ? "partial" : "succeeded";
+        const counts = { markets: markets.length, competitors: compareRows.length, hydratedProfiles: profileRows.filter((row) => !row.error).length };
+        await ctx.artifacts.writeManifest(status, counts, warnings, []);
+        return { title: "Maps Comparison", summary, status, counts, warnings, errors: [], reportPath };
+      }
+    };
+    serpComparisonWorkflowDefinition = {
+      id: "serp-comparison",
+      title: "SERP Comparison",
+      description: "Compare ranking pages, SERP features, PAA evidence, AI Overview citations, and page-level content gaps.",
+      inputSchema: SerpComparisonInputSchema,
+      async run(input, ctx) {
+        await ctx.artifacts.writeManifest("running", {}, [], []);
+        const warnings = [];
+        const targetDomain = normalizeDomain2(input.domain ?? input.url ?? null);
+        const serp = await ctx.client.post("/harvest/sync", {
+          query: input.keyword,
+          location: input.location,
+          serpOnly: true,
+          maxQuestions: 1,
+          format: "json"
+        }, 18e4);
+        await ctx.artifacts.writeJson("SERP raw JSON", "raw/serp.json", serp);
+        let paa = null;
+        if (input.includePaa) {
+          try {
+            paa = await ctx.client.post("/harvest/sync", {
+              query: input.keyword,
+              location: input.location,
+              maxQuestions: input.maxQuestions,
+              format: "json"
+            }, 28e4);
+            await ctx.artifacts.writeJson("PAA raw JSON", "raw/paa.json", paa);
+          } catch (err) {
+            warnings.push(`PAA evidence unavailable: ${err instanceof Error ? err.message : String(err)}`);
+          }
+        }
+        const organic = organicRows(serp, targetDomain).slice(0, input.maxResults);
+        const organicSources = (serp.organicResults ?? []).slice(0, input.maxResults);
+        const targetSource = input.url ? { position: 0, title: "Target page", url: input.url, domain: domainFromUrl2(input.url) } : organicSources.find((result) => targetDomain && (normalizeDomain2(result.domain ?? "") ?? domainFromUrl2(result.url)) === targetDomain);
+        const competitorSources = organicSources.filter((result) => result.url && result.url !== targetSource?.url).filter((result) => !targetDomain || (normalizeDomain2(result.domain ?? "") ?? domainFromUrl2(result.url)) !== targetDomain).slice(0, input.extractTop);
+        const targetPages = targetSource ? await extractPages(ctx, [targetSource], warnings, "Target") : [];
+        const competitorPages = input.extractTop > 0 ? await extractPages(ctx, competitorSources, warnings, "Competitor") : [];
+        const targetPage = targetPages[0]?.page ?? null;
+        const pageRows = [
+          ...targetPages.map(({ source, page }) => pageSummaryRow(page, { url: source.url ?? "", domain: normalizeDomain2(source.domain ?? "") ?? domainFromUrl2(source.url), position: source.position, title: source.title })),
+          ...competitorPages.map(({ source, page }) => pageSummaryRow(page, { url: source.url ?? "", domain: normalizeDomain2(source.domain ?? "") ?? domainFromUrl2(source.url), position: source.position, title: source.title }))
+        ];
+        const gaps = pageGapRows(targetPage, competitorPages);
+        const questions = questionRows(paa);
+        const aiRows = (serp.aiOverview?.citations ?? []).map((citation, index) => ({
+          citation_position: index + 1,
+          citation_text: citation.text ?? "",
+          url: citation.href ?? "",
+          domain: domainFromUrl2(citation.href ?? ""),
+          is_target: targetDomain ? domainFromUrl2(citation.href ?? "") === targetDomain : false
+        }));
+        await ctx.artifacts.writeCsv("Organic results CSV", "organic-results.csv", ["position", "title", "url", "domain", "snippet", "is_target"], organic);
+        await ctx.artifacts.writeCsv("Page comparison CSV", "page-comparison.csv", ["position", "domain", "url", "serp_title", "page_title", "h1", "meta_description", "word_count", "heading_count", "schema_types"], pageRows);
+        await ctx.artifacts.writeCsv("Content gaps CSV", "content-gaps.csv", ["source_position", "source_domain", "source_url", "heading_level", "competitor_heading", "target_coverage", "terms"], gaps);
+        await ctx.artifacts.writeCsv("PAA questions CSV", "paa-questions.csv", ["position", "intent", "question", "answer_excerpt", "source_title", "source_domain", "source_url"], questions);
+        await ctx.artifacts.writeCsv("AI Overview citations CSV", "ai-overview-citations.csv", ["citation_position", "citation_text", "url", "domain", "is_target"], aiRows);
+        await ctx.artifacts.writeJson("SERP comparison evidence", "evidence.json", { input, serp, paa, organic, pageRows, gaps, questions, aiRows, warnings });
+        await ctx.artifacts.writeText("Writer brief", "brief.md", [
+          `# SERP Comparison Brief: ${input.keyword}`,
+          "",
+          `Target: ${targetDomain ?? input.url ?? "not specified"}`,
+          `Location: ${input.location ?? "not specified"}`,
+          "",
+          "## Recommended Actions",
+          "- Use `content-gaps.csv` to decide which missing sections deserve coverage.",
+          "- Use `paa-questions.csv` for FAQ and answer-block candidates.",
+          "- Use `ai-overview-citations.csv` to see whether the target is cited in AI Overview evidence.",
+          "- Treat extracted page headings as evidence, not a complete semantic analysis."
+        ].join("\n"));
+        const summary = `${organic.length} organic results, ${pageRows.length} extracted pages, ${gaps.length} heading gaps, ${questions.length} PAA questions.`;
+        const reportPath = await ctx.artifacts.writeHtml("HTML report", "report.html", renderWorkflowReport({
+          title: "SERP Comparison",
+          subtitle: `${input.keyword}${input.location ? ` \xB7 ${input.location}` : ""}`,
+          summary,
+          warnings,
+          tables: [
+            { title: "Organic Results", columns: ["position", "title", "domain", "is_target"], rows: organic },
+            { title: "Page Comparison", columns: ["position", "domain", "h1", "word_count", "heading_count", "schema_types"], rows: pageRows },
+            { title: "Content Gaps", columns: ["source_position", "source_domain", "competitor_heading", "target_coverage", "terms"], rows: gaps.slice(0, 80) },
+            { title: "PAA Questions", columns: ["position", "intent", "question", "source_domain"], rows: questions.slice(0, 80) }
+          ]
+        }));
+        const status = warnings.length ? "partial" : "succeeded";
+        const counts = { organic: organic.length, pages: pageRows.length, gaps: gaps.length, questions: questions.length, aiCitations: aiRows.length };
+        await ctx.artifacts.writeManifest(status, counts, warnings, []);
+        return { title: "SERP Comparison", summary, status, counts, warnings, errors: [], reportPath };
+      }
+    };
+    paaExpansionBriefWorkflowDefinition = {
+      id: "paa-expansion-brief",
+      title: "PAA Expansion Brief",
+      description: "Expand People Also Ask questions into an evidence-backed writer brief, section map, and source table.",
+      inputSchema: PaaExpansionBriefInputSchema,
+      async run(input, ctx) {
+        await ctx.artifacts.writeManifest("running", {}, [], []);
+        const warnings = [];
+        const paa = await ctx.client.post("/harvest/sync", {
+          query: input.keyword,
+          location: input.location,
+          maxQuestions: input.maxQuestions,
+          depth: input.depth,
+          format: "json"
+        }, 3e5);
+        await ctx.artifacts.writeJson("PAA raw JSON", "raw/paa.json", paa);
+        const questions = questionRows(paa);
+        const sourceRows2 = sourceDomainRows(questions);
+        const byIntent = /* @__PURE__ */ new Map();
+        for (const row of questions) {
+          const list = byIntent.get(String(row.intent)) ?? [];
+          list.push(row);
+          byIntent.set(String(row.intent), list);
+        }
+        const sectionRows = [...byIntent.entries()].map(([intent, rows]) => ({
+          recommended_section: intent,
+          question_count: rows.length,
+          sample_questions: rows.slice(0, 5).map((row) => row.question).join(" | "),
+          source_domains: [...new Set(rows.map((row) => row.source_domain).filter(Boolean))].slice(0, 5).join("; "),
+          terms: textTerms(rows.map((row) => `${row.question} ${row.answer_excerpt}`).join(" "), 10)
+        })).sort((a, b) => Number(b.question_count) - Number(a.question_count));
+        await ctx.artifacts.writeCsv("PAA questions CSV", "paa-questions.csv", ["position", "intent", "question", "answer_excerpt", "source_title", "source_domain", "source_url"], questions);
+        await ctx.artifacts.writeCsv("Source domains CSV", "source-domains.csv", ["domain", "question_mentions", "source_url_count", "top_intents"], sourceRows2);
+        await ctx.artifacts.writeCsv("Section map CSV", "section-map.csv", ["recommended_section", "question_count", "sample_questions", "source_domains", "terms"], sectionRows);
+        await ctx.artifacts.writeJson("PAA brief evidence", "evidence.json", { input, paa, questions, sourceRows: sourceRows2, sectionRows });
+        await ctx.artifacts.writeText("Writer brief", "writer-brief.md", [
+          `# PAA Expansion Brief: ${input.keyword}`,
+          "",
+          `Location: ${input.location ?? "not specified"}`,
+          "",
+          "## Suggested Page Structure",
+          ...sectionRows.map((row) => `- ${row.recommended_section}: answer ${row.question_count} related question(s). Sample: ${row.sample_questions}`),
+          "",
+          "## Writing Rules",
+          "- Answer the highest-frequency question in the first 60 words of each section.",
+          "- Use exact customer question language from `paa-questions.csv` for H2/H3 candidates.",
+          "- Use `source-domains.csv` to identify which source types Google is already rewarding.",
+          "- Do not invent citations; cite only rows that have a source URL."
+        ].join("\n"));
+        const summary = `${questions.length} PAA questions grouped into ${sectionRows.length} writing sections.`;
+        const reportPath = await ctx.artifacts.writeHtml("HTML report", "report.html", renderWorkflowReport({
+          title: "PAA Expansion Brief",
+          subtitle: `${input.keyword}${input.location ? ` \xB7 ${input.location}` : ""}`,
+          summary,
+          warnings,
+          tables: [
+            { title: "Section Map", columns: ["recommended_section", "question_count", "sample_questions", "source_domains", "terms"], rows: sectionRows },
+            { title: "Questions", columns: ["position", "intent", "question", "source_domain"], rows: questions.slice(0, 120) },
+            { title: "Source Domains", columns: ["domain", "question_mentions", "source_url_count", "top_intents"], rows: sourceRows2 }
+          ]
+        }));
+        const counts = { questions: questions.length, sections: sectionRows.length, sourceDomains: sourceRows2.length };
+        await ctx.artifacts.writeManifest("succeeded", counts, warnings, []);
+        return { title: "PAA Expansion Brief", summary, status: "succeeded", counts, warnings, errors: [], reportPath };
+      }
+    };
+    aiOverviewLanguageWorkflowDefinition = {
+      id: "ai-overview-language",
+      title: "AI Overview Language Brief",
+      description: "Turn AI Overview, citation, PAA, and ranking-page evidence into answer-block and citation-hook guidance.",
+      inputSchema: AiOverviewLanguageInputSchema,
+      async run(input, ctx) {
+        await ctx.artifacts.writeManifest("running", {}, [], []);
+        const warnings = [];
+        const targetDomain = normalizeDomain2(input.domain ?? input.url ?? null);
+        const serp = await ctx.client.post("/harvest/sync", {
+          query: input.keyword,
+          location: input.location,
+          serpOnly: true,
+          maxQuestions: 1,
+          format: "json"
+        }, 18e4);
+        await ctx.artifacts.writeJson("SERP raw JSON", "raw/serp.json", serp);
+        let paa = null;
+        try {
+          paa = await ctx.client.post("/harvest/sync", {
+            query: input.keyword,
+            location: input.location,
+            maxQuestions: input.maxQuestions,
+            format: "json"
+          }, 28e4);
+          await ctx.artifacts.writeJson("PAA raw JSON", "raw/paa.json", paa);
+        } catch (err) {
+          warnings.push(`PAA evidence unavailable: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const citations = (serp.aiOverview?.citations ?? []).map((citation, index) => {
+          const domain = domainFromUrl2(citation.href ?? "");
+          return {
+            citation_position: index + 1,
+            citation_text: citation.text ?? "",
+            url: citation.href ?? "",
+            domain,
+            is_target: targetDomain ? domain === targetDomain : false
+          };
+        });
+        const aioSentences = splitSentences(serp.aiOverview?.text);
+        const claimRows = aioSentences.map((sentence, index) => ({
+          position: index + 1,
+          claim_type: classifySentence(sentence),
+          sentence,
+          reusable_pattern: sentence.length > 140 ? `${sentence.slice(0, 140)}...` : sentence
+        }));
+        const questions = questionRows(paa);
+        const citationSources = (serp.aiOverview?.citations ?? []).filter((citation) => citation.href).map((citation, index) => ({ position: index + 1, title: citation.text, url: citation.href, domain: domainFromUrl2(citation.href) })).slice(0, input.extractTop);
+        const extractedCitations = input.extractTop > 0 ? await extractPages(ctx, citationSources, warnings, "Citation") : [];
+        const extractedRows = extractedCitations.map(({ source, page }) => pageSummaryRow(page, { url: source.url ?? "", domain: normalizeDomain2(source.domain ?? "") ?? domainFromUrl2(source.url), position: source.position, title: source.title }));
+        const languageRows = [
+          {
+            block: "direct_answer",
+            guidance: "Open with a 40-70 word answer that directly resolves the query before adding context.",
+            evidence_basis: questions[0]?.question ?? input.keyword
+          },
+          {
+            block: "criteria_or_steps",
+            guidance: "List the criteria, steps, or decision factors Google is already compressing into AI Overview language.",
+            evidence_basis: claimRows.filter((row) => ["criteria", "process"].includes(String(row.claim_type))).map((row) => row.sentence).slice(0, 3).join(" | ")
+          },
+          {
+            block: "citation_hook",
+            guidance: "Add source-worthy details competitors can cite: definitions, numbers, examples, process details, and named entity relationships.",
+            evidence_basis: citations.map((row) => `${row.domain}: ${row.citation_text}`).slice(0, 5).join(" | ")
+          },
+          {
+            block: "faq_followups",
+            guidance: "Use PAA phrasing for follow-up sections so the page answers adjacent questions in Google language.",
+            evidence_basis: questions.slice(0, 5).map((row) => row.question).join(" | ")
+          }
+        ];
+        await ctx.artifacts.writeCsv("AI Overview citations CSV", "ai-overview-citations.csv", ["citation_position", "citation_text", "url", "domain", "is_target"], citations);
+        await ctx.artifacts.writeCsv("AI Overview claim patterns CSV", "claim-patterns.csv", ["position", "claim_type", "sentence", "reusable_pattern"], claimRows);
+        await ctx.artifacts.writeCsv("Language guidance CSV", "language-guidance.csv", ["block", "guidance", "evidence_basis"], languageRows);
+        await ctx.artifacts.writeCsv("PAA questions CSV", "paa-questions.csv", ["position", "intent", "question", "answer_excerpt", "source_title", "source_domain", "source_url"], questions);
+        await ctx.artifacts.writeCsv("Extracted citation pages CSV", "citation-pages.csv", ["position", "domain", "url", "serp_title", "page_title", "h1", "meta_description", "word_count", "heading_count", "schema_types"], extractedRows);
+        await ctx.artifacts.writeJson("AI Overview language evidence", "evidence.json", { input, serp, paa, citations, claimRows, languageRows, extractedRows, warnings });
+        await ctx.artifacts.writeText("Answer block template", "answer-block-template.md", [
+          `# AI Overview Language Brief: ${input.keyword}`,
+          "",
+          `AI Overview detected: ${serp.aiOverview?.detected ? "yes" : "no"}`,
+          `Target cited: ${targetDomain ? citations.some((row) => row.is_target) ? "yes" : "no" : "target not specified"}`,
+          "",
+          "## Direct Answer Block",
+          "Write one compact answer block that starts with the answer, not background. Keep it clear enough that Google could lift it as a standalone summary.",
+          "",
+          "## Suggested Follow-Up Blocks",
+          ...languageRows.map((row) => `- ${row.block}: ${row.guidance}`),
+          "",
+          "## Evidence to Mirror",
+          ...claimRows.slice(0, 8).map((row) => `- ${row.claim_type}: ${row.sentence}`),
+          "",
+          "## Citation Hooks",
+          ...citations.slice(0, 8).map((row) => `- ${row.domain}: ${row.citation_text}`)
+        ].join("\n"));
+        const summary = `${citations.length} AI Overview citations, ${claimRows.length} claim patterns, ${questions.length} PAA questions, ${extractedRows.length} citation pages extracted.`;
+        const reportPath = await ctx.artifacts.writeHtml("HTML report", "report.html", renderWorkflowReport({
+          title: "AI Overview Language Brief",
+          subtitle: `${input.keyword}${input.location ? ` \xB7 ${input.location}` : ""}`,
+          summary,
+          warnings,
+          tables: [
+            { title: "Language Guidance", columns: ["block", "guidance", "evidence_basis"], rows: languageRows },
+            { title: "AI Overview Citations", columns: ["citation_position", "citation_text", "domain", "is_target"], rows: citations },
+            { title: "Claim Patterns", columns: ["position", "claim_type", "sentence"], rows: claimRows },
+            { title: "PAA Follow-Ups", columns: ["position", "intent", "question", "source_domain"], rows: questions.slice(0, 60) }
+          ]
+        }));
+        const status = warnings.length || !serp.aiOverview?.detected ? "partial" : "succeeded";
+        const counts = { citations: citations.length, claimPatterns: claimRows.length, questions: questions.length, extractedCitationPages: extractedRows.length };
+        await ctx.artifacts.writeManifest(status, counts, warnings, []);
+        return { title: "AI Overview Language Brief", summary, status, counts, warnings, errors: [], reportPath };
+      }
+    };
+  }
+});
+
 // src/workflows/registry.ts
 function listWorkflowDefinitions() {
   return DEFINITIONS.map(({ id, title, description }) => ({ id, title, description }));
@@ -15662,7 +16690,7 @@ async function runWorkflow(id, rawInput, options = {}) {
   if (!apiKey) throw new Error("MCP_SCRAPER_API_KEY is required for workflow runs. Pass --api-key or set the environment variable.");
   const apiUrl = options.apiUrl?.trim() || process.env.MCP_SCRAPER_API_URL?.trim() || "https://mcpscraper.dev";
   const artifacts = await ArtifactWriter.create(definition.id, definition.title, input, options.outputDir, options.runId);
-  const client2 = new WorkflowHttpClient(apiUrl, apiKey, options.fetchImpl);
+  const client2 = new WorkflowHttpClient(apiUrl, apiKey, options.fetchImpl, options.headers);
   try {
     return await definition.run(input, {
       runId: artifacts.runId,
@@ -15681,20 +16709,25 @@ ${message}
     throw err;
   }
 }
-var import_zod22, DEFINITIONS;
+var import_zod23, DEFINITIONS;
 var init_registry2 = __esm({
   "src/workflows/registry.ts"() {
     "use strict";
-    import_zod22 = require("zod");
+    import_zod23 = require("zod");
     init_artifact_writer();
     init_http_client2();
     init_agent_packet();
     init_directory();
     init_local_competitive_audit();
+    init_comparison_briefs();
     DEFINITIONS = [
       directoryWorkflowDefinition,
       agentPacketWorkflowDefinition,
-      localCompetitiveAuditWorkflowDefinition
+      localCompetitiveAuditWorkflowDefinition,
+      mapComparisonWorkflowDefinition,
+      serpComparisonWorkflowDefinition,
+      paaExpansionBriefWorkflowDefinition,
+      aiOverviewLanguageWorkflowDefinition
     ];
   }
 });
@@ -15756,7 +16789,7 @@ async function readManifestFromSummary(summary) {
 function webhookSignature(body, timestamp2) {
   const secret2 = process.env.MCP_SCRAPER_WEBHOOK_SECRET?.trim();
   if (!secret2) return null;
-  return (0, import_node_crypto2.createHmac)("sha256", secret2).update(`${timestamp2}.${body}`).digest("hex");
+  return (0, import_node_crypto3.createHmac)("sha256", secret2).update(`${timestamp2}.${body}`).digest("hex");
 }
 async function deliverWorkflowWebhook(input) {
   if (!input.webhookUrl) return;
@@ -15810,7 +16843,8 @@ async function executeWorkflowRun(input) {
       apiKey: input.user.api_key,
       apiUrl: input.apiUrl,
       outputDir: hostedWorkflowOutputDir(),
-      runId: input.runId
+      runId: input.runId,
+      headers: input.concurrencyLockId ? { "x-mcp-scraper-concurrency-lock": input.concurrencyLockId } : void 0
     });
     const manifest = await readManifestFromSummary(summary);
     await completeWorkflowRunRecord(input.runId, summary.status, manifest ?? { summary });
@@ -15839,19 +16873,28 @@ async function dispatchDueWorkflowSchedules(apiUrl, limit = 3) {
       continue;
     }
     const scheduledFor = schedule.next_run_at ?? now;
-    const run = await createWorkflowRun({
-      userId: user.id,
-      scheduleId: schedule.id,
-      workflowId: schedule.workflow_id,
-      workflowInput: schedule.input,
-      idempotencyKey: `${schedule.id}:${scheduledFor}`
+    const gate = await acquireConcurrencyGate(user, "workflow_schedule_dispatch", {
+      ttlSeconds: 60 * 60,
+      metadata: { scheduleId: schedule.id, workflowId: schedule.workflow_id }
     });
-    await markWorkflowScheduleRan(schedule.id, now, addCadence(scheduledFor, schedule.cadence));
-    if (run.status !== "queued") {
-      results.push({ scheduleId: schedule.id, runId: run.id, status: run.status });
+    if (!gate.ok) {
+      results.push({ scheduleId: schedule.id, status: "deferred", error: concurrencyLimitExceededResponse(gate).message });
       continue;
     }
+    let run = null;
     try {
+      run = await createWorkflowRun({
+        userId: user.id,
+        scheduleId: schedule.id,
+        workflowId: schedule.workflow_id,
+        workflowInput: schedule.input,
+        idempotencyKey: `${schedule.id}:${scheduledFor}`
+      });
+      await markWorkflowScheduleRan(schedule.id, now, addCadence(scheduledFor, schedule.cadence));
+      if (run.status !== "queued") {
+        results.push({ scheduleId: schedule.id, runId: run.id, status: run.status });
+        continue;
+      }
       const executed = await executeWorkflowRun({
         runId: run.id,
         user,
@@ -15859,55 +16902,59 @@ async function dispatchDueWorkflowSchedules(apiUrl, limit = 3) {
         workflowInput: schedule.input,
         apiUrl,
         scheduleId: schedule.id,
-        webhookUrl: schedule.webhook_url
+        webhookUrl: schedule.webhook_url,
+        concurrencyLockId: gate.lockId
       });
       results.push({ scheduleId: schedule.id, runId: executed.run.id, status: executed.run.status });
     } catch (err) {
-      results.push({ scheduleId: schedule.id, runId: run.id, status: "failed", error: err instanceof Error ? err.message : String(err) });
+      results.push({ scheduleId: schedule.id, runId: run?.id, status: "failed", error: err instanceof Error ? err.message : String(err) });
+    } finally {
+      await releaseConcurrencyGate(gate.lockId);
     }
   }
   return { dispatched: results.length, results };
 }
-var import_node_crypto2, import_promises7, import_hono7, import_zod23, workflowApp, WorkflowInputSchema, WorkflowIdSchema, CadenceSchema, ScheduleStatusSchema, RunBodySchema, ScheduleCreateSchema, SchedulePatchSchema;
+var import_node_crypto3, import_promises7, import_hono7, import_zod24, workflowApp, WorkflowInputSchema, WorkflowIdSchema, CadenceSchema, ScheduleStatusSchema, RunBodySchema, ScheduleCreateSchema, SchedulePatchSchema;
 var init_workflow_routes = __esm({
   "src/api/workflow-routes.ts"() {
     "use strict";
-    import_node_crypto2 = require("crypto");
+    import_node_crypto3 = require("crypto");
     import_promises7 = require("fs/promises");
     import_hono7 = require("hono");
-    import_zod23 = require("zod");
+    import_zod24 = require("zod");
     init_artifact_writer();
     init_registry2();
     init_api_auth();
     init_db();
     init_url_utils();
+    init_concurrency_gates();
     workflowApp = new import_hono7.Hono();
-    WorkflowInputSchema = import_zod23.z.record(import_zod23.z.unknown()).default({});
-    WorkflowIdSchema = import_zod23.z.string().min(1);
-    CadenceSchema = import_zod23.z.enum(["daily", "weekly", "monthly"]);
-    ScheduleStatusSchema = import_zod23.z.enum(["active", "paused"]);
-    RunBodySchema = import_zod23.z.object({
+    WorkflowInputSchema = import_zod24.z.record(import_zod24.z.unknown()).default({});
+    WorkflowIdSchema = import_zod24.z.string().min(1);
+    CadenceSchema = import_zod24.z.enum(["daily", "weekly", "monthly"]);
+    ScheduleStatusSchema = import_zod24.z.enum(["active", "paused"]);
+    RunBodySchema = import_zod24.z.object({
       workflowId: WorkflowIdSchema,
       input: WorkflowInputSchema,
-      webhookUrl: import_zod23.z.string().url().optional()
+      webhookUrl: import_zod24.z.string().url().optional()
     });
-    ScheduleCreateSchema = import_zod23.z.object({
+    ScheduleCreateSchema = import_zod24.z.object({
       workflowId: WorkflowIdSchema,
-      name: import_zod23.z.string().min(1).max(120).optional(),
+      name: import_zod24.z.string().min(1).max(120).optional(),
       input: WorkflowInputSchema,
       cadence: CadenceSchema.default("weekly"),
-      timezone: import_zod23.z.string().min(1).max(64).default("UTC"),
-      webhookUrl: import_zod23.z.string().url().optional(),
-      nextRunAt: import_zod23.z.string().datetime().optional()
+      timezone: import_zod24.z.string().min(1).max(64).default("UTC"),
+      webhookUrl: import_zod24.z.string().url().optional(),
+      nextRunAt: import_zod24.z.string().datetime().optional()
     });
-    SchedulePatchSchema = import_zod23.z.object({
-      name: import_zod23.z.string().min(1).max(120).optional(),
+    SchedulePatchSchema = import_zod24.z.object({
+      name: import_zod24.z.string().min(1).max(120).optional(),
       status: ScheduleStatusSchema.optional(),
       input: WorkflowInputSchema.optional(),
       cadence: CadenceSchema.optional(),
-      timezone: import_zod23.z.string().min(1).max(64).optional(),
-      webhookUrl: import_zod23.z.string().url().nullable().optional(),
-      nextRunAt: import_zod23.z.string().datetime().nullable().optional()
+      timezone: import_zod24.z.string().min(1).max(64).optional(),
+      webhookUrl: import_zod24.z.string().url().nullable().optional(),
+      nextRunAt: import_zod24.z.string().datetime().nullable().optional()
     });
     workflowApp.get("/definitions", createApiKeyAuth(), (c) => {
       return c.json({ workflows: listWorkflowDefinitions() });
@@ -15924,20 +16971,29 @@ var init_workflow_routes = __esm({
       } catch (err) {
         return c.json({ error: err instanceof Error ? err.message : String(err) }, 400);
       }
-      const run = await createWorkflowRun({ userId: user.id, workflowId: parsed.data.workflowId, workflowInput: input });
+      const gate = await acquireConcurrencyGate(user, "workflow_run", {
+        ttlSeconds: 60 * 60,
+        metadata: { workflowId: parsed.data.workflowId }
+      });
+      if (!gate.ok) return c.json(concurrencyLimitExceededResponse(gate), 429, { "Retry-After": String(gate.retryAfterSeconds) });
+      let run = null;
       try {
+        run = await createWorkflowRun({ userId: user.id, workflowId: parsed.data.workflowId, workflowInput: input });
         const executed = await executeWorkflowRun({
           runId: run.id,
           user,
           workflowId: parsed.data.workflowId,
           workflowInput: input,
           apiUrl: originFromUrl(c.req.url),
-          webhookUrl
+          webhookUrl,
+          concurrencyLockId: gate.lockId
         });
         return c.json({ run: exposeRun(c, executed.run, executed.artifacts), summary: executed.summary });
       } catch (err) {
-        const failed = await getWorkflowRun(run.id, user.id);
+        const failed = run ? await getWorkflowRun(run.id, user.id) : null;
         return c.json({ run: failed, error: err instanceof Error ? err.message : String(err) }, 500);
+      } finally {
+        await releaseConcurrencyGate(gate.lockId);
       }
     });
     workflowApp.get("/runs", createApiKeyAuth(), async (c) => {
@@ -16035,8 +17091,14 @@ var init_workflow_routes = __esm({
       const user = c.get("user");
       const schedule = await getWorkflowSchedule(c.req.param("id"), user.id);
       if (!schedule) return c.json({ error: "Schedule not found" }, 404);
-      const run = await createWorkflowRun({ userId: user.id, scheduleId: schedule.id, workflowId: schedule.workflow_id, workflowInput: schedule.input });
+      const gate = await acquireConcurrencyGate(user, "workflow_schedule_run", {
+        ttlSeconds: 60 * 60,
+        metadata: { scheduleId: schedule.id, workflowId: schedule.workflow_id }
+      });
+      if (!gate.ok) return c.json(concurrencyLimitExceededResponse(gate), 429, { "Retry-After": String(gate.retryAfterSeconds) });
+      let run = null;
       try {
+        run = await createWorkflowRun({ userId: user.id, scheduleId: schedule.id, workflowId: schedule.workflow_id, workflowInput: schedule.input });
         const executed = await executeWorkflowRun({
           runId: run.id,
           user,
@@ -16044,12 +17106,15 @@ var init_workflow_routes = __esm({
           workflowInput: schedule.input,
           apiUrl: originFromUrl(c.req.url),
           scheduleId: schedule.id,
-          webhookUrl: schedule.webhook_url
+          webhookUrl: schedule.webhook_url,
+          concurrencyLockId: gate.lockId
         });
         return c.json({ run: exposeRun(c, executed.run, executed.artifacts), summary: executed.summary });
       } catch (err) {
-        const failed = await getWorkflowRun(run.id, user.id);
+        const failed = run ? await getWorkflowRun(run.id, user.id) : null;
         return c.json({ run: failed, error: err instanceof Error ? err.message : String(err) }, 500);
+      } finally {
+        await releaseConcurrencyGate(gate.lockId);
       }
     });
     workflowApp.post("/cron/dispatch", async (c) => {
@@ -16065,7 +17130,7 @@ var init_workflow_routes = __esm({
 // src/serp-intelligence/page-snapshot-extractor.ts
 function sha256(value) {
   if (!value) return null;
-  return (0, import_node_crypto3.createHash)("sha256").update(value).digest("hex");
+  return (0, import_node_crypto4.createHash)("sha256").update(value).digest("hex");
 }
 function countWords(markdown) {
   const matches = markdown.trim().match(/\b[\p{L}\p{N}][\p{L}\p{N}'-]*\b/gu);
@@ -16365,11 +17430,11 @@ async function capturePageSnapshots(targets, options = {}) {
     }
   };
 }
-var import_node_crypto3, import_p_limit3, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_CONCURRENCY, DEFAULT_MAX_CONTENT_CHARS;
+var import_node_crypto4, import_p_limit3, DEFAULT_TIMEOUT_MS, DEFAULT_MAX_CONCURRENCY, DEFAULT_MAX_CONTENT_CHARS;
 var init_page_snapshot_extractor = __esm({
   "src/serp-intelligence/page-snapshot-extractor.ts"() {
     "use strict";
-    import_node_crypto3 = require("crypto");
+    import_node_crypto4 = require("crypto");
     import_p_limit3 = __toESM(require("p-limit"), 1);
     init_kpo_extractor();
     init_url_utils();
@@ -18246,11 +19311,11 @@ function isPublicHttpUrl(value) {
     return false;
   }
 }
-var import_zod24, SerpIntelligenceDeviceValues, SerpIntelligenceProxyModeValues, SerpIntelligenceAttemptOutcomeValues, SerpIntelligenceLocalizationStatusValues, SerpPageSnapshotSourceKindValues, SerpPageFetchStatusValues, SerpPageFetchedViaValues, HostnameSuffixPattern, Ipv4Pattern, SerpIntelligencePublicHttpUrlSchema, SerpIntelligenceCaptureBodySchema, SerpIntelligencePageSnapshotRequestSchema, SerpIntelligencePageSnapshotsBodySchema, SerpIntelligenceAICitationSchema, SerpIntelligenceOrganicResultSchema, SerpIntelligenceLocationEvidenceSchema, SerpIntelligenceHarvestResultSchema, SerpIntelligenceCaptureAttemptSchema, SerpPageSnapshotCaptureSchema, SerpIntelligenceCaptureResponseSchema, SerpIntelligencePageSnapshotsResponseSchema;
+var import_zod25, SerpIntelligenceDeviceValues, SerpIntelligenceProxyModeValues, SerpIntelligenceAttemptOutcomeValues, SerpIntelligenceLocalizationStatusValues, SerpPageSnapshotSourceKindValues, SerpPageFetchStatusValues, SerpPageFetchedViaValues, HostnameSuffixPattern, Ipv4Pattern, SerpIntelligencePublicHttpUrlSchema, SerpIntelligenceCaptureBodySchema, SerpIntelligencePageSnapshotRequestSchema, SerpIntelligencePageSnapshotsBodySchema, SerpIntelligenceAICitationSchema, SerpIntelligenceOrganicResultSchema, SerpIntelligenceLocationEvidenceSchema, SerpIntelligenceHarvestResultSchema, SerpIntelligenceCaptureAttemptSchema, SerpPageSnapshotCaptureSchema, SerpIntelligenceCaptureResponseSchema, SerpIntelligencePageSnapshotsResponseSchema;
 var init_schemas4 = __esm({
   "src/serp-intelligence/schemas.ts"() {
     "use strict";
-    import_zod24 = require("zod");
+    import_zod25 = require("zod");
     SerpIntelligenceDeviceValues = ["desktop", "mobile"];
     SerpIntelligenceProxyModeValues = ["location", "configured", "none"];
     SerpIntelligenceAttemptOutcomeValues = [
@@ -18284,171 +19349,171 @@ var init_schemas4 = __esm({
     SerpPageFetchedViaValues = ["fetch", "headless", "browser", "mcp"];
     HostnameSuffixPattern = /(^|\.)localhost$/i;
     Ipv4Pattern = /^\d{1,3}(?:\.\d{1,3}){3}$/;
-    SerpIntelligencePublicHttpUrlSchema = import_zod24.z.string().url().refine(isPublicHttpUrl, "url must be a public HTTP or HTTPS URL");
-    SerpIntelligenceCaptureBodySchema = import_zod24.z.object({
-      query: import_zod24.z.string().trim().min(1, "query is required"),
-      location: import_zod24.z.string().trim().min(1).optional(),
-      gl: import_zod24.z.string().trim().length(2).default("us"),
-      hl: import_zod24.z.string().trim().length(2).default("en"),
-      device: import_zod24.z.enum(SerpIntelligenceDeviceValues).default("desktop"),
-      proxyMode: import_zod24.z.enum(SerpIntelligenceProxyModeValues).default("location"),
-      proxyZip: import_zod24.z.string().regex(/^\d{5}$/).optional(),
-      pages: import_zod24.z.number().int().min(1).max(2).default(1),
-      debug: import_zod24.z.boolean().default(false),
-      includePageSnapshots: import_zod24.z.boolean().default(false),
-      pageSnapshotLimit: import_zod24.z.number().int().min(0).max(10).default(0)
+    SerpIntelligencePublicHttpUrlSchema = import_zod25.z.string().url().refine(isPublicHttpUrl, "url must be a public HTTP or HTTPS URL");
+    SerpIntelligenceCaptureBodySchema = import_zod25.z.object({
+      query: import_zod25.z.string().trim().min(1, "query is required"),
+      location: import_zod25.z.string().trim().min(1).optional(),
+      gl: import_zod25.z.string().trim().length(2).default("us"),
+      hl: import_zod25.z.string().trim().length(2).default("en"),
+      device: import_zod25.z.enum(SerpIntelligenceDeviceValues).default("desktop"),
+      proxyMode: import_zod25.z.enum(SerpIntelligenceProxyModeValues).default("location"),
+      proxyZip: import_zod25.z.string().regex(/^\d{5}$/).optional(),
+      pages: import_zod25.z.number().int().min(1).max(2).default(1),
+      debug: import_zod25.z.boolean().default(false),
+      includePageSnapshots: import_zod25.z.boolean().default(false),
+      pageSnapshotLimit: import_zod25.z.number().int().min(0).max(10).default(0)
     }).strict();
-    SerpIntelligencePageSnapshotRequestSchema = import_zod24.z.object({
+    SerpIntelligencePageSnapshotRequestSchema = import_zod25.z.object({
       url: SerpIntelligencePublicHttpUrlSchema,
-      sourceKind: import_zod24.z.enum(SerpPageSnapshotSourceKindValues).default("configured_target"),
-      sourcePosition: import_zod24.z.number().int().min(1).optional()
+      sourceKind: import_zod25.z.enum(SerpPageSnapshotSourceKindValues).default("configured_target"),
+      sourcePosition: import_zod25.z.number().int().min(1).optional()
     }).strict();
-    SerpIntelligencePageSnapshotsBodySchema = import_zod24.z.object({
-      urls: import_zod24.z.array(SerpIntelligencePublicHttpUrlSchema).min(1).max(25),
-      targets: import_zod24.z.array(SerpIntelligencePageSnapshotRequestSchema).min(1).max(25).optional(),
-      maxConcurrency: import_zod24.z.number().int().min(1).max(5).default(2),
-      timeoutMs: import_zod24.z.number().int().min(1e3).max(6e4).default(15e3),
-      debug: import_zod24.z.boolean().default(false)
+    SerpIntelligencePageSnapshotsBodySchema = import_zod25.z.object({
+      urls: import_zod25.z.array(SerpIntelligencePublicHttpUrlSchema).min(1).max(25),
+      targets: import_zod25.z.array(SerpIntelligencePageSnapshotRequestSchema).min(1).max(25).optional(),
+      maxConcurrency: import_zod25.z.number().int().min(1).max(5).default(2),
+      timeoutMs: import_zod25.z.number().int().min(1e3).max(6e4).default(15e3),
+      debug: import_zod25.z.boolean().default(false)
     }).strict();
-    SerpIntelligenceAICitationSchema = import_zod24.z.object({
-      text: import_zod24.z.string(),
-      href: import_zod24.z.string()
+    SerpIntelligenceAICitationSchema = import_zod25.z.object({
+      text: import_zod25.z.string(),
+      href: import_zod25.z.string()
     }).strict();
-    SerpIntelligenceOrganicResultSchema = import_zod24.z.object({
-      position: import_zod24.z.number().int().min(1),
-      title: import_zod24.z.string(),
-      url: import_zod24.z.string(),
-      domain: import_zod24.z.string(),
-      cite: import_zod24.z.string().nullable(),
-      snippet: import_zod24.z.string().nullable(),
-      isRedditStyle: import_zod24.z.boolean(),
-      inlineRating: import_zod24.z.object({
-        value: import_zod24.z.string(),
-        count: import_zod24.z.string()
+    SerpIntelligenceOrganicResultSchema = import_zod25.z.object({
+      position: import_zod25.z.number().int().min(1),
+      title: import_zod25.z.string(),
+      url: import_zod25.z.string(),
+      domain: import_zod25.z.string(),
+      cite: import_zod25.z.string().nullable(),
+      snippet: import_zod25.z.string().nullable(),
+      isRedditStyle: import_zod25.z.boolean(),
+      inlineRating: import_zod25.z.object({
+        value: import_zod25.z.string(),
+        count: import_zod25.z.string()
       }).strict().nullable()
     }).strict();
-    SerpIntelligenceLocationEvidenceSchema = import_zod24.z.object({
-      status: import_zod24.z.enum(SerpIntelligenceLocalizationStatusValues),
-      expected: import_zod24.z.object({
-        city: import_zod24.z.string(),
-        regionCode: import_zod24.z.string().nullable(),
-        canonicalLocation: import_zod24.z.string()
+    SerpIntelligenceLocationEvidenceSchema = import_zod25.z.object({
+      status: import_zod25.z.enum(SerpIntelligenceLocalizationStatusValues),
+      expected: import_zod25.z.object({
+        city: import_zod25.z.string(),
+        regionCode: import_zod25.z.string().nullable(),
+        canonicalLocation: import_zod25.z.string()
       }).strict().nullable(),
-      candidates: import_zod24.z.array(import_zod24.z.object({
-        city: import_zod24.z.string(),
-        regionCode: import_zod24.z.string(),
-        count: import_zod24.z.number().int().min(0),
-        examples: import_zod24.z.array(import_zod24.z.string())
+      candidates: import_zod25.z.array(import_zod25.z.object({
+        city: import_zod25.z.string(),
+        regionCode: import_zod25.z.string(),
+        count: import_zod25.z.number().int().min(0),
+        examples: import_zod25.z.array(import_zod25.z.string())
       }).strict())
     }).strict();
-    SerpIntelligenceHarvestResultSchema = import_zod24.z.object({
-      seed: import_zod24.z.string(),
-      location: import_zod24.z.string().nullable(),
-      extractedAt: import_zod24.z.string(),
-      totalQuestions: import_zod24.z.number().int().min(0),
-      surface: import_zod24.z.enum(["web", "aim", "unknown"]),
-      aiOverview: import_zod24.z.object({
-        detected: import_zod24.z.boolean(),
-        text: import_zod24.z.string().nullable(),
-        citations: import_zod24.z.array(SerpIntelligenceAICitationSchema),
-        expanded: import_zod24.z.boolean().optional(),
-        fullyExpanded: import_zod24.z.boolean().optional(),
-        sections: import_zod24.z.array(import_zod24.z.string()).optional()
+    SerpIntelligenceHarvestResultSchema = import_zod25.z.object({
+      seed: import_zod25.z.string(),
+      location: import_zod25.z.string().nullable(),
+      extractedAt: import_zod25.z.string(),
+      totalQuestions: import_zod25.z.number().int().min(0),
+      surface: import_zod25.z.enum(["web", "aim", "unknown"]),
+      aiOverview: import_zod25.z.object({
+        detected: import_zod25.z.boolean(),
+        text: import_zod25.z.string().nullable(),
+        citations: import_zod25.z.array(SerpIntelligenceAICitationSchema),
+        expanded: import_zod25.z.boolean().optional(),
+        fullyExpanded: import_zod25.z.boolean().optional(),
+        sections: import_zod25.z.array(import_zod25.z.string()).optional()
       }).strict(),
-      aiMode: import_zod24.z.object({
-        detected: import_zod24.z.boolean(),
-        text: import_zod24.z.string().nullable(),
-        citations: import_zod24.z.array(SerpIntelligenceAICitationSchema)
+      aiMode: import_zod25.z.object({
+        detected: import_zod25.z.boolean(),
+        text: import_zod25.z.string().nullable(),
+        citations: import_zod25.z.array(SerpIntelligenceAICitationSchema)
       }).strict(),
-      tree: import_zod24.z.array(import_zod24.z.unknown()),
-      flat: import_zod24.z.array(import_zod24.z.unknown()),
-      videos: import_zod24.z.array(import_zod24.z.unknown()),
-      forums: import_zod24.z.array(import_zod24.z.unknown()),
-      organicResults: import_zod24.z.array(SerpIntelligenceOrganicResultSchema),
-      localPack: import_zod24.z.array(import_zod24.z.unknown()),
-      entityIds: import_zod24.z.object({
-        entities: import_zod24.z.array(import_zod24.z.object({
-          name: import_zod24.z.string(),
-          kgId: import_zod24.z.string().nullable(),
-          cid: import_zod24.z.string().nullable(),
-          gcid: import_zod24.z.string().nullable()
+      tree: import_zod25.z.array(import_zod25.z.unknown()),
+      flat: import_zod25.z.array(import_zod25.z.unknown()),
+      videos: import_zod25.z.array(import_zod25.z.unknown()),
+      forums: import_zod25.z.array(import_zod25.z.unknown()),
+      organicResults: import_zod25.z.array(SerpIntelligenceOrganicResultSchema),
+      localPack: import_zod25.z.array(import_zod25.z.unknown()),
+      entityIds: import_zod25.z.object({
+        entities: import_zod25.z.array(import_zod25.z.object({
+          name: import_zod25.z.string(),
+          kgId: import_zod25.z.string().nullable(),
+          cid: import_zod25.z.string().nullable(),
+          gcid: import_zod25.z.string().nullable()
         }).strict()),
-        kgIds: import_zod24.z.array(import_zod24.z.string()),
-        cids: import_zod24.z.array(import_zod24.z.string()),
-        gcids: import_zod24.z.array(import_zod24.z.string())
+        kgIds: import_zod25.z.array(import_zod25.z.string()),
+        cids: import_zod25.z.array(import_zod25.z.string()),
+        gcids: import_zod25.z.array(import_zod25.z.string())
       }).strict(),
-      stats: import_zod24.z.object({
-        seed: import_zod24.z.string(),
-        totalQuestions: import_zod24.z.number().int().min(0),
-        maxDepthReached: import_zod24.z.number().int().min(0),
-        durationMs: import_zod24.z.number().min(0),
-        errorCount: import_zod24.z.number().int().min(0)
+      stats: import_zod25.z.object({
+        seed: import_zod25.z.string(),
+        totalQuestions: import_zod25.z.number().int().min(0),
+        maxDepthReached: import_zod25.z.number().int().min(0),
+        durationMs: import_zod25.z.number().min(0),
+        errorCount: import_zod25.z.number().int().min(0)
       }).strict(),
-      diagnostics: import_zod24.z.object({
-        completionStatus: import_zod24.z.enum(["paa_found", "no_paa", "serp_only"]),
-        problem: import_zod24.z.null(),
-        warnings: import_zod24.z.array(import_zod24.z.unknown()).optional(),
-        debug: import_zod24.z.object({
+      diagnostics: import_zod25.z.object({
+        completionStatus: import_zod25.z.enum(["paa_found", "no_paa", "serp_only"]),
+        problem: import_zod25.z.null(),
+        warnings: import_zod25.z.array(import_zod25.z.unknown()).optional(),
+        debug: import_zod25.z.object({
           locationEvidence: SerpIntelligenceLocationEvidenceSchema.optional()
         }).passthrough().optional()
       }).passthrough(),
-      whatPeopleSaying: import_zod24.z.array(import_zod24.z.unknown())
+      whatPeopleSaying: import_zod25.z.array(import_zod25.z.unknown())
     }).strict();
-    SerpIntelligenceCaptureAttemptSchema = import_zod24.z.object({
-      attemptNumber: import_zod24.z.number().int().min(1),
-      outcome: import_zod24.z.enum(SerpIntelligenceAttemptOutcomeValues),
-      startedAt: import_zod24.z.string().optional(),
-      completedAt: import_zod24.z.string().optional(),
-      durationMs: import_zod24.z.number().min(0).optional(),
-      problemCode: import_zod24.z.string().optional(),
-      message: import_zod24.z.string().optional(),
-      kernelSessionId: import_zod24.z.string().nullable().optional(),
-      cleanupSucceeded: import_zod24.z.boolean().nullable().optional()
+    SerpIntelligenceCaptureAttemptSchema = import_zod25.z.object({
+      attemptNumber: import_zod25.z.number().int().min(1),
+      outcome: import_zod25.z.enum(SerpIntelligenceAttemptOutcomeValues),
+      startedAt: import_zod25.z.string().optional(),
+      completedAt: import_zod25.z.string().optional(),
+      durationMs: import_zod25.z.number().min(0).optional(),
+      problemCode: import_zod25.z.string().optional(),
+      message: import_zod25.z.string().optional(),
+      kernelSessionId: import_zod25.z.string().nullable().optional(),
+      cleanupSucceeded: import_zod25.z.boolean().nullable().optional()
     }).strict();
-    SerpPageSnapshotCaptureSchema = import_zod24.z.object({
+    SerpPageSnapshotCaptureSchema = import_zod25.z.object({
       url: SerpIntelligencePublicHttpUrlSchema,
       requestedUrl: SerpIntelligencePublicHttpUrlSchema,
       finalUrl: SerpIntelligencePublicHttpUrlSchema.nullable(),
-      sourceKind: import_zod24.z.enum(SerpPageSnapshotSourceKindValues),
-      sourcePosition: import_zod24.z.number().int().min(1).nullable(),
-      status: import_zod24.z.enum(SerpPageFetchStatusValues),
-      fetchedVia: import_zod24.z.enum(SerpPageFetchedViaValues).nullable(),
-      httpStatus: import_zod24.z.number().int().min(100).max(599).nullable(),
-      contentType: import_zod24.z.string().nullable(),
-      title: import_zod24.z.string().nullable(),
+      sourceKind: import_zod25.z.enum(SerpPageSnapshotSourceKindValues),
+      sourcePosition: import_zod25.z.number().int().min(1).nullable(),
+      status: import_zod25.z.enum(SerpPageFetchStatusValues),
+      fetchedVia: import_zod25.z.enum(SerpPageFetchedViaValues).nullable(),
+      httpStatus: import_zod25.z.number().int().min(100).max(599).nullable(),
+      contentType: import_zod25.z.string().nullable(),
+      title: import_zod25.z.string().nullable(),
       canonicalUrl: SerpIntelligencePublicHttpUrlSchema.nullable(),
-      metaDescription: import_zod24.z.string().nullable(),
-      headings: import_zod24.z.array(import_zod24.z.object({
-        level: import_zod24.z.number().int().min(1).max(6),
-        text: import_zod24.z.string()
+      metaDescription: import_zod25.z.string().nullable(),
+      headings: import_zod25.z.array(import_zod25.z.object({
+        level: import_zod25.z.number().int().min(1).max(6),
+        text: import_zod25.z.string()
       }).strict()).default([]),
-      artifact: import_zod24.z.object({
-        htmlBlobUrl: import_zod24.z.string().url().nullable(),
-        textBlobUrl: import_zod24.z.string().url().nullable(),
-        markdownBlobUrl: import_zod24.z.string().url().nullable(),
-        screenshotBlobUrl: import_zod24.z.string().url().nullable(),
-        contentSha256: import_zod24.z.string().nullable(),
-        capturedAt: import_zod24.z.string().nullable()
+      artifact: import_zod25.z.object({
+        htmlBlobUrl: import_zod25.z.string().url().nullable(),
+        textBlobUrl: import_zod25.z.string().url().nullable(),
+        markdownBlobUrl: import_zod25.z.string().url().nullable(),
+        screenshotBlobUrl: import_zod25.z.string().url().nullable(),
+        contentSha256: import_zod25.z.string().nullable(),
+        capturedAt: import_zod25.z.string().nullable()
       }).strict(),
-      error: import_zod24.z.object({
-        code: import_zod24.z.string(),
-        message: import_zod24.z.string()
+      error: import_zod25.z.object({
+        code: import_zod25.z.string(),
+        message: import_zod25.z.string()
       }).strict().nullable()
     }).strict();
-    SerpIntelligenceCaptureResponseSchema = import_zod24.z.object({
+    SerpIntelligenceCaptureResponseSchema = import_zod25.z.object({
       harvestResult: SerpIntelligenceHarvestResultSchema,
-      attempts: import_zod24.z.array(SerpIntelligenceCaptureAttemptSchema),
+      attempts: import_zod25.z.array(SerpIntelligenceCaptureAttemptSchema),
       locationEvidence: SerpIntelligenceLocationEvidenceSchema.nullable(),
-      pageSnapshotArtifacts: import_zod24.z.array(SerpPageSnapshotCaptureSchema),
-      billing: import_zod24.z.object({
-        creditsUsed: import_zod24.z.number().min(0).optional(),
-        requestId: import_zod24.z.string().optional(),
-        jobId: import_zod24.z.string().optional()
+      pageSnapshotArtifacts: import_zod25.z.array(SerpPageSnapshotCaptureSchema),
+      billing: import_zod25.z.object({
+        creditsUsed: import_zod25.z.number().min(0).optional(),
+        requestId: import_zod25.z.string().optional(),
+        jobId: import_zod25.z.string().optional()
       }).strict().optional()
     }).strict();
-    SerpIntelligencePageSnapshotsResponseSchema = import_zod24.z.object({
-      pageSnapshotArtifacts: import_zod24.z.array(SerpPageSnapshotCaptureSchema),
-      attempts: import_zod24.z.array(SerpIntelligenceCaptureAttemptSchema).default([])
+    SerpIntelligencePageSnapshotsResponseSchema = import_zod25.z.object({
+      pageSnapshotArtifacts: import_zod25.z.array(SerpPageSnapshotCaptureSchema),
+      attempts: import_zod25.z.array(SerpIntelligenceCaptureAttemptSchema).default([])
     }).strict();
   }
 });
@@ -18665,26 +19730,6 @@ async function enforceSerpIntelligenceRateLimit(c, userId) {
     { "Retry-After": String(result.resetSeconds) }
   );
 }
-async function enforceSerpIntelligenceConcurrency(user) {
-  const active = await countActiveJobsForUser(user.id);
-  const limit = 1 + (user.extra_concurrency_slots ?? 0);
-  if (active < limit) return null;
-  return new Response(
-    JSON.stringify(structuredError({
-      error_code: "concurrency_limit_exceeded",
-      error_type: "concurrency_limit",
-      message: `You have ${active} active job${active !== 1 ? "s" : ""}. Your account allows ${limit} concurrent job${limit !== 1 ? "s" : ""}.`,
-      retryable: true
-    })),
-    {
-      status: 429,
-      headers: {
-        "Content-Type": "application/json",
-        "Retry-After": "30"
-      }
-    }
-  );
-}
 function pageSnapshotTargetsFromBody(body) {
   return body.targets?.length ? body.targets : body.urls.map((url) => ({
     url,
@@ -18704,6 +19749,7 @@ var init_serp_intelligence_routes = __esm({
     init_api_auth();
     init_db();
     init_rates();
+    init_concurrency_gates();
     SERP_INTELLIGENCE_RATE_LIMIT = 60;
     SERP_INTELLIGENCE_RATE_WINDOW_SECONDS = 60;
     POST_CAPTURE_ROUTE_LABEL = "POST /capture";
@@ -18718,17 +19764,22 @@ var init_serp_intelligence_routes = __esm({
       if (!parsed.success) return c.json(formatZodError(parsed.error), 400);
       const limited = await enforceSerpIntelligenceRateLimit(c, user.id);
       if (limited) return limited;
-      const concurrencyLimited = await enforceSerpIntelligenceConcurrency(user);
-      if (concurrencyLimited) return concurrencyLimited;
+      const gate = await acquireConcurrencyGate(user, "serp_intelligence_capture", {
+        reuseLockId: c.req.header("x-mcp-scraper-concurrency-lock"),
+        metadata: { query: parsed.data.query, location: parsed.data.location }
+      });
+      if (!gate.ok) return c.json(concurrencyLimitExceededResponse(gate), 429, { "Retry-After": String(gate.retryAfterSeconds) });
       const cost = MC_COSTS.serp;
-      const { ok, balance_mc } = await debitMc(
-        user.id,
-        cost,
-        LedgerOperation.SERP,
-        parsed.data.query
-      );
-      if (!ok) return c.json(insufficientBalanceResponse(balance_mc, cost), 402);
+      let debited = false;
       try {
+        const { ok, balance_mc } = await debitMc(
+          user.id,
+          cost,
+          LedgerOperation.SERP,
+          parsed.data.query
+        );
+        if (!ok) return c.json(insufficientBalanceResponse(balance_mc, cost), 402);
+        debited = true;
         const result = await captureSerpIntelligenceSnapshot(parsed.data, {
           kernelApiKey: browserServiceApiKey(),
           kernelProxyId: browserServiceProxyId(),
@@ -18746,7 +19797,7 @@ var init_serp_intelligence_routes = __esm({
         });
         return c.json(result);
       } catch (error) {
-        await creditMc(user.id, cost, LedgerOperation.REFUND, "failed serp intelligence capture");
+        if (debited) await creditMc(user.id, cost, LedgerOperation.REFUND, "failed serp intelligence capture");
         const body = error instanceof SerpIntelligenceCaptureError ? error.toJSON() : structuredError({
           error_code: "capture_failed",
           error_type: "capture_error",
@@ -18763,6 +19814,8 @@ var init_serp_intelligence_routes = __esm({
         });
         const status = error instanceof SerpIntelligenceCaptureError ? error.httpStatus : 500;
         return c.json(body, status);
+      } finally {
+        await releaseConcurrencyGate(gate.lockId);
       }
     });
     serpIntelligenceApp.post("/page-snapshots", async (c) => {
@@ -18773,18 +19826,23 @@ var init_serp_intelligence_routes = __esm({
       if (!parsed.success) return c.json(formatZodError(parsed.error), 400);
       const limited = await enforceSerpIntelligenceRateLimit(c, user.id);
       if (limited) return limited;
-      const concurrencyLimited = await enforceSerpIntelligenceConcurrency(user);
-      if (concurrencyLimited) return concurrencyLimited;
       const targets = pageSnapshotTargetsFromBody(parsed.data);
+      const gate = await acquireConcurrencyGate(user, "serp_intelligence_page_snapshots", {
+        reuseLockId: c.req.header("x-mcp-scraper-concurrency-lock"),
+        metadata: { targets: targets.length }
+      });
+      if (!gate.ok) return c.json(concurrencyLimitExceededResponse(gate), 429, { "Retry-After": String(gate.retryAfterSeconds) });
       const cost = targets.length * MC_COSTS.page_scrape;
-      const { ok, balance_mc } = await debitMc(
-        user.id,
-        cost,
-        LedgerOperation.EXTRACT_URL,
-        `serp intelligence page snapshots: ${targets.length}`
-      );
-      if (!ok) return c.json(insufficientBalanceResponse(balance_mc, cost), 402);
+      let debited = false;
       try {
+        const { ok, balance_mc } = await debitMc(
+          user.id,
+          cost,
+          LedgerOperation.EXTRACT_URL,
+          `serp intelligence page snapshots: ${targets.length}`
+        );
+        if (!ok) return c.json(insufficientBalanceResponse(balance_mc, cost), 402);
+        debited = true;
         const result = await capturePageSnapshots(targets, {
           kernelApiKey: browserServiceApiKey(),
           timeoutMs: parsed.data.timeoutMs,
@@ -18801,7 +19859,7 @@ var init_serp_intelligence_routes = __esm({
         });
         return c.json(result);
       } catch (error) {
-        await creditMc(user.id, cost, LedgerOperation.REFUND, "failed serp intelligence page snapshots");
+        if (debited) await creditMc(user.id, cost, LedgerOperation.REFUND, "failed serp intelligence page snapshots");
         const body = structuredError({
           error_code: "page_snapshot_failed",
           error_type: "capture_error",
@@ -18816,6 +19874,8 @@ var init_serp_intelligence_routes = __esm({
           error: body.message
         });
         return c.json(body, 500);
+      } finally {
+        await releaseConcurrencyGate(gate.lockId);
       }
     });
   }
@@ -18826,133 +19886,133 @@ var PACKAGE_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    PACKAGE_VERSION = "0.2.12";
+    PACKAGE_VERSION = "0.2.14";
   }
 });
 
 // src/mcp/mcp-tool-schemas.ts
-var import_zod25, HarvestPaaInputSchema, ExtractUrlInputSchema, MapSiteUrlsInputSchema, ExtractSiteInputSchema, YoutubeHarvestInputSchema, YoutubeTranscribeInputSchema, FacebookPageIntelInputSchema, FacebookAdSearchInputSchema, FacebookAdTranscribeInputSchema, MapsPlaceIntelInputSchema, MapsSearchInputSchema, DirectoryWorkflowInputSchema, RankTrackerModeSchema, RankTrackerBlueprintInputSchema, NullableString, MapsSearchAttemptOutput, MapsSearchOutputSchema, DirectoryMapsBusinessOutput, DirectoryWorkflowOutputSchema, RankTrackerToolPlanOutput, RankTrackerTableOutput, RankTrackerCronJobOutput, RankTrackerBlueprintOutputSchema, OrganicResultOutput, AiOverviewOutput, EntityIdsOutput, HarvestPaaOutputSchema, SearchSerpOutputSchema, ExtractUrlOutputSchema, ExtractSiteOutputSchema, MapsPlaceIntelOutputSchema, CreditsInfoOutputSchema, MapSiteUrlsOutputSchema, YoutubeHarvestOutputSchema, FacebookAdSearchOutputSchema, FacebookPageIntelOutputSchema, CreditsInfoInputSchema, SearchSerpInputSchema, CaptureSerpSnapshotInputSchema, ScreenshotInputSchema, CaptureSerpPageSnapshotsInputSchema;
+var import_zod26, HarvestPaaInputSchema, ExtractUrlInputSchema, MapSiteUrlsInputSchema, ExtractSiteInputSchema, YoutubeHarvestInputSchema, YoutubeTranscribeInputSchema, FacebookPageIntelInputSchema, FacebookAdSearchInputSchema, FacebookAdTranscribeInputSchema, MapsPlaceIntelInputSchema, MapsSearchInputSchema, DirectoryWorkflowInputSchema, RankTrackerModeSchema, RankTrackerBlueprintInputSchema, NullableString, MapsSearchAttemptOutput, MapsSearchOutputSchema, DirectoryMapsBusinessOutput, DirectoryWorkflowOutputSchema, RankTrackerToolPlanOutput, RankTrackerTableOutput, RankTrackerCronJobOutput, RankTrackerBlueprintOutputSchema, OrganicResultOutput, AiOverviewOutput, EntityIdsOutput, HarvestPaaOutputSchema, SearchSerpOutputSchema, ExtractUrlOutputSchema, ExtractSiteOutputSchema, MapsPlaceIntelOutputSchema, CreditsInfoOutputSchema, MapSiteUrlsOutputSchema, YoutubeHarvestOutputSchema, FacebookAdSearchOutputSchema, FacebookPageIntelOutputSchema, CreditsInfoInputSchema, SearchSerpInputSchema, CaptureSerpSnapshotInputSchema, ScreenshotInputSchema, CaptureSerpPageSnapshotsInputSchema;
 var init_mcp_tool_schemas = __esm({
   "src/mcp/mcp-tool-schemas.ts"() {
     "use strict";
-    import_zod25 = require("zod");
+    import_zod26 = require("zod");
     HarvestPaaInputSchema = {
-      query: import_zod25.z.string().min(1).describe('Core search topic only. If the user says "best hvac company in Denver CO", use query="best hvac company" and location="Denver, CO". Do not include the location in query when it can be separated.'),
-      location: import_zod25.z.string().optional().describe('City, region, or country for geo-targeted results, inferred from the user request when present, e.g. "Denver, CO", "Tokyo, Japan", "London, UK".'),
-      maxQuestions: import_zod25.z.number().int().min(1).max(200).default(30).describe("Number of PAA questions to extract. Default 30. Maximum 200. Use 10 for quick probes, 30 for normal research, 100-200 when the user asks for everything/full/deep research. Larger harvests get a longer server time budget (151-200 questions \u2192 up to 280s). Credits are charged by extracted question; unused request hold is refunded."),
-      gl: import_zod25.z.string().length(2).default("us").describe("Google country code inferred from location or user language. Examples: United States us, United Kingdom gb, Japan jp, Canada ca, Australia au."),
-      hl: import_zod25.z.string().default("en").describe("Google interface/content language inferred from the user request. Use en unless the user asks for another language or locale."),
-      device: import_zod25.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use desktop by default; use mobile only when the user asks for mobile rankings."),
-      proxyMode: import_zod25.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default for US city/state SERPs; it creates a fresh residential proxy ID per attempt. If Google shows a CAPTCHA/challenge, browser-service sessions briefly wait for the automatic solver first, then retry with a fresh proxy/session if the challenge does not clear. Also retries proxy tunnel failure and wrong-location evidence before returning. Use configured only for the static configured proxy. Use none only for direct-network debugging."),
-      proxyZip: import_zod25.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use when the user gives a specific ZIP or when city-center targeting needs to be forced. With proxyMode location this ZIP is used for each fresh proxy attempt."),
-      debug: import_zod25.z.boolean().default(false).describe("Include sanitized browser/session/location diagnostics in the response. Use true when debugging localization, CAPTCHA, or proxy behavior.")
+      query: import_zod26.z.string().min(1).describe('Core search topic only. If the user says "best hvac company in Denver CO", use query="best hvac company" and location="Denver, CO". Do not include the location in query when it can be separated.'),
+      location: import_zod26.z.string().optional().describe('City, region, or country for geo-targeted results, inferred from the user request when present, e.g. "Denver, CO", "Tokyo, Japan", "London, UK".'),
+      maxQuestions: import_zod26.z.number().int().min(1).max(200).default(30).describe("Number of PAA questions to extract. Default 30. Maximum 200. Use 10 for quick probes, 30 for normal research, 100-200 when the user asks for everything/full/deep research. Larger harvests get a longer server time budget (151-200 questions \u2192 up to 280s). Credits are charged by extracted question; unused request hold is refunded."),
+      gl: import_zod26.z.string().length(2).default("us").describe("Google country code inferred from location or user language. Examples: United States us, United Kingdom gb, Japan jp, Canada ca, Australia au."),
+      hl: import_zod26.z.string().default("en").describe("Google interface/content language inferred from the user request. Use en unless the user asks for another language or locale."),
+      device: import_zod26.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use desktop by default; use mobile only when the user asks for mobile rankings."),
+      proxyMode: import_zod26.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default for US city/state SERPs; it creates a fresh residential proxy ID per attempt. If Google shows a CAPTCHA/challenge, browser-service sessions briefly wait for the automatic solver first, then retry with a fresh proxy/session if the challenge does not clear. Also retries proxy tunnel failure and wrong-location evidence before returning. Use configured only for the static configured proxy. Use none only for direct-network debugging."),
+      proxyZip: import_zod26.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use when the user gives a specific ZIP or when city-center targeting needs to be forced. With proxyMode location this ZIP is used for each fresh proxy attempt."),
+      debug: import_zod26.z.boolean().default(false).describe("Include sanitized browser/session/location diagnostics in the response. Use true when debugging localization, CAPTCHA, or proxy behavior.")
     };
     ExtractUrlInputSchema = {
-      url: import_zod25.z.string().url().describe("Public http/https URL to extract. Use this when the user provides one specific page URL."),
-      screenshot: import_zod25.z.boolean().default(false).describe("Also capture a full-page screenshot of the URL. Saved to ~/Downloads/mcp-scraper/screenshots/ and returned inline. Use when the user asks to see or capture the page visually."),
-      screenshotDevice: import_zod25.z.enum(["desktop", "mobile"]).default("desktop").describe("Viewport for screenshot. desktop = 1440\xD7900. mobile = 390\xD7844. Default desktop."),
-      extractBranding: import_zod25.z.boolean().default(false).describe("Extract brand colors, fonts, logo, and favicon using a rendered browser session. Returns colorScheme (light/dark), colors (primary/accent/background/text/heading as hex), fonts (heading/body family names), and assets (logo URL, favicon URL). Use when the user asks about brand colors, site theme, or brand assets."),
-      downloadMedia: import_zod25.z.boolean().default(false).describe("Extract and download all page media (images, video, audio) to ~/Downloads/mcp-scraper/media/. Ad networks, tracking pixels, and noise URLs are filtered automatically. Use when the user asks to download or harvest assets from a page."),
-      mediaTypes: import_zod25.z.array(import_zod25.z.enum(["image", "video", "audio"])).default(["image", "video", "audio"]).describe("Which media types to download. Default all three."),
-      allowLocal: import_zod25.z.boolean().default(false).describe("Allow localhost and private-network URLs. For local development only.")
+      url: import_zod26.z.string().url().describe("Public http/https URL to extract. Use this when the user provides one specific page URL."),
+      screenshot: import_zod26.z.boolean().default(false).describe("Also capture a full-page screenshot of the URL. Saved to ~/Downloads/mcp-scraper/screenshots/ and returned inline. Use when the user asks to see or capture the page visually."),
+      screenshotDevice: import_zod26.z.enum(["desktop", "mobile"]).default("desktop").describe("Viewport for screenshot. desktop = 1440\xD7900. mobile = 390\xD7844. Default desktop."),
+      extractBranding: import_zod26.z.boolean().default(false).describe("Extract brand colors, fonts, logo, and favicon using a rendered browser session. Returns colorScheme (light/dark), colors (primary/accent/background/text/heading as hex), fonts (heading/body family names), and assets (logo URL, favicon URL). Use when the user asks about brand colors, site theme, or brand assets."),
+      downloadMedia: import_zod26.z.boolean().default(false).describe("Extract and download all page media (images, video, audio) to ~/Downloads/mcp-scraper/media/. Ad networks, tracking pixels, and noise URLs are filtered automatically. Use when the user asks to download or harvest assets from a page."),
+      mediaTypes: import_zod26.z.array(import_zod26.z.enum(["image", "video", "audio"])).default(["image", "video", "audio"]).describe("Which media types to download. Default all three."),
+      allowLocal: import_zod26.z.boolean().default(false).describe("Allow localhost and private-network URLs. For local development only.")
     };
     MapSiteUrlsInputSchema = {
-      url: import_zod25.z.string().url().describe("Public website URL or domain to crawl for internal URLs. Use before extract_site when the user asks to audit/map/crawl a site."),
-      maxUrls: import_zod25.z.number().int().min(1).max(500).optional().describe("Maximum URLs to discover. Use 100 for normal maps, higher when the user asks for a full inventory.")
+      url: import_zod26.z.string().url().describe("Public website URL or domain to crawl for internal URLs. Use before extract_site when the user asks to audit/map/crawl a site."),
+      maxUrls: import_zod26.z.number().int().min(1).max(500).optional().describe("Maximum URLs to discover. Use 100 for normal maps, higher when the user asks for a full inventory.")
     };
     ExtractSiteInputSchema = {
-      url: import_zod25.z.string().url().describe("Public website URL or domain to extract across multiple pages. Use when the user asks for a site audit, website crawl, or full-site content/schema extraction."),
-      maxPages: import_zod25.z.number().int().min(1).max(50).optional().describe("Maximum pages to extract. Use 50 when the user asks for full results or a complete crawl within MCP limits.")
+      url: import_zod26.z.string().url().describe("Public website URL or domain to extract across multiple pages. Use when the user asks for a site audit, website crawl, or full-site content/schema extraction."),
+      maxPages: import_zod26.z.number().int().min(1).max(50).optional().describe("Maximum pages to extract. Use 50 when the user asks for full results or a complete crawl within MCP limits.")
     };
     YoutubeHarvestInputSchema = {
-      mode: import_zod25.z.enum(["search", "channel"]).describe("Use search for topic/keyword requests. Use channel when the user provides @handle, channel ID, or channel URL."),
-      query: import_zod25.z.string().optional().describe("Required when mode is search. The YouTube search topic in the user\u2019s words."),
-      channelHandle: import_zod25.z.string().optional().describe("YouTube channel handle, channel ID, or URL. Examples: @mkbhd, UC..., https://youtube.com/@mkbhd."),
-      maxVideos: import_zod25.z.number().int().min(1).max(500).default(50).describe("Number of videos to return. Default 50. Increase when user asks for full channel/history.")
+      mode: import_zod26.z.enum(["search", "channel"]).describe("Use search for topic/keyword requests. Use channel when the user provides @handle, channel ID, or channel URL."),
+      query: import_zod26.z.string().optional().describe("Required when mode is search. The YouTube search topic in the user\u2019s words."),
+      channelHandle: import_zod26.z.string().optional().describe("YouTube channel handle, channel ID, or URL. Examples: @mkbhd, UC..., https://youtube.com/@mkbhd."),
+      maxVideos: import_zod26.z.number().int().min(1).max(500).default(50).describe("Number of videos to return. Default 50. Increase when user asks for full channel/history.")
     };
     YoutubeTranscribeInputSchema = {
-      videoId: import_zod25.z.string().min(1).describe("YouTube video ID, e.g. dQw4w9WgXcQ")
+      videoId: import_zod26.z.string().min(1).describe("YouTube video ID, e.g. dQw4w9WgXcQ")
     };
     FacebookPageIntelInputSchema = {
-      pageId: import_zod25.z.string().optional(),
-      libraryId: import_zod25.z.string().optional(),
-      query: import_zod25.z.string().optional().describe("Advertiser or brand name when pageId/libraryId is not known. One of pageId, libraryId, or query is required."),
-      maxAds: import_zod25.z.number().int().min(1).max(200).default(50),
-      country: import_zod25.z.string().length(2).default("US")
+      pageId: import_zod26.z.string().optional(),
+      libraryId: import_zod26.z.string().optional(),
+      query: import_zod26.z.string().optional().describe("Advertiser or brand name when pageId/libraryId is not known. One of pageId, libraryId, or query is required."),
+      maxAds: import_zod26.z.number().int().min(1).max(200).default(50),
+      country: import_zod26.z.string().length(2).default("US")
     };
     FacebookAdSearchInputSchema = {
-      query: import_zod25.z.string().min(1).describe("Advertiser, brand, competitor, niche, or keyword to search in Facebook Ad Library."),
-      country: import_zod25.z.string().length(2).default("US"),
-      maxResults: import_zod25.z.number().int().min(1).max(20).default(10)
+      query: import_zod26.z.string().min(1).describe("Advertiser, brand, competitor, niche, or keyword to search in Facebook Ad Library."),
+      country: import_zod26.z.string().length(2).default("US"),
+      maxResults: import_zod26.z.number().int().min(1).max(20).default(10)
     };
     FacebookAdTranscribeInputSchema = {
-      videoUrl: import_zod25.z.string().url().describe("Facebook CDN video URL from a facebook_page_intel result")
+      videoUrl: import_zod26.z.string().url().describe("Facebook CDN video URL from a facebook_page_intel result")
     };
     MapsPlaceIntelInputSchema = {
-      businessName: import_zod25.z.string().min(1).describe('Business name only. If user says "Elite Roofing Denver CO", use businessName="Elite Roofing" and location="Denver, CO".'),
-      location: import_zod25.z.string().min(1).describe('City/region/country where the business should be searched, e.g. "Denver, CO". Infer from the user request when possible.'),
-      gl: import_zod25.z.string().length(2).default("us").describe("Google country code inferred from location."),
-      hl: import_zod25.z.string().length(2).default("en").describe("Language inferred from user request."),
-      includeReviews: import_zod25.z.boolean().default(false).describe("Whether to fetch individual review cards"),
-      maxReviews: import_zod25.z.number().int().min(1).max(500).default(50).describe("Max review cards to return (requires includeReviews: true)")
+      businessName: import_zod26.z.string().min(1).describe('Business name only. If user says "Elite Roofing Denver CO", use businessName="Elite Roofing" and location="Denver, CO".'),
+      location: import_zod26.z.string().min(1).describe('City/region/country where the business should be searched, e.g. "Denver, CO". Infer from the user request when possible.'),
+      gl: import_zod26.z.string().length(2).default("us").describe("Google country code inferred from location."),
+      hl: import_zod26.z.string().length(2).default("en").describe("Language inferred from user request."),
+      includeReviews: import_zod26.z.boolean().default(false).describe("Whether to fetch individual review cards"),
+      maxReviews: import_zod26.z.number().int().min(1).max(500).default(50).describe("Max review cards to return (requires includeReviews: true)")
     };
     MapsSearchInputSchema = {
-      query: import_zod25.z.string().min(1).describe('Business category, niche, keyword, or search term. If the user says "roofers in Denver CO", use query="roofers" and location="Denver, CO". Do not put the location here when it can be separated.'),
-      location: import_zod25.z.string().optional().describe('City, region, country, or service area for the Maps search, e.g. "Denver, CO". Infer from the user request when present.'),
-      gl: import_zod25.z.string().length(2).default("us").describe("Google country code inferred from location."),
-      hl: import_zod25.z.string().length(2).default("en").describe("Language inferred from user request."),
-      maxResults: import_zod25.z.number().int().min(1).max(50).default(10).describe("Number of Google Maps business/profile candidates to return. Default 10. Maximum 50. Use 10 unless the user asks for more."),
-      proxyMode: import_zod25.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default for US city/state Maps searches; retryable failures create a new residential proxy ID and new browser session for up to 5 attempts. Use configured for the server proxy ID, and none only for local direct-network debugging."),
-      proxyZip: import_zod25.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use when the user gives a specific ZIP or city-center ZIP."),
-      debug: import_zod25.z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics when debugging Maps localization, CAPTCHA, or proxy behavior.")
+      query: import_zod26.z.string().min(1).describe('Business category, niche, keyword, or search term. If the user says "roofers in Denver CO", use query="roofers" and location="Denver, CO". Do not put the location here when it can be separated.'),
+      location: import_zod26.z.string().optional().describe('City, region, country, or service area for the Maps search, e.g. "Denver, CO". Infer from the user request when present.'),
+      gl: import_zod26.z.string().length(2).default("us").describe("Google country code inferred from location."),
+      hl: import_zod26.z.string().length(2).default("en").describe("Language inferred from user request."),
+      maxResults: import_zod26.z.number().int().min(1).max(50).default(10).describe("Number of Google Maps business/profile candidates to return. Default 10. Maximum 50. Use 10 unless the user asks for more."),
+      proxyMode: import_zod26.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default for US city/state Maps searches; retryable failures create a new residential proxy ID and new browser session for up to 5 attempts. Use configured for the server proxy ID, and none only for local direct-network debugging."),
+      proxyZip: import_zod26.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use when the user gives a specific ZIP or city-center ZIP."),
+      debug: import_zod26.z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics when debugging Maps localization, CAPTCHA, or proxy behavior.")
     };
     DirectoryWorkflowInputSchema = {
-      query: import_zod25.z.string().min(1).describe("Business category, niche, or keyword to search on Google Maps for every selected market, e.g. roofers, dentists, med spas. Do not include the city here."),
-      state: import_zod25.z.string().min(2).default("TN").describe("US state abbreviation or state name used to select Census places, e.g. TN or Tennessee."),
-      minPopulation: import_zod25.z.number().int().min(0).default(1e5).describe('Minimum Census place population for market selection. Use 100000 for "cities above 100k population".'),
-      populationYear: import_zod25.z.number().int().min(2020).max(2025).default(2025).describe("Census population estimate year from the 2020-2025 Population Estimates Program city/place dataset."),
-      maxCities: import_zod25.z.number().int().min(1).max(100).default(25).describe("Maximum number of markets to process after sorting by population descending."),
-      maxResultsPerCity: import_zod25.z.number().int().min(1).max(50).default(50).describe("Google Maps business/profile candidates to collect for each city. Maximum 50."),
-      concurrency: import_zod25.z.number().int().min(1).max(5).default(5).describe("How many city Maps searches to run in parallel. Use 5 for broad directory batches unless debugging."),
-      includeZipGroups: import_zod25.z.boolean().default(true).describe("Attach ZIP groups from a configured US ZIPS CSV when available. Set MCP_SCRAPER_USZIPS_CSV_PATH on the API server or pass usZipsCsvPath in local/test mode."),
-      usZipsCsvPath: import_zod25.z.string().optional().describe("Local/test-only path to a US ZIPS CSV with state_abbr, zipcode, county, city columns, such as Lead Magician tools/analytics/data/uszips.csv. Deployed APIs should use MCP_SCRAPER_USZIPS_CSV_PATH instead."),
-      saveCsv: import_zod25.z.boolean().default(true).describe("Save a directory-ready CSV to the MCP Scraper output directory and return its path. CSV rows include source_location, result_position, business_name, review_stars, review_count, category, address, phone, hours_status, website_url, directions_url, place_url, CID fields, population, and ZIP groups."),
-      proxyMode: import_zod25.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode for every city Maps search. Use location by default for US city/state batches; retryable failures create a new residential proxy ID and new browser session for up to 5 attempts per city. Use configured for the server proxy ID, and none only for local direct-network debugging."),
-      proxyZip: import_zod25.z.string().regex(/^\d{5}$/).optional().describe("Optional ZIP override for proxy targeting. Normally omit it so each city can use its Lead Magician ZIP group or city/state location."),
-      debug: import_zod25.z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics in each Maps browser session when supported.")
+      query: import_zod26.z.string().min(1).describe("Business category, niche, or keyword to search on Google Maps for every selected market, e.g. roofers, dentists, med spas. Do not include the city here."),
+      state: import_zod26.z.string().min(2).default("TN").describe("US state abbreviation or state name used to select Census places, e.g. TN or Tennessee."),
+      minPopulation: import_zod26.z.number().int().min(0).default(1e5).describe('Minimum Census place population for market selection. Use 100000 for "cities above 100k population".'),
+      populationYear: import_zod26.z.number().int().min(2020).max(2025).default(2025).describe("Census population estimate year from the 2020-2025 Population Estimates Program city/place dataset."),
+      maxCities: import_zod26.z.number().int().min(1).max(100).default(25).describe("Maximum number of markets to process after sorting by population descending."),
+      maxResultsPerCity: import_zod26.z.number().int().min(1).max(50).default(50).describe("Google Maps business/profile candidates to collect for each city. Maximum 50."),
+      concurrency: import_zod26.z.number().int().min(1).max(5).default(5).describe("How many city Maps searches to run in parallel. Use 5 for broad directory batches unless debugging."),
+      includeZipGroups: import_zod26.z.boolean().default(true).describe("Attach ZIP groups from a configured US ZIPS CSV when available. Set MCP_SCRAPER_USZIPS_CSV_PATH on the API server or pass usZipsCsvPath in local/test mode."),
+      usZipsCsvPath: import_zod26.z.string().optional().describe("Local/test-only path to a US ZIPS CSV with state_abbr, zipcode, county, city columns, such as Lead Magician tools/analytics/data/uszips.csv. Deployed APIs should use MCP_SCRAPER_USZIPS_CSV_PATH instead."),
+      saveCsv: import_zod26.z.boolean().default(true).describe("Save a directory-ready CSV to the MCP Scraper output directory and return its path. CSV rows include source_location, result_position, business_name, review_stars, review_count, category, address, phone, hours_status, website_url, directions_url, place_url, CID fields, population, and ZIP groups."),
+      proxyMode: import_zod26.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode for every city Maps search. Use location by default for US city/state batches; retryable failures create a new residential proxy ID and new browser session for up to 5 attempts per city. Use configured for the server proxy ID, and none only for local direct-network debugging."),
+      proxyZip: import_zod26.z.string().regex(/^\d{5}$/).optional().describe("Optional ZIP override for proxy targeting. Normally omit it so each city can use its Lead Magician ZIP group or city/state location."),
+      debug: import_zod26.z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics in each Maps browser session when supported.")
     };
-    RankTrackerModeSchema = import_zod25.z.enum(["maps", "organic", "ai_overview", "paa"]);
+    RankTrackerModeSchema = import_zod26.z.enum(["maps", "organic", "ai_overview", "paa"]);
     RankTrackerBlueprintInputSchema = {
-      projectName: import_zod25.z.string().min(1).optional().describe("Optional name for the rank tracker project, client, or campaign."),
-      targetDomain: import_zod25.z.string().min(1).optional().describe("Primary domain to track in organic results, AI Overview citations, and PAA sources, e.g. example.com."),
-      targetBusinessName: import_zod25.z.string().min(1).optional().describe("Primary Google Business Profile or brand/business name to match in Maps results. Required for reliable Maps rank tracking."),
-      trackingModes: import_zod25.z.array(RankTrackerModeSchema).min(1).max(4).default(["maps", "organic", "ai_overview", "paa"]).describe("Rank tracker surfaces to build. maps uses directory_workflow/maps_search. organic uses search_serp. ai_overview uses search_serp/harvest_paa. paa uses harvest_paa source presence."),
-      keywords: import_zod25.z.array(import_zod25.z.string().min(1)).max(200).default([]).describe("Seed keywords or service queries to track. Leave empty when the downstream AI should create the keyword table from user input."),
-      locations: import_zod25.z.array(import_zod25.z.string().min(1)).max(100).default([]).describe("Markets, cities, ZIPs, or service areas to track. Use city/state strings like Denver, CO for localized SERP and Maps checks."),
-      competitors: import_zod25.z.array(import_zod25.z.string().min(1)).max(100).default([]).describe("Optional competitor domains or business names to persist as comparison targets."),
-      database: import_zod25.z.enum(["postgres", "neon", "supabase", "sqlite", "mysql"]).default("postgres").describe("Database family the downstream AI should target when generating migrations."),
-      scheduleCadence: import_zod25.z.enum(["daily", "weekly", "monthly", "custom"]).default("weekly").describe("Default recurring rank check cadence for the generated cron/heartbeat plan."),
-      customCron: import_zod25.z.string().min(1).optional().describe("Cron expression to use when scheduleCadence is custom."),
-      timezone: import_zod25.z.string().min(1).default("UTC").describe("IANA timezone for scheduled rank checks, e.g. America/Denver."),
-      includeCron: import_zod25.z.boolean().default(true).describe("Include a cron or heartbeat worker plan. Keep true for production rank trackers."),
-      includeDashboard: import_zod25.z.boolean().default(true).describe("Include dashboard/reporting requirements in the generated prompt."),
-      includeAlerts: import_zod25.z.boolean().default(true).describe("Include alert rules for rank movement and SERP feature gains/losses."),
-      notes: import_zod25.z.string().max(4e3).optional().describe("Extra product, client, stack, or hosting requirements to include in the implementation prompt.")
+      projectName: import_zod26.z.string().min(1).optional().describe("Optional name for the rank tracker project, client, or campaign."),
+      targetDomain: import_zod26.z.string().min(1).optional().describe("Primary domain to track in organic results, AI Overview citations, and PAA sources, e.g. example.com."),
+      targetBusinessName: import_zod26.z.string().min(1).optional().describe("Primary Google Business Profile or brand/business name to match in Maps results. Required for reliable Maps rank tracking."),
+      trackingModes: import_zod26.z.array(RankTrackerModeSchema).min(1).max(4).default(["maps", "organic", "ai_overview", "paa"]).describe("Rank tracker surfaces to build. maps uses directory_workflow/maps_search. organic uses search_serp. ai_overview uses search_serp/harvest_paa. paa uses harvest_paa source presence."),
+      keywords: import_zod26.z.array(import_zod26.z.string().min(1)).max(200).default([]).describe("Seed keywords or service queries to track. Leave empty when the downstream AI should create the keyword table from user input."),
+      locations: import_zod26.z.array(import_zod26.z.string().min(1)).max(100).default([]).describe("Markets, cities, ZIPs, or service areas to track. Use city/state strings like Denver, CO for localized SERP and Maps checks."),
+      competitors: import_zod26.z.array(import_zod26.z.string().min(1)).max(100).default([]).describe("Optional competitor domains or business names to persist as comparison targets."),
+      database: import_zod26.z.enum(["postgres", "neon", "supabase", "sqlite", "mysql"]).default("postgres").describe("Database family the downstream AI should target when generating migrations."),
+      scheduleCadence: import_zod26.z.enum(["daily", "weekly", "monthly", "custom"]).default("weekly").describe("Default recurring rank check cadence for the generated cron/heartbeat plan."),
+      customCron: import_zod26.z.string().min(1).optional().describe("Cron expression to use when scheduleCadence is custom."),
+      timezone: import_zod26.z.string().min(1).default("UTC").describe("IANA timezone for scheduled rank checks, e.g. America/Denver."),
+      includeCron: import_zod26.z.boolean().default(true).describe("Include a cron or heartbeat worker plan. Keep true for production rank trackers."),
+      includeDashboard: import_zod26.z.boolean().default(true).describe("Include dashboard/reporting requirements in the generated prompt."),
+      includeAlerts: import_zod26.z.boolean().default(true).describe("Include alert rules for rank movement and SERP feature gains/losses."),
+      notes: import_zod26.z.string().max(4e3).optional().describe("Extra product, client, stack, or hosting requirements to include in the implementation prompt.")
     };
-    NullableString = import_zod25.z.string().nullable();
-    MapsSearchAttemptOutput = import_zod25.z.object({
-      attemptNumber: import_zod25.z.number().int().min(1),
-      maxAttempts: import_zod25.z.number().int().min(1),
-      status: import_zod25.z.enum(["ok", "failed"]),
-      outcome: import_zod25.z.string(),
-      willRetry: import_zod25.z.boolean(),
-      durationMs: import_zod25.z.number().int().min(0),
-      resultCount: import_zod25.z.number().int().min(0),
+    NullableString = import_zod26.z.string().nullable();
+    MapsSearchAttemptOutput = import_zod26.z.object({
+      attemptNumber: import_zod26.z.number().int().min(1),
+      maxAttempts: import_zod26.z.number().int().min(1),
+      status: import_zod26.z.enum(["ok", "failed"]),
+      outcome: import_zod26.z.string(),
+      willRetry: import_zod26.z.boolean(),
+      durationMs: import_zod26.z.number().int().min(0),
+      resultCount: import_zod26.z.number().int().min(0),
       error: NullableString,
-      proxyMode: import_zod25.z.enum(["location", "configured", "none"]),
-      proxyResolutionSource: import_zod25.z.enum(["disabled", "location_reused", "location_created", "configured_fallback", "unavailable"]).nullable(),
+      proxyMode: import_zod26.z.enum(["location", "configured", "none"]),
+      proxyResolutionSource: import_zod26.z.enum(["disabled", "location_reused", "location_created", "configured_fallback", "unavailable"]).nullable(),
       proxyIdSuffix: NullableString,
-      proxyTargetLevel: import_zod25.z.enum(["zip", "city", "state"]).nullable(),
+      proxyTargetLevel: import_zod26.z.enum(["zip", "city", "state"]).nullable(),
       proxyTargetLocation: NullableString,
       proxyTargetZip: NullableString,
       browserSessionIdSuffix: NullableString,
@@ -18961,17 +20021,17 @@ var init_mcp_tool_schemas = __esm({
       observedRegion: NullableString
     });
     MapsSearchOutputSchema = {
-      query: import_zod25.z.string(),
-      location: import_zod25.z.string().nullable(),
-      searchQuery: import_zod25.z.string(),
-      searchUrl: import_zod25.z.string().url(),
-      extractedAt: import_zod25.z.string(),
-      requestedMaxResults: import_zod25.z.number().int().min(1).max(50),
-      resultCount: import_zod25.z.number().int().min(0).max(50),
-      results: import_zod25.z.array(import_zod25.z.object({
-        position: import_zod25.z.number().int().min(1),
-        name: import_zod25.z.string(),
-        placeUrl: import_zod25.z.string().url(),
+      query: import_zod26.z.string(),
+      location: import_zod26.z.string().nullable(),
+      searchQuery: import_zod26.z.string(),
+      searchUrl: import_zod26.z.string().url(),
+      extractedAt: import_zod26.z.string(),
+      requestedMaxResults: import_zod26.z.number().int().min(1).max(50),
+      resultCount: import_zod26.z.number().int().min(0).max(50),
+      results: import_zod26.z.array(import_zod26.z.object({
+        position: import_zod26.z.number().int().min(1),
+        name: import_zod26.z.string(),
+        placeUrl: import_zod26.z.string().url(),
         cid: NullableString,
         cidDecimal: NullableString,
         rating: NullableString,
@@ -18982,15 +20042,15 @@ var init_mcp_tool_schemas = __esm({
         hoursStatus: NullableString,
         websiteUrl: NullableString,
         directionsUrl: NullableString,
-        metadata: import_zod25.z.array(import_zod25.z.string())
+        metadata: import_zod26.z.array(import_zod26.z.string())
       })),
-      attempts: import_zod25.z.array(MapsSearchAttemptOutput),
-      durationMs: import_zod25.z.number().int().min(0)
+      attempts: import_zod26.z.array(MapsSearchAttemptOutput),
+      durationMs: import_zod26.z.number().int().min(0)
     };
-    DirectoryMapsBusinessOutput = import_zod25.z.object({
-      position: import_zod25.z.number().int().min(1),
-      name: import_zod25.z.string(),
-      placeUrl: import_zod25.z.string().url(),
+    DirectoryMapsBusinessOutput = import_zod26.z.object({
+      position: import_zod26.z.number().int().min(1),
+      name: import_zod26.z.string(),
+      placeUrl: import_zod26.z.string().url(),
       cid: NullableString,
       cidDecimal: NullableString,
       rating: NullableString,
@@ -19001,113 +20061,113 @@ var init_mcp_tool_schemas = __esm({
       hoursStatus: NullableString,
       websiteUrl: NullableString,
       directionsUrl: NullableString,
-      metadata: import_zod25.z.array(import_zod25.z.string())
+      metadata: import_zod26.z.array(import_zod26.z.string())
     });
     DirectoryWorkflowOutputSchema = {
-      query: import_zod25.z.string(),
-      state: import_zod25.z.string(),
-      minPopulation: import_zod25.z.number().int().min(0),
-      populationYear: import_zod25.z.number().int().min(2020).max(2025),
-      maxResultsPerCity: import_zod25.z.number().int().min(1).max(50),
-      concurrency: import_zod25.z.number().int().min(1).max(5),
-      censusSourceUrl: import_zod25.z.string().url(),
+      query: import_zod26.z.string(),
+      state: import_zod26.z.string(),
+      minPopulation: import_zod26.z.number().int().min(0),
+      populationYear: import_zod26.z.number().int().min(2020).max(2025),
+      maxResultsPerCity: import_zod26.z.number().int().min(1).max(50),
+      concurrency: import_zod26.z.number().int().min(1).max(5),
+      censusSourceUrl: import_zod26.z.string().url(),
       usZipsSourcePath: NullableString,
-      warnings: import_zod25.z.array(import_zod25.z.string()),
-      extractedAt: import_zod25.z.string(),
-      selectedCityCount: import_zod25.z.number().int().min(0),
-      totalResultCount: import_zod25.z.number().int().min(0),
+      warnings: import_zod26.z.array(import_zod26.z.string()),
+      extractedAt: import_zod26.z.string(),
+      selectedCityCount: import_zod26.z.number().int().min(0),
+      totalResultCount: import_zod26.z.number().int().min(0),
       csvPath: NullableString,
-      cities: import_zod25.z.array(import_zod25.z.object({
-        city: import_zod25.z.string(),
-        state: import_zod25.z.string(),
-        location: import_zod25.z.string(),
-        cityKey: import_zod25.z.string(),
-        censusName: import_zod25.z.string(),
-        population: import_zod25.z.number().int().min(0),
-        populationYear: import_zod25.z.number().int().min(2020).max(2025),
-        zips: import_zod25.z.array(import_zod25.z.string()),
-        counties: import_zod25.z.array(import_zod25.z.string()),
-        status: import_zod25.z.enum(["ok", "empty", "failed"]),
+      cities: import_zod26.z.array(import_zod26.z.object({
+        city: import_zod26.z.string(),
+        state: import_zod26.z.string(),
+        location: import_zod26.z.string(),
+        cityKey: import_zod26.z.string(),
+        censusName: import_zod26.z.string(),
+        population: import_zod26.z.number().int().min(0),
+        populationYear: import_zod26.z.number().int().min(2020).max(2025),
+        zips: import_zod26.z.array(import_zod26.z.string()),
+        counties: import_zod26.z.array(import_zod26.z.string()),
+        status: import_zod26.z.enum(["ok", "empty", "failed"]),
         error: NullableString,
-        resultCount: import_zod25.z.number().int().min(0),
-        durationMs: import_zod25.z.number().int().min(0),
-        attempts: import_zod25.z.array(MapsSearchAttemptOutput),
-        results: import_zod25.z.array(DirectoryMapsBusinessOutput)
+        resultCount: import_zod26.z.number().int().min(0),
+        durationMs: import_zod26.z.number().int().min(0),
+        attempts: import_zod26.z.array(MapsSearchAttemptOutput),
+        results: import_zod26.z.array(DirectoryMapsBusinessOutput)
       })),
-      durationMs: import_zod25.z.number().int().min(0)
+      durationMs: import_zod26.z.number().int().min(0)
     };
-    RankTrackerToolPlanOutput = import_zod25.z.object({
-      tool: import_zod25.z.string(),
-      purpose: import_zod25.z.string()
+    RankTrackerToolPlanOutput = import_zod26.z.object({
+      tool: import_zod26.z.string(),
+      purpose: import_zod26.z.string()
     });
-    RankTrackerTableOutput = import_zod25.z.object({
-      name: import_zod25.z.string(),
-      purpose: import_zod25.z.string(),
-      keyColumns: import_zod25.z.array(import_zod25.z.string())
+    RankTrackerTableOutput = import_zod26.z.object({
+      name: import_zod26.z.string(),
+      purpose: import_zod26.z.string(),
+      keyColumns: import_zod26.z.array(import_zod26.z.string())
     });
-    RankTrackerCronJobOutput = import_zod25.z.object({
-      name: import_zod25.z.string(),
-      purpose: import_zod25.z.string(),
-      modes: import_zod25.z.array(RankTrackerModeSchema),
-      recommendedTools: import_zod25.z.array(import_zod25.z.string())
+    RankTrackerCronJobOutput = import_zod26.z.object({
+      name: import_zod26.z.string(),
+      purpose: import_zod26.z.string(),
+      modes: import_zod26.z.array(RankTrackerModeSchema),
+      recommendedTools: import_zod26.z.array(import_zod26.z.string())
     });
     RankTrackerBlueprintOutputSchema = {
-      projectName: import_zod25.z.string(),
+      projectName: import_zod26.z.string(),
       targetDomain: NullableString,
       targetBusinessName: NullableString,
-      trackingModes: import_zod25.z.array(RankTrackerModeSchema),
-      database: import_zod25.z.string(),
-      recommendedTools: import_zod25.z.array(RankTrackerToolPlanOutput),
-      tables: import_zod25.z.array(RankTrackerTableOutput),
-      cron: import_zod25.z.object({
-        enabled: import_zod25.z.boolean(),
-        cadence: import_zod25.z.string(),
-        expression: import_zod25.z.string(),
-        timezone: import_zod25.z.string(),
-        jobs: import_zod25.z.array(RankTrackerCronJobOutput)
+      trackingModes: import_zod26.z.array(RankTrackerModeSchema),
+      database: import_zod26.z.string(),
+      recommendedTools: import_zod26.z.array(RankTrackerToolPlanOutput),
+      tables: import_zod26.z.array(RankTrackerTableOutput),
+      cron: import_zod26.z.object({
+        enabled: import_zod26.z.boolean(),
+        cadence: import_zod26.z.string(),
+        expression: import_zod26.z.string(),
+        timezone: import_zod26.z.string(),
+        jobs: import_zod26.z.array(RankTrackerCronJobOutput)
       }),
-      metrics: import_zod25.z.array(import_zod25.z.string()),
-      implementationPrompt: import_zod25.z.string()
+      metrics: import_zod26.z.array(import_zod26.z.string()),
+      implementationPrompt: import_zod26.z.string()
     };
-    OrganicResultOutput = import_zod25.z.object({
-      position: import_zod25.z.number().int(),
-      title: import_zod25.z.string(),
-      url: import_zod25.z.string(),
-      domain: import_zod25.z.string(),
+    OrganicResultOutput = import_zod26.z.object({
+      position: import_zod26.z.number().int(),
+      title: import_zod26.z.string(),
+      url: import_zod26.z.string(),
+      domain: import_zod26.z.string(),
       snippet: NullableString
     });
-    AiOverviewOutput = import_zod25.z.object({
-      detected: import_zod25.z.boolean(),
+    AiOverviewOutput = import_zod26.z.object({
+      detected: import_zod26.z.boolean(),
       text: NullableString
     }).nullable();
-    EntityIdsOutput = import_zod25.z.object({
-      kgIds: import_zod25.z.array(import_zod25.z.string()),
-      cids: import_zod25.z.array(import_zod25.z.string()),
-      gcids: import_zod25.z.array(import_zod25.z.string())
+    EntityIdsOutput = import_zod26.z.object({
+      kgIds: import_zod26.z.array(import_zod26.z.string()),
+      cids: import_zod26.z.array(import_zod26.z.string()),
+      gcids: import_zod26.z.array(import_zod26.z.string())
     }).nullable();
     HarvestPaaOutputSchema = {
-      query: import_zod25.z.string(),
+      query: import_zod26.z.string(),
       location: NullableString,
-      questionCount: import_zod25.z.number().int().min(0),
+      questionCount: import_zod26.z.number().int().min(0),
       completionStatus: NullableString,
-      questions: import_zod25.z.array(import_zod25.z.object({
-        question: import_zod25.z.string(),
+      questions: import_zod26.z.array(import_zod26.z.object({
+        question: import_zod26.z.string(),
         answer: NullableString,
         sourceTitle: NullableString,
         sourceSite: NullableString
       })),
-      organicResults: import_zod25.z.array(OrganicResultOutput),
+      organicResults: import_zod26.z.array(OrganicResultOutput),
       aiOverview: AiOverviewOutput,
       entityIds: EntityIdsOutput,
-      durationMs: import_zod25.z.number().min(0).nullable()
+      durationMs: import_zod26.z.number().min(0).nullable()
     };
     SearchSerpOutputSchema = {
-      query: import_zod25.z.string(),
+      query: import_zod26.z.string(),
       location: NullableString,
-      organicResults: import_zod25.z.array(OrganicResultOutput),
-      localPack: import_zod25.z.array(import_zod25.z.object({
-        position: import_zod25.z.number().int(),
-        name: import_zod25.z.string(),
+      organicResults: import_zod26.z.array(OrganicResultOutput),
+      localPack: import_zod26.z.array(import_zod26.z.object({
+        position: import_zod26.z.number().int(),
+        name: import_zod26.z.string(),
         rating: NullableString,
         reviewCount: NullableString,
         websiteUrl: NullableString
@@ -19116,31 +20176,31 @@ var init_mcp_tool_schemas = __esm({
       entityIds: EntityIdsOutput
     };
     ExtractUrlOutputSchema = {
-      url: import_zod25.z.string(),
+      url: import_zod26.z.string(),
       title: NullableString,
-      headings: import_zod25.z.array(import_zod25.z.object({
-        level: import_zod25.z.number().int(),
-        text: import_zod25.z.string()
+      headings: import_zod26.z.array(import_zod26.z.object({
+        level: import_zod26.z.number().int(),
+        text: import_zod26.z.string()
       })),
-      schemaBlockCount: import_zod25.z.number().int().min(0),
+      schemaBlockCount: import_zod26.z.number().int().min(0),
       entityName: NullableString,
-      entityTypes: import_zod25.z.array(import_zod25.z.string()),
-      napScore: import_zod25.z.number().nullable(),
-      missingSchemaFields: import_zod25.z.array(import_zod25.z.string()),
+      entityTypes: import_zod26.z.array(import_zod26.z.string()),
+      napScore: import_zod26.z.number().nullable(),
+      missingSchemaFields: import_zod26.z.array(import_zod26.z.string()),
       screenshotSaved: NullableString
     };
     ExtractSiteOutputSchema = {
-      url: import_zod25.z.string(),
-      pageCount: import_zod25.z.number().int().min(0),
-      pages: import_zod25.z.array(import_zod25.z.object({
-        url: import_zod25.z.string(),
+      url: import_zod26.z.string(),
+      pageCount: import_zod26.z.number().int().min(0),
+      pages: import_zod26.z.array(import_zod26.z.object({
+        url: import_zod26.z.string(),
         title: NullableString,
-        schemaTypes: import_zod25.z.array(import_zod25.z.string())
+        schemaTypes: import_zod26.z.array(import_zod26.z.string())
       })),
-      durationMs: import_zod25.z.number().min(0)
+      durationMs: import_zod26.z.number().min(0)
     };
     MapsPlaceIntelOutputSchema = {
-      name: import_zod25.z.string(),
+      name: import_zod26.z.string(),
       rating: NullableString,
       reviewCount: NullableString,
       category: NullableString,
@@ -19152,60 +20212,75 @@ var init_mcp_tool_schemas = __esm({
       kgmid: NullableString,
       cidDecimal: NullableString,
       cidUrl: NullableString,
-      lat: import_zod25.z.number().nullable(),
-      lng: import_zod25.z.number().nullable(),
-      reviewsStatus: import_zod25.z.string(),
-      reviewsCollected: import_zod25.z.number().int().min(0),
-      reviewTopics: import_zod25.z.array(import_zod25.z.object({
-        label: import_zod25.z.string(),
-        count: import_zod25.z.string()
+      lat: import_zod26.z.number().nullable(),
+      lng: import_zod26.z.number().nullable(),
+      reviewsStatus: import_zod26.z.string(),
+      reviewsCollected: import_zod26.z.number().int().min(0),
+      reviewTopics: import_zod26.z.array(import_zod26.z.object({
+        label: import_zod26.z.string(),
+        count: import_zod26.z.string()
       }))
     };
     CreditsInfoOutputSchema = {
-      balanceCredits: import_zod25.z.number().nullable(),
-      matchedCost: import_zod25.z.object({
-        label: import_zod25.z.string(),
-        credits: import_zod25.z.number(),
-        unit: import_zod25.z.string(),
+      balanceCredits: import_zod26.z.number().nullable(),
+      matchedCost: import_zod26.z.object({
+        label: import_zod26.z.string(),
+        credits: import_zod26.z.number(),
+        unit: import_zod26.z.string(),
         notes: NullableString
       }).nullable(),
-      costs: import_zod25.z.array(import_zod25.z.object({
-        key: import_zod25.z.string(),
-        label: import_zod25.z.string(),
-        credits: import_zod25.z.number(),
-        unit: import_zod25.z.string(),
+      costs: import_zod26.z.array(import_zod26.z.object({
+        key: import_zod26.z.string(),
+        label: import_zod26.z.string(),
+        credits: import_zod26.z.number(),
+        unit: import_zod26.z.string(),
         notes: NullableString
       })),
-      ledger: import_zod25.z.array(import_zod25.z.object({
-        createdAt: import_zod25.z.string(),
-        operation: import_zod25.z.string(),
-        credits: import_zod25.z.number(),
+      ledger: import_zod26.z.array(import_zod26.z.object({
+        createdAt: import_zod26.z.string(),
+        operation: import_zod26.z.string(),
+        credits: import_zod26.z.number(),
         description: NullableString
-      }))
+      })),
+      concurrency: import_zod26.z.object({
+        currentExtraSlots: import_zod26.z.number().int().min(0),
+        currentLimit: import_zod26.z.number().int().min(1),
+        hasSubscription: import_zod26.z.boolean(),
+        upgrade: import_zod26.z.object({
+          product: import_zod26.z.string(),
+          priceLabel: import_zod26.z.string(),
+          unitAmountUsd: import_zod26.z.number(),
+          currency: import_zod26.z.string(),
+          interval: import_zod26.z.string(),
+          billingUrl: import_zod26.z.string().url(),
+          terminalCommand: import_zod26.z.string(),
+          terminalCommandWithApiKeyEnv: import_zod26.z.string()
+        })
+      }).nullable()
     };
     MapSiteUrlsOutputSchema = {
-      startUrl: import_zod25.z.string(),
-      totalFound: import_zod25.z.number().int().min(0),
-      truncated: import_zod25.z.boolean(),
-      okCount: import_zod25.z.number().int().min(0),
-      redirectCount: import_zod25.z.number().int().min(0),
-      brokenCount: import_zod25.z.number().int().min(0),
-      urls: import_zod25.z.array(import_zod25.z.object({
-        url: import_zod25.z.string(),
-        status: import_zod25.z.number().int().nullable()
+      startUrl: import_zod26.z.string(),
+      totalFound: import_zod26.z.number().int().min(0),
+      truncated: import_zod26.z.boolean(),
+      okCount: import_zod26.z.number().int().min(0),
+      redirectCount: import_zod26.z.number().int().min(0),
+      brokenCount: import_zod26.z.number().int().min(0),
+      urls: import_zod26.z.array(import_zod26.z.object({
+        url: import_zod26.z.string(),
+        status: import_zod26.z.number().int().nullable()
       })),
-      durationMs: import_zod25.z.number().min(0)
+      durationMs: import_zod26.z.number().min(0)
     };
     YoutubeHarvestOutputSchema = {
-      mode: import_zod25.z.string(),
-      videoCount: import_zod25.z.number().int().min(0),
-      channel: import_zod25.z.object({
+      mode: import_zod26.z.string(),
+      videoCount: import_zod26.z.number().int().min(0),
+      channel: import_zod26.z.object({
         title: NullableString,
         subscriberCount: NullableString
       }).nullable(),
-      videos: import_zod25.z.array(import_zod25.z.object({
-        videoId: import_zod25.z.string(),
-        title: import_zod25.z.string(),
+      videos: import_zod26.z.array(import_zod26.z.object({
+        videoId: import_zod26.z.string(),
+        title: import_zod26.z.string(),
         channelName: NullableString,
         views: NullableString,
         duration: NullableString,
@@ -19213,21 +20288,21 @@ var init_mcp_tool_schemas = __esm({
       }))
     };
     FacebookAdSearchOutputSchema = {
-      query: import_zod25.z.string(),
-      advertiserCount: import_zod25.z.number().int().min(0),
-      advertisers: import_zod25.z.array(import_zod25.z.object({
+      query: import_zod26.z.string(),
+      advertiserCount: import_zod26.z.number().int().min(0),
+      advertisers: import_zod26.z.array(import_zod26.z.object({
         name: NullableString,
-        adCount: import_zod25.z.number().int().nullable(),
+        adCount: import_zod26.z.number().int().nullable(),
         libraryId: NullableString
       }))
     };
     FacebookPageIntelOutputSchema = {
       advertiserName: NullableString,
-      totalAds: import_zod25.z.number().int().min(0),
-      activeCount: import_zod25.z.number().int().min(0),
-      videoCount: import_zod25.z.number().int().min(0),
-      imageCount: import_zod25.z.number().int().min(0),
-      ads: import_zod25.z.array(import_zod25.z.object({
+      totalAds: import_zod26.z.number().int().min(0),
+      activeCount: import_zod26.z.number().int().min(0),
+      videoCount: import_zod26.z.number().int().min(0),
+      imageCount: import_zod26.z.number().int().min(0),
+      ads: import_zod26.z.array(import_zod26.z.object({
         libraryId: NullableString,
         status: NullableString,
         creativeType: NullableString,
@@ -19235,58 +20310,58 @@ var init_mcp_tool_schemas = __esm({
         cta: NullableString,
         startDate: NullableString,
         videoUrl: NullableString,
-        variations: import_zod25.z.number().int().nullable()
+        variations: import_zod26.z.number().int().nullable()
       }))
     };
     CreditsInfoInputSchema = {
-      item: import_zod25.z.string().optional().describe('Optional tool, action, or feature to look up, e.g. "maps reviews", "extract_url", or "YouTube transcription"'),
-      includeLedger: import_zod25.z.boolean().default(false).describe("Whether to include recent credit ledger entries")
+      item: import_zod26.z.string().optional().describe('Optional tool, action, or feature to look up, e.g. "maps reviews", "extract_url", "YouTube transcription", or "concurrency"'),
+      includeLedger: import_zod26.z.boolean().default(false).describe("Whether to include recent credit ledger entries")
     };
     SearchSerpInputSchema = {
-      query: import_zod25.z.string().min(1).describe('Core search topic only. Separate location when possible. If user says "best dentist in Brooklyn NY serp", use query="best dentist" and location="Brooklyn, NY".'),
-      location: import_zod25.z.string().optional().describe("City, region, or country for geo-targeted results, inferred from user request when present."),
-      gl: import_zod25.z.string().length(2).default("us").describe("Google country code inferred from location or user language."),
-      hl: import_zod25.z.string().default("en").describe("Google interface/content language inferred from user request."),
-      device: import_zod25.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use desktop by default; use mobile only when the user asks for mobile rankings."),
-      proxyMode: import_zod25.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default for US city/state SERPs; it creates a fresh residential proxy ID per attempt. If Google shows a CAPTCHA/challenge, browser-service sessions briefly wait for the automatic solver first, then retry with a fresh proxy/session if the challenge does not clear. Also retries proxy tunnel failure and wrong-location evidence before returning. Use configured only for the static configured proxy. Use none only for direct-network debugging."),
-      proxyZip: import_zod25.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use when the user gives a specific ZIP or when city-center targeting needs to be forced. With proxyMode location this ZIP is used for each fresh proxy attempt."),
-      debug: import_zod25.z.boolean().default(false).describe("Include sanitized browser/session/location diagnostics in the response. Use true when debugging localization, CAPTCHA, or proxy behavior."),
-      pages: import_zod25.z.number().int().min(1).max(2).default(1).describe("Number of result pages to fetch (1\u20132)")
+      query: import_zod26.z.string().min(1).describe('Core search topic only. Separate location when possible. If user says "best dentist in Brooklyn NY serp", use query="best dentist" and location="Brooklyn, NY".'),
+      location: import_zod26.z.string().optional().describe("City, region, or country for geo-targeted results, inferred from user request when present."),
+      gl: import_zod26.z.string().length(2).default("us").describe("Google country code inferred from location or user language."),
+      hl: import_zod26.z.string().default("en").describe("Google interface/content language inferred from user request."),
+      device: import_zod26.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use desktop by default; use mobile only when the user asks for mobile rankings."),
+      proxyMode: import_zod26.z.enum(["location", "configured", "none"]).default("location").describe("Proxy targeting mode. Use location by default for US city/state SERPs; it creates a fresh residential proxy ID per attempt. If Google shows a CAPTCHA/challenge, browser-service sessions briefly wait for the automatic solver first, then retry with a fresh proxy/session if the challenge does not clear. Also retries proxy tunnel failure and wrong-location evidence before returning. Use configured only for the static configured proxy. Use none only for direct-network debugging."),
+      proxyZip: import_zod26.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting. Use when the user gives a specific ZIP or when city-center targeting needs to be forced. With proxyMode location this ZIP is used for each fresh proxy attempt."),
+      debug: import_zod26.z.boolean().default(false).describe("Include sanitized browser/session/location diagnostics in the response. Use true when debugging localization, CAPTCHA, or proxy behavior."),
+      pages: import_zod26.z.number().int().min(1).max(2).default(1).describe("Number of result pages to fetch (1\u20132)")
     };
     CaptureSerpSnapshotInputSchema = {
-      query: import_zod25.z.string().min(1).describe("Core search query to capture as a structured SERP Intelligence snapshot. Separate the place into location when the user gives a city, region, country, or ZIP."),
-      location: import_zod25.z.string().optional().describe("City, region, country, or service area used for localized Google results. MCP Scraper records location evidence; UULE alone is not proof of localization."),
-      gl: import_zod25.z.string().length(2).default("us").describe("Google country code inferred from the requested market, e.g. us, gb, ca, au."),
-      hl: import_zod25.z.string().default("en").describe("Google interface/content language inferred from the user request."),
-      device: import_zod25.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use mobile only when the user asks for mobile rankings or mobile SERP evidence."),
-      proxyMode: import_zod25.z.enum(["location", "configured", "none"]).default("location").describe("Proxy behavior for capture. Use location for localized US residential evidence; it creates a fresh proxy ID per attempt. If Google shows a CAPTCHA/challenge, browser-service sessions briefly wait for the automatic solver first, then retry with a fresh proxy/session if the challenge does not clear. Also retries proxy tunnel failure and wrong-location evidence before returning. Use configured only for the static residential proxy, and none only for direct-network debugging."),
-      proxyZip: import_zod25.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting when a precise city-center or ZIP proxy is needed. With proxyMode location this ZIP is used for each fresh proxy attempt."),
-      pages: import_zod25.z.number().int().min(1).max(2).default(1).describe("Number of Google result pages to capture. Use 1 normally and 2 only when the user needs deeper ranking evidence."),
-      debug: import_zod25.z.boolean().default(false).describe("Include sanitized browser, proxy, and location diagnostics. Use true when debugging localization, CAPTCHA, proxy selection, or capture reliability."),
-      includePageSnapshots: import_zod25.z.boolean().default(false).describe("Also capture ranking-page snapshots for selected SERP URLs through the same product capture path."),
-      pageSnapshotLimit: import_zod25.z.number().int().min(0).max(10).default(0).describe("Maximum ranking-page snapshots to capture when includePageSnapshots is true. Use 0 when only SERP evidence is needed.")
+      query: import_zod26.z.string().min(1).describe("Core search query to capture as a structured SERP Intelligence snapshot. Separate the place into location when the user gives a city, region, country, or ZIP."),
+      location: import_zod26.z.string().optional().describe("City, region, country, or service area used for localized Google results. MCP Scraper records location evidence; UULE alone is not proof of localization."),
+      gl: import_zod26.z.string().length(2).default("us").describe("Google country code inferred from the requested market, e.g. us, gb, ca, au."),
+      hl: import_zod26.z.string().default("en").describe("Google interface/content language inferred from the user request."),
+      device: import_zod26.z.enum(["desktop", "mobile"]).default("desktop").describe("SERP device context. Use mobile only when the user asks for mobile rankings or mobile SERP evidence."),
+      proxyMode: import_zod26.z.enum(["location", "configured", "none"]).default("location").describe("Proxy behavior for capture. Use location for localized US residential evidence; it creates a fresh proxy ID per attempt. If Google shows a CAPTCHA/challenge, browser-service sessions briefly wait for the automatic solver first, then retry with a fresh proxy/session if the challenge does not clear. Also retries proxy tunnel failure and wrong-location evidence before returning. Use configured only for the static residential proxy, and none only for direct-network debugging."),
+      proxyZip: import_zod26.z.string().regex(/^\d{5}$/).optional().describe("Optional US ZIP override for residential location proxy targeting when a precise city-center or ZIP proxy is needed. With proxyMode location this ZIP is used for each fresh proxy attempt."),
+      pages: import_zod26.z.number().int().min(1).max(2).default(1).describe("Number of Google result pages to capture. Use 1 normally and 2 only when the user needs deeper ranking evidence."),
+      debug: import_zod26.z.boolean().default(false).describe("Include sanitized browser, proxy, and location diagnostics. Use true when debugging localization, CAPTCHA, proxy selection, or capture reliability."),
+      includePageSnapshots: import_zod26.z.boolean().default(false).describe("Also capture ranking-page snapshots for selected SERP URLs through the same product capture path."),
+      pageSnapshotLimit: import_zod26.z.number().int().min(0).max(10).default(0).describe("Maximum ranking-page snapshots to capture when includePageSnapshots is true. Use 0 when only SERP evidence is needed.")
     };
     ScreenshotInputSchema = {
-      url: import_zod25.z.string().url().describe("URL to capture as a full-page screenshot. Use http or https. Pass allowLocal: true to capture localhost or private-network URLs during development."),
-      device: import_zod25.z.enum(["desktop", "mobile"]).default("desktop").describe("Viewport profile. desktop = 1440\xD7900. mobile = 390\xD7844. Use desktop by default; use mobile when the user asks for a mobile view."),
-      allowLocal: import_zod25.z.boolean().default(false).describe("Allow localhost and private-network URLs (127.x, 192.168.x, 10.x, etc.). For local development only \u2014 not for production use.")
+      url: import_zod26.z.string().url().describe("URL to capture as a full-page screenshot. Use http or https. Pass allowLocal: true to capture localhost or private-network URLs during development."),
+      device: import_zod26.z.enum(["desktop", "mobile"]).default("desktop").describe("Viewport profile. desktop = 1440\xD7900. mobile = 390\xD7844. Use desktop by default; use mobile when the user asks for a mobile view."),
+      allowLocal: import_zod26.z.boolean().default(false).describe("Allow localhost and private-network URLs (127.x, 192.168.x, 10.x, etc.). For local development only \u2014 not for production use.")
     };
     CaptureSerpPageSnapshotsInputSchema = {
-      urls: import_zod25.z.array(import_zod25.z.string().url()).min(1).max(25).describe("Public HTTP/HTTPS URLs to capture as SERP Intelligence page snapshots. Do not pass localhost, private IPs, file URLs, or internal admin URLs."),
-      targets: import_zod25.z.array(import_zod25.z.object({
-        url: import_zod25.z.string().url().describe("Public HTTP/HTTPS URL to capture."),
-        sourceKind: import_zod25.z.enum(["organic", "ai_citation", "local_pack_website", "configured_target", "site_subject"]).default("configured_target").describe("Why this page is being captured for SERP Intelligence evidence."),
-        sourcePosition: import_zod25.z.number().int().min(1).optional().describe("Ranking or citation position when the page came from SERP evidence.")
+      urls: import_zod26.z.array(import_zod26.z.string().url()).min(1).max(25).describe("Public HTTP/HTTPS URLs to capture as SERP Intelligence page snapshots. Do not pass localhost, private IPs, file URLs, or internal admin URLs."),
+      targets: import_zod26.z.array(import_zod26.z.object({
+        url: import_zod26.z.string().url().describe("Public HTTP/HTTPS URL to capture."),
+        sourceKind: import_zod26.z.enum(["organic", "ai_citation", "local_pack_website", "configured_target", "site_subject"]).default("configured_target").describe("Why this page is being captured for SERP Intelligence evidence."),
+        sourcePosition: import_zod26.z.number().int().min(1).optional().describe("Ranking or citation position when the page came from SERP evidence.")
       }).strict()).min(1).max(25).optional().describe("Structured page snapshot targets. Use this instead of urls when source kind or position should be preserved."),
-      maxConcurrency: import_zod25.z.number().int().min(1).max(5).default(2).describe("Parallel page captures. Use 2 normally; higher values can increase proxy/browser pressure."),
-      timeoutMs: import_zod25.z.number().int().min(1e3).max(6e4).default(15e3).describe("Per-page capture timeout in milliseconds. Increase for slow pages; timeout artifacts are returned as structured capture failures."),
-      debug: import_zod25.z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics for page snapshot debugging. Use true for capture, network, or proxy troubleshooting.")
+      maxConcurrency: import_zod26.z.number().int().min(1).max(5).default(2).describe("Parallel page captures. Use 2 normally; higher values can increase proxy/browser pressure."),
+      timeoutMs: import_zod26.z.number().int().min(1e3).max(6e4).default(15e3).describe("Per-page capture timeout in milliseconds. Increase for slow pages; timeout artifacts are returned as structured capture failures."),
+      debug: import_zod26.z.boolean().default(false).describe("Include sanitized browser/proxy diagnostics for page snapshot debugging. Use true for capture, network, or proxy troubleshooting.")
     };
   }
 });
 
 // src/mcp/rank-tracker-blueprint.ts
-function normalizeDomain2(value) {
+function normalizeDomain3(value) {
   const trimmed = value?.trim();
   if (!trimmed) return null;
   try {
@@ -19548,7 +20623,7 @@ function buildPrompt(input, modes, tools, tables, jobs, metrics, expression, tar
 }
 function buildRankTrackerBlueprint(input) {
   const trackingModes = uniqueModes(input.trackingModes);
-  const targetDomain = normalizeDomain2(input.targetDomain);
+  const targetDomain = normalizeDomain3(input.targetDomain);
   const targetBusinessName = input.targetBusinessName?.trim() || null;
   const projectName = input.projectName?.trim() || "MCP Scraper Rank Tracker";
   const database = input.database || "postgres";
@@ -19775,7 +20850,7 @@ function registerPaaExtractorMcpTools(server, executor, options = {}) {
   }, async (input) => buildRankTrackerBlueprint(input));
   server.registerTool("credits_info", {
     title: "MCP Scraper Credits & Costs",
-    description: "Answer questions about MCP Scraper credits: current credit balance, what a specific tool/action costs, the full cost table, and optionally recent credit ledger entries. Does not expose payment methods or credit card information.",
+    description: "Answer questions about MCP Scraper credits, usage limits, and concurrency upgrades: current credit balance, what a specific tool/action costs, the full cost table, current concurrency limit, the extra-slot price, billing URL, and the terminal checkout command. Does not expose payment methods or credit card information.",
     inputSchema: CreditsInfoInputSchema,
     outputSchema: CreditsInfoOutputSchema,
     annotations: {
@@ -20008,6 +21083,7 @@ async function migrateBrowserAgent() {
       status              TEXT NOT NULL DEFAULT 'open',
       label               TEXT,
       user_id             INTEGER,
+      concurrency_lock_id TEXT,
       created_at          TEXT NOT NULL DEFAULT (datetime('now')),
       closed_at           TEXT,
       last_action_at      TEXT,
@@ -20017,6 +21093,11 @@ async function migrateBrowserAgent() {
   `);
   await db.execute(`CREATE INDEX IF NOT EXISTS browser_agent_sessions_status ON browser_agent_sessions(status)`);
   await db.execute(`CREATE INDEX IF NOT EXISTS browser_agent_sessions_user ON browser_agent_sessions(user_id)`);
+  try {
+    await db.execute(`ALTER TABLE browser_agent_sessions ADD COLUMN concurrency_lock_id TEXT`);
+  } catch {
+  }
+  await db.execute(`CREATE INDEX IF NOT EXISTS browser_agent_sessions_concurrency_lock ON browser_agent_sessions(concurrency_lock_id)`);
   await db.execute(`
     CREATE TABLE IF NOT EXISTS browser_agent_actions (
       id          TEXT PRIMARY KEY,
@@ -20044,11 +21125,11 @@ async function migrateBrowserAgent() {
 }
 async function createSessionRow(input) {
   const db = getDb();
-  const id = `bas_${(0, import_node_crypto4.randomUUID)().replace(/-/g, "").slice(0, 20)}`;
+  const id = `bas_${(0, import_node_crypto5.randomUUID)().replace(/-/g, "").slice(0, 20)}`;
   await db.execute({
-    sql: `INSERT INTO browser_agent_sessions (id, runtime_session_id, live_view_url, cdp_ws_url, status, label, user_id, last_action_at)
-          VALUES (?, ?, ?, ?, 'open', ?, ?, datetime('now'))`,
-    args: [id, input.runtimeSessionId, input.liveViewUrl, input.cdpWsUrl, input.label, input.userId]
+    sql: `INSERT INTO browser_agent_sessions (id, runtime_session_id, live_view_url, cdp_ws_url, status, label, user_id, concurrency_lock_id, last_action_at)
+          VALUES (?, ?, ?, ?, 'open', ?, ?, ?, datetime('now'))`,
+    args: [id, input.runtimeSessionId, input.liveViewUrl, input.cdpWsUrl, input.label, input.userId, input.concurrencyLockId ?? null]
   });
   const row = await getSessionRow(id);
   if (!row) throw new Error("session insert failed");
@@ -20105,7 +21186,7 @@ async function recordAction(input) {
     sql: `INSERT INTO browser_agent_actions (id, session_id, type, params_json, ok, error)
           VALUES (?, ?, ?, ?, ?, ?)`,
     args: [
-      `baa_${(0, import_node_crypto4.randomUUID)().replace(/-/g, "").slice(0, 20)}`,
+      `baa_${(0, import_node_crypto5.randomUUID)().replace(/-/g, "").slice(0, 20)}`,
       input.sessionId,
       input.type,
       input.params == null ? null : JSON.stringify(input.params),
@@ -20145,11 +21226,11 @@ async function listReplayRows(sessionId) {
   });
   return res.rows;
 }
-var import_node_crypto4, _ready;
+var import_node_crypto5, _ready;
 var init_browser_agent_db = __esm({
   "src/api/browser-agent-db.ts"() {
     "use strict";
-    import_node_crypto4 = require("crypto");
+    import_node_crypto5 = require("crypto");
     init_db();
     _ready = false;
   }
@@ -20469,6 +21550,12 @@ var init_browser_agent_service = __esm({
 });
 
 // src/api/browser-agent-routes.ts
+function browserSessionLockTtlSeconds(timeoutSeconds) {
+  if (typeof timeoutSeconds === "number" && Number.isFinite(timeoutSeconds) && timeoutSeconds > 0) {
+    return Math.max(30 * 60, Math.min(Math.trunc(timeoutSeconds) + 5 * 60, 24 * 60 * 60));
+  }
+  return DEFAULT_BROWSER_SESSION_LOCK_TTL_SECONDS;
+}
 async function charge(sessionId, userId, startedAtMs) {
   const elapsedMs = Date.now() - startedAtMs;
   const { active_ms, billed_mc } = await addActiveMs(sessionId, elapsedMs);
@@ -20524,6 +21611,8 @@ async function loadOpenSession(id, userId) {
   const row = await getSessionRow(id);
   if (!row) return null;
   if (row.user_id != null && row.user_id !== userId) return null;
+  if (row.status !== "open") return null;
+  await extendConcurrencyGate(row.concurrency_lock_id, DEFAULT_BROWSER_SESSION_LOCK_TTL_SECONDS);
   return row;
 }
 function buildBrowserAgentRoutes() {
@@ -20539,23 +21628,39 @@ function buildBrowserAgentRoutes() {
       return c.json(insufficientBalanceResponse(Number(user.balance_mc ?? 0), BROWSER_OPEN_MIN_BALANCE_MC), 402);
     }
     const body = await c.req.json().catch(() => ({}));
+    const timeoutSeconds = typeof body.timeout_seconds === "number" ? body.timeout_seconds : void 0;
+    const gate = await acquireConcurrencyGate(user, "browser_agent_session", {
+      ttlSeconds: browserSessionLockTtlSeconds(timeoutSeconds),
+      metadata: { label: typeof body.label === "string" ? body.label : null }
+    });
+    if (!gate.ok) return c.json(concurrencyLimitExceededResponse(gate), 429, { "Retry-After": String(gate.retryAfterSeconds) });
+    let runtimeSessionId = null;
     try {
       const created = await createSession({
-        timeoutSeconds: typeof body.timeout_seconds === "number" ? body.timeout_seconds : void 0,
+        timeoutSeconds,
         proxyId: typeof body.proxy_id === "string" ? body.proxy_id : void 0,
         profileName: typeof body.profile === "string" ? body.profile : void 0,
         disableDefaultProxy: body.disable_default_proxy === true,
         viewport: body.viewport && typeof body.viewport === "object" ? body.viewport : void 0
       });
+      runtimeSessionId = created.runtimeSessionId;
       const row = await createSessionRow({
         runtimeSessionId: created.runtimeSessionId,
         liveViewUrl: created.liveViewUrl,
         cdpWsUrl: created.cdpWsUrl,
         label: typeof body.label === "string" ? body.label : null,
-        userId: user.id
+        userId: user.id,
+        concurrencyLockId: gate.lockId
       });
       return c.json({ ...publicSession(row), watch_url: `/console/${row.id}` });
     } catch (err) {
+      if (runtimeSessionId) {
+        try {
+          await closeSession(runtimeSessionId);
+        } catch {
+        }
+      }
+      await releaseConcurrencyGate(gate.lockId);
       return c.json(failure(err), 502);
     }
   });
@@ -20586,6 +21691,7 @@ function buildBrowserAgentRoutes() {
     } catch {
     }
     await markSessionClosed(row.id);
+    await releaseConcurrencyGate(row.concurrency_lock_id);
     return c.json({ ok: true });
   });
   app2.post("/sessions/:id/goto", async (c) => {
@@ -20843,7 +21949,7 @@ function buildBrowserAgentRoutes() {
   });
   return app2;
 }
-var import_hono10, auth;
+var import_hono10, auth, DEFAULT_BROWSER_SESSION_LOCK_TTL_SECONDS;
 var init_browser_agent_routes = __esm({
   "src/api/browser-agent-routes.ts"() {
     "use strict";
@@ -20854,7 +21960,9 @@ var init_browser_agent_routes = __esm({
     init_rates();
     init_browser_agent_db();
     init_browser_agent_service();
+    init_concurrency_gates();
     auth = createApiKeyAuth();
+    DEFAULT_BROWSER_SESSION_LOCK_TTL_SECONDS = 2 * 60 * 60;
   }
 });
 
@@ -21170,31 +22278,31 @@ var init_site_audit_worker = __esm({
 });
 
 // src/api/billing-schemas.ts
-var import_zod26, BillingCheckoutBodySchema, FreeCreditBreakdownSchema, BillingBalanceResponseSchema, MonthlyRefreshSweepResultSchema;
+var import_zod27, BillingCheckoutBodySchema, FreeCreditBreakdownSchema, BillingBalanceResponseSchema, MonthlyRefreshSweepResultSchema;
 var init_billing_schemas = __esm({
   "src/api/billing-schemas.ts"() {
     "use strict";
-    import_zod26 = require("zod");
-    BillingCheckoutBodySchema = import_zod26.z.object({
-      priceId: import_zod26.z.string().min(1)
+    import_zod27 = require("zod");
+    BillingCheckoutBodySchema = import_zod27.z.object({
+      priceId: import_zod27.z.string().min(1)
     });
-    FreeCreditBreakdownSchema = import_zod26.z.object({
-      signup_grant_mc: import_zod26.z.number().int().nonnegative(),
-      monthly_refresh_mc: import_zod26.z.number().int().nonnegative(),
-      total_free_mc: import_zod26.z.number().int().nonnegative(),
-      signup_grant_credits: import_zod26.z.number().nonnegative(),
-      monthly_refresh_credits: import_zod26.z.number().nonnegative(),
-      total_free_credits: import_zod26.z.number().nonnegative()
+    FreeCreditBreakdownSchema = import_zod27.z.object({
+      signup_grant_mc: import_zod27.z.number().int().nonnegative(),
+      monthly_refresh_mc: import_zod27.z.number().int().nonnegative(),
+      total_free_mc: import_zod27.z.number().int().nonnegative(),
+      signup_grant_credits: import_zod27.z.number().nonnegative(),
+      monthly_refresh_credits: import_zod27.z.number().nonnegative(),
+      total_free_credits: import_zod27.z.number().nonnegative()
     });
-    BillingBalanceResponseSchema = import_zod26.z.object({
-      balance_mc: import_zod26.z.number().int().nonnegative(),
-      balance_credits: import_zod26.z.number().nonnegative(),
+    BillingBalanceResponseSchema = import_zod27.z.object({
+      balance_mc: import_zod27.z.number().int().nonnegative(),
+      balance_credits: import_zod27.z.number().nonnegative(),
       free_credits: FreeCreditBreakdownSchema,
-      ledger: import_zod26.z.array(import_zod26.z.any())
+      ledger: import_zod27.z.array(import_zod27.z.any())
     });
-    MonthlyRefreshSweepResultSchema = import_zod26.z.object({
-      usersRefreshed: import_zod26.z.number().int().nonnegative(),
-      totalMcGranted: import_zod26.z.number().int().nonnegative()
+    MonthlyRefreshSweepResultSchema = import_zod27.z.object({
+      usersRefreshed: import_zod27.z.number().int().nonnegative(),
+      totalMcGranted: import_zod27.z.number().int().nonnegative()
     });
   }
 });
@@ -21356,14 +22464,14 @@ function getSessionSecret() {
 function safeEqualHex(a, b) {
   if (a.length !== b.length) return false;
   try {
-    return (0, import_node_crypto5.timingSafeEqual)(Buffer.from(a, "hex"), Buffer.from(b, "hex"));
+    return (0, import_node_crypto6.timingSafeEqual)(Buffer.from(a, "hex"), Buffer.from(b, "hex"));
   } catch {
     return false;
   }
 }
 function signSession(userId) {
   const payload = String(userId);
-  const sig = (0, import_node_crypto5.createHmac)("sha256", secret()).update(payload).digest("hex");
+  const sig = (0, import_node_crypto6.createHmac)("sha256", secret()).update(payload).digest("hex");
   return `${payload}.${sig}`;
 }
 function verifySession(token) {
@@ -21371,16 +22479,16 @@ function verifySession(token) {
   if (dot === -1) return null;
   const payload = token.slice(0, dot);
   const sig = token.slice(dot + 1);
-  const expected = (0, import_node_crypto5.createHmac)("sha256", secret()).update(payload).digest("hex");
+  const expected = (0, import_node_crypto6.createHmac)("sha256", secret()).update(payload).digest("hex");
   if (!safeEqualHex(sig, expected)) return null;
   const id = parseInt(payload);
   return isNaN(id) ? null : id;
 }
-var import_node_crypto5, isProduction, secret;
+var import_node_crypto6, isProduction, secret;
 var init_session = __esm({
   "src/api/session.ts"() {
     "use strict";
-    import_node_crypto5 = require("crypto");
+    import_node_crypto6 = require("crypto");
     isProduction = () => process.env.NODE_ENV === "production" || process.env.VERCEL === "1";
     secret = () => getSessionSecret();
   }
@@ -21589,14 +22697,23 @@ function countPaaQuestions2(result) {
 function paaCostForQuestionCount2(questionCount) {
   return Math.max(1, questionCount) * MC_COSTS.paa;
 }
-async function checkHarvestLimits(userId, email, extraSlots = 0) {
-  if (BYPASS_EMAILS.has(email)) return null;
-  const limit = 1 + extraSlots;
-  const active = await countActiveJobsForUser(userId);
-  if (active >= limit) return { error: `You have ${active} job${active !== 1 ? "s" : ""} running. Your account allows ${limit} concurrent job${limit !== 1 ? "s" : ""}. Wait for one to finish or add a concurrency slot at mcpscraper.dev/billing.` };
+async function checkHarvestLimits(user, reuseLockId) {
+  if (reuseLockId && await reuseExistingConcurrencyGate(user.id, reuseLockId, 30 * 60)) return null;
+  if (isConcurrencyLimitBypassed(user)) return null;
+  const limit = concurrencyLimitForUser(user);
+  const active = await countActiveUsageForUser(user.id);
+  if (active >= limit) {
+    return concurrencyLimitExceededResponse({
+      ok: false,
+      active,
+      limit,
+      operation: "harvest",
+      retryAfterSeconds: 30
+    });
+  }
   return null;
 }
-var import_resend, import_hono12, import_hono13, import_factory6, import_cookie, import_stripe2, secureCookies, isProduction2, sessionCookieOptions, requireAllowedOrigin, auth2, adminAuth, sessionAuth, app, STRIPE_API_VERSION, BYPASS_EMAILS, SYNC_HARVEST_TIMEOUT_OVERRIDE_MS;
+var import_resend, import_hono12, import_hono13, import_factory6, import_cookie, import_stripe2, secureCookies, isProduction2, sessionCookieOptions, requireAllowedOrigin, auth2, adminAuth, sessionAuth, app, STRIPE_API_VERSION, SYNC_HARVEST_TIMEOUT_OVERRIDE_MS;
 var init_server = __esm({
   "src/api/server.ts"() {
     "use strict";
@@ -21642,6 +22759,7 @@ var init_server = __esm({
     init_harvest_problems();
     init_harvest_attempt_events();
     init_session();
+    init_concurrency_gates();
     secureCookies = process.env.NODE_ENV === "production" || process.env.VERCEL === "1";
     isProduction2 = secureCookies;
     sessionCookieOptions = {
@@ -21838,9 +22956,6 @@ var init_server = __esm({
       await revokeApiKey(user.id);
       return c.json({ ok: true });
     });
-    BYPASS_EMAILS = new Set(
-      (process.env.HARVEST_LIMIT_BYPASS_EMAILS ?? "").split(",").map((e) => e.trim()).filter(Boolean)
-    );
     SYNC_HARVEST_TIMEOUT_OVERRIDE_MS = (() => {
       const raw = process.env.SYNC_HARVEST_TIMEOUT_MS;
       const parsed = raw === void 0 ? NaN : Number(raw);
@@ -21858,8 +22973,8 @@ var init_server = __esm({
         if (checked.error) return c.json({ error: checked.error }, 400);
         body.callback_url = checked.parsed?.href;
       }
-      const limitErr = await checkHarvestLimits(user.id, user.email, user.extra_concurrency_slots);
-      if (limitErr) return c.json(limitErr, 429);
+      const limitErr = await checkHarvestLimits(user, c.req.header("x-mcp-scraper-concurrency-lock"));
+      if (limitErr) return c.json(limitErr, 429, { "Retry-After": "30" });
       const options = {
         query: body.query.trim(),
         location: body.location,
@@ -21894,8 +23009,8 @@ var init_server = __esm({
       const bodyResult = HarvestBodySchema.safeParse(raw);
       if (!bodyResult.success) return c.json({ error: bodyResult.error.issues[0]?.message ?? "Invalid request" }, 400);
       const body = bodyResult.data;
-      const limitErr = await checkHarvestLimits(user.id, user.email, user.extra_concurrency_slots);
-      if (limitErr) return c.json(limitErr, 429);
+      const limitErr = await checkHarvestLimits(user, c.req.header("x-mcp-scraper-concurrency-lock"));
+      if (limitErr) return c.json(limitErr, 429, { "Retry-After": "30" });
       const options = {
         query: body.query.trim(),
         location: body.location,
@@ -22054,9 +23169,16 @@ var init_server = __esm({
         }
       })();
       const user = c.get("user");
-      const { ok: euOk, balance_mc: euBal } = await debitMc(user.id, MC_COSTS.page_scrape, LedgerOperation.EXTRACT_URL, new URL(canonicalUrl).hostname);
-      if (!euOk) return c.json(insufficientBalanceResponse(euBal, MC_COSTS.page_scrape), 402);
+      const gate = await acquireConcurrencyGate(user, "extract_url", {
+        reuseLockId: c.req.header("x-mcp-scraper-concurrency-lock"),
+        metadata: { url: canonicalUrl }
+      });
+      if (!gate.ok) return c.json(concurrencyLimitExceededResponse(gate), 429, { "Retry-After": String(gate.retryAfterSeconds) });
+      let debited = false;
       try {
+        const { ok: euOk, balance_mc: euBal } = await debitMc(user.id, MC_COSTS.page_scrape, LedgerOperation.EXTRACT_URL, new URL(canonicalUrl).hostname);
+        if (!euOk) return c.json(insufficientBalanceResponse(euBal, MC_COSTS.page_scrape), 402);
+        debited = true;
         const kernelApiKey = browserServiceApiKey();
         const device = screenshotDevice === "mobile" ? "mobile" : "desktop";
         const [result, pageData] = await Promise.all([
@@ -22074,9 +23196,11 @@ var init_server = __esm({
         return c.json({ ...result, screenshot: screenshotMeta, branding: brandingData, media: mediaMeta });
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        await creditMc(user.id, MC_COSTS.page_scrape, LedgerOperation.EXTRACT_URL, "failed call");
+        if (debited) await creditMc(user.id, MC_COSTS.page_scrape, LedgerOperation.EXTRACT_URL, "failed call");
         await logRequestEvent({ userId: user.id, source: "extract_url", status: "failed", query: canonicalUrl, error: msg });
         return c.json({ error: msg }, 500);
+      } finally {
+        await releaseConcurrencyGate(gate.lockId);
       }
     });
     app.post("/map-urls", auth2, async (c) => {
@@ -22088,9 +23212,16 @@ var init_server = __esm({
       if (checked.error || !checked.parsed) return c.json({ error: checked.error ?? "Invalid URL" }, 400);
       const parsed = checked.parsed;
       const user = c.get("user");
-      const { ok: mapOk, balance_mc: mapBal } = await debitMc(user.id, MC_COSTS.url_map, LedgerOperation.URL_MAP, parsed.hostname);
-      if (!mapOk) return c.json(insufficientBalanceResponse(mapBal, MC_COSTS.url_map), 402);
+      const gate = await acquireConcurrencyGate(user, "map_urls", {
+        reuseLockId: c.req.header("x-mcp-scraper-concurrency-lock"),
+        metadata: { url: parsed.href }
+      });
+      if (!gate.ok) return c.json(concurrencyLimitExceededResponse(gate), 429, { "Retry-After": String(gate.retryAfterSeconds) });
+      let debited = false;
       try {
+        const { ok: mapOk, balance_mc: mapBal } = await debitMc(user.id, MC_COSTS.url_map, LedgerOperation.URL_MAP, parsed.hostname);
+        if (!mapOk) return c.json(insufficientBalanceResponse(mapBal, MC_COSTS.url_map), 402);
+        debited = true;
         const result = await spiderSite({
           startUrl: parsed.href,
           maxUrls: Math.min(2e3, Math.max(1, body.maxUrls ?? 500)),
@@ -22108,7 +23239,7 @@ var init_server = __esm({
         return c.json(result);
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        await creditMc(user.id, MC_COSTS.url_map, LedgerOperation.URL_MAP_REFUND, "failed call");
+        if (debited) await creditMc(user.id, MC_COSTS.url_map, LedgerOperation.URL_MAP_REFUND, "failed call");
         await logRequestEvent({
           userId: user.id,
           source: "map_urls",
@@ -22117,6 +23248,8 @@ var init_server = __esm({
           error: msg
         });
         return c.json({ error: msg }, 500);
+      } finally {
+        await releaseConcurrencyGate(gate.lockId);
       }
     });
     app.post("/extract-site", auth2, async (c) => {
@@ -22129,9 +23262,16 @@ var init_server = __esm({
       const parsed = checked.parsed;
       const user = c.get("user");
       const siteHoldMc = MC_COSTS.page_scrape * 10;
-      const { ok: siteOk, balance_mc: siteBal } = await debitMc(user.id, siteHoldMc, LedgerOperation.EXTRACT_SITE_HOLD, parsed.hostname);
-      if (!siteOk) return c.json(insufficientBalanceResponse(siteBal, siteHoldMc), 402);
+      const gate = await acquireConcurrencyGate(user, "extract_site", {
+        reuseLockId: c.req.header("x-mcp-scraper-concurrency-lock"),
+        metadata: { url: parsed.href }
+      });
+      if (!gate.ok) return c.json(concurrencyLimitExceededResponse(gate), 429, { "Retry-After": String(gate.retryAfterSeconds) });
+      let debited = false;
       try {
+        const { ok: siteOk, balance_mc: siteBal } = await debitMc(user.id, siteHoldMc, LedgerOperation.EXTRACT_SITE_HOLD, parsed.hostname);
+        if (!siteOk) return c.json(insufficientBalanceResponse(siteBal, siteHoldMc), 402);
+        debited = true;
         const result = await extractSite({
           startUrl: parsed.href,
           maxPages: Math.min(200, Math.max(1, body.maxPages ?? 100)),
@@ -22152,7 +23292,7 @@ var init_server = __esm({
         });
         return c.json(result);
       } catch (err) {
-        await creditMc(user.id, siteHoldMc, LedgerOperation.EXTRACT_SITE_REFUND, "failed call");
+        if (debited) await creditMc(user.id, siteHoldMc, LedgerOperation.EXTRACT_SITE_REFUND, "failed call");
         const msg = err instanceof Error ? err.message : String(err);
         await logRequestEvent({
           userId: user.id,
@@ -22162,6 +23302,8 @@ var init_server = __esm({
           error: msg
         });
         return c.json({ error: msg }, 500);
+      } finally {
+        await releaseConcurrencyGate(gate.lockId);
       }
     });
     app.post("/billing/checkout", requireAllowedOrigin, sessionAuth, async (c) => {
@@ -22230,6 +23372,60 @@ var init_server = __esm({
         return c.json({ error: message }, 500);
       }
     });
+    app.post("/billing/concurrency/terminal-checkout", auth2, async (c) => {
+      try {
+        const user = c.get("user");
+        const upgrade = concurrencySlotBillingInfo();
+        if (user.concurrency_stripe_sub_id) {
+          return c.json({
+            error: "Already subscribed. Your account already has an active extra concurrency slot subscription.",
+            error_code: "concurrency_subscription_exists",
+            concurrency: {
+              extra_slots: user.extra_concurrency_slots,
+              limit: concurrencyLimitForUser(user),
+              has_subscription: true,
+              upgrade
+            }
+          }, 409);
+        }
+        const secret2 = process.env.STRIPE_SECRET_KEY?.trim();
+        if (!secret2) return c.json({ error: "Stripe is not configured." }, 503);
+        const stripeClient = new import_stripe2.default(secret2, { apiVersion: STRIPE_API_VERSION });
+        let customerId = user.stripe_customer_id;
+        if (!customerId) {
+          const customer = await stripeClient.customers.create({ email: user.email });
+          customerId = customer.id;
+          await setStripeCustomerId(user.id, customerId);
+        }
+        const session = await stripeClient.checkout.sessions.create({
+          customer: customerId,
+          mode: "subscription",
+          line_items: [{ price: CONCURRENCY_PRICE_ID, quantity: 1 }],
+          automatic_tax: { enabled: true },
+          billing_address_collection: "required",
+          customer_update: { address: "auto", name: "auto" },
+          tax_id_collection: { enabled: true },
+          success_url: `${appOrigin()}/billing?slot_added=1&source=terminal`,
+          cancel_url: `${appOrigin()}/billing?slot_cancelled=1&source=terminal`
+        });
+        if (!session.url) return c.json({ error: "Stripe did not return a checkout URL." }, 502);
+        return c.json({
+          checkout_url: session.url,
+          price: upgrade,
+          concurrency: {
+            current_extra_slots: user.extra_concurrency_slots,
+            current_limit: concurrencyLimitForUser(user),
+            after_checkout_extra_slots: user.extra_concurrency_slots + 1,
+            after_checkout_limit: concurrencyLimitForUser({ extra_concurrency_slots: user.extra_concurrency_slots + 1 })
+          },
+          next_step: "Open checkout_url in a browser, complete checkout, then restart or retry the MCP request."
+        });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unable to start terminal checkout.";
+        console.error("[billing/concurrency/terminal-checkout]", message);
+        return c.json({ error: message }, 500);
+      }
+    });
     app.post("/billing/concurrency/cancel", requireAllowedOrigin, sessionAuth, async (c) => {
       const user = c.get("sessionUser");
       if (!user.concurrency_stripe_sub_id) return c.json({ error: "No active concurrency subscription." }, 404);
@@ -22237,9 +23433,10 @@ var init_server = __esm({
       if (!stripeSecret) return c.json({ error: "Stripe is not configured." }, 503);
       const stripeClient = new import_stripe2.default(stripeSecret, { apiVersion: STRIPE_API_VERSION });
       await stripeClient.subscriptions.cancel(user.concurrency_stripe_sub_id);
-      await setExtraConcurrencySlots(user.id, Math.max(0, user.extra_concurrency_slots - 1));
+      const nextSlots = Math.max(0, user.extra_concurrency_slots - 1);
+      await setExtraConcurrencySlots(user.id, nextSlots);
       await setConcurrencySubId(user.id, null);
-      return c.json({ ok: true, concurrency_limit: user.extra_concurrency_slots });
+      return c.json({ ok: true, extra_concurrency_slots: nextSlots, concurrency_limit: 1 + nextSlots });
     });
     app.get("/billing/balance", auth2, async (c) => {
       const user = c.get("user");
@@ -22274,6 +23471,12 @@ var init_server = __esm({
         item: body.item ?? null,
         matched_cost: matchedCost ? (({ aliases, ...cost }) => cost)(matchedCost) : null,
         costs,
+        concurrency: {
+          current_extra_slots: user.extra_concurrency_slots,
+          current_limit: concurrencyLimitForUser(user),
+          has_subscription: !!user.concurrency_stripe_sub_id,
+          upgrade: concurrencySlotBillingInfo()
+        },
         ledger
       });
     });