mcp-scraper 0.21.2 → 0.21.3

package/dist/bin/api-server.cjs

@@ -3602,6 +3602,7 @@ __export(db_exports, {
   creditMc: () => creditMc,
   deactivateUser: () => deactivateUser,
   debitMc: () => debitMc,
+  debitMcIdempotent: () => debitMcIdempotent,
   deleteWorkflowSchedule: () => deleteWorkflowSchedule,
   expireOldLots: () => expireOldLots,
   failJob: () => failJob,
@@ -3918,6 +3919,19 @@ async function migrate() {
   `);
   await db.execute(`CREATE INDEX IF NOT EXISTS billing_events_user_created_at ON billing_events(user_id, created_at DESC)`);
   await db.execute(`CREATE INDEX IF NOT EXISTS billing_events_authorization ON billing_events(authorization_id)`);
+  await db.execute(`
+    CREATE TABLE IF NOT EXISTS billing_debits (
+      idempotency_key TEXT PRIMARY KEY,
+      user_id         INTEGER NOT NULL REFERENCES users(id),
+      amount_mc       INTEGER NOT NULL,
+      operation       TEXT NOT NULL,
+      description     TEXT,
+      status          TEXT NOT NULL DEFAULT 'claimed',
+      created_at      TEXT NOT NULL DEFAULT (datetime('now')),
+      applied_at      TEXT
+    )
+  `);
+  await db.execute(`CREATE INDEX IF NOT EXISTS billing_debits_user_status ON billing_debits(user_id, status)`);
   await db.execute(`
     CREATE TABLE IF NOT EXISTS site_audit_jobs (
       id            TEXT    PRIMARY KEY,
@@ -5289,6 +5303,72 @@ async function debitMc(userId, mc, operation, description) {
   const res = await db.execute({ sql: "SELECT balance_mc FROM users WHERE id = ?", args: [userId] });
   return { ok: true, balance_mc: Number(res.rows[0]?.balance_mc ?? 0) };
 }
+async function debitMcIdempotent(userId, mc, operation, description, idempotencyKey) {
+  if (!Number.isSafeInteger(mc) || mc <= 0) throw new Error("idempotent debit amount must be a positive integer");
+  if (!idempotencyKey || idempotencyKey.length > 500) throw new Error("idempotent debit key is required and must be bounded");
+  const db = getDb();
+  await ensureMigrated(userId);
+  const results = await db.batch([
+    {
+      sql: "UPDATE billing_debits SET amount_mc = ?, description = ? WHERE idempotency_key = ? AND user_id = ? AND operation = ? AND status = 'claimed'",
+      args: [mc, description, idempotencyKey, userId, operation]
+    },
+    {
+      sql: "INSERT OR IGNORE INTO billing_debits (idempotency_key, user_id, amount_mc, operation, description, status) VALUES (?, ?, ?, ?, ?, 'claimed')",
+      args: [idempotencyKey, userId, mc, operation, description]
+    },
+    {
+      sql: "UPDATE users SET balance_mc = balance_mc - ? WHERE id = ? AND balance_mc >= ? AND EXISTS (SELECT 1 FROM billing_debits WHERE idempotency_key = ? AND user_id = ? AND amount_mc = ? AND operation = ? AND status = 'claimed')",
+      args: [mc, userId, mc, idempotencyKey, userId, mc, operation]
+    },
+    {
+      sql: "UPDATE billing_debits SET status = 'applying' WHERE idempotency_key = ? AND user_id = ? AND amount_mc = ? AND operation = ? AND status = 'claimed' AND changes() = 1",
+      args: [idempotencyKey, userId, mc, operation]
+    },
+    {
+      sql: `WITH ordered AS MATERIALIZED (
+              SELECT id,
+                     remaining_mc,
+                     COALESCE(SUM(remaining_mc) OVER (
+                       ORDER BY expires_at ASC, granted_at ASC, id ASC
+                       ROWS BETWEEN UNBOUNDED PRECEDING AND 1 PRECEDING
+                     ), 0) AS prior_mc
+              FROM credit_lots
+              WHERE user_id = ? AND remaining_mc > 0 AND expires_at > datetime('now')
+            ), allocation AS (
+              SELECT id, MIN(remaining_mc, MAX(0, ? - prior_mc)) AS take_mc
+              FROM ordered
+            )
+            UPDATE credit_lots
+            SET remaining_mc = remaining_mc - COALESCE((SELECT take_mc FROM allocation WHERE allocation.id = credit_lots.id), 0)
+            WHERE id IN (SELECT id FROM allocation WHERE take_mc > 0)
+              AND EXISTS (SELECT 1 FROM billing_debits WHERE idempotency_key = ? AND status = 'applying')`,
+      args: [userId, mc, idempotencyKey]
+    },
+    {
+      sql: "INSERT INTO ledger (user_id, amount_mc, operation, description) SELECT user_id, -amount_mc, operation, description FROM billing_debits WHERE idempotency_key = ? AND status = 'applying'",
+      args: [idempotencyKey]
+    },
+    {
+      sql: "UPDATE billing_debits SET status = 'applied', applied_at = datetime('now') WHERE idempotency_key = ? AND status = 'applying'",
+      args: [idempotencyKey]
+    }
+  ], "write");
+  const claim = await db.execute({
+    sql: "SELECT user_id, amount_mc, operation, status FROM billing_debits WHERE idempotency_key = ? LIMIT 1",
+    args: [idempotencyKey]
+  });
+  const row = claim.rows[0];
+  if (!row || Number(row.user_id) !== userId || Number(row.amount_mc) !== mc || String(row.operation) !== operation) {
+    throw new Error("idempotent debit key conflicts with another debit");
+  }
+  const balance = await db.execute({ sql: "SELECT balance_mc FROM users WHERE id = ?", args: [userId] });
+  return {
+    ok: String(row.status) === "applied",
+    balance_mc: Number(balance.rows[0]?.balance_mc ?? 0),
+    duplicate: results[2]?.rowsAffected === 0 && String(row.status) === "applied"
+  };
+}
 async function getLedger(userId, limit = 50) {
   const res = await getDb().execute({
     sql: "SELECT * FROM ledger WHERE user_id = ? ORDER BY created_at DESC LIMIT ?",
@@ -8496,6 +8576,18 @@ function vendorCostUsdToMc(costUsd, markupBps) {
   if (mc > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error("calculated mc exceeds the safe integer range");
   return Number(mc);
 }
+function getPublicRatesPayload() {
+  const starter = SUBSCRIPTION_TIER_BY_KEY.starter;
+  const costs = CREDIT_COST_CATALOG.map(({ aliases, ...cost }) => ({
+    ...cost,
+    ...cost.notes ? { notes: cost.notes.replace(/ via fal\.ai/g, "") } : {}
+  }));
+  return {
+    creditsPerDollarStarter: Math.round(mcToCredits(starter.credits_mc) / starter.monthly_usd),
+    costs,
+    scheduling: SCHEDULED_ACTIONS_RATE_POLICY
+  };
+}
 function concurrencySlotBillingInfo() {
   const billingUrl = process.env.CONCURRENCY_BILLING_URL ?? "https://mcpscraper.dev/billing";
   return {
@@ -8525,12 +8617,14 @@ function insufficientBalanceResponse(balanceMc, requiredMc) {
     topup_url: topupUrl
   };
 }
-var MC_COSTS, MC_PER_BROWSER_MS, BROWSER_OPEN_MIN_BALANCE_MC, MC_PER_CREDIT, BILLING_MC_PER_USD_NUMERATOR, BILLING_MC_PER_USD_DENOMINATOR, BILLING_BASIS_POINTS, USD_NANOS, SCHEDULED_RUN_BASE_CREDITS, SCHEDULED_RUN_BASE_MC, SCHEDULED_AGENT_LLM_MARKUP_BPS, SCHEDULED_AGENT_LLM_MARKUP, SCHEDULED_RUN_DEFAULT_MAX_CREDITS, CREDIT_COST_CATALOG, CONCURRENCY_PRICE_ID, SUBSCRIPTION_TIERS, SUBSCRIPTION_TIER_BY_KEY, CONCURRENCY_SLOT_PRICE_USD, CONCURRENCY_SLOT_PRICE_CURRENCY, CONCURRENCY_SLOT_PRICE_INTERVAL, CONCURRENCY_SLOT_PRICE_LABEL, CONCURRENCY_SLOT_TERMINAL_COMMAND, FREE_SIGNUP_MC, MEMORY_FREE_QUOTA_BYTES, MEMORY_PLANS, MEMORY_PLAN_QUOTA, MEMORY_MARGIN_MULTIPLE, MEMORY_PRO_COST_BUDGET_USD, LedgerOperation, MEMORY_AI_MARGIN_MULTIPLE, SITE_AUDIT_LLM_MARGIN_MULTIPLE, VIDEO_ANALYSIS_LLM_MARGIN_MULTIPLE, MEDIA_TRANSCRIBE_MARGIN_MULTIPLE, MEDIA_TRANSCRIBE_HOLD_MC, MC_PER_USD;
+var MC_COSTS, MC_PER_BROWSER_MS, BROWSER_OPEN_MIN_BALANCE_MC, MC_PER_CREDIT, BILLING_MC_PER_USD_NUMERATOR, BILLING_MC_PER_USD_DENOMINATOR, BILLING_BASIS_POINTS, USD_NANOS, SCHEDULED_RUN_BASE_CREDITS, SCHEDULED_RUN_BASE_MC, SCHEDULED_AGENT_LLM_MARKUP_BPS, SCHEDULED_AGENT_LLM_MARKUP, SCHEDULED_RUN_DEFAULT_MAX_CREDITS, SCHEDULED_ACTIONS_RATE_POLICY, CREDIT_COST_CATALOG, CONCURRENCY_PRICE_ID, SUBSCRIPTION_TIERS, SUBSCRIPTION_TIER_BY_KEY, CONCURRENCY_SLOT_PRICE_USD, CONCURRENCY_SLOT_PRICE_CURRENCY, CONCURRENCY_SLOT_PRICE_INTERVAL, CONCURRENCY_SLOT_PRICE_LABEL, CONCURRENCY_SLOT_TERMINAL_COMMAND, FREE_SIGNUP_MC, MEMORY_FREE_QUOTA_BYTES, MEMORY_PLANS, MEMORY_PLAN_QUOTA, MEMORY_MARGIN_MULTIPLE, MEMORY_PRO_COST_BUDGET_USD, LedgerOperation, MEMORY_AI_MARGIN_MULTIPLE, SITE_AUDIT_LLM_MARGIN_MULTIPLE, VIDEO_ANALYSIS_LLM_MARGIN_MULTIPLE, MEDIA_TRANSCRIBE_MARGIN_MULTIPLE, MEDIA_TRANSCRIBE_HOLD_MC, MC_PER_USD;
 var init_rates = __esm({
   "src/api/rates.ts"() {
     "use strict";
     MC_COSTS = {
       serp: 100,
+      serp_headless: 400,
+      serp_headful: 1400,
       paa: 300,
       paa_base: 5500,
       page_scrape: 100,
@@ -8571,14 +8665,38 @@ var init_rates = __esm({
     SCHEDULED_AGENT_LLM_MARKUP_BPS = 15e3;
     SCHEDULED_AGENT_LLM_MARKUP = SCHEDULED_AGENT_LLM_MARKUP_BPS / BILLING_BASIS_POINTS;
     SCHEDULED_RUN_DEFAULT_MAX_CREDITS = 5e3;
+    SCHEDULED_ACTIONS_RATE_POLICY = {
+      billingMode: "credits",
+      entitlement: "paid_plan_included",
+      separateSubscriptionRequired: false,
+      chargeEvent: "started_occurrence",
+      runBaseCredits: SCHEDULED_RUN_BASE_CREDITS,
+      runBaseMc: SCHEDULED_RUN_BASE_MC,
+      llmCostMultiplier: SCHEDULED_AGENT_LLM_MARKUP,
+      llmCostMultiplierBps: SCHEDULED_AGENT_LLM_MARKUP_BPS,
+      modes: {
+        connection_sync: {
+          runBaseCredits: SCHEDULED_RUN_BASE_CREDITS,
+          modelCostBilling: "none",
+          modelCostMultiplier: 0
+        },
+        agent: {
+          runBaseCredits: SCHEDULED_RUN_BASE_CREDITS,
+          modelCostBilling: "actual_reported_cost",
+          modelCostProvider: "openrouter",
+          modelCostMultiplier: SCHEDULED_AGENT_LLM_MARKUP,
+          modelCostMultiplierBps: SCHEDULED_AGENT_LLM_MARKUP_BPS
+        }
+      }
+    };
     CREDIT_COST_CATALOG = [
       {
         key: "serp",
         label: "SERP search",
         aliases: ["search_serp", "serp", "google search", "organic results"],
-        credits: mcToCredits(MC_COSTS.serp),
-        unit: "per search",
-        notes: "Returns AI Overview, PAA snippet, videos, forums, and local pack."
+        credits: mcToCredits(MC_COSTS.serp_headless),
+        unit: "per search (headless); escalates to headful only when needed",
+        notes: `Returns AI Overview, PAA snippet, videos, forums, and local pack. Billed ${mcToCredits(MC_COSTS.serp_headless)} credits when served headless (the common case), ${mcToCredits(MC_COSTS.serp_headful)} credits if an anti-bot escalation forces headful mode (overestimate refunded).`
       },
       {
         key: "paa",
@@ -8818,6 +8936,7 @@ var init_rates = __esm({
       PAA: "paa",
       PAA_REFUND: "paa_refund",
       SERP: "serp",
+      SERP_REFUND: "serp_refund",
       REFUND: "refund",
       TRANSCRIPTION: "transcription",
       TRANSCRIPTION_HOLD: "transcription_hold",
@@ -11901,8 +12020,17 @@ var init_internal_memory_routes = __esm({
 });
 
 // src/api/scheduling-access.ts
+function schedulingAccessOverrides() {
+  return new Set(
+    (process.env.SCHEDULING_ACCESS_OVERRIDE_IDENTITIES ?? "").split(",").map((identity) => identity.trim().toLowerCase()).filter(Boolean)
+  );
+}
 function hasPaidSchedulingAccess(user) {
-  return typeof user.subscription_tier === "string" && user.subscription_tier.trim().length > 0;
+  const tier = typeof user.subscription_tier === "string" ? user.subscription_tier.trim() : "";
+  const subscriptionId = typeof user.subscription_id === "string" ? user.subscription_id.trim() : "";
+  if (tier && subscriptionId) return true;
+  const identity = typeof user.email === "string" ? user.email.trim().toLowerCase() : "";
+  return identity.length > 0 && schedulingAccessOverrides().has(identity);
 }
 function paidPlanRequiredPayload() {
   return {
@@ -11995,6 +12123,15 @@ function safeMetadata(value) {
   if (!value) return "{}";
   return JSON.stringify(value).slice(0, 4e3);
 }
+function metadataReason(row) {
+  if (!row.metadata) return void 0;
+  try {
+    const metadata = JSON.parse(row.metadata);
+    return typeof metadata.reason === "string" ? metadata.reason : void 0;
+  } catch {
+    return void 0;
+  }
+}
 function mapAuthorization(row, balanceMc) {
   return {
     id: row.id,
@@ -12023,23 +12160,28 @@ async function eventByKey(idempotencyKey) {
   });
   return result.rows[0] ? result.rows[0] : null;
 }
-function mapEvent(row, balanceMc, duplicate) {
-  let reason;
-  if (row.metadata) {
-    try {
-      const metadata = JSON.parse(row.metadata);
-      if (typeof metadata.reason === "string") reason = metadata.reason;
-    } catch {
-    }
-  }
+function mapStartEvent(row, balanceMc, duplicate) {
+  return {
+    id: row.id,
+    authorizationId: row.authorization_id,
+    status: "started",
+    amountMc: SCHEDULED_RUN_BASE_MC,
+    credits: SCHEDULED_RUN_BASE_MC / MC_PER_CREDIT,
+    balanceMc,
+    duplicate
+  };
+}
+function mapSettlementEvent(row, balanceMc, duplicate) {
   const rawNanos = row.raw_cost_usd_nanos == null ? null : Number(row.raw_cost_usd_nanos);
-  const modelMc = Math.max(0, Number(row.amount_mc) - SCHEDULED_RUN_BASE_MC);
+  const modelMc = Math.max(0, Number(row.amount_mc));
+  const amountMc = SCHEDULED_RUN_BASE_MC + modelMc;
+  const reason = metadataReason(row);
   return {
     id: row.id,
     authorizationId: row.authorization_id,
     status: row.status === "settled" ? "settled" : "cost_pending",
-    amountMc: Number(row.amount_mc),
-    credits: Number(row.amount_mc) / MC_PER_CREDIT,
+    amountMc,
+    credits: amountMc / MC_PER_CREDIT,
     baseMc: SCHEDULED_RUN_BASE_MC,
     modelMc,
     rawCostUsd: rawNanos == null ? null : rawNanos / USD_NANOS,
@@ -12061,7 +12203,7 @@ async function authorizeScheduledRun(args) {
     args: [user.id, SCHEDULED_RUN_BILLING_CLASS]
   });
   if (pending.rows.length > 0) {
-    throw new UnifiedBillingError("pending_cost", "a previous scheduled run has an unresolved cost", 409);
+    throw new UnifiedBillingError("pending_cost", "a previous scheduled run has an unresolved model cost", 409);
   }
   const existing = await getDb().execute({
     sql: "SELECT id, user_id, idempotency_key, status, minimum_amount_mc, maximum_amount_mc, token_hash, expires_at FROM billing_authorizations WHERE idempotency_key = ? LIMIT 1",
@@ -12070,14 +12212,9 @@ async function authorizeScheduledRun(args) {
   if (existing.rows[0]) {
     const row = existing.rows[0];
     if (Number(row.user_id) !== user.id) {
-      throw new UnifiedBillingError(
-        "invalid_request",
-        "the idempotency key is already in use by another billing identity",
-        409
-      );
+      throw new UnifiedBillingError("invalid_request", "the idempotency key is already in use by another billing identity", 409);
     }
-    const balanceMc2 = await reconcileBalanceMc(user.id, user.balance_mc);
-    return mapAuthorization(row, balanceMc2);
+    return mapAuthorization(row, await reconcileBalanceMc(user.id, user.balance_mc));
   }
   const maximumCredits = args.maximumCredits ?? SCHEDULED_RUN_DEFAULT_MAX_CREDITS;
   if (!Number.isFinite(maximumCredits) || maximumCredits < SCHEDULED_RUN_BASE_MC / MC_PER_CREDIT) {
@@ -12098,17 +12235,7 @@ async function authorizeScheduledRun(args) {
   const expiresAt = new Date(Date.now() + AUTHORIZATION_TTL_MS).toISOString();
   const inserted = await getDb().execute({
     sql: "INSERT OR IGNORE INTO billing_authorizations (id, user_id, idempotency_key, billing_class, status, minimum_amount_mc, maximum_amount_mc, token_hash, metadata, expires_at) VALUES (?, ?, ?, ?, 'authorized', ?, ?, ?, ?, ?)",
-    args: [
-      id,
-      user.id,
-      idempotencyKey,
-      SCHEDULED_RUN_BILLING_CLASS,
-      SCHEDULED_RUN_BASE_MC,
-      maximumMc,
-      tokenHash(token),
-      safeMetadata(args.metadata),
-      expiresAt
-    ]
+    args: [id, user.id, idempotencyKey, SCHEDULED_RUN_BILLING_CLASS, SCHEDULED_RUN_BASE_MC, maximumMc, tokenHash(token), safeMetadata(args.metadata), expiresAt]
   });
   if (inserted.rowsAffected === 0) {
     const raced = await getDb().execute({
@@ -12118,11 +12245,7 @@ async function authorizeScheduledRun(args) {
     if (!raced.rows[0]) throw new Error("billing authorization insert raced without a readable winner");
     const row = raced.rows[0];
     if (Number(row.user_id) !== user.id) {
-      throw new UnifiedBillingError(
-        "invalid_request",
-        "the idempotency key is already in use by another billing identity",
-        409
-      );
+      throw new UnifiedBillingError("invalid_request", "the idempotency key is already in use by another billing identity", 409);
     }
     return mapAuthorization(row, balanceMc);
   }
@@ -12139,180 +12262,235 @@ async function authorizeScheduledRun(args) {
     reservationMode: "balance_check"
   };
 }
-async function settleScheduledRun(args) {
-  const identity = normalizeIdentity(args.identity);
-  const user = await getUserByEmail(identity);
-  if (!user) throw new UnifiedBillingError("user_not_found", "billing identity was not found", 404);
-  const authorization = await authorizationById(args.authorizationId);
+async function startScheduledRun(args) {
+  const user = await resolveSchedulingUser(args.identity);
+  let authorization = await authorizationById(args.authorizationId);
   if (!authorization || Number(authorization.user_id) !== user.id) {
     throw new UnifiedBillingError("authorization_not_found", "billing authorization was not found", 404);
   }
   verifyToken(authorization, args.authorizationToken);
-  const settlementKey = authorization.id + ":settlement";
-  const existing = await eventByKey(settlementKey);
-  if (existing) {
-    const balanceMc = await reconcileBalanceMc(user.id, user.balance_mc);
-    if (existing.status === "settling") {
-      throw new UnifiedBillingError("settlement_in_progress", "scheduled-run settlement is already in progress", 409);
-    }
-    return mapEvent(existing, balanceMc, true);
+  const startKey = authorization.id + ":start";
+  const existing = await eventByKey(startKey);
+  if (existing?.status === "settled") {
+    await getDb().execute({
+      sql: "UPDATE billing_authorizations SET status = 'started' WHERE id = ? AND status IN ('authorized', 'starting')",
+      args: [authorization.id]
+    });
+    return mapStartEvent(existing, await reconcileBalanceMc(user.id, user.balance_mc), true);
   }
-  if (authorization.status !== "authorized") {
-    throw new UnifiedBillingError("authorization_closed", "billing authorization is no longer open", 409);
+  if (!hasPaidSchedulingAccess(user)) {
+    throw new UnifiedBillingError(PAID_PLAN_REQUIRED_CODE, PAID_PLAN_REQUIRED_MESSAGE, 403);
   }
-  if (Date.parse(authorization.expires_at) <= Date.now()) {
+  if (authorization.status === "authorized") {
+    if (Date.parse(authorization.expires_at) <= Date.now()) {
+      await getDb().execute({
+        sql: "UPDATE billing_authorizations SET status = 'expired' WHERE id = ? AND status = 'authorized'",
+        args: [authorization.id]
+      });
+      throw new UnifiedBillingError("authorization_expired", "billing authorization expired before execution started", 409);
+    }
     await getDb().execute({
-      sql: "UPDATE billing_authorizations SET status = 'expired' WHERE id = ? AND status = 'authorized'",
+      sql: "UPDATE billing_authorizations SET status = 'starting' WHERE id = ? AND status = 'authorized'",
       args: [authorization.id]
     });
-    throw new UnifiedBillingError("authorization_expired", "billing authorization expired before settlement", 409);
-  }
-  const rawCostUsd = args.rawCostUsd ?? null;
-  if (args.modelCostStatus === "reported" && (rawCostUsd == null || !Number.isFinite(rawCostUsd) || rawCostUsd < 0)) {
-    throw new UnifiedBillingError("invalid_request", "reported model cost must be a finite non-negative number", 400);
+    authorization = await authorizationById(authorization.id);
   }
-  if (args.modelCostStatus === "not_applicable" && rawCostUsd != null && rawCostUsd !== 0) {
-    throw new UnifiedBillingError("invalid_request", "not_applicable model cost cannot include a non-zero cost", 400);
+  if (!authorization || !["starting", "started"].includes(authorization.status)) {
+    throw new UnifiedBillingError("authorization_closed", "billing authorization is no longer startable", 409);
   }
-  const eventId = (0, import_node_crypto4.randomUUID)();
-  const rawCostNanos = rawCostUsd == null ? null : Math.round(rawCostUsd * USD_NANOS);
-  const modelMc = rawCostUsd == null ? 0 : vendorCostUsdToMc(rawCostUsd, SCHEDULED_AGENT_LLM_MARKUP_BPS);
-  const totalMc = SCHEDULED_RUN_BASE_MC + modelMc;
-  const pendingReason = args.modelCostStatus === "missing" ? "openrouter_cost_missing" : totalMc > Number(authorization.maximum_amount_mc) ? "max_credits_per_run_exceeded" : null;
-  if (pendingReason) {
+  const eventId = existing?.id ?? (0, import_node_crypto4.randomUUID)();
+  if (!existing) {
     await getDb().execute({
-      sql: "INSERT INTO billing_events (id, user_id, authorization_id, idempotency_key, billing_class, source_surface, status, amount_mc, raw_cost_usd_nanos, multiplier_bps, input_tokens, output_tokens, cached_tokens, model_steps, metadata) VALUES (?, ?, ?, ?, ?, ?, 'cost_pending', ?, ?, ?, ?, ?, ?, ?, ?)",
+      sql: "INSERT OR IGNORE INTO billing_events (id, user_id, authorization_id, idempotency_key, billing_class, source_surface, status, amount_mc, multiplier_bps, metadata) VALUES (?, ?, ?, ?, ?, ?, 'capturing', ?, ?, ?)",
       args: [
         eventId,
         user.id,
         authorization.id,
-        settlementKey,
+        startKey,
         SCHEDULED_RUN_BILLING_CLASS,
         SCHEDULED_RUN_SOURCE_SURFACE,
-        totalMc,
-        rawCostNanos,
+        SCHEDULED_RUN_BASE_MC,
         SCHEDULED_AGENT_LLM_MARKUP_BPS,
-        Math.max(0, Math.round(args.inputTokens ?? 0)),
-        Math.max(0, Math.round(args.outputTokens ?? 0)),
-        Math.max(0, Math.round(args.cachedTokens ?? 0)),
-        Math.max(0, Math.round(args.modelSteps ?? 0)),
-        safeMetadata({ ...args.metadata, reason: pendingReason })
+        safeMetadata({ ...args.metadata, billingPhase: "start", chargeMode: "base_capture" })
       ]
     });
-    await getDb().execute({
-      sql: "UPDATE billing_authorizations SET status = 'cost_pending', settled_at = datetime('now') WHERE id = ?",
-      args: [authorization.id]
-    });
-    return {
-      id: eventId,
-      authorizationId: authorization.id,
-      status: "cost_pending",
-      amountMc: totalMc,
-      credits: totalMc / MC_PER_CREDIT,
-      baseMc: SCHEDULED_RUN_BASE_MC,
-      modelMc,
-      rawCostUsd,
-      multiplierBps: SCHEDULED_AGENT_LLM_MARKUP_BPS,
-      balanceMc: await reconcileBalanceMc(user.id, user.balance_mc),
-      reason: pendingReason,
-      duplicate: false
-    };
-  }
-  const claimed = await getDb().execute({
-    sql: "INSERT OR IGNORE INTO billing_events (id, user_id, authorization_id, idempotency_key, billing_class, source_surface, status, amount_mc, raw_cost_usd_nanos, multiplier_bps, input_tokens, output_tokens, cached_tokens, model_steps, metadata) VALUES (?, ?, ?, ?, ?, ?, 'settling', ?, ?, ?, ?, ?, ?, ?, ?)",
-    args: [
-      eventId,
-      user.id,
-      authorization.id,
-      settlementKey,
-      SCHEDULED_RUN_BILLING_CLASS,
-      SCHEDULED_RUN_SOURCE_SURFACE,
-      totalMc,
-      rawCostNanos,
-      SCHEDULED_AGENT_LLM_MARKUP_BPS,
-      Math.max(0, Math.round(args.inputTokens ?? 0)),
-      Math.max(0, Math.round(args.outputTokens ?? 0)),
-      Math.max(0, Math.round(args.cachedTokens ?? 0)),
-      Math.max(0, Math.round(args.modelSteps ?? 0)),
-      safeMetadata(args.metadata)
-    ]
-  });
-  if (claimed.rowsAffected === 0) {
-    const raced = await eventByKey(settlementKey);
-    if (!raced) throw new Error("billing settlement raced without a readable winner");
-    if (raced.status === "settling") {
-      throw new UnifiedBillingError("settlement_in_progress", "scheduled-run settlement is already in progress", 409);
-    }
-    return mapEvent(raced, await reconcileBalanceMc(user.id, user.balance_mc), true);
   }
-  const debit = await debitMc(
+  const debit = await debitMcIdempotent(
     user.id,
-    totalMc,
+    SCHEDULED_RUN_BASE_MC,
     LedgerOperation.SCHEDULED_RUN,
-    "scheduled-run:" + authorization.id
+    "scheduled-run:" + authorization.id + ":base",
+    startKey
   );
   if (!debit.ok) {
-    const metadata = safeMetadata({ ...args.metadata, reason: "insufficient_credits_at_settlement" });
-    await getDb().execute({
-      sql: "UPDATE billing_events SET status = 'cost_pending', metadata = ? WHERE id = ?",
-      args: [metadata, eventId]
-    });
     await getDb().execute({
-      sql: "UPDATE billing_authorizations SET status = 'cost_pending', settled_at = datetime('now') WHERE id = ?",
+      sql: "UPDATE billing_authorizations SET status = 'authorized' WHERE id = ? AND status = 'starting'",
       args: [authorization.id]
     });
-    return {
-      id: eventId,
-      authorizationId: authorization.id,
-      status: "cost_pending",
-      amountMc: totalMc,
-      credits: totalMc / MC_PER_CREDIT,
-      baseMc: SCHEDULED_RUN_BASE_MC,
+    throw new UnifiedBillingError(
+      "insufficient_credits",
+      "the wallet could not capture the scheduled-run base charge",
+      402,
+      { balanceMc: debit.balance_mc, requiredMc: SCHEDULED_RUN_BASE_MC }
+    );
+  }
+  await getDb().execute({
+    sql: "UPDATE billing_events SET status = 'settled', settled_at = datetime('now') WHERE idempotency_key = ? AND status = 'capturing'",
+    args: [startKey]
+  });
+  await getDb().execute({
+    sql: "UPDATE billing_authorizations SET status = 'started' WHERE id = ? AND status IN ('authorized', 'starting', 'started')",
+    args: [authorization.id]
+  });
+  const started = await eventByKey(startKey);
+  if (!started) throw new Error("scheduled-run base capture completed without an event receipt");
+  return mapStartEvent(started, debit.balance_mc, debit.duplicate);
+}
+function validateModelCost(args) {
+  const rawCostUsd = args.rawCostUsd ?? null;
+  if (args.modelCostStatus === "reported" && (rawCostUsd == null || !Number.isFinite(rawCostUsd) || rawCostUsd < 0)) {
+    throw new UnifiedBillingError("invalid_request", "reported model cost must be a finite non-negative number", 400);
+  }
+  if (args.modelCostStatus === "not_applicable" && rawCostUsd != null && rawCostUsd !== 0) {
+    throw new UnifiedBillingError("invalid_request", "not_applicable model cost cannot include a non-zero cost", 400);
+  }
+  return rawCostUsd;
+}
+async function recoverSettlement(row, user, authorization, duplicate) {
+  const modelMc = Math.max(0, Number(row.amount_mc));
+  let balanceMc = await reconcileBalanceMc(user.id, user.balance_mc);
+  if (modelMc > 0) {
+    const debit = await debitMcIdempotent(
+      user.id,
       modelMc,
-      rawCostUsd,
-      multiplierBps: SCHEDULED_AGENT_LLM_MARKUP_BPS,
-      balanceMc: debit.balance_mc,
-      reason: "insufficient_credits_at_settlement",
-      duplicate: false
-    };
+      LedgerOperation.SCHEDULED_RUN,
+      "scheduled-run:" + authorization.id + ":model",
+      authorization.id + ":model"
+    );
+    balanceMc = debit.balance_mc;
+    if (!debit.ok) {
+      await getDb().execute({
+        sql: "UPDATE billing_events SET status = 'cost_pending', metadata = ? WHERE id = ? AND status = 'settling'",
+        args: [safeMetadata({ reason: "insufficient_credits_for_model_delta", billingPhase: "settlement", chargeMode: "model_delta" }), row.id]
+      });
+      await getDb().execute({
+        sql: "UPDATE billing_authorizations SET status = 'cost_pending' WHERE id = ? AND status IN ('started', 'cost_pending')",
+        args: [authorization.id]
+      });
+      const pending = await eventByKey(authorization.id + ":settlement");
+      if (!pending) throw new Error("scheduled-run pending settlement lost its event");
+      return mapSettlementEvent(pending, balanceMc, duplicate);
+    }
   }
   await getDb().execute({
-    sql: "UPDATE billing_events SET status = 'settled', settled_at = datetime('now') WHERE id = ?",
-    args: [eventId]
+    sql: "UPDATE billing_events SET status = 'settled', settled_at = datetime('now') WHERE id = ? AND status = 'settling'",
+    args: [row.id]
   });
   await getDb().execute({
-    sql: "UPDATE billing_authorizations SET status = 'settled', settled_at = datetime('now') WHERE id = ?",
+    sql: "UPDATE billing_authorizations SET status = 'settled', settled_at = datetime('now') WHERE id = ? AND status IN ('started', 'cost_pending', 'settled')",
     args: [authorization.id]
   });
-  return {
-    id: eventId,
-    authorizationId: authorization.id,
-    status: "settled",
-    amountMc: totalMc,
-    credits: totalMc / MC_PER_CREDIT,
-    baseMc: SCHEDULED_RUN_BASE_MC,
+  const settled = await eventByKey(authorization.id + ":settlement");
+  if (!settled) throw new Error("scheduled-run settlement completed without an event receipt");
+  return mapSettlementEvent(settled, balanceMc, duplicate);
+}
+async function settleScheduledRun(args) {
+  const user = await resolveSchedulingUser(args.identity);
+  let authorization = await authorizationById(args.authorizationId);
+  if (!authorization || Number(authorization.user_id) !== user.id) {
+    throw new UnifiedBillingError("authorization_not_found", "billing authorization was not found", 404);
+  }
+  verifyToken(authorization, args.authorizationToken);
+  const rawCostUsd = validateModelCost(args);
+  const startEvent = await eventByKey(authorization.id + ":start");
+  if (!startEvent || startEvent.status !== "settled") {
+    throw new UnifiedBillingError("authorization_closed", "scheduled-run settlement requires a captured start", 409);
+  }
+  if (authorization.status === "starting") {
+    await getDb().execute({
+      sql: "UPDATE billing_authorizations SET status = 'started' WHERE id = ? AND status = 'starting'",
+      args: [authorization.id]
+    });
+    authorization = await authorizationById(authorization.id);
+  }
+  if (!authorization || !["started", "cost_pending", "settled"].includes(authorization.status)) {
+    throw new UnifiedBillingError("authorization_closed", "billing authorization is not open for settlement", 409);
+  }
+  const settlementKey = authorization.id + ":settlement";
+  let existing = await eventByKey(settlementKey);
+  if (existing?.status === "settled") {
+    return mapSettlementEvent(existing, await reconcileBalanceMc(user.id, user.balance_mc), true);
+  }
+  if (existing?.status === "settling") {
+    return recoverSettlement(existing, user, authorization, true);
+  }
+  const hadExistingClaim = Boolean(existing);
+  const rawCostNanos = rawCostUsd == null ? null : Math.round(rawCostUsd * USD_NANOS);
+  const modelMc = rawCostUsd == null ? 0 : vendorCostUsdToMc(rawCostUsd, SCHEDULED_AGENT_LLM_MARKUP_BPS);
+  const maximumModelMc = Math.max(0, Number(authorization.maximum_amount_mc) - SCHEDULED_RUN_BASE_MC);
+  const pendingReason = args.modelCostStatus === "missing" ? "openrouter_cost_missing" : modelMc > maximumModelMc ? "max_credits_per_run_exceeded" : null;
+  const metadata = safeMetadata({
+    ...args.metadata,
+    billingPhase: "settlement",
+    chargeMode: "model_delta",
+    ...pendingReason ? { reason: pendingReason } : {}
+  });
+  const eventId = existing?.id ?? (0, import_node_crypto4.randomUUID)();
+  const status = pendingReason ? "cost_pending" : "settling";
+  const eventValues = [
     modelMc,
-    rawCostUsd,
-    multiplierBps: SCHEDULED_AGENT_LLM_MARKUP_BPS,
-    balanceMc: debit.balance_mc,
-    duplicate: false
-  };
+    rawCostNanos,
+    SCHEDULED_AGENT_LLM_MARKUP_BPS,
+    Math.max(0, Math.round(args.inputTokens ?? 0)),
+    Math.max(0, Math.round(args.outputTokens ?? 0)),
+    Math.max(0, Math.round(args.cachedTokens ?? 0)),
+    Math.max(0, Math.round(args.modelSteps ?? 0)),
+    metadata
+  ];
+  if (existing) {
+    await getDb().execute({
+      sql: "UPDATE billing_events SET status = ?, amount_mc = ?, raw_cost_usd_nanos = ?, multiplier_bps = ?, input_tokens = ?, output_tokens = ?, cached_tokens = ?, model_steps = ?, metadata = ?, settled_at = NULL WHERE id = ? AND status = 'cost_pending'",
+      args: [status, ...eventValues, existing.id]
+    });
+  } else {
+    await getDb().execute({
+      sql: "INSERT OR IGNORE INTO billing_events (id, user_id, authorization_id, idempotency_key, billing_class, source_surface, status, amount_mc, raw_cost_usd_nanos, multiplier_bps, input_tokens, output_tokens, cached_tokens, model_steps, metadata) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+      args: [eventId, user.id, authorization.id, settlementKey, SCHEDULED_RUN_BILLING_CLASS, SCHEDULED_RUN_SOURCE_SURFACE, status, ...eventValues]
+    });
+  }
+  existing = await eventByKey(settlementKey);
+  if (!existing) throw new Error("scheduled-run settlement claim was not readable");
+  const duplicateClaim = hadExistingClaim || eventId !== existing.id;
+  if (existing.status === "settled") {
+    return mapSettlementEvent(existing, await reconcileBalanceMc(user.id, user.balance_mc), true);
+  }
+  if (existing.status === "cost_pending") {
+    await getDb().execute({
+      sql: "UPDATE billing_authorizations SET status = 'cost_pending' WHERE id = ? AND status IN ('started', 'cost_pending')",
+      args: [authorization.id]
+    });
+    return mapSettlementEvent(existing, await reconcileBalanceMc(user.id, user.balance_mc), duplicateClaim);
+  }
+  if (existing.status !== "settling") {
+    throw new UnifiedBillingError("settlement_in_progress", "scheduled-run settlement could not be claimed", 409);
+  }
+  return recoverSettlement(existing, user, authorization, duplicateClaim);
 }
 async function voidScheduledRunAuthorization(args) {
-  const identity = normalizeIdentity(args.identity);
-  const user = await getUserByEmail(identity);
-  if (!user) throw new UnifiedBillingError("user_not_found", "billing identity was not found", 404);
+  const user = await resolveSchedulingUser(args.identity);
   const authorization = await authorizationById(args.authorizationId);
   if (!authorization || Number(authorization.user_id) !== user.id) {
     throw new UnifiedBillingError("authorization_not_found", "billing authorization was not found", 404);
   }
   verifyToken(authorization, args.authorizationToken);
   if (authorization.status === "authorized") {
-    await getDb().execute({
+    const result = await getDb().execute({
       sql: "UPDATE billing_authorizations SET status = 'void', metadata = ?, settled_at = datetime('now') WHERE id = ? AND status = 'authorized'",
       args: [safeMetadata({ reason: args.reason ?? "voided_before_execution" }), authorization.id]
     });
-    return { ok: true, status: "void" };
+    if (result.rowsAffected > 0) return { ok: true, status: "void" };
+    const raced = await authorizationById(authorization.id);
+    return { ok: true, status: raced?.status ?? "closed" };
   }
   return { ok: true, status: authorization.status };
 }
@@ -12326,7 +12504,7 @@ var init_unified_billing = __esm({
     init_scheduling_access();
     SCHEDULED_RUN_BILLING_CLASS = "scheduled_agent_run";
     SCHEDULED_RUN_SOURCE_SURFACE = "mastra_scheduler";
-    AUTHORIZATION_TTL_MS = 30 * 60 * 1e3;
+    AUTHORIZATION_TTL_MS = 24 * 60 * 60 * 1e3;
     UnifiedBillingError = class extends Error {
       constructor(code, message, httpStatus, details = {}) {
         super(message);
@@ -12551,7 +12729,7 @@ function billingError(error) {
     status: 500
   };
 }
-var import_hono3, import_zod12, internalBillingApp, metadataSchema, schedulingAccessSchema, authorizeSchema, settleSchema, voidSchema;
+var import_hono3, import_zod12, internalBillingApp, metadataSchema, schedulingAccessSchema, authorizeSchema, settleSchema, startSchema, voidSchema;
 var init_internal_billing_routes = __esm({
   "src/api/internal-billing-routes.ts"() {
     "use strict";
@@ -12585,6 +12763,12 @@ var init_internal_billing_routes = __esm({
       modelSteps: import_zod12.z.number().finite().nonnegative().optional(),
       metadata: metadataSchema
     });
+    startSchema = import_zod12.z.object({
+      identity: import_zod12.z.string().min(1).max(320),
+      authorizationId: import_zod12.z.string().uuid(),
+      authorizationToken: import_zod12.z.string().min(20).max(500),
+      metadata: metadataSchema
+    });
     voidSchema = import_zod12.z.object({
       identity: import_zod12.z.string().min(1).max(320),
       authorizationId: import_zod12.z.string().uuid(),
@@ -12658,6 +12842,19 @@ var init_internal_billing_routes = __esm({
         return c.json(response.body, response.status);
       }
     });
+    internalBillingApp.post("/scheduled-run/start", async (c) => {
+      const parsed = startSchema.safeParse(await c.req.json().catch(() => null));
+      if (!parsed.success) {
+        return c.json({ ok: false, error_code: "invalid_request", error: "invalid scheduled-run start request" }, 400);
+      }
+      try {
+        const start = await startScheduledRun(parsed.data);
+        return c.json({ ok: true, start });
+      } catch (error) {
+        const response = billingError(error);
+        return c.json(response.body, response.status);
+      }
+    });
     internalBillingApp.post("/scheduled-run/void", async (c) => {
       const parsed = voidSchema.safeParse(await c.req.json().catch(() => null));
       if (!parsed.success) {
@@ -12944,6 +13141,7 @@ var init_BrowserDriver = __esm({
           else if (config.headlessMode === "headless") useHeadless = true;
           else useHeadless = costCtx?.forceHeadless === true || process.env.KERNEL_HEADLESS_DISABLED !== "true" && !!costCtx?.op && HEADLESS_OPS.has(costCtx.op);
           this.kernelHeadlessSent = useHeadless ? true : null;
+          if (costCtx?.headlessSentOut) costCtx.headlessSentOut.value = this.kernelHeadlessSent;
           const kernelBrowser = await this.kernelClient.browsers.create({
             stealth: true,
             timeout_seconds: timeoutSeconds,
@@ -28499,7 +28697,7 @@ var PACKAGE_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    PACKAGE_VERSION = "0.21.2";
+    PACKAGE_VERSION = "0.21.3";
   }
 });
 
@@ -42307,8 +42505,9 @@ async function processJob(job) {
   running++;
   try {
     const opts = typeof job.options === "string" ? JSON.parse(job.options) : job.options;
+    const headlessSentOut = { value: null };
     const result = await runWithCostContext(
-      { op: opts.serpOnly ? "serp" : "paa", userId: Number(job.user_id) },
+      { op: opts.serpOnly ? "serp" : "paa", userId: Number(job.user_id), headlessSentOut },
       () => harvest({
         ...opts,
         kernelApiKey: browserServiceApiKey(),
@@ -42325,6 +42524,11 @@ async function processJob(job) {
       const diff = opts.billingHoldMc - actualCost;
       if (diff > 0) await creditMc(job.user_id, diff, "paa_refund", "overestimate refund");
       else if (diff < 0) await debitMc(job.user_id, -diff, "paa", opts.query ?? job.query);
+    } else if (opts.serpOnly && typeof opts.billingHoldMc === "number") {
+      const actualCost = headlessSentOut.value === true ? MC_COSTS.serp_headless : MC_COSTS.serp_headful;
+      const diff = opts.billingHoldMc - actualCost;
+      if (diff > 0) await creditMc(job.user_id, diff, "serp_refund", "headless-mode pricing settle");
+      else if (diff < 0) await debitMc(job.user_id, -diff, "serp", opts.query ?? job.query);
     }
     if (job.callback_url) {
       await deliverWebhook(job.callback_url, { job_id: job.id, status: "done", result, attempts });
@@ -42923,11 +43127,7 @@ var init_server = __esm({
       return c.json(CATALOG);
     });
     app.get("/rates", (c) => {
-      const costs = CREDIT_COST_CATALOG.map(({ aliases, ...cost }) => ({
-        ...cost,
-        ...cost.notes ? { notes: cost.notes.replace(/ via fal\.ai/g, "") } : {}
-      }));
-      return c.json({ creditsPerDollarStarter: Math.round(1 / 15e-5), costs });
+      return c.json(getPublicRatesPayload());
     });
     app.get("/me", async (c) => {
       const token = (0, import_cookie2.getCookie)(c, "session");
@@ -43842,7 +44042,7 @@ var init_server = __esm({
         serpOnly: body.serpOnly ?? false,
         pages: Math.min(2, Math.max(1, body.pages ?? 1))
       };
-      const harvestCost = options.serpOnly ? MC_COSTS.serp : paaCostForQuestionCount2(options.maxQuestions);
+      const harvestCost = options.serpOnly ? MC_COSTS.serp_headful : paaCostForQuestionCount2(options.maxQuestions);
       const { ok: harvestOk, balance_mc: harvestBal } = await debitMc(user.id, harvestCost, options.serpOnly ? LedgerOperation.SERP : LedgerOperation.PAA, options.query);
       if (!harvestOk) return c.json(insufficientBalanceResponse(harvestBal, harvestCost), 402);
       const jobId = await createJob(user.id, options.query, { ...options, billingHoldMc: harvestCost }, body.callback_url);
@@ -43878,7 +44078,7 @@ var init_server = __esm({
         serpOnly: body.serpOnly ?? false,
         pages: Math.min(2, Math.max(1, body.pages ?? 1))
       };
-      const syncCost = options.serpOnly ? MC_COSTS.serp : paaCostForQuestionCount2(options.maxQuestions);
+      const syncCost = options.serpOnly ? MC_COSTS.serp_headful : paaCostForQuestionCount2(options.maxQuestions);
       const { ok: syncOk, balance_mc: syncBal } = await debitMc(user.id, syncCost, options.serpOnly ? LedgerOperation.SERP : LedgerOperation.PAA, options.query);
       if (!syncOk) return c.json(insufficientBalanceResponse(syncBal, syncCost), 402);
       const jobId = await createRunningJob(user.id, options.query, options);
@@ -43888,10 +44088,11 @@ var init_server = __esm({
         c.req.raw.signal,
         AbortSignal.timeout(syncTimeoutMs)
       ]);
+      const headlessSentOut = { value: null };
       try {
         const harvestCtx = currentCostContext();
         const result = await runWithCostContext(
-          { ...harvestCtx, op: options.serpOnly ? "serp" : "paa", userId: user.id },
+          { ...harvestCtx, op: options.serpOnly ? "serp" : "paa", userId: user.id, headlessSentOut },
           () => harvest({
             ...options,
             kernelApiKey: browserServiceApiKey(),
@@ -43910,6 +44111,11 @@ var init_server = __esm({
           const diff = syncCost - actualCost;
           if (diff > 0) await creditMc(user.id, diff, LedgerOperation.PAA_REFUND, "overestimate refund");
           else if (diff < 0) await debitMc(user.id, -diff, LedgerOperation.PAA, options.query);
+        } else {
+          const actualCost = headlessSentOut.value === true ? MC_COSTS.serp_headless : MC_COSTS.serp_headful;
+          const diff = syncCost - actualCost;
+          if (diff > 0) await creditMc(user.id, diff, LedgerOperation.SERP_REFUND, "headless-mode pricing settle");
+          else if (diff < 0) await debitMc(user.id, -diff, LedgerOperation.SERP, options.query);
         }
         return c.json({ job_id: jobId, status: "done", result: sanitizeHarvestResult(result), attempts: sanitizeAttempts(attempts) });
       } catch (err) {