unbrowse 3.0.2 → 3.1.0-experiments.5e7a7bb

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unbrowse",
-  "version": "3.0.2",
+  "version": "3.1.0-experiments.5e7a7bb",
   "description": "Reverse-engineer any website into reusable API skills. Zero-dep single binary with embedded browser engine.",
   "type": "module",
   "bin": {

package/runtime-src/api/browse-index.ts

@@ -1,6 +1,7 @@
 import { nanoid } from "nanoid";
 import { readFileSync } from "node:fs";
-import { extractEndpoints } from "../reverse-engineer/index.js";
+import { extractEndpoints, extractAuthHeaders } from "../reverse-engineer/index.js";
+import { enrichEndpointsWithTokenSources } from "../reverse-engineer/token-sources.js";
 import { buildSkillOperationGraph, inferEndpointSemantic } from "../graph/index.js";
 import { validateExtractionQuality } from "../execution/index.js";
 import { assessIntentResult } from "../intent-match.js";
@@ -10,6 +11,8 @@ import type { RawRequest } from "../capture/index.js";
 import { cachePublishedSkill, findExistingSkillForDomain } from "../client/index.js";
 import { mergeEndpoints } from "../marketplace/index.js";
 import { upsertDagEdgesFromOperationGraph } from "../orchestrator/dag-feedback.js";
+import { storeCredential } from "../vault/index.js";
+import { getRegistrableDomain } from "../domain.js";
 import {
   buildResolveCacheKey,
   domainSkillCache,
@@ -151,14 +154,25 @@ export async function cacheBrowseRequests(params: {
   sessionDomain: string;
   requests: RawRequest[];
   getPageHtml?: () => Promise<string>;
+  jsBundles?: Map<string, string>;
   intent?: string;
 }): Promise<BrowseIndexResult> {
-  const { sessionUrl, sessionDomain, requests, getPageHtml } = params;
+  const { sessionUrl, sessionDomain, requests, getPageHtml, jsBundles } = params;
   let domain: string;
   try { domain = new URL(sessionUrl).hostname; } catch { domain = sessionDomain; }
   const intent = params.intent ?? `browse ${domain}`;
 
   const rawEndpoints = extractEndpoints(requests, undefined, { pageUrl: sessionUrl, finalUrl: sessionUrl });
+
+  // Extract and persist auth headers (authorization, csrf, bearer tokens)
+  // so serverFetch can replay them. Use registrable domain for vault key
+  // so ads.x.com and ads-api.x.com share the same session.
+  const capturedAuthHeaders = extractAuthHeaders(requests);
+  if (Object.keys(capturedAuthHeaders).length > 0) {
+    const sessionKey = `${getRegistrableDomain(domain)}-session`;
+    await storeCredential(sessionKey, JSON.stringify({ headers: capturedAuthHeaders })).catch(() => {});
+  }
+
   if (rawEndpoints.length > 0) {
     const existingSkill = findExistingSkillForDomain(domain);
     let allExisting = existingSkill?.endpoints ?? [];
@@ -183,7 +197,6 @@ export async function cacheBrowseRequests(params: {
       for (const endpoint of mergedEndpoints) {
         if (!endpoint.description) endpoint.description = generateLocalDescription(endpoint);
       }
-
       const quickSkill: SkillManifest = {
         skill_id: existingSkill?.skill_id ?? nanoid(),
         version: "1.0.0",
@@ -202,6 +215,16 @@ export async function cacheBrowseRequests(params: {
         intents: Array.from(new Set([...(existingSkill?.intents ?? []), intent])),
       };
 
+      // Token source discovery: scan live HTML for tokens used in captured
+      // request headers and attach AuthTokenBinding entries so serverFetch
+      // can rescrape fresh tokens on replay.
+      try {
+        const html = getPageHtml ? await getPageHtml() : undefined;
+        if (html && html.startsWith("<")) {
+          enrichEndpointsWithTokenSources(quickSkill.endpoints, requests, html, jsBundles);
+        }
+      } catch { /* best-effort */ }
+
       const cacheKey = buildResolveCacheKey(domain, intent, sessionUrl);
       const scopedKey = scopedCacheKey("global", cacheKey);
       writeSkillSnapshot(scopedKey, quickSkill);
@@ -294,7 +317,6 @@ export async function cacheBrowseRequests(params: {
       operation_graph: buildSkillOperationGraph(allEndpoints),
       intents: [...new Set([...(existing?.intents ?? []), intent])],
     };
-
     const cacheKey = buildResolveCacheKey(domain, intent, sessionUrl);
     const scopedKey = scopedCacheKey("global", cacheKey);
     writeSkillSnapshot(scopedKey, skill);

package/runtime-src/api/routes.ts

@@ -2,7 +2,7 @@ import type { FastifyInstance } from "fastify";
 import * as kuri from "../kuri/client.js";
 import type { KuriHarEntry } from "../kuri/client.js";
 import { extractEndpoints, extractAuthHeaders } from "../reverse-engineer/index.js";
-import { INTERCEPTOR_SCRIPT, enrichPassiveCaptureRequests, injectInterceptor } from "../capture/index.js";
+import { INTERCEPTOR_SCRIPT, enrichPassiveCaptureRequests, injectInterceptor, collectInterceptedRequests } from "../capture/index.js";
 import { indexSkillLocally, mergeAgentReview, publishIndexedSkill, queueBackgroundIndex } from "../indexer/index.js";
 import { nanoid } from "nanoid";
 import type { ExecutionTrace, OrchestrationTiming, ProjectionOptions, SkillManifest } from "../types/index.js";
@@ -11,6 +11,7 @@ import { buildSkillOperationGraph, getEndpointDescriptionMetadata, getSkillChunk
 import { augmentEndpointsWithAgent } from "../graph/agent-augment.js";
 import { findExistingSkillForDomain, cachePublishedSkill } from "../client/index.js";
 import { storeCredential } from "../vault/index.js";
+import { getRegistrableDomain } from "../domain.js";
 import { generateLocalDescription, writeSkillSnapshot, buildResolveCacheKey, getDomainReuseKey, domainSkillCache, persistDomainCache, scopedCacheKey, snapshotPathForCacheKey, invalidateRouteCacheForDomain, summarizeSchema, extractSampleValues } from "../orchestrator/index.js";
 import { TRACE_VERSION, CODE_HASH, DEFAULT_BACKEND_URL, GIT_SHA, PACKAGE_VERSION } from "../version.js";
 import { promoteExplicitExecution, resolveAndExecute, type OrchestratorResult } from "../orchestrator/index.js";
@@ -135,7 +136,7 @@ function passiveIndexFromRequests(
       // 2. Extract and store auth credentials (cookies + sensitive headers)
       const capturedAuthHeaders = extractAuthHeaders(requests);
       if (Object.keys(capturedAuthHeaders).length > 0) {
-        const authKey = `${domain}-session`;
+        const authKey = `${getRegistrableDomain(domain)}-session`;
         await storeCredential(authKey, JSON.stringify({ headers: capturedAuthHeaders }));
       }
 
@@ -1178,11 +1179,9 @@ export async function registerRoutes(app: FastifyInstance) {
 
   async function restartBrowseCapture(session: BrowseSession): Promise<void> {
     const broker = brokerForSession(session);
-    const load = await broker.waitForLoad(session.tabId, 2_000).catch(() => null);
-    if (load && load.status === "timeout") {
-      session.harActive = false;
-      return;
-    }
+    // Start HAR + interceptor regardless of page load state — the page will load
+    // and HAR records all traffic from the moment it starts.
+    await broker.waitForLoad(session.tabId, 2_000).catch(() => null);
     await broker.networkEnable(session.tabId).catch(() => {});
     await broker.harStart(session.tabId).catch(() => {});
     await broker.scriptInject(session.tabId, INTERCEPTOR_SCRIPT).catch(() => {});
@@ -1234,11 +1233,23 @@ export async function registerRoutes(app: FastifyInstance) {
       harEntries,
       intent: `browse ${session.domain || profileName(session.url)}`,
     });
+
+    // Collect JS bundle bodies for token source scanning
+    const jsBundles = new Map<string, string>();
+    try {
+      const intercepted = await collectInterceptedRequests(session.tabId).catch(() => []);
+      for (const entry of intercepted) {
+        if (entry.is_js && entry.response_body && jsBundles.size < 20) {
+          jsBundles.set(entry.url, entry.response_body);
+        }
+      }
+    } catch { /* best-effort */ }
     const syncResult = await cacheBrowseRequests({
       sessionUrl: session.url,
       sessionDomain: session.domain,
       requests: allRequests,
       getPageHtml: () => brokerForSession(session).getPageHtml(session.tabId),
+      jsBundles: jsBundles.size > 0 ? jsBundles : undefined,
       intent: `browse ${session.domain || profileName(session.url)}`,
     });
 
@@ -1325,12 +1336,35 @@ export async function registerRoutes(app: FastifyInstance) {
 
         let cookiesInjected = 0;
         if (newDomain && newDomain !== session.domain) {
-          cookiesInjected = await importBrowserCookiesIntoTab(session.tabId, newDomain);
-          await loadAuthProfileBestEffort(session.tabId, newDomain, "browse_go");
+          // Check if the browser already has fresh session cookies for this domain.
+          // If so, skip vault/profile cookie injection — browser cookies are fresher
+          // and injecting stale vault cookies (e.g. JSESSIONID) causes HTTP 400 on
+          // sites like LinkedIn that validate CSRF alignment.
+          const browserHasFreshSession = await (async () => {
+            try {
+              const { extractBrowserCookies } = await import("../auth/browser-cookies.js");
+              const { cookies } = extractBrowserCookies(newDomain);
+              // Consider the session fresh if we have session-like cookies that aren't expired
+              const now = Date.now() / 1000;
+              return cookies.some((c) =>
+                (c.httpOnly || c.secure) && (!c.expires || c.expires > now),
+              );
+            } catch { return false; }
+          })();
+
+          if (browserHasFreshSession) {
+            // Import browser cookies via CDP (they're fresh from Chrome's jar)
+            cookiesInjected = await importBrowserCookiesIntoTab(session.tabId, newDomain);
+          } else {
+            // No fresh browser cookies — load from vault/auth profile
+            cookiesInjected = await importBrowserCookiesIntoTab(session.tabId, newDomain);
+            await loadAuthProfileBestEffort(session.tabId, newDomain, "browse_go");
+          }
         }
 
         await restartBrowseCapture(session);
 
+        await broker.navigate(session.tabId, url);
         await broker.navigate(session.tabId, url);
         const finalUrl = await broker.getCurrentUrl(session.tabId).catch(() => url);
         session.url = typeof finalUrl === "string" && finalUrl.startsWith("http") ? finalUrl : url;

package/runtime-src/browser/index.ts

@@ -10,6 +10,7 @@ import { buildSkillOperationGraph } from "../graph/index.js";
 import { augmentEndpointsWithAgent } from "../graph/agent-augment.js";
 import { findExistingSkillForDomain, cachePublishedSkill } from "../client/index.js";
 import { storeCredential } from "../vault/index.js";
+import { getRegistrableDomain } from "../domain.js";
 import {
   importBrowserCookiesIntoTab,
   loadAuthProfileBestEffort,
@@ -83,7 +84,7 @@ function passiveIndexHar(entries: KuriHarEntry[], pageUrl: string): void {
       // Store auth credentials
       const capturedAuthHeaders = extractAuthHeaders(requests);
       if (Object.keys(capturedAuthHeaders).length > 0) {
-        await storeCredential(`${domain}-session`, JSON.stringify({ headers: capturedAuthHeaders }));
+        await storeCredential(`${getRegistrableDomain(domain)}-session`, JSON.stringify({ headers: capturedAuthHeaders }));
       }
 
       // Merge with existing skill (never reduce endpoint count)

package/runtime-src/build-info.generated.ts

@@ -1,6 +1,6 @@
-export const BUILD_RELEASE_VERSION = "3.0.2";
-export const BUILD_GIT_SHA = "25aed2ccf282";
+export const BUILD_RELEASE_VERSION = "3.1.0-experiments.5e7a7bb";
+export const BUILD_GIT_SHA = "5e7a7bb949c1";
 export const BUILD_CODE_HASH = "1488fc1d92b7";
-export const BUILD_RELEASE_MANIFEST_BASE64 = "eyJzY2hlbWFfdmVyc2lvbiI6MSwicmVsZWFzZV92ZXJzaW9uIjoiMy4wLjIiLCJnaXRfc2hhIjoiMjVhZWQyY2NmMjgyIiwiY29kZV9oYXNoIjoiMTQ4OGZjMWQ5MmI3IiwidHJhY2VfdmVyc2lvbiI6IjE0ODhmYzFkOTJiN0AyNWFlZDJjY2YyODIiLCJpc3N1ZWRfYXQiOiIyMDI2LTA0LTA0VDE0OjExOjM3LjQ4NloifQ";
-export const BUILD_RELEASE_MANIFEST_SIGNATURE = "KPLG1erp1N-qP2bkczhQp8g-pod6ObDr845_DElQzdM";
-export const BUILD_DEFAULT_BACKEND_URL = "https://beta-api.unbrowse.ai";
+export const BUILD_RELEASE_MANIFEST_BASE64 = "eyJzY2hlbWFfdmVyc2lvbiI6MSwicmVsZWFzZV92ZXJzaW9uIjoiMy4xLjAtZXhwZXJpbWVudHMuNWU3YTdiYiIsImdpdF9zaGEiOiI1ZTdhN2JiOTQ5YzEiLCJjb2RlX2hhc2giOiIxNDg4ZmMxZDkyYjciLCJ0cmFjZV92ZXJzaW9uIjoiMTQ4OGZjMWQ5MmI3QDVlN2E3YmI5NDljMSIsImlzc3VlZF9hdCI6IjIwMjYtMDQtMDVUMTQ6NTY6MjkuNjY2WiJ9";
+export const BUILD_RELEASE_MANIFEST_SIGNATURE = "OuZD9NeemoStAyT3-MgMS3V3eeatbRMKkVY_J4_6nsM";
+export const BUILD_DEFAULT_BACKEND_URL = "https://unbrowse-backend-experiments.lewis-6d8.workers.dev";

package/runtime-src/capture/index.ts

@@ -30,6 +30,114 @@ const activeTabRegistry = new Set<string>();
 // Tracks tabs where scriptInject has been registered (persistent across navigations)
 const interceptorInjectedTabs = new Set<string>();
 
+// Tracks tabs where CDP-level document-start injection has been registered
+const cdpDocStartTabs = new Set<string>();
+
+/**
+ * Register a script via Chrome's Page.addScriptToEvaluateOnNewDocument CDP method directly.
+ * This runs BEFORE any page JS on every navigation — critical for catching early fetch() calls.
+ * Falls back silently if CDP is unavailable.
+ */
+export async function registerDocumentStartScript(tabId: string, source: string): Promise<boolean> {
+  if (cdpDocStartTabs.has(tabId)) return true;
+  const cdpPort = kuri.getCdpPort();
+  if (!cdpPort) return false;
+
+  try {
+    // Get the WebSocket URL for this tab
+    const resp = await fetch(`http://127.0.0.1:${cdpPort}/json`);
+    const targets = await resp.json() as Array<{ id: string; webSocketDebuggerUrl?: string }>;
+    const target = targets.find((t) => t.id === tabId);
+    if (!target?.webSocketDebuggerUrl) return false;
+
+    // Connect via WebSocket and send CDP command
+    const ws = new WebSocket(target.webSocketDebuggerUrl);
+    const result = await new Promise<boolean>((resolve) => {
+      const timeout = setTimeout(() => { ws.close(); resolve(false); }, 3000);
+      ws.onopen = () => {
+        ws.send(JSON.stringify({
+          id: 1,
+          method: "Page.addScriptToEvaluateOnNewDocument",
+          params: { source },
+        }));
+      };
+      ws.onmessage = (event) => {
+        try {
+          const msg = JSON.parse(String(event.data));
+          if (msg.id === 1) {
+            clearTimeout(timeout);
+            ws.close();
+            resolve(!msg.error);
+          }
+        } catch { /* ignore parse errors */ }
+      };
+      ws.onerror = () => { clearTimeout(timeout); ws.close(); resolve(false); };
+    });
+
+    if (result) {
+      cdpDocStartTabs.add(tabId);
+      log("capture", `document-start interceptor registered via direct CDP for tab ${tabId}`);
+    }
+    return result;
+  } catch {
+    return false;
+  }
+}
+
+// Tracks captured request headers from CDP Network events
+const cdpCapturedHeaders = new Map<string, Map<string, Record<string, string>>>();
+
+/**
+ * Enable CDP Network.requestWillBeSent listener to capture full request headers
+ * including auth headers that HAR/interceptor miss. Stores headers indexed by URL.
+ */
+export async function enableNetworkHeaderCapture(tabId: string): Promise<void> {
+  const cdpPort = kuri.getCdpPort();
+  if (!cdpPort) return;
+
+  try {
+    const resp = await fetch(`http://127.0.0.1:${cdpPort}/json`);
+    const targets = await resp.json() as Array<{ id: string; webSocketDebuggerUrl?: string }>;
+    const target = targets.find((t) => t.id === tabId);
+    if (!target?.webSocketDebuggerUrl) return;
+
+    const headers = new Map<string, Record<string, string>>();
+    cdpCapturedHeaders.set(tabId, headers);
+
+    const ws = new WebSocket(target.webSocketDebuggerUrl);
+    ws.onopen = () => {
+      // Enable network domain (may already be enabled, that's OK)
+      ws.send(JSON.stringify({ id: 1, method: "Network.enable", params: {} }));
+    };
+    ws.onmessage = (event) => {
+      try {
+        const msg = JSON.parse(String(event.data));
+        if (msg.method === "Network.requestWillBeSent") {
+          const req = msg.params?.request;
+          if (req?.url && req?.headers) {
+            // Only capture headers for API-like URLs
+            if (/\/(api|graphql|v\d+)\b/i.test(req.url) || /ads-api|voyager/i.test(req.url)) {
+              headers.set(req.url, req.headers);
+            }
+          }
+        }
+      } catch { /* ignore */ }
+    };
+    // Keep ws alive — it will be cleaned up when tab closes
+    ws.onerror = () => { cdpCapturedHeaders.delete(tabId); };
+
+    log("capture", `CDP network header capture enabled for tab ${tabId}`);
+  } catch { /* best-effort */ }
+}
+
+/**
+ * Get captured request headers for a tab. Returns a map of URL → headers.
+ * These come from CDP Network.requestWillBeSent which includes auth headers
+ * that HAR and the JS interceptor miss.
+ */
+export function getCapturedNetworkHeaders(tabId: string): Map<string, Record<string, string>> {
+  return cdpCapturedHeaders.get(tabId) ?? new Map();
+}
 // Hard timeout per capture: 90s prevents stuck tabs from holding slots forever
 const CAPTURE_TIMEOUT_MS = 90_000;
 const CAPTURE_NAV_TIMEOUT_MS = 20_000;
@@ -376,6 +484,11 @@ export const INTERCEPTOR_SCRIPT = `(function() {
     var method = (opts.method || 'GET').toUpperCase();
     var reqBody = opts.body ? String(opts.body).substring(0, MAX_BODY) : undefined;
     var reqHeaders = {};
+    // Extract headers from Request object (first arg)
+    if (args[0] && typeof args[0] === 'object' && args[0].headers && typeof args[0].headers.forEach === 'function') {
+      args[0].headers.forEach(function(v, k) { reqHeaders[k] = v; });
+    }
+    // Override/merge with explicit opts.headers (second arg)
     if (opts.headers) {
       if (typeof opts.headers.forEach === 'function') {
         opts.headers.forEach(function(v, k) { reqHeaders[k] = v; });

package/runtime-src/cli.ts

@@ -13,10 +13,15 @@ import {
   detectTelemetryHostType,
   ensureCliInstallTracked,
   ensureRegistered,
+  getAgentId,
   getApiKey,
+  getCreatorEarnings,
+  getMyProfile,
+  getTransactionHistory,
   recordFunnelTelemetryEvent,
   recordInstallTelemetryEvent,
 } from "./client/index.js";
+import { appendImpact, getImpactLogPath, impactFromResult, readImpactSummary } from "./impact-log.js";
 import { findSitePack, findTask, allSitePacks, buildDepsGraph, planExecution, buildDepsMetadata, type SitePack } from "./cli/shortcuts.js";
 import { ensureLocalServer, checkServerVersion, stopServer, restartServer } from "./runtime/local-server.js";
 import { isBundledVirtualEntrypoint, isMainModule, resolveSiblingEntrypoint, runtimeArgsForEntrypoint } from "./runtime/paths.js";
@@ -30,6 +35,7 @@ loadEnv({ path: ".env.runtime", quiet: true });
 
 const BASE_URL = process.env.UNBROWSE_URL || "http://localhost:6969";
 const CLI_CLIENT_ID = process.env.UNBROWSE_CLIENT_ID || `cli-${process.ppid || process.pid}`;
+let walletNudgeShown = false;
 
 // ---------------------------------------------------------------------------
 // Arg parser
@@ -184,6 +190,14 @@ function formatSavedDuration(ms: number): string {
   return `${ms}ms`;
 }
 
+function formatCostUsd(uc: number): string {
+  // uc = micro-USD (1e-6 USD). 1M uc = $1.
+  const usd = uc / 1_000_000;
+  if (usd >= 1) return `$${usd.toFixed(2)}`;
+  if (usd >= 0.01) return `$${usd.toFixed(3)}`;
+  return `$${usd.toFixed(4)}`;
+}
+
 function emitImpactSummary(result: Record<string, unknown>): void {
   const impact = result.impact as Record<string, unknown> | undefined;
   if (!impact) return;
@@ -192,12 +206,14 @@ function emitImpactSummary(result: Record<string, unknown>): void {
   const tokensSaved = typeof impact.tokens_saved === "number" ? impact.tokens_saved : 0;
   const timeSavedPct = typeof impact.time_saved_pct === "number" ? impact.time_saved_pct : 0;
   const tokensSavedPct = typeof impact.tokens_saved_pct === "number" ? impact.tokens_saved_pct : 0;
+  const costSavedUc = typeof impact.cost_saved_uc === "number" ? impact.cost_saved_uc : 0;
   const browserAvoided = impact.browser_avoided === true;
-  if (timeSavedMs <= 0 && tokensSaved <= 0 && !browserAvoided) return;
+  if (timeSavedMs <= 0 && tokensSaved <= 0 && costSavedUc <= 0 && !browserAvoided) return;
 
   const parts: string[] = [];
   if (timeSavedMs > 0) parts.push(`${formatSavedDuration(timeSavedMs)} saved (${timeSavedPct}% faster)`);
   if (tokensSaved > 0) parts.push(`${tokensSaved.toLocaleString("en-US")} tokens saved (${tokensSavedPct}% less context)`);
+  if (costSavedUc > 0) parts.push(`${formatCostUsd(costSavedUc)} saved`);
   if (browserAvoided) parts.push("browser avoided");
   info(parts.join(" • "));
 }
@@ -370,10 +386,27 @@ async function cmdResolve(flags: Record<string, string | boolean>): Promise<void
 
     result = slimTrace(result);
     emitImpactSummary(result);
+    {
+      const entry = impactFromResult("resolve", result, { intent, domain, });
+      if (entry) appendImpact(entry);
+    }
     emitNextActionSummary(result);
 
     const skill = result.skill as Record<string, unknown> | undefined;
     const trace = result.trace as Record<string, unknown> | undefined;
+
+    // Nudge wallet setup after successful resolve that indexed routes
+    if (trace?.success && !walletNudgeShown) {
+      try {
+        const { checkWalletConfigured } = await import("./payments/wallet.js");
+        const wallet = checkWalletConfigured();
+        if (!wallet.configured) {
+          info("You're indexing routes but have no payout wallet. Run: npx @crossmint/lobster-cli setup");
+          walletNudgeShown = true;
+        }
+      } catch (_e) { /* non-fatal */ }
+    }
+
     if (skill?.skill_id && trace) {
       (result as Record<string, unknown>)._feedback = `unbrowse feedback --skill ${skill.skill_id} --endpoint ${trace.endpoint_id || "?"} --rating <1-5>`;
     }
@@ -548,6 +581,13 @@ async function cmdExecute(flags: Record<string, string | boolean>): Promise<void
     // Strip metadata bloat
     result = slimTrace(result);
     emitImpactSummary(result);
+    {
+      const entry = impactFromResult("execute", result, {
+        skill_id: skillId,
+        endpoint_id: typeof flags.endpoint === "string" ? flags.endpoint : undefined,
+      });
+      if (entry) appendImpact(entry);
+    }
     emitNextActionSummary(result);
 
     const pathFlag = flags.path as string | undefined;
@@ -812,6 +852,18 @@ async function cmdSetup(flags: Record<string, string | boolean>): Promise<void>
     }
   }
 
+  // Wallet status — tell the user if they're missing payout config
+  if (report.wallet.configured) {
+    info(`Wallet configured (${report.wallet.provider}): ${(report.wallet as Record<string, unknown>).wallet_address ?? "linked"}`);
+  } else if ((report.wallet as Record<string, unknown>).lobster_installed) {
+    info("Wallet not paired — your indexed routes won't earn payouts.");
+    info("Run: npx @crossmint/lobster-cli setup");
+  } else {
+    info("No wallet configured — you're indexing routes for free.");
+    info("Set up a wallet so you earn when agents use your routes:");
+    info("  npx @crossmint/lobster-cli setup");
+  }
+
   await recordInstallTelemetryEvent("setup", {
     hostType,
     status: report.browser_engine.action === "failed" ? "failed" : "installed",
@@ -913,6 +965,7 @@ export const CLI_REFERENCE = {
     { name: "forward", usage: "[--session id]", desc: "Navigate forward" },
     { name: "sync", usage: "[--session id]", desc: "Checkpoint current capture, keep tab open, queue background index + publish, then inspect via skill/publish review" },
     { name: "close", usage: "[--session id]", desc: "Checkpoint capture, queue background index + publish, close browse session, then inspect via skill/publish review" },
+    { name: "stats", usage: "[--json] [--pretty]", desc: "Show lifetime time/tokens/cost saved and marketplace earnings/spending" },
   ],
   globalFlags: [
     { flag: "--pretty", desc: "Indented JSON output" },
@@ -954,6 +1007,139 @@ export const CLI_REFERENCE = {
   ],
 };
 
+
+// ---------------------------------------------------------------------------
+// stats — show lifetime impact (savings + earnings) for the current agent
+// ---------------------------------------------------------------------------
+
+function formatTotalDuration(ms: number): string {
+  if (ms >= 3_600_000) return `${(ms / 3_600_000).toFixed(1)}h`;
+  if (ms >= 60_000) return `${(ms / 60_000).toFixed(1)}m`;
+  if (ms >= 1000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${ms}ms`;
+}
+
+async function cmdStats(flags: Record<string, string | boolean>): Promise<void> {
+  const pretty = !!flags.pretty;
+  const jsonOnly = !!flags.json;
+  const local = readImpactSummary();
+  const agentId = getAgentId();
+
+  type EarningsLedger = { total_earned_uc: number; total_earned_usd: number; transaction_count: number; last_transaction_at?: string } | null;
+  type SpendingLedger = { total_spent_uc: number; total_spent_usd: number; transaction_count: number; last_transaction_at?: string } | null;
+
+  let profile: Awaited<ReturnType<typeof getMyProfile>> | null = null;
+  let earnings: { ledger: EarningsLedger; transactions: unknown[] } | null = null;
+  let spending: { ledger: SpendingLedger; transactions: unknown[] } | null = null;
+  const remoteErrors: Record<string, string> = {};
+
+  if (agentId) {
+    const results = await Promise.allSettled([
+      getMyProfile(),
+      getCreatorEarnings(agentId),
+      getTransactionHistory(agentId),
+    ]);
+    if (results[0].status === "fulfilled") profile = results[0].value;
+    else remoteErrors.profile = (results[0].reason as Error)?.message ?? String(results[0].reason);
+    if (results[1].status === "fulfilled") earnings = results[1].value as { ledger: EarningsLedger; transactions: unknown[] };
+    else remoteErrors.earnings = (results[1].reason as Error)?.message ?? String(results[1].reason);
+    if (results[2].status === "fulfilled") spending = results[2].value as { ledger: SpendingLedger; transactions: unknown[] };
+    else remoteErrors.spending = (results[2].reason as Error)?.message ?? String(results[2].reason);
+  } else {
+    remoteErrors.profile = "No agent_id in local config. Run `unbrowse setup` to register.";
+  }
+
+  const earnedUsd = earnings?.ledger?.total_earned_usd ?? 0;
+  const spentUsd = spending?.ledger?.total_spent_usd ?? 0;
+  const netUsd = earnedUsd - spentUsd;
+  const savedUsd = local.total_cost_saved_uc / 1_000_000;
+
+  const payload = {
+    agent_id: agentId,
+    profile,
+    impact: {
+      total_runs: local.total_runs,
+      successful_runs: local.successful_runs,
+      browser_avoided_runs: local.browser_avoided_runs,
+      total_time_saved_ms: local.total_time_saved_ms,
+      total_time_saved_human: formatTotalDuration(local.total_time_saved_ms),
+      total_tokens_saved: local.total_tokens_saved,
+      total_cost_saved_usd: Number(savedUsd.toFixed(6)),
+      avg_time_saved_pct: local.avg_time_saved_pct,
+      avg_tokens_saved_pct: local.avg_tokens_saved_pct,
+      by_source: local.by_source,
+      first_entry_at: local.first_entry_at,
+      last_entry_at: local.last_entry_at,
+      log_path: getImpactLogPath(),
+    },
+    earnings: {
+      total_earned_usd: earnedUsd,
+      total_earned_uc: earnings?.ledger?.total_earned_uc ?? 0,
+      transaction_count: earnings?.ledger?.transaction_count ?? 0,
+      last_transaction_at: earnings?.ledger?.last_transaction_at ?? null,
+    },
+    spending: {
+      total_spent_usd: spentUsd,
+      total_spent_uc: spending?.ledger?.total_spent_uc ?? 0,
+      transaction_count: spending?.ledger?.transaction_count ?? 0,
+      last_transaction_at: spending?.ledger?.last_transaction_at ?? null,
+    },
+    net_usd: netUsd,
+    ...(Object.keys(remoteErrors).length > 0 ? { remote_errors: remoteErrors } : {}),
+  };
+
+  if (jsonOnly) {
+    output(payload, pretty);
+    return;
+  }
+
+  // Human-readable view (to stderr like other info) + JSON to stdout for piping.
+  const lines: string[] = [];
+  lines.push("Unbrowse stats");
+  lines.push(`  agent_id: ${agentId ?? "(not registered — run `unbrowse setup`)"}`);
+  if (profile?.name) lines.push(`  name: ${profile.name}`);
+  lines.push("");
+  lines.push("Impact (local, this machine):");
+  if (local.total_runs === 0) {
+    lines.push("  No resolve/execute runs recorded yet.");
+    lines.push(`  Log file: ${getImpactLogPath()}`);
+  } else {
+    lines.push(`  Runs: ${local.total_runs} (${local.successful_runs} successful, ${local.browser_avoided_runs} browser-avoided)`);
+    if (local.total_time_saved_ms > 0) {
+      lines.push(`  Time saved: ${formatTotalDuration(local.total_time_saved_ms)} (avg ${local.avg_time_saved_pct}% faster)`);
+    }
+    if (local.total_tokens_saved > 0) {
+      lines.push(`  Tokens saved: ${local.total_tokens_saved.toLocaleString("en-US")} (avg ${local.avg_tokens_saved_pct}% less context)`);
+    }
+    if (savedUsd > 0) {
+      lines.push(`  Cost saved: ${formatCostUsd(local.total_cost_saved_uc)}`);
+    }
+    if (Object.keys(local.by_source).length > 0) {
+      const topSources = Object.entries(local.by_source)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(", ");
+      lines.push(`  By source: ${topSources}`);
+    }
+  }
+  lines.push("");
+  lines.push("Money (backend ledger):");
+  if (!agentId) {
+    lines.push("  (not registered — earnings/spending unavailable)");
+  } else if (remoteErrors.earnings || remoteErrors.spending) {
+    if (remoteErrors.earnings) lines.push(`  earnings: error — ${remoteErrors.earnings}`);
+    if (remoteErrors.spending) lines.push(`  spending: error — ${remoteErrors.spending}`);
+  } else {
+    lines.push(`  Earned:  $${earnedUsd.toFixed(4)} (${earnings?.ledger?.transaction_count ?? 0} payouts)`);
+    lines.push(`  Spent:   $${spentUsd.toFixed(4)} (${spending?.ledger?.transaction_count ?? 0} payments)`);
+    lines.push(`  Net:     ${netUsd >= 0 ? "+" : ""}$${netUsd.toFixed(4)}`);
+  }
+  lines.push("");
+  info(lines.join("\n"));
+  output(payload, pretty);
+}
+
 function printHelp(): void {
   const r = CLI_REFERENCE;
   const lines: string[] = ["unbrowse \u2014 shell-safe CLI for the local API", ""];
@@ -1463,6 +1649,7 @@ async function main(): Promise<void> {
   if (command === "restart") return cmdRestart(flags);
   if (command === "upgrade" || command === "update") return cmdUpgrade(flags);
   if (command === "connect-chrome") return cmdConnectChrome();
+  if (command === "stats") return cmdStats(flags);
 
   // --- Shortcut resolution: unbrowse <site> [task] [flags] ---
   const KNOWN_COMMANDS = new Set([
@@ -1471,7 +1658,7 @@ async function main(): Promise<void> {
     "status", "stop", "restart", "upgrade", "update",
     "go", "submit", "snap", "click", "fill", "type", "press", "select", "scroll",
     "screenshot", "text", "markdown", "cookies", "eval", "back", "forward", "sync", "close",
-    "connect-chrome",
+    "connect-chrome", "stats",
   ]);
 
   if (!KNOWN_COMMANDS.has(command)) {
@@ -1533,6 +1720,7 @@ async function main(): Promise<void> {
     case "sync": return cmdSync(flags);
     case "close": return cmdClose(flags);
     case "connect-chrome": return cmdConnectChrome();
+    case "stats": return cmdStats(flags);
     default: info(`Unknown command: ${command}`); printHelp(); process.exit(1);
   }
 }