ebay-mcp-remote-edition 4.1.0 → 4.2.0

package/README.md

@@ -24,6 +24,9 @@ This project extends [Yosef Hayim's eBay MCP](https://github.com/YosefHayim/ebay
 - **Cloudflare KV / Upstash Redis** token and session storage for persistent multi-user auth
 - **Admin session management** — inspect, revoke, or delete sessions via authenticated endpoints
 - **TTL-aligned records** — every stored record (OAuth state, auth code, session, user token) carries an `expiresAt` timestamp and a matching KV/Redis TTL so storage and application expiry are always in sync
+- **Env-selected eBay Research session persistence** — the first-party research bootstrap/runtime can persist Playwright storage state to Cloudflare KV, Upstash KV, or explicit filesystem mode via `EBAY_RESEARCH_SESSION_STORE`
+- **QStash-triggered Telegram alerts for eBay Research session expiry** — bootstrap can schedule version-aware expiry callbacks that notify operators before first-party research auth silently degrades
+- **Alert-safe scheduling guardrails** — expiry callbacks are only scheduled when the callback URL is externally reachable and the research session store supports shared alert locks (`upstash-redis` or `filesystem`)
 
 ---
 
@@ -295,6 +298,24 @@ CLOUDFLARE_API_TOKEN=
 UPSTASH_REDIS_REST_URL=
 UPSTASH_REDIS_REST_TOKEN=
 
+# eBay Research session-expiry alerts (optional but recommended when using
+# first-party research in hosted mode)
+TELEGRAM_BOT_TOKEN=
+TELEGRAM_CHAT_ID=1574052684
+QSTASH_URL=
+QSTASH_TOKEN=
+QSTASH_CURRENT_SIGNING_KEY=
+QSTASH_NEXT_SIGNING_KEY=
+EBAY_RESEARCH_SESSION_ALERTS_ENABLED=true
+EBAY_RESEARCH_SESSION_ALERT_WINDOW_24H=true
+EBAY_RESEARCH_SESSION_ALERT_WINDOW_6H=true
+EBAY_RESEARCH_SESSION_ALERT_ON_EXPIRED=true
+EBAY_RESEARCH_SESSION_ALERT_CALLBACK_URL=
+
+# Alert scheduling additionally requires:
+# - PUBLIC_BASE_URL or EBAY_RESEARCH_SESSION_ALERT_CALLBACK_URL to be externally reachable
+# - EBAY_RESEARCH_SESSION_STORE=upstash-redis or filesystem
+
 # Security
 ADMIN_API_KEY=              # required for admin session endpoints
 OAUTH_START_KEY=            # optional; protects /oauth/start with a shared secret
@@ -358,7 +379,7 @@ Store eBay credentials in a mounted secret file rather than raw environment vari
 }
 ```
 
-### Deploy to Render
+### Deploy to Render / Railway / other Nixpacks hosts
 
 1. Connect your repo to Render as a **Web Service**
 2. Set **Build command:**
@@ -374,6 +395,12 @@ Store eBay credentials in a mounted secret file rather than raw environment vari
 
 The server starts on the port Render assigns via `$PORT` and logs the active KV backend on startup.
 
+For Nixpacks-based platforms such as Railway and Coolify:
+
+- The repository now includes `nixpacks.toml` so the generated image uses `pnpm install --frozen-lockfile`, runs `pnpm run build`, installs Chromium for the Playwright-backed validation paths, and starts with `pnpm run start:http`.
+- Runtime secrets should be configured in the platform dashboard as runtime environment variables or mounted secret files. Do not bake secrets into Docker build arguments or `ENV` layers.
+- Keep `pnpm-lock.yaml` committed and in sync with `package.json`; Nixpacks installs with a frozen lockfile.
+
 ### OAuth flows
 
 eBay requires a single registered callback URL per application. The hosted server registers `/oauth/callback` at the root and recovers the environment from the stored OAuth state record.
@@ -593,6 +620,7 @@ GET /health
 GET /whoami
 GET /sandbox/validation/health
 GET /production/validation/health
+POST /internal/ebay-research/check-session-expiry
 ```
 
 Recommended debugging flow:
@@ -600,6 +628,7 @@ Recommended debugging flow:
 1. Call `/health` to confirm the HTTP service is up.
 2. Call `/whoami` with a Bearer hosted session token to confirm the active hosted user session, bound environment, expiry, and revocation status.
 3. Call the matching env-scoped `/validation/health` route with `X-Admin-API-Key` to confirm the validation runner user is configured, stored tokens exist, and token refresh succeeds.
+4. The internal `POST /internal/ebay-research/check-session-expiry` route is reserved for signed QStash callbacks and should not be used as an unauthenticated public endpoint.
 
 `/whoami` is especially useful when an operator wants to verify which hosted session is currently active before registering or troubleshooting the validation runner user. Validation routes themselves still authenticate with the admin key and a stored hosted runner identity, not with MCP auth.
 
@@ -623,7 +652,7 @@ Provider behavior:
 - **Browse debug semantics:** validation debug now keeps browse candidate generation, selected query/tier, browse-specific sample size, and per-candidate result counts separate from sold-provider result counts so operators can tell whether the browse layer contributed a field, fell back to a weaker query, or returned no usable match.
 - **Sold provider:** [`src/validation/providers/ebay-sold.ts`](src/validation/providers/ebay-sold.ts) uses a temporary external sold-data source configured by `SOLD_ITEMS_API_URL` and `SOLD_ITEMS_API_KEY`. It uses the same query-fallback strategy as the browse provider and returns sold-price ranges, sample sold items, and recent sold-velocity buckets when available.
 - **Terapeak / eBay research provider:** [`src/validation/providers/terapeak.ts`](src/validation/providers/terapeak.ts) now evaluates authenticated eBay Research candidates for both current-market and previous-POB contexts, scores them against title alignment and subtype coverage, preserves per-candidate diagnostics in debug output, and derives sold-day buckets from sold-row timestamps when available.
-- **Authenticated research session source:** [`src/validation/providers/ebay-research.ts`](src/validation/providers/ebay-research.ts) can source eBay Research authentication from cookie JSON, persisted KV-backed session state, Playwright storage state, or a browser profile directory. Parsed ACTIVE and SOLD tab responses are cached, but automatically invalidated when the authenticated cookie fingerprint changes.
+- **Authenticated research session source:** [`src/validation/providers/ebay-research.ts`](src/validation/providers/ebay-research.ts) now prefers KV-backed Playwright storage state first, then environment-provided storage state / cookie fallbacks, then local storage-state/profile fallbacks for local development only. Parsed ACTIVE and SOLD tab responses are cached, automatically invalidated when the authenticated cookie fingerprint changes, and emit explicit auth-resolution debug fields including `sessionSource`, KV/env/filesystem attempt status, and fallback reasons.
 - **Social provider:** [`src/validation/providers/social.ts`](src/validation/providers/social.ts) supports phase-1 Twitter/X recent activity, YouTube average-daily-views proxy data exposed through the `youtubeViews24hMillions` field, and Reddit recent post counts. These signals degrade gracefully on provider/API failure and are used as supportive indicators rather than authoritative demand truth.
 - **Chart provider:** [`src/validation/providers/chart.ts`](src/validation/providers/chart.ts) is still a stub and does not currently contribute chart-based metrics.
 - **Previous comeback research provider:** [`src/validation/providers/research.ts`](src/validation/providers/research.ts) now performs Perplexity-backed historical research when `PERPLEXITY_API_KEY` is configured. It attempts to resolve the prior comeback, normalize previous first-week sales when support exists, assign a `perplexityHistoricalContextScore`, generate concise `historicalContextNotes`, and emit debug diagnostics covering the research query, citations/snippets, resolved prior release, confidence, and score reasoning.
@@ -640,12 +669,27 @@ Known limitations in the current implementation:
 - The sold-data provider depends on external configuration via `SOLD_ITEMS_API_URL` and `SOLD_ITEMS_API_KEY`.
 - If those sold-data variables are missing, validation still runs but sold enrichment degrades to an unavailable/error state rather than providing full historical-sales signals.
 - The sold-data provider is temporary and intended to be replaced by an internal implementation later.
-- Authenticated eBay Research requires a valid session source such as `EBAY_RESEARCH_COOKIES_JSON`, a persisted KV session, Playwright storage state, or a browser profile directory; without one, the provider degrades to diagnostic-only output.
+- Authenticated eBay Research requires a valid session source such as KV-backed Playwright storage state, `EBAY_RESEARCH_STORAGE_STATE_JSON`, `EBAY_RESEARCH_COOKIES_JSON`, a local Playwright storage-state file, or a local browser profile directory; without one, the provider degrades to diagnostic-only output with explicit structured auth-resolution debug.
+
+#### eBay Research bootstrap and hosted runtime notes
+
+- Install Chromium for hosted runtimes with [`package.json`](package.json) script `playwright:install` (`pnpm run playwright:install`).
+- The Docker deployment path now provisions Chromium during image build in [`Dockerfile`](Dockerfile).
+- Canonical production session source of truth is KV-backed Playwright storage-state JSON stored under `ebay_research_storage_state_json` with companion metadata in `ebay_research_storage_state_meta`, including `updatedAt`, `expiresAt`, `ttlSeconds`, `marketplace`, `sessionStore`, and `sessionVersion`.
+- Bootstrap a signed-in eBay Research storage state into KV with [`src/scripts/bootstrap-ebay-research-session.ts`](src/scripts/bootstrap-ebay-research-session.ts) via the packaged/runtime-safe [`package.json`](package.json) script `research:bootstrap` (`pnpm run build && pnpm run research:bootstrap`).
+- Inspect canonical eBay Research session persistence and fresh-client readback diagnostics with [`src/scripts/inspect-ebay-research-session.ts`](src/scripts/inspect-ebay-research-session.ts) via the packaged/runtime-safe [`package.json`](package.json) script `research:inspect-session` (`pnpm run build && pnpm run research:inspect-session`).
+- Verify headless Chromium launchability with [`src/scripts/check-playwright.ts`](src/scripts/check-playwright.ts) via the packaged/runtime-safe [`package.json`](package.json) script `research:check-browser` (`pnpm run build && pnpm run research:check-browser`).
+- Runtime precedence is: KV storage state → `EBAY_RESEARCH_STORAGE_STATE_JSON` → `EBAY_RESEARCH_COOKIES_JSON` → local storage-state file → local Playwright profile → explicit auth-missing fallback.
+- Every candidate session source is validated against the first-party ACTIVE endpoint before the provider reports `authState = loaded`; failed validation is surfaced through debug fields including `kvStorageStateBytes`, `authValidationAttempted`, and `authValidationSucceeded`.
+- Once a validated session is loaded, ACTIVE and SOLD endpoint fetches automatically become the preferred first-party research source while legacy active/sold fallbacks remain intact when auth is missing or invalid.
+- Successful bootstrap also schedules signed QStash callbacks for 24 hours before expiry, 6 hours before expiry, and at expiry. Those callbacks target `POST /internal/ebay-research/check-session-expiry`, which verifies QStash signatures, suppresses stale reminders by `sessionVersion`, and sends Telegram alerts to `TELEGRAM_CHAT_ID`.
+- Alert scheduling is intentionally skipped when the callback URL resolves to localhost/loopback or when `EBAY_RESEARCH_SESSION_STORE` uses a backend without shared lock support, because those configurations cannot safely deliver or deduplicate hosted reminders.
+- Session refresh is manual by design for now: rerun `pnpm run build && pnpm run research:bootstrap` whenever eBay expires the stored session, then redeploy or restart the hosted service if your platform does not hot-reload env/KV-backed state.
 - The previous-comeback research provider depends on grounded external research and therefore degrades to low-confidence notes with a zero historical score when `PERPLEXITY_API_KEY` is missing, the response cannot be normalized, or reliable evidence is not found.
 - The browse provider still relies on heuristic query selection and fallback matching.
 - The YouTube-backed `youtubeViews24hMillions` field is currently an **average daily views proxy**, not a true trailing 24-hour delta.
 - Social signals are supportive/proxy data only and should not be presented as decisive automated buy logic.
-- eBay-derived metrics are intentionally practical rather than exhaustive; for example, watchers are not yet populated by the live eBay provider.
+- eBay-derived metrics are intentionally practical rather than exhaustive, but authenticated ACTIVE research rows now populate watcher-derived metrics whenever watcher counts are present in the first-party response.
 
 ### Roadmap note: provider maturation
 
@@ -765,7 +809,7 @@ Review the diff, commit the generated changes you want to keep, and deploy.
 
 ### Local env management
 
-For local development, standard runtime scripts automatically load `.env` via dotenvx. Hosted platforms should provide environment variables directly — the server detects hosted environments (e.g. `RENDER=true`) and skips local file loading.
+For local development, standard runtime scripts load `.env` via dotenvx only when a real local [`.env`](.env) file is present. Hosted platforms should provide environment variables directly — the server skips dotenvx for hosted/runtime environments (including Nixpacks-style deployments, which set [`DISABLE_DOTENVX`](nixpacks.toml:26)) and whenever no local [`.env`](.env) file exists.
 
 ```bash
 pnpm run env:encrypt   # encrypt .env for safe sharing
@@ -871,6 +915,31 @@ Common causes:
 - `SOLD_ITEMS_API_URL` or `SOLD_ITEMS_API_KEY` is missing, causing sold enrichment to degrade
 - one or more social-provider credentials are absent, which causes the related supportive signal to degrade gracefully instead of failing the entire run
 
+### eBay Research debug shows `authState = missing` or `sessionStrategy = none`
+
+This means the first-party research provider could not load a validated authenticated session and validation is intentionally falling back to browse and/or the temporary sold provider.
+
+Run this checklist:
+
+```bash
+pnpm run playwright:install
+pnpm run build
+pnpm run research:check-browser
+pnpm run research:bootstrap
+```
+
+Expected post-bootstrap debug characteristics from [`src/validation/providers/ebay-research.ts`](src/validation/providers/ebay-research.ts):
+
+- `authState = loaded`
+- `sessionStrategy = storage_state`
+- `sessionSource = kv`
+- `kvLoadAttempted = true`
+- `kvLoadSucceeded = true`
+- `authValidationAttempted = true`
+- `authValidationSucceeded = true`
+
+If the provider still reports `missing`, verify that your hosted deployment can reach the configured KV backend, that Chromium is available in the runtime image, and that the stored eBay session has not expired. Refresh the session by rerunning `pnpm run research:bootstrap`.
+
 If `authDebug.tokenEndpoint` or the captured upstream response looks wrong, verify the environment-specific OAuth configuration and token-base resolution.
 
 ### Security checklist

package/build/auth/kv-store.js

@@ -26,6 +26,20 @@ export class InMemoryKVStore {
         });
         return Promise.resolve();
     }
+    putIfAbsent(key, value, expirationTtl) {
+        const entry = this.store.get(key);
+        if (entry && (entry.expiresAt === undefined || Date.now() <= entry.expiresAt)) {
+            return Promise.resolve(false);
+        }
+        if (entry?.expiresAt !== undefined && Date.now() > entry.expiresAt) {
+            this.store.delete(key);
+        }
+        this.store.set(key, {
+            value,
+            expiresAt: expirationTtl !== undefined ? Date.now() + expirationTtl * 1_000 : undefined,
+        });
+        return Promise.resolve(true);
+    }
     delete(key) {
         this.store.delete(key);
         return Promise.resolve();
@@ -97,6 +111,9 @@ export class CloudflareKVStore {
             : this.cacheTtlMs;
         this.cache.set(key, { value, expiresAt: Date.now() + cacheTtl });
     }
+    putIfAbsent() {
+        throw new Error('Atomic putIfAbsent is not supported for Cloudflare KV');
+    }
     async delete(key) {
         await this.client.delete(`/values/${encodeURIComponent(key)}`);
         this.cache.delete(key);
@@ -153,6 +170,19 @@ export class UpstashRedisKVStore {
             : this.cacheTtlMs;
         this.cache.set(key, { value, expiresAt: Date.now() + cacheTtl });
     }
+    async putIfAbsent(key, value, expirationTtl) {
+        const response = expirationTtl !== undefined
+            ? await this.client.set(key, value, { ex: expirationTtl, nx: true })
+            : await this.client.set(key, value, { nx: true });
+        if (response === 'OK' || response === true) {
+            const cacheTtl = expirationTtl
+                ? Math.min(expirationTtl * 1_000, this.cacheTtlMs)
+                : this.cacheTtlMs;
+            this.cache.set(key, { value, expiresAt: Date.now() + cacheTtl });
+            return true;
+        }
+        return false;
+    }
     async delete(key) {
         await this.client.del(key);
         this.cache.delete(key);
@@ -180,6 +210,54 @@ export class UpstashRedisKVStore {
  * that need to swap the backend.
  */
 let _kvStoreSingleton = null;
+const _kvStoreSingletonsByBackend = new Map();
+function normalizeKVStoreBackend(value) {
+    const backend = (value ?? 'cloudflare-kv').toLowerCase().trim();
+    switch (backend) {
+        case 'memory':
+        case 'in-memory':
+            return 'memory';
+        case 'upstash-redis':
+        case 'upstash':
+        case 'redis':
+            return 'upstash-redis';
+        case 'cloudflare-kv':
+        case 'cloudflare':
+        default:
+            return 'cloudflare-kv';
+    }
+}
+function createKVStoreInstance(backend, rawEnv) {
+    switch (backend) {
+        case 'memory': {
+            console.log(`[kv-store] EBAY_TOKEN_STORE_BACKEND="${rawEnv ?? ''}" → using InMemoryKVStore (no external KV calls)`);
+            return new InMemoryKVStore();
+        }
+        case 'upstash-redis': {
+            console.log(`[kv-store] EBAY_TOKEN_STORE_BACKEND="${rawEnv ?? ''}" → using UpstashRedisKVStore (url="${process.env.UPSTASH_REDIS_REST_URL ?? '(unset)'}")`);
+            return new UpstashRedisKVStore();
+        }
+        case 'cloudflare-kv':
+        default: {
+            console.log(`[kv-store] EBAY_TOKEN_STORE_BACKEND="${rawEnv ?? '(unset)'}" → using CloudflareKVStore (accountId="${process.env.CLOUDFLARE_ACCOUNT_ID ?? '(unset)'}") — set EBAY_TOKEN_STORE_BACKEND=memory to disable`);
+            return new CloudflareKVStore();
+        }
+    }
+}
+export function createFreshKVStoreForBackend(backend) {
+    const normalizedBackend = normalizeKVStoreBackend(backend);
+    return createKVStoreInstance(normalizedBackend, backend);
+}
+export function createKVStoreForBackend(backend) {
+    const normalizedBackend = normalizeKVStoreBackend(backend);
+    const existing = _kvStoreSingletonsByBackend.get(normalizedBackend);
+    if (existing) {
+        return existing;
+    }
+    const store = createKVStoreInstance(normalizedBackend, backend);
+    _kvStoreSingletonsByBackend.set(normalizedBackend, store);
+    return store;
+}
 /**
  * Returns (or lazily creates) the process-wide KV store singleton based on the
  * EBAY_TOKEN_STORE_BACKEND environment variable:
@@ -196,30 +274,10 @@ export function createKVStore() {
         return _kvStoreSingleton;
     }
     const rawEnv = process.env.EBAY_TOKEN_STORE_BACKEND;
-    const backend = (rawEnv ?? 'cloudflare-kv').toLowerCase().trim();
-    // Log exactly once, at the point the singleton is first constructed.
-    switch (backend) {
-        case 'memory':
-        case 'in-memory': {
-            console.log(`[kv-store] EBAY_TOKEN_STORE_BACKEND="${rawEnv ?? ''}" → using InMemoryKVStore (no external KV calls)`);
-            _kvStoreSingleton = new InMemoryKVStore();
-            break;
-        }
-        case 'upstash-redis':
-        case 'upstash':
-        case 'redis': {
-            console.log(`[kv-store] EBAY_TOKEN_STORE_BACKEND="${rawEnv ?? ''}" → using UpstashRedisKVStore (url="${process.env.UPSTASH_REDIS_REST_URL ?? '(unset)'}")`);
-            _kvStoreSingleton = new UpstashRedisKVStore();
-            break;
-        }
-        case 'cloudflare-kv':
-        case 'cloudflare':
-        default: {
-            console.log(`[kv-store] EBAY_TOKEN_STORE_BACKEND="${rawEnv ?? '(unset)'}" → using CloudflareKVStore (accountId="${process.env.CLOUDFLARE_ACCOUNT_ID ?? '(unset)'}") — set EBAY_TOKEN_STORE_BACKEND=memory to disable`);
-            _kvStoreSingleton = new CloudflareKVStore();
-            break;
-        }
-    }
+    const normalizedBackend = normalizeKVStoreBackend(rawEnv);
+    _kvStoreSingleton =
+        _kvStoreSingletonsByBackend.get(normalizedBackend) ??
+            createKVStoreForBackend(rawEnv ?? normalizedBackend);
     return _kvStoreSingleton;
 }
 /**
@@ -234,4 +292,5 @@ export function createKVStore() {
  */
 export function resetKVStoreSingleton(replacement = null) {
     _kvStoreSingleton = replacement;
+    _kvStoreSingletonsByBackend.clear();
 }

package/build/config/environment.js

@@ -296,6 +296,14 @@ export function getValidationRunnerUserId(environment) {
     const resolved = (envSpecific ?? process.env.VALIDATION_RUNNER_USER_ID ?? '').trim();
     return resolved || null;
 }
+export function getTelegramChatId() {
+    const value = (process.env.TELEGRAM_CHAT_ID ?? '').trim();
+    return value || null;
+}
+export function getTelegramBotToken() {
+    const value = (process.env.TELEGRAM_BOT_TOKEN ?? '').trim();
+    return value || null;
+}
 export function getBaseUrl(environment) {
     return environment === 'production' ? 'https://api.ebay.com' : 'https://api.sandbox.ebay.com';
 }

package/build/scripts/bootstrap-ebay-research-session.js

@@ -0,0 +1,130 @@
+import { stdin as input, stdout as output } from 'node:process';
+import { createInterface } from 'node:readline';
+import { clearEbayResearchAuthCache, inspectEbayResearchAuthState, inspectEbayResearchSessionPersistence, storeEbayResearchSessionToKv, } from '../validation/providers/ebay-research.js';
+import { createEbayResearchSessionStoreResolution, } from '../validation/providers/ebay-research-session-store.js';
+import { scheduleEbayResearchSessionAlerts } from '../validation/providers/ebay-research-session-alerts.js';
+import { loadChromium } from './playwright-runtime.js';
+const configuredMarketplace = process.env.EBAY_RESEARCH_BOOTSTRAP_MARKETPLACE?.trim();
+const marketplace = configuredMarketplace && configuredMarketplace.length > 0 ? configuredMarketplace : 'EBAY-US';
+const researchUrl = `https://www.ebay.com/sh/research?marketplace=${encodeURIComponent(marketplace)}`;
+function getExpectedVerificationSessionSource(selectedStore) {
+    if (selectedStore === 'cloudflare_kv' || selectedStore === 'upstash-redis') {
+        return 'kv';
+    }
+    if (selectedStore === 'filesystem') {
+        return 'filesystem';
+    }
+    return null;
+}
+function getChromiumChannel() {
+    const configuredChannel = process.env.PLAYWRIGHT_CHROMIUM_CHANNEL?.trim();
+    return configuredChannel && configuredChannel.length > 0 ? configuredChannel : undefined;
+}
+function alertingLooksConfigured() {
+    return [
+        process.env.QSTASH_URL,
+        process.env.QSTASH_TOKEN,
+        process.env.QSTASH_CURRENT_SIGNING_KEY,
+        process.env.QSTASH_NEXT_SIGNING_KEY,
+        process.env.TELEGRAM_BOT_TOKEN,
+        process.env.TELEGRAM_CHAT_ID,
+        process.env.EBAY_RESEARCH_SESSION_ALERT_CALLBACK_URL,
+        process.env.PUBLIC_BASE_URL,
+    ].some((value) => typeof value === 'string' && value.trim().length > 0);
+}
+async function waitForEnter(promptText) {
+    await new Promise((resolve) => {
+        const rl = createInterface({ input, output });
+        rl.question(promptText, () => {
+            rl.close();
+            resolve();
+        });
+    });
+}
+async function main() {
+    const chromium = await loadChromium();
+    const browser = await chromium.launch({
+        headless: false,
+        channel: getChromiumChannel(),
+    });
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    try {
+        console.log(`Opening eBay Research bootstrap flow for marketplace ${marketplace}...`);
+        await page.goto(researchUrl, { waitUntil: 'domcontentloaded' });
+        await waitForEnter('Sign in to eBay Research in the opened browser window, confirm the research UI is accessible, then press Enter to persist storage state to KV. ');
+        await page.goto(researchUrl, { waitUntil: 'domcontentloaded' });
+        const currentUrl = page.url();
+        if (!currentUrl.includes('/sh/research')) {
+            throw new Error(`Research UI access could not be confirmed before persistence (currentUrl=${currentUrl}).`);
+        }
+        const storageState = await context.storageState();
+        await storeEbayResearchSessionToKv(marketplace, storageState, 'storage_state');
+        clearEbayResearchAuthCache();
+        const persistence = await inspectEbayResearchSessionPersistence(marketplace);
+        console.log(`[eBayResearchSessionBootstrap] wrote storage state to ${persistence.sessionStoreSelected} key=${persistence.canonicalStateKey ?? 'null'} bytes=${persistence.storageStateBytes}`);
+        console.log(`[eBayResearchSessionBootstrap] canonical storage-state key ${persistence.canonicalStateKey ?? 'null'} exists=${persistence.storageStateExists} bytes=${persistence.storageStateBytes} valid=${persistence.storageStateValid}`);
+        console.log(`[eBayResearchSessionBootstrap] fresh-client canonical key ${persistence.freshCanonicalReadback.key ?? 'null'} exists=${persistence.freshCanonicalReadback.exists} type=${persistence.freshCanonicalReadback.valueType} bytes=${persistence.freshCanonicalReadback.bytes} valid=${persistence.freshCanonicalReadback.validPlaywrightStorageStateJson} configuredFrom=${persistence.freshCanonicalReadback.configuredFrom} scope=${persistence.freshCanonicalReadback.stateKeyScope} connection=${persistence.freshCanonicalReadback.connection ?? 'null'} credentialFingerprint=${persistence.freshCanonicalReadback.credentialFingerprint ?? 'null'} error=${persistence.freshCanonicalReadback.error ?? 'null'}`);
+        console.log(`[eBayResearchSessionBootstrap] metadata key ${persistence.canonicalMetaKey ?? 'null'} exists=${persistence.metadataExists}`);
+        if (persistence.storeTargetConnection) {
+            console.log(`[eBayResearchSessionBootstrap] target=${persistence.storeTargetConnection} credentialsConfigured=${persistence.storeCredentialsConfigured}`);
+        }
+        const verification = await inspectEbayResearchAuthState(marketplace);
+        const expectedSessionSource = getExpectedVerificationSessionSource(persistence.sessionStoreSelected);
+        if (verification.authState !== 'loaded' ||
+            verification.sessionSource !== expectedSessionSource ||
+            verification.authValidationSucceeded !== true) {
+            throw new Error(`eBay Research session bootstrap verification failed (authState=${verification.authState}, sessionSource=${verification.sessionSource ?? 'none'}, authValidationSucceeded=${verification.authValidationSucceeded}, cookieCount=${verification.cookieCount}).`);
+        }
+        const latestStoreResolution = createEbayResearchSessionStoreResolution(marketplace);
+        const meta = latestStoreResolution.store ? await latestStoreResolution.store.getMeta() : null;
+        if (typeof meta?.expiresAt === 'string' && typeof meta?.sessionVersion === 'string') {
+            const scheduleResult = await scheduleEbayResearchSessionAlerts({
+                marketplace,
+                expiresAt: meta.expiresAt,
+                sessionVersion: meta.sessionVersion,
+            });
+            console.log(`[eBayResearchSessionAlerts] schedule status=${scheduleResult.status} reason=${scheduleResult.reason ?? 'none'} callbackUrl=${scheduleResult.callbackUrl} entries=${scheduleResult.scheduled.length}`);
+            for (const entry of scheduleResult.scheduled) {
+                console.log(`[eBayResearchSessionAlerts] scheduled threshold=${entry.threshold} targetTime=${entry.targetTime} messageId=${entry.messageId ?? 'null'}`);
+            }
+            if (scheduleResult.status === 'skipped' &&
+                alertingLooksConfigured() &&
+                (scheduleResult.reason === 'shared_lock_backend_unavailable' ||
+                    scheduleResult.reason === 'callback_url_not_public' ||
+                    scheduleResult.reason === 'callback_url_invalid')) {
+                throw new Error(scheduleResult.reason === 'shared_lock_backend_unavailable'
+                    ? 'eBay Research session alerts require EBAY_RESEARCH_SESSION_STORE=upstash-redis or filesystem because the current backend cannot provide shared alert locks.'
+                    : 'eBay Research session alerts require a publicly reachable callback URL. Set PUBLIC_BASE_URL or EBAY_RESEARCH_SESSION_ALERT_CALLBACK_URL to an externally reachable URL before bootstrapping.');
+            }
+        }
+        console.log(JSON.stringify({
+            ok: true,
+            marketplace,
+            persistedTo: persistence.sessionStoreSelected,
+            storeTargetConnection: persistence.storeTargetConnection,
+            storeCredentialsConfigured: persistence.storeCredentialsConfigured,
+            canonicalKeys: {
+                storageState: persistence.canonicalStateKey,
+                metadata: persistence.canonicalMetaKey,
+            },
+            sessionMetadata: meta,
+            persistence,
+            inspectCommand: 'pnpm run research:inspect-session',
+            refreshCommand: 'pnpm run research:bootstrap',
+            verification,
+        }, null, 2));
+    }
+    finally {
+        await context.close();
+        await browser.close();
+    }
+}
+void main().catch((error) => {
+    console.error(JSON.stringify({
+        ok: false,
+        marketplace,
+        error: error instanceof Error ? error.message : String(error),
+    }, null, 2));
+    process.exit(1);
+});

package/build/scripts/check-playwright.js

@@ -0,0 +1,31 @@
+import { loadChromium } from './playwright-runtime.js';
+function getChromiumChannel() {
+    const configuredChannel = process.env.PLAYWRIGHT_CHROMIUM_CHANNEL?.trim();
+    return configuredChannel && configuredChannel.length > 0 ? configuredChannel : undefined;
+}
+async function main() {
+    const chromium = await loadChromium();
+    const browser = await chromium.launch({
+        headless: true,
+        channel: getChromiumChannel(),
+    });
+    try {
+        const page = await browser.newPage();
+        await page.goto('about:blank');
+        console.log(JSON.stringify({
+            ok: true,
+            browserVersion: browser.version(),
+            pageUrl: page.url(),
+        }, null, 2));
+    }
+    finally {
+        await browser.close();
+    }
+}
+void main().catch((error) => {
+    console.error(JSON.stringify({
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+    }, null, 2));
+    process.exit(1);
+});

package/build/scripts/env-check.js

@@ -1,29 +1,41 @@
+import { existsSync } from 'fs';
 import { resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { spawn } from 'child_process';
 function isHostedEnvironment() {
-    return (process.env.RENDER === 'true' ||
+    return (process.env.DISABLE_DOTENVX === '1' ||
+        process.env.DISABLE_DOTENVX === 'true' ||
+        process.env.NIXPACKS === '1' ||
+        process.env.NIXPACKS_METADATA !== undefined ||
+        process.env.RENDER === 'true' ||
         process.env.RAILWAY_ENVIRONMENT !== undefined ||
         process.env.VERCEL === '1' ||
         process.env.K_SERVICE !== undefined ||
         process.env.AWS_EXECUTION_ENV !== undefined);
 }
+function hasLocalEnvFile() {
+    return existsSync(resolve(process.cwd(), '.env'));
+}
 function main() {
     const args = process.argv.slice(2);
     if (args.length === 0) {
         throw new Error('Usage: tsx src/scripts/env-check.ts <command> [args...]');
     }
     const hosted = isHostedEnvironment();
+    const useDotenvx = !hosted && hasLocalEnvFile();
     const [command, ...commandArgs] = args;
-    const finalCommand = hosted ? command : 'npx';
-    const finalArgs = hosted
-        ? commandArgs
-        : // --overload ensures .env values always win over any pre-set shell env vars
+    const finalCommand = useDotenvx ? 'npx' : command;
+    const finalArgs = useDotenvx
+        ? // --overload ensures .env values always win over any pre-set shell env vars
             // (e.g. a stale EBAY_TOKEN_STORE_BACKEND exported in .zshrc from a previous run)
-            ['-y', '@dotenvx/dotenvx', 'run', '--overload', '--', command, ...commandArgs];
-    console.log(hosted
+            ['-y', '@dotenvx/dotenvx', 'run', '--overload', '--', command, ...commandArgs]
+        : commandArgs;
+    const modeMessage = hosted
         ? '[env-launcher] Hosted environment detected, using platform-provided env vars'
-        : '[env-launcher] Local environment detected, loading env via dotenvx');
+        : useDotenvx
+            ? '[env-launcher] Local .env detected, loading env via dotenvx'
+            : '[env-launcher] No local .env detected, running without dotenvx';
+    console.log(modeMessage);
     const child = spawn(finalCommand, finalArgs, {
         stdio: 'inherit',
         shell: false,

package/build/scripts/inspect-ebay-research-session.js

@@ -0,0 +1,49 @@
+import { inspectEbayResearchSessionPersistence } from '../validation/providers/ebay-research.js';
+function getMarketplace() {
+    const cliMarketplace = process.argv[2]?.trim();
+    if (cliMarketplace && cliMarketplace.length > 0) {
+        return cliMarketplace;
+    }
+    const configuredMarketplace = process.env.EBAY_RESEARCH_BOOTSTRAP_MARKETPLACE?.trim();
+    return configuredMarketplace && configuredMarketplace.length > 0
+        ? configuredMarketplace
+        : 'EBAY-US';
+}
+async function main() {
+    const marketplace = getMarketplace();
+    const persistence = await inspectEbayResearchSessionPersistence(marketplace);
+    console.log(JSON.stringify({
+        ok: persistence.error === null,
+        marketplace,
+        sessionStoreConfigured: persistence.sessionStoreConfigured,
+        sessionStoreSelected: persistence.sessionStoreSelected,
+        sessionStoreConfiguredFrom: persistence.sessionStoreConfiguredFrom,
+        sessionStoreRawConfiguredValue: persistence.sessionStoreRawConfiguredValue,
+        storeTargetConnection: persistence.storeTargetConnection,
+        storeCredentialsConfigured: persistence.storeCredentialsConfigured,
+        storeCredentialFingerprint: persistence.storeCredentialFingerprint,
+        researchEnvironment: persistence.researchEnvironment,
+        storageStateKeyScope: persistence.storageStateKeyScope,
+        canonical: {
+            storageStateKey: persistence.canonicalStateKey,
+            metadataKey: persistence.canonicalMetaKey,
+            storageStateExists: persistence.storageStateExists,
+            metadataExists: persistence.metadataExists,
+            storageStateBytes: persistence.storageStateBytes,
+            validPlaywrightStorageStateJson: persistence.storageStateValid,
+        },
+        freshCanonicalReadback: persistence.freshCanonicalReadback,
+        error: persistence.error,
+    }, null, 2));
+    if (persistence.error) {
+        process.exit(1);
+    }
+}
+void main().catch((error) => {
+    console.error(JSON.stringify({
+        ok: false,
+        marketplace: getMarketplace(),
+        error: error instanceof Error ? error.message : String(error),
+    }, null, 2));
+    process.exit(1);
+});

package/build/scripts/playwright-runtime.js

@@ -0,0 +1,5 @@
+const PLAYWRIGHT_MODULE_NAME = 'playwright-core';
+export async function loadChromium() {
+    const playwrightModule = (await import(PLAYWRIGHT_MODULE_NAME));
+    return playwrightModule.chromium;
+}