@swimmingliu/autovpn 2.1.2 → 2.2.2

package/dist/pipeline/credential-source.js

@@ -9,6 +9,23 @@ import { BRANDS, brandFromSite, brandSite, normalizeBrand } from '../pool/brands
 import { FingerprintStore, resolveFingerprintCacheDir } from './brand-cache.js';
 import { resolveUserRuntimeRoot } from '../runtime/paths.js';
 import { redactText } from '../runtime/redaction.js';
+/**
+ * How many pooled accounts one source may try before it reports failure.
+ *
+ * A redirected row leases from a foreign vendor's list, and only a minority of
+ * those accounts exist on the backend: measured against the deployed pool, 2 of
+ * 40 黑洞 accounts log in on the 雷霆 backend. Each rejected attempt retires that
+ * account and leases the next by least-recent use, so the width decides whether
+ * the run ever reaches a usable credential. A row without a redirect keeps the
+ * tighter default.
+ */
+export function credentialAccountAttempts(source, brand) {
+    const backend = normalizeBrand(String(source.backend_brand ?? '').trim());
+    const redirected = Boolean(backend && brand && backend !== brand);
+    const fallback = redirected ? 24 : 3;
+    const parsed = Math.trunc(Number(source.account_retry_limit ?? fallback));
+    return Number.isFinite(parsed) && parsed >= 1 ? parsed : fallback;
+}
 /**
  * Each brand concatenates `getCommParams()` in its own order with its own
  * literal block. The layout can be overridden from the profile, and is picked
@@ -28,7 +45,9 @@ export function resolveBrandLayout(source) {
             return { afterPackage: explicit.startsWith('&') ? explicit : `&${explicit}` };
         }
     }
-    const brand = String(source.brand ?? '').trim();
+    // A redirected data plane speaks the backend's parameter order, not the
+    // storefront's: the backend decides which flag block it recognises.
+    const brand = String(source.brand_override ?? source.brand ?? '').trim();
     if (brand.includes('旋风') || /xuanfeng/i.test(brand)) {
         return { vipFirst: true, viewport: true };
     }
@@ -47,7 +66,7 @@ export function resolveBrandLayout(source) {
  * downloader uses a Chinese product name, so both are mapped. The official
  * host is the last resort when a profile uses a custom source name.
  */
-const BRAND_APK_PREFIXES = {
+export const BRAND_APK_PREFIXES = {
     雷霆: 'lt',
     旋风: 'xf',
     黑洞: 'hd',
@@ -70,6 +89,22 @@ function siteHost(site) {
         return '';
     }
 }
+/**
+ * Archive prefix for any spelling of a brand: its English key, its Chinese
+ * label, a known storefront host, or a name that normalizes to one of them.
+ */
+function credentialPrefixFor(value) {
+    const raw = String(value ?? '').trim();
+    if (!raw) {
+        return null;
+    }
+    const direct = BRAND_APK_PREFIXES[raw] ?? BRAND_APK_PREFIXES[raw.toLowerCase()];
+    if (direct) {
+        return direct;
+    }
+    const brand = normalizeBrand(raw);
+    return brand ? (BRAND_APK_PREFIXES[brand] ?? null) : null;
+}
 /**
  * Stable key for a brand's fingerprint.
  *
@@ -81,14 +116,82 @@ function siteHost(site) {
  * be established, which keeps custom entries working.
  */
 export function credentialBrandKey(sourceName, source) {
-    const site = String(source.official_site ?? '').trim();
-    const host = siteHost(site);
+    // Brand first, host second. A row's own name identifies the APK even when the
+    // operator points it at an alternate storefront (`www.leitingku.com`,
+    // `www.heidongm.com`, …), and hosting the file under that host split one
+    // brand across several cache entries — so a redirected row keyed by prefix
+    // never saw the entry the native row had just written.
+    const name = String(sourceName ?? '').trim();
+    const byName = credentialPrefixFor(name);
+    if (byName) {
+        return byName;
+    }
+    const host = siteHost(String(source.official_site ?? '').trim());
+    const byHost = credentialPrefixFor(host);
+    if (byHost) {
+        return byHost;
+    }
+    const lowered = name.toLowerCase();
+    return host || lowered || 'unknown';
+}
+/**
+ * Fingerprint key for the data plane a row actually reads.
+ *
+ * A redirected row carries the backend's canonical brand key (`leiting`), not
+ * the short archive prefix its cache file is named with (`lt`). Using the
+ * canonical key straight away produced `brand-leiting.json`, which never
+ * exists: every run missed the cache, fell back to downloading the APK from the
+ * storefront, and on a host that cannot reach that storefront failed with
+ * "APK could not be located" — while `brand-lt.json` sat on disk, unused.
+ */
+export function fingerprintKeyFor(sourceName, source) {
+    if (!String(source.brand_override ?? '').trim()) {
+        return credentialBrandKey(sourceName, source);
+    }
+    return credentialPrefixFor(String(source.brand_override))
+        ?? String(source.brand_override).trim().toLowerCase();
+}
+/**
+ * What to do with a pooled account after its login was refused.
+ *
+ * Retirement and rotation are separate decisions. Only a *classified* rejection
+ * — the vendor said the password or the account is wrong, or that the
+ * membership lapsed — is evidence the row is dead, so only that retires it.
+ * Any rejection at all, though, means this account cannot be used right now and
+ * the pool holds more.
+ *
+ * Conflating the two ended the source at zero rounds: 雷霆 refuses most of this
+ * pool with a bare `code=128` and no message, which matches neither classifier,
+ * so the loop gave up on the first account while 159 active rows went unread.
+ */
+export function accountFollowUp(state) {
+    if (state.membershipExpired) {
+        return { act: true, retire: 'expired', rotate: true };
+    }
+    if (state.credentialRejected) {
+        return { act: true, retire: 'invalid', rotate: true };
+    }
+    if (state.loginRejected) {
+        // Usable by nobody right now, but nothing proves it is dead: keep the row.
+        return { act: true, retire: null, rotate: true };
+    }
+    return { act: false, retire: null, rotate: false };
+}
+/**
+ * Cache files an earlier build may have written for this row.
+ *
+ * Before brand-first keying, the key was the official-site host, so a row
+ * pointed at an alternate storefront wrote `brand-www.leitingku.com.json`
+ * instead of `brand-lt.json`. Those files hold a valid fingerprint — often the
+ * only verified one on a host that cannot reach the vendor's site — so a read
+ * falls back to them and migrates the entry to the canonical key.
+ */
+function legacyFingerprintKey(sourceName, source) {
+    const host = siteHost(String(source.official_site ?? '').trim());
     if (host) {
-        return BRAND_APK_PREFIXES[host] ?? host;
+        return host;
     }
-    const name = String(sourceName ?? '').trim().toLowerCase();
-    const prefix = BRAND_APK_PREFIXES[sourceName] ?? BRAND_APK_PREFIXES[name];
-    return prefix ?? (name || 'unknown');
+    return String(sourceName ?? '').trim().toLowerCase() || 'unknown';
 }
 export function createFingerprintMemo(store, brand) {
     let value = store?.read(brand) ?? null;
@@ -176,6 +279,59 @@ export const MAX_EMPTY_ROUNDS = 5;
  * node is stopped explicitly and reported.
  */
 export const PLACEHOLDER_ONLY_ROUNDS = 8;
+/**
+ * Lap-mode defaults. A lap is one full pass over the frozen area list, so
+ * these numbers mean what they say: 50 laps × N areas is the request ceiling,
+ * 13 empty laps × N areas is the give-up point. The legacy round defaults
+ * above stay untouched for rows that never set a lap key.
+ */
+export const DEFAULT_MAX_LAPS = 50;
+export const DEFAULT_DRY_LAPS = 13;
+function finiteLapValue(value, min) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed >= min;
+}
+/**
+ * Resolve the lap policy, or null when the row never opted in.
+ *
+ * Null is the compatibility contract: the caller then runs the legacy round
+ * path with the same arguments as before, so an untouched profile produces
+ * the same request sequence after an upgrade.
+ */
+export function resolveLapRoundPolicy(source, areaCount) {
+    const optedIn = finiteLapValue(source.max_laps, 1) || finiteLapValue(source.dry_laps, 1) || finiteLapValue(source.min_laps, 0);
+    if (!optedIn) {
+        return null;
+    }
+    const areas = Math.max(1, Math.trunc(numberOrDefault(areaCount, 1)));
+    const cap = Math.max(1, Math.trunc(numberOrDefault(source.max_laps, DEFAULT_MAX_LAPS)));
+    const plateau = Math.max(1, Math.trunc(numberOrDefault(source.dry_laps, DEFAULT_DRY_LAPS)));
+    const floor = Math.min(Math.max(0, Math.trunc(numberOrDefault(source.min_laps, 0))), cap);
+    return {
+        policy: {
+            max_iterations: cap,
+            min_iterations: floor,
+            plateau_limit: plateau,
+            max_runtime_seconds: Math.max(0, numberOrDefault(source.max_runtime_seconds, 0))
+        },
+        areas_per_round: areas,
+        // The guards were tuned in rounds of 8 areas; keep their request volume
+        // when the unit becomes a lap of N areas, never below two laps.
+        empty_round_limit: Math.max(2, Math.ceil((MAX_EMPTY_ROUNDS * DEFAULT_AREAS_PER_ROUND) / areas)),
+        placeholder_round_limit: Math.max(2, Math.ceil((PLACEHOLDER_ONLY_ROUNDS * DEFAULT_AREAS_PER_ROUND) / areas)),
+        round_unit: 'lap'
+    };
+}
+/**
+ * The budget to advertise before the area list is known. Pre-flight events
+ * fire before login, so they must report the unit the loop will run in.
+ */
+export function resolveAdvertisedMaxIterations(source) {
+    if (finiteLapValue(source.max_laps, 1) || finiteLapValue(source.dry_laps, 1) || finiteLapValue(source.min_laps, 0)) {
+        return Math.max(1, Math.trunc(numberOrDefault(source.max_laps, DEFAULT_MAX_LAPS)));
+    }
+    return resolveRoundPolicy(source).max_iterations;
+}
 /** How many areas one round takes from the immutable list. */
 export function resolveAreasPerRound(value, areaCount) {
     const parsed = Math.trunc(Number(value));
@@ -490,6 +646,16 @@ function declaredSizeTooLarge(response) {
     const length = Number(raw);
     return Number.isFinite(length) && length > MAX_APK_BYTES;
 }
+/**
+ * Test seam: `defaultLoadApk` with the brand name spelled out.
+ *
+ * The archive prefix is chosen from this name, and a redirected row must pass
+ * its backend's name rather than the row's. Exported so a test can prove which
+ * name reaches the loader without standing up a whole extraction.
+ */
+export async function loadApkWithBrand(source, fetchImpl, timeoutMs, now, log, brandName, egress) {
+    return defaultLoadApk(source, fetchImpl, timeoutMs, now, log, brandName, egress);
+}
 async function defaultLoadApk(source, fetchImpl, timeoutMs, now, log, brandName = '', egress) {
     if (source.apk_path) {
         try {
@@ -805,9 +971,14 @@ export async function fetchCredentialSourceLinks(input, options = {}) {
     }
 }
 async function fetchCredentialSourceLinksWithTransport(input, options) {
-    const source = input.source;
+    // A copy: a redirected data plane rewrites the site and the layout marker,
+    // and the caller's config object must not carry that into later stages.
+    const source = { ...input.source };
     const platforms = resolveCredentialPlatforms(source);
-    const policy = resolveRoundPolicy(source);
+    // Pre-flight events fire before the area list exists, so the budget is
+    // advertised in the unit the loop will run in: laps or legacy rounds.
+    const advertisedIterations = resolveAdvertisedMaxIterations(source);
+    const legacyPolicy = resolveRoundPolicy(source);
     const errors = [];
     const diagnostics = {
         brand: input.source_name,
@@ -827,7 +998,7 @@ async function fetchCredentialSourceLinksWithTransport(input, options) {
     };
     const empty = {
         source_name: input.source_name,
-        requested_iterations: policy.max_iterations,
+        requested_iterations: advertisedIterations,
         successful_iterations: 0,
         failed_iterations: 0,
         links: [],
@@ -835,8 +1006,8 @@ async function fetchCredentialSourceLinksWithTransport(input, options) {
     };
     event(options, 'extract_source_started', {
         source_name: input.source_name,
-        requested_iterations: policy.max_iterations,
-        min_iterations: policy.min_iterations,
+        requested_iterations: advertisedIterations,
+        min_iterations: legacyPolicy.min_iterations,
         resume_from_iteration: 1,
         platforms
     });
@@ -845,6 +1016,29 @@ async function fetchCredentialSourceLinksWithTransport(input, options) {
     const brand = normalizeBrand(input.source_name)
         ?? brandFromSite(source.official_site)
         ?? normalizeBrand(credentialBrandKey(input.source_name, source));
+    // The account is always leased as the row's own brand; only the data plane
+    // can be redirected. See `backend_brand` for why 黑洞 needs this.
+    const backendBrand = normalizeBrand(String(source.backend_brand ?? '').trim()) ?? brand;
+    if (backendBrand && brand && backendBrand !== brand) {
+        const redirected = brandSite(backendBrand);
+        if (redirected) {
+            // A pinned `apk_path` / `apk_url` is the operator's explicit choice of
+            // build and stays as given: it may already be the backend's own APK, and
+            // discarding it turned a working pinned profile into "APK could not be
+            // located". Only the site moves.
+            if (!source.apk_path && !source.apk_url) {
+                source.official_site = redirected;
+            }
+            // The layout is picked from `brand` at every call site; carrying the row
+            // name through would keep sending the storefront's own flag block.
+            source.brand_override = backendBrand;
+        }
+        // Informational, not an error: the row is expected to work this way.
+        diagnostics.backend_brand = backendBrand;
+        event(options, 'log', {
+            message: `[extract][${input.source_name}] data plane ${brand} -> ${backendBrand}`
+        });
+    }
     let store = options.accountStore ?? null;
     let ownsStore = false;
     let leased = null;
@@ -872,20 +1066,32 @@ async function fetchCredentialSourceLinksWithTransport(input, options) {
             store?.close();
         event(options, 'extract_source_completed', {
             source_name: input.source_name,
-            requested_iterations: policy.max_iterations,
+            requested_iterations: advertisedIterations,
             successful_iterations: 0,
             failed_iterations: 1,
             raw_links: 0
         });
         return { ...empty, failed_iterations: 1 };
     }
-    const memo = options.memo ?? createFingerprintMemo(options.fingerprintStore ?? null, credentialBrandKey(input.source_name, source));
+    // Keyed by the data plane, not the storefront: a redirected row downloads and
+    // inspects the backend's APK, so it must share that brand's cached entry.
+    //
+    // A caller-supplied memo cannot be trusted here. The orchestrator builds one
+    // per row name before the redirect exists, so `options.memo` for a `heidong`
+    // row is seeded from 黑洞's entry while every read and write below goes to the
+    // 雷霆 one. That pairing sends the 黑洞 APK's package and seeds to the 雷霆
+    // backend on a cached run, and it hides the 雷霆 entry the next run should
+    // reuse. A redirect therefore always gets a memo of its own key; the shared
+    // one is used only when the two brands agree.
+    const memoBrandKey = fingerprintKeyFor(input.source_name, source);
+    const memo = source.brand_override
+        ? createFingerprintMemo(options.fingerprintStore ?? null, memoBrandKey)
+        : (options.memo ?? createFingerprintMemo(options.fingerprintStore ?? null, memoBrandKey));
     let linkQueue = Promise.resolve();
     // A non-numeric retry limit (a hand-edited `account_retry_limit = "three"`)
     // must not turn the attempt loop into zero passes, which reported the source
     // as successful with no links and no error.
-    const retryLimit = Math.trunc(Number(source.account_retry_limit ?? 3));
-    const attempts = explicitAccount && explicitPassword ? 1 : (Number.isFinite(retryLimit) && retryLimit >= 1 ? retryLimit : 3);
+    const attempts = explicitAccount && explicitPassword ? 1 : credentialAccountAttempts(source, brand);
     let results = [];
     let callbackFailure = null;
     // The dashboard reads per-source totals from one `extract_iteration` stream.
@@ -915,8 +1121,8 @@ async function fetchCredentialSourceLinksWithTransport(input, options) {
                             event(options, 'extract_platform_started', {
                                 ...payload,
                                 platform,
-                                requested_iterations: policy.max_iterations,
-                                min_iterations: policy.min_iterations
+                                requested_iterations: advertisedIterations,
+                                min_iterations: legacyPolicy.min_iterations
                             });
                             return;
                         }
@@ -942,7 +1148,7 @@ async function fetchCredentialSourceLinksWithTransport(input, options) {
                                 // counter.
                                 platform,
                                 iteration: Number(payload.iteration ?? 0),
-                                requested_iterations: policy.max_iterations,
+                                requested_iterations: advertisedIterations,
                                 new_items: Number(payload.new_items ?? 0),
                                 new_meaningful_items: Number(payload.new_meaningful_items ?? 0),
                                 extracted_links: Number(payload.extracted_links ?? 0),
@@ -1006,29 +1212,54 @@ async function fetchCredentialSourceLinksWithTransport(input, options) {
                     if (lapsed) {
                         store.markExpired(leased.id, 'membership expired');
                     }
-                    else if (level !== undefined && level < 2 && !linked) {
+                    else if (level !== undefined && level < 2 && !linked && !source.brand_override) {
                         // A free-tier account (level 0/1) only ever produces placeholders.
                         // Retire it, but only when it actually produced nothing: a paid
                         // account misreported as level 1 must not lose its row.
+                        //
+                        // A redirected row is exempt: the level it reports is the *row*
+                        // brand's backend grading it, not the backend it now reads, so a
+                        // low level there says nothing about whether the account works.
+                        // Retiring on it would discard exactly the accounts the rotation
+                        // below is trying to find.
                         store.markInvalid(leased.id, 'no paid membership');
                     }
                 }
+                // A login is not proof the account is usable. On a backend that gates
+                // routes by membership, a free-tier account logs in fine and then sees
+                // every paid row disabled, so the vendor filter leaves nothing to ask.
+                // Publishing that as a finished source was the bug; rotate instead.
+                // The account itself is valid, so it is not retired — only skipped.
+                const producedRoutes = results.some((result) => result.diagnostics.route_count > 0);
+                const producedLinks = results.some((result) => result.links.length > 0);
+                if (!producedRoutes && !producedLinks && store && leased && attempt < attempts && brand) {
+                    const next = store.lease(brand);
+                    if (next) {
+                        leased = next;
+                        account = next.account;
+                        password = next.password;
+                        continue;
+                    }
+                }
                 break;
             }
             const membershipExpired = results.length > 0
                 && results.every((result) => result.diagnostics.login_rejected)
                 && results.some((result) => result.diagnostics.membership_expired);
             const credentialRejected = results.length > 0 && results.every((result) => result.diagnostics.credential_rejected);
-            if (store && leased && (membershipExpired || credentialRejected)) {
-                if (membershipExpired)
+            const loginRejected = results.length > 0 && results.every((result) => result.diagnostics.login_rejected);
+            const followUp = accountFollowUp({ membershipExpired, credentialRejected, loginRejected });
+            if (store && leased && followUp.act) {
+                if (followUp.retire === 'expired')
                     store.markExpired(leased.id, 'membership expired');
-                else
+                else if (followUp.retire === 'invalid')
                     store.markInvalid(leased.id, 'login rejected');
-                if (attempt < attempts && brand) {
-                    leased = store.lease(brand);
-                    if (leased) {
-                        account = leased.account;
-                        password = leased.password;
+                if (followUp.rotate && attempt < attempts && brand) {
+                    const next = store.lease(brand);
+                    if (next) {
+                        leased = next;
+                        account = next.account;
+                        password = next.password;
                         continue;
                     }
                 }
@@ -1109,15 +1340,19 @@ async function fetchCredentialSourceLinksWithTransport(input, options) {
     }
     event(options, 'extract_source_completed', {
         source_name: input.source_name,
-        requested_iterations: policy.max_iterations,
+        requested_iterations: advertisedIterations,
         successful_iterations: successful,
         failed_iterations: failed,
         raw_links: links.length,
-        platforms
+        platforms,
+        // route_count is the max across platforms; both channels freeze the same
+        // vendor list, so this is the drawer's per-row area count.
+        area_count: diagnostics.route_count,
+        round_unit: resolveLapRoundPolicy(source, diagnostics.route_count) ? 'lap' : 'round'
     });
     return {
         source_name: input.source_name,
-        requested_iterations: policy.max_iterations,
+        requested_iterations: advertisedIterations,
         successful_iterations: successful,
         failed_iterations: failed,
         links,
@@ -1190,11 +1425,13 @@ async function runCredentialPlatform(input, options) {
         errors.push('account and password are required');
         return empty;
     }
+    // Advertised before the area list is known: lap rows report their lap cap.
+    const startLap = resolveLapRoundPolicy(source, 0);
     const startPolicy = resolveRoundPolicy(source);
     event(options, 'extract_source_started', {
         source_name: input.source_name,
-        requested_iterations: startPolicy.max_iterations,
-        min_iterations: startPolicy.min_iterations,
+        requested_iterations: resolveAdvertisedMaxIterations(source),
+        min_iterations: startLap ? startLap.policy.min_iterations : startPolicy.min_iterations,
         resume_from_iteration: 1,
         platform
     });
@@ -1203,15 +1440,38 @@ async function runCredentialPlatform(input, options) {
     // These only change when the vendor publishes a new build, so a cached entry
     // is used first and the APK is inspected only when the cached seeds all stop
     // answering. That keeps a normal run to a handful of HTTP calls.
-    const brandKey = credentialBrandKey(input.source_name, source);
+    // Keyed by the data plane, not the storefront: a redirected row downloads and
+    // inspects the backend's APK, so it must share that brand's cached entry.
+    const brandKey = fingerprintKeyFor(input.source_name, source);
     const store = options.fingerprintStore ?? null;
-    const memo = options.memo ?? createFingerprintMemo(store, brandKey);
+    // Same rule as the outer memo: a caller-supplied memo is keyed by the row
+    // name, so a redirected row must not read or write through it.
+    const memo = source.brand_override
+        ? createFingerprintMemo(store, brandKey)
+        : (options.memo ?? createFingerprintMemo(store, brandKey));
     // A fingerprint past its trust window is still used when its seeds answer,
     // but it is re-verified against the APK rather than trusted indefinitely: a
     // vendor can rotate the signing certificate while the old seeds still serve
     // `/api/eversion`, and then every login fails on a stale certificate.
     const fresh = store?.readFresh(brandKey) ?? null;
-    const storedEntry = store?.read(brandKey) ?? null;
+    let storedEntry = store?.read(brandKey) ?? null;
+    if (!storedEntry && store && !source.brand_override) {
+        // An older build keyed this row by its official-site host. Reuse that entry
+        // instead of forcing an APK download the host may not be able to make, and
+        // move it to the canonical key so the next run reads it directly.
+        const legacyKey = legacyFingerprintKey(input.source_name, source);
+        if (legacyKey !== brandKey) {
+            const legacy = store.readFresh(legacyKey) ?? store.read(legacyKey);
+            if (legacy) {
+                log(`[extract] adopting fingerprint cached under ${legacyKey}`);
+                // Copies the entry under the canonical key while keeping the original
+                // `verified_at`: stamping a new one would promote an entry that is
+                // genuinely past its window into a trusted one.
+                store.adopt(brandKey, legacy);
+                storedEntry = store.read(brandKey);
+            }
+        }
+    }
     const staleButUsable = Boolean(storedEntry) && !fresh;
     const cached = staleButUsable ? storedEntry : memo.get();
     const session = options.egressSession;
@@ -1222,20 +1482,30 @@ async function runCredentialPlatform(input, options) {
     // Report real extraction work instead of making the UI infer APK/domain
     // activity from text logs. Cache reuse remains distinct from executed work.
     const substage = (name, status) => event(options, 'extract_substage', { source_name: input.source_name, platform, substage: name, status });
-    const inspectApk = async () => {
+    const inspectApk = async (recordFailure = true) => {
         substage('apk_download', 'running');
         let apkBytes = null;
         try {
             apkBytes = options.loadApk
                 ? await options.loadApk(source)
-                : await defaultLoadApk(source, fetchImpl, timeoutMs, now, log, input.source_name, egress);
+                : await defaultLoadApk(source, fetchImpl, timeoutMs, now, log, 
+                // The archive prefix names the *backend's* build (`_lt`, not `_hd`):
+                // a redirected row downloads from the backend's CDN, which publishes
+                // only the backend's own archives. Passing the row name here made
+                // every candidate `_hd<N>.apk` against a 雷霆 host, so all lookback
+                // slots missed and the run failed with "APK could not be located".
+                source.brand_override ?? input.source_name, egress);
         }
         catch (error) {
-            errors.push(`apk: ${error instanceof Error ? error.message : String(error)}`);
+            if (recordFailure) {
+                errors.push(`apk: ${error instanceof Error ? error.message : String(error)}`);
+            }
         }
         if (!apkBytes) {
             substage('apk_download', 'failed');
-            errors.push('APK could not be located');
+            if (recordFailure) {
+                errors.push('APK could not be located');
+            }
             return null;
         }
         substage('apk_download', 'success');
@@ -1252,7 +1522,7 @@ async function runCredentialPlatform(input, options) {
         log(`[extract] ${discovered.package_name} ${discovered.version_name} seeds=${discovered.seed_domains.length}`);
         return discovered.seed_domains.length > 0 ? discovered : null;
     };
-    const inspectSharedApk = () => (memo.resolve ? memo.resolve(inspectApk) : inspectApk());
+    const inspectSharedApk = (recordFailure = true) => (memo.resolve ? memo.resolve(() => inspectApk(recordFailure)) : inspectApk(recordFailure));
     // `apk_url` / `apk_path` are an explicit override: when either is set the
     // caller is asserting a specific build, so a cached fingerprint must not
     // shadow it. Otherwise the cache would make the override a no-op.
@@ -1273,7 +1543,11 @@ async function runCredentialPlatform(input, options) {
             // stale certificate fails every login with no other signal.
             if (staleButUsable) {
                 log('[extract] cached fingerprint is past its trust window; re-inspecting the APK');
-                const refreshed = await inspectSharedApk();
+                // The refresh is opportunistic: the cached entry already answered
+                // `/api/eversion`, so an unreachable storefront must not also append
+                // "APK could not be located" to a run that is about to work. That line
+                // was the whole error text of a run whose nodes came through fine.
+                const refreshed = await inspectSharedApk(false);
                 if (refreshed) {
                     const refreshedEversion = await tryEversion(refreshed, credentialKeyCandidates(source, refreshed));
                     if (refreshedEversion) {
@@ -1348,7 +1622,7 @@ async function runCredentialPlatform(input, options) {
             platform,
             timestampMs: ts,
             code: ''
-        }, resolveBrandLayout({ ...source, brand: input.source_name })), keys, timeoutMs, egress);
+        }, resolveBrandLayout({ ...source, brand: source.brand_override ?? input.source_name })), keys, timeoutMs, egress);
         substage('domain_discovery', resolved ? 'success' : 'failed');
         return resolved;
     }
@@ -1359,7 +1633,7 @@ async function runCredentialPlatform(input, options) {
         identity,
         device,
         platform,
-        layout: resolveBrandLayout({ ...source, brand: input.source_name }),
+        layout: resolveBrandLayout({ ...source, brand: source.brand_override ?? input.source_name }),
         token: '',
         // Before login the app's local KV has no `code`, so the request carries an
         // empty one; `&code=` only holds a value once the account has one.
@@ -1391,10 +1665,15 @@ async function runCredentialPlatform(input, options) {
             diagnostics.membership_expired = isMembershipExpiredMessage(message);
             diagnostics.credential_rejected = !diagnostics.membership_expired && isCredentialLoginRejection(message);
             errors.push(`login rejected: code=${String(payload.code)}`);
-            // A cached fingerprint whose seeds answer eversion but whose signing
-            // cert the vendor rotated keeps failing here on every run. Drop the
-            // cache so the next run re-inspects the APK instead of repeating this.
-            if (cachedInUse) {
+            // A cached fingerprint whose signing cert the vendor rotated fails here,
+            // so the cache must not outlive the failure. Only a real credential
+            // rejection is evidence of that: a throttled or free-tier account is
+            // rejected too, and dropping the brand's fingerprint for it made the next
+            // run re-download the APK from a storefront this host cannot reach —
+            // turning one bad account into a source that never runs again. On a
+            // redirected row that rejection is the norm (most accounts are unknown to
+            // the backend), so there the cache is never dropped on a login result.
+            if (cachedInUse && diagnostics.credential_rejected && !source.brand_override) {
                 store?.clear(brandKey);
             }
             return { ...empty, failed_iterations: 1 };
@@ -1518,9 +1797,13 @@ async function runCredentialPlatform(input, options) {
     // Raw totals use the exact-string identity the pipeline dedupes with, so the
     // live number and `extract_source_completed.raw_links` agree.
     const linkIds = new Set();
-    const policy = resolveRoundPolicy(source);
+    // Lap mode: one round is one full sweep of the frozen list, so the cap and
+    // the plateau are laps with no conversion factor. A row with no lap key
+    // keeps the legacy round policy with identical arguments.
+    const lap = resolveLapRoundPolicy(source, activeRoutes.length);
+    const policy = lap ? lap.policy : resolveRoundPolicy(source);
     const maxIterations = policy.max_iterations;
-    const areasPerRound = resolveAreasPerRound(source.areas_per_round, activeRoutes.length);
+    const areasPerRound = lap ? lap.areas_per_round : resolveAreasPerRound(source.areas_per_round, activeRoutes.length);
     const areaConcurrency = resolveConcurrency(source.area_concurrency, DEFAULT_AREA_CONCURRENCY);
     const cursor = new AreaCursor(activeRoutes);
     const startedAt = Date.now();
@@ -1533,8 +1816,11 @@ async function runCredentialPlatform(input, options) {
     diagnostics.route_count = activeRoutes.length;
     diagnostics.areas_per_round = areasPerRound;
     diagnostics.area_concurrency = areaConcurrency;
-    log(`[extract] area list frozen: ${activeRoutes.length} areas,` +
-        ` ${areasPerRound}/round, concurrency ${areaConcurrency}, egress ${session.transport}`);
+    log(lap
+        ? `[extract] area list frozen: ${activeRoutes.length} areas, ${maxIterations} 遍 (1 遍 = 全部区域各一次),` +
+            ` concurrency ${areaConcurrency}, egress ${session.transport}`
+        : `[extract] area list frozen: ${activeRoutes.length} areas,` +
+            ` ${areasPerRound}/round, concurrency ${areaConcurrency}, egress ${session.transport}`);
     for (let round = 1; round <= maxIterations; round += 1) {
         if (!shouldStartRound(round, policy, (Date.now() - startedAt) / 1000)) {
             break;
@@ -1620,8 +1906,8 @@ async function runCredentialPlatform(input, options) {
             if (session.reportEmptySweep()) {
                 log('[extract] no route answered; switching to the upstream proxy');
             }
-            if (emptySweep >= MAX_EMPTY_ROUNDS) {
-                errors.push(`no route answered for ${emptySweep} consecutive rounds`);
+            if (emptySweep >= (lap?.empty_round_limit ?? MAX_EMPTY_ROUNDS)) {
+                errors.push(`no route answered for ${emptySweep} consecutive ${lap ? 'laps' : 'rounds'}`);
                 break;
             }
         }
@@ -1644,17 +1930,19 @@ async function runCredentialPlatform(input, options) {
             new_item_fingerprints: newFingerprints,
             new_item_link_ids: newLinkIds
         });
-        log(`[extract] round ${round}/${maxIterations} area=${batch.map((route) => route.area).join(',')}` +
+        log((lap
+            ? `[extract] 遍 ${round}/${maxIterations} area=${batch.map((route) => route.area).join(',')}`
+            : `[extract] round ${round}/${maxIterations} area=${batch.map((route) => route.area).join(',')}`) +
             ` +${appendedInRound} new (+${meaningfulInRound} meaningful, total ${links.length},` +
-            ` plateau ${plateau}/${policy.plateau_limit})`);
+            ` plateau ${plateau}/${policy.plateau_limit}${lap ? ' 遍' : ''})`);
         if (shouldStopOnPlateau(round, plateau, policy)) {
-            log(`[extract] early stop: ${plateau} consecutive rounds without a meaningful new node`);
+            log(`[extract] early stop: ${plateau} consecutive ${lap ? 'laps' : 'rounds'} without a meaningful new node`);
             break;
         }
-        if (placeholderStreak >= PLACEHOLDER_ONLY_ROUNDS) {
-            errors.push(`channel produced only placeholder nodes for ${placeholderStreak} rounds; stopping it` +
+        if (placeholderStreak >= (lap?.placeholder_round_limit ?? PLACEHOLDER_ONLY_ROUNDS)) {
+            errors.push(`channel produced only placeholder nodes for ${placeholderStreak} ${lap ? 'laps' : 'rounds'}; stopping it` +
                 ' (this brand does not serve real nodes on this platform)');
-            log(`[extract] ${platform} channel stopped: ${placeholderStreak} rounds of placeholder nodes only.` +
+            log(`[extract] ${platform} channel stopped: ${placeholderStreak} ${lap ? 'laps' : 'rounds'} of placeholder nodes only.` +
                 ' The other channel still runs; this platform is not serving real nodes for this brand.');
             break;
         }
@@ -1670,7 +1958,9 @@ async function runCredentialPlatform(input, options) {
         requested_iterations: maxIterations,
         successful_iterations: successfulRounds,
         failed_iterations: failedRounds,
-        raw_links: links.length
+        raw_links: links.length,
+        area_count: activeRoutes.length,
+        round_unit: lap ? 'lap' : 'round'
     });
     return {
         source_name: input.source_name,
@@ -1681,6 +1971,36 @@ async function runCredentialPlatform(input, options) {
         diagnostics
     };
 }
+/**
+ * Decide what a membership sweep does with one pooled row.
+ *
+ * The sweep logs in with explicit credentials, so the run path's own retirement
+ * (which only fires for a *leased* row) never runs for it — the same decision has
+ * to be reachable from here, or a free-tier account with a date years in the
+ * future stays in rotation forever. Kept pure so the policy can be asserted
+ * without a vendor login.
+ */
+export function classifyMembershipRefresh(facts, today) {
+    const expires = String(facts.membership_expires_at ?? '');
+    if (facts.login_ok) {
+        if (expires && expires < today)
+            return { status: 'expired', reason: 'membership expired' };
+        const level = facts.membership_level;
+        const produced = Number(facts.produced_links ?? 0) > 0 || Number(facts.route_count ?? 0) > 0;
+        // A free-tier row (level 0/1) only ever yields placeholders. Retire it only
+        // when it produced nothing, exactly as the run path does, so a paid row the
+        // vendor misreports as level 1 keeps its place.
+        if (level !== undefined && level < 2 && !produced)
+            return { status: 'retired', reason: 'no paid membership' };
+        return { status: 'updated', reason: '' };
+    }
+    if (facts.membership_expired)
+        return { status: 'expired', reason: 'membership expired' };
+    // The vendor rejected the credential itself: the row cannot log in at all.
+    if (facts.credential_rejected)
+        return { status: 'retired', reason: 'login rejected' };
+    return { status: 'failed', reason: '' };
+}
 /**
  * Learn every pooled account's real membership expiry by logging in.
  *
@@ -1701,7 +2021,7 @@ export async function refreshAccountExpiry(input = {}) {
         cacheDir: resolveFingerprintCacheDir(resolveUserRuntimeRoot(env)),
         now
     });
-    const outcome = { checked: 0, updated: 0, expired: 0, failed: 0, results: [] };
+    const outcome = { checked: 0, updated: 0, expired: 0, retired: 0, failed: 0, results: [] };
     const todayText = localDay(now());
     const requested = input.brand ? normalizeBrand(input.brand) : null;
     // Every brand the pool knows, from the registry rather than a second list.
@@ -1743,25 +2063,30 @@ export async function refreshAccountExpiry(input = {}) {
                     }, { env, now, memo, fingerprintStore });
                     const expires = result.diagnostics.membership_expires_at ?? '';
                     entry.expires_at = expires;
-                    if (result.diagnostics.login_ok && expires) {
-                        store.setExpiry(brand, leased.account, expires);
-                        if (expires < todayText) {
-                            store.markExpired(leased.id, 'membership expired');
-                            entry.status = 'expired';
-                            outcome.expired += 1;
-                        }
-                        else {
-                            entry.status = 'updated';
-                            outcome.updated += 1;
-                        }
+                    const verdict = classifyMembershipRefresh({
+                        ...result.diagnostics,
+                        produced_links: result.links.length
+                    }, todayText);
+                    entry.status = verdict.status;
+                    if (verdict.status === 'updated' || verdict.status === 'expired') {
+                        // A lapsed date is still the account's real date: keep it on the row
+                        // so the pool shows when it ran out, not an em dash.
+                        if (expires)
+                            store.setExpiry(brand, leased.account, expires);
                     }
-                    else if (result.diagnostics.membership_expired) {
-                        store.markExpired(leased.id, 'membership expired');
-                        entry.status = 'expired';
+                    if (verdict.status === 'expired') {
+                        store.markExpired(leased.id, verdict.reason);
                         outcome.expired += 1;
                     }
+                    else if (verdict.status === 'retired') {
+                        store.markInvalid(leased.id, verdict.reason);
+                        entry.error = verdict.reason;
+                        outcome.retired += 1;
+                    }
+                    else if (verdict.status === 'updated') {
+                        outcome.updated += 1;
+                    }
                     else {
-                        entry.status = 'failed';
                         // The CLI prints this line, so nothing that can carry a credential
                         // or a request URL may reach it.
                         entry.error = redactText(result.diagnostics.errors.join('; ')) || 'login did not report an expiry';