editmamei 1.4.0 → 1.5.1

package/dist/kernel/module-lifecycle.js

@@ -3,12 +3,18 @@ import { pathToFileURL } from 'node:url';
 import { existsSync } from 'node:fs';
 import { EDITION } from '../edition.js';
 import { resolveProBinaryPath } from '../api/snippet-client.js';
-import { isProEntitled } from '../license/entitlement.js';
+import { isProEntitled, REFRESH_AFTER_MS } from '../license/entitlement.js';
+import { licenseAdvisory, PRO_RESTART_TO_LOAD } from '../license/advisory.js';
+import { toolsInTier } from '../core/tool-tiers.js';
 import { loadVerifiedModule, readInstalledModule, installedPath, PRO_SKU, } from '../delivery/store.js';
 import { provisionModules, compareVersions, VERSION_RE, } from '../delivery/provision.js';
-import { readLicense } from '../license/store.js';
+import { readLicense, readCheckState, updateCheckState, } from '../license/store.js';
 import { HOST_MIN_ABI, KERNEL_ABI } from './host-api.js';
 import { VERSION } from '../version.js';
+export const MODULE_FRESH_AFTER_MS = REFRESH_AFTER_MS;
+export const MODULE_RETRY_AFTER_FAILURE_MS = 15 * 60_000;
+const PRO_STUB_DESCRIPTION = 'Unavailable right now: this Editmamei Pro tool needs an active license on this machine. ' +
+    'Call it to get the reason and how to restore it, then relay that to the user.';
 export function classifyModuleOutcome(inputs) {
     if (inputs.proModuleLoaded && inputs.skipReason === null)
         return 'loaded';
@@ -26,6 +32,9 @@ export class ModuleLifecycle {
     constructor(deps) {
         this.deps = deps;
     }
+    get store() {
+        return this.deps.licenseStore ?? {};
+    }
     get proModule() {
         return this._proModule;
     }
@@ -36,7 +45,7 @@ export class ModuleLifecycle {
         this.kernel = kernel;
     }
     resolveProModule() {
-        if (isProEntitled()) {
+        if (isProEntitled(this.store)) {
             const verified = loadVerifiedModule(PRO_SKU);
             if (verified) {
                 const installed = readInstalledModule(PRO_SKU);
@@ -71,8 +80,10 @@ export class ModuleLifecycle {
         return null;
     }
     async loadModules() {
-        if (!this._proModule)
+        if (!this._proModule) {
+            this.registerLapsedProStubs();
             return;
+        }
         if (this._proModule.abi !== null && this._proModule.abi < HOST_MIN_ABI) {
             this.deps.logger.warn(`Pro module (abi ${this._proModule.abi}) is older than this host requires ` +
                 `(min abi ${HOST_MIN_ABI}) — booting Community; will re-provision in the background.`);
@@ -128,8 +139,46 @@ export class ModuleLifecycle {
             this._moduleSkipReason = 'incompatible';
         }
     }
+    registerLapsedProStubs() {
+        if (readLicense(this.store) === null)
+            return;
+        if (isProEntitled(this.store))
+            return;
+        const names = [];
+        for (const name of toolsInTier('pro')) {
+            try {
+                this.deps.classifyTool(name);
+            }
+            catch {
+                this.deps.logger.warn(`Skipping Pro stub for unclassified tool '${name}'.`);
+                continue;
+            }
+            names.push(name);
+            this.deps.toolRegistry.register(name, {
+                tool: {
+                    name,
+                    description: PRO_STUB_DESCRIPTION,
+                    inputSchema: { type: 'object', properties: {} },
+                    annotations: { title: name, readOnlyHint: true, idempotentHint: true },
+                },
+                handler: async () => ({
+                    content: [
+                        {
+                            type: 'text',
+                            text: isProEntitled(this.store)
+                                ? PRO_RESTART_TO_LOAD
+                                : (licenseAdvisory(this.store) ?? PRO_RESTART_TO_LOAD),
+                        },
+                    ],
+                    isError: true,
+                }),
+            });
+        }
+        this.deps.logger.info(`Pro is not unlocked on this machine — registered ${names.length} Pro tool name(s) ` +
+            `as explain-only stubs so the reason is answerable.`);
+    }
     computeModuleStatus() {
-        if (!readLicense())
+        if (!readLicense(this.store))
             return null;
         const installed = readInstalledModule(PRO_SKU);
         return {
@@ -137,7 +186,7 @@ export class ModuleLifecycle {
             outcome: classifyModuleOutcome({
                 proModuleLoaded: this._proModule !== null,
                 skipReason: this._moduleSkipReason,
-                entitled: isProEntitled(),
+                entitled: isProEntitled(this.store),
             }),
             module_version: installed?.version ?? null,
             abi: installed?.abi ?? null,
@@ -147,12 +196,13 @@ export class ModuleLifecycle {
         const reason = this._moduleSkipReason;
         if (reason === null)
             return;
-        const license = readLicense();
+        const license = readLicense(this.store);
         if (!license) {
             this.deps.logger.warn('A Pro module was skipped but no cached license was found — staying Community. ' +
                 'Run `editmamei activate <key>` to restore Pro.');
             return;
         }
+        let outcome = null;
         try {
             const prov = await provisionModules(license.key, {
                 force: reason === 'corrupt',
@@ -165,46 +215,66 @@ export class ModuleLifecycle {
                 for (const m of prov.installed) {
                     this.deps.logger.info(`Pro module updated to v${m.version}, restart to load.`);
                 }
-                return;
+                outcome = 'updated';
             }
-            if (prov.notConfigured) {
+            else if (prov.notConfigured) {
                 this.deps.logger.warn('Module delivery is not configured — staying Community.');
-                return;
-            }
-            const abiTooNew = prov.errors.some((e) => e.code === 'abi_too_new');
-            for (const e of prov.errors) {
-                if (e.code === 'abi_too_new')
-                    continue;
-                this.deps.logger.warn(`Could not re-provision the ${e.sku} module (staying Community): ${e.message}`);
             }
-            if (prov.errors.length === 0 || abiTooNew) {
-                if (reason === 'incompatible' || abiTooNew) {
-                    this.deps.logger.warn('The published Pro module does not yet support this host version — staying ' +
-                        'Community. Update Editmamei when a compatible release ships; ' +
-                        '`editmamei report` files a diagnostic.');
+            else {
+                const abiTooNew = prov.errors.some((e) => e.code === 'abi_too_new');
+                for (const e of prov.errors) {
+                    if (e.code === 'abi_too_new')
+                        continue;
+                    this.deps.logger.warn(`Could not re-provision the ${e.sku} module (staying Community): ${e.message}`);
                 }
-                else {
-                    this.deps.logger.warn('Re-provision installed nothing for the corrupt Pro module — staying ' +
-                        'Community. Try `editmamei repair`; `editmamei report` if it persists.');
+                if (prov.errors.length === 0 || abiTooNew) {
+                    if (reason === 'incompatible' || abiTooNew) {
+                        this.deps.logger.warn('The published Pro module does not yet support this host version — staying ' +
+                            'Community. Update Editmamei when a compatible release ships; ' +
+                            '`editmamei report` files a diagnostic.');
+                    }
+                    else {
+                        this.deps.logger.warn('Re-provision installed nothing for the corrupt Pro module — staying ' +
+                            'Community. Try `editmamei repair`; `editmamei report` if it persists.');
+                    }
                 }
+                if (prov.errors.length > 0)
+                    outcome = 'failed';
             }
         }
         catch (err) {
             this.deps.logger.warn(`Background Pro-module re-provision failed (staying Community): ` +
                 `${err instanceof Error ? err.message : String(err)}`);
+            outcome = 'failed';
+        }
+        if (outcome !== null) {
+            try {
+                this.deps.onModuleUpdate?.(outcome);
+            }
+            catch {
+            }
         }
     }
     async ensureEntitledModuleFresh(delivery = {}) {
         if (this._moduleSkipReason !== null)
             return;
-        if (!isProEntitled())
+        if (!isProEntitled(this.store))
             return;
         const underTest = process.env.VITEST !== undefined || process.env.NODE_ENV === 'test';
         if (underTest && !delivery.fetchImpl)
             return;
-        const license = readLicense();
+        const license = readLicense(this.store);
         if (!license)
             return;
+        const now = (delivery.now ?? Date.now)();
+        const freshAfterMs = delivery.freshAfterMs ?? MODULE_FRESH_AFTER_MS;
+        const retryAfter = readCheckState(this.store).module_retry_after;
+        if (retryAfter !== undefined && now < retryAfter && retryAfter - now <= freshAfterMs)
+            return;
+        const alreadyInstalled = readInstalledModule(PRO_SKU) !== null;
+        const failureWaitMs = alreadyInstalled ? freshAfterMs : MODULE_RETRY_AFTER_FAILURE_MS;
+        updateCheckState({ module_retry_after: now + failureWaitMs }, this.store);
+        let outcome = null;
         try {
             const prov = await provisionModules(license.key, {
                 config: delivery.config,
@@ -215,6 +285,12 @@ export class ModuleLifecycle {
             for (const m of prov.installed) {
                 this.deps.logger.info(`Pro module updated to v${m.version} — restart to load.`);
             }
+            if (prov.installed.length > 0) {
+                outcome = 'updated';
+            }
+            else if (prov.errors.length > 0) {
+                outcome = 'failed';
+            }
             for (const e of prov.errors) {
                 if (e.code === 'abi_too_new') {
                     this.deps.logger.info(`A newer Pro module is published but needs a newer Editmamei than this ` +
@@ -228,6 +304,17 @@ export class ModuleLifecycle {
         catch (err) {
             this.deps.logger.warn(`Background Pro-module freshness check failed (staying on the installed version): ` +
                 `${err instanceof Error ? err.message : String(err)}`);
+            outcome = 'failed';
+        }
+        if (outcome !== 'failed') {
+            updateCheckState({ module_retry_after: now + freshAfterMs }, this.store);
+        }
+        if (outcome !== null) {
+            try {
+                this.deps.onModuleUpdate?.(outcome);
+            }
+            catch {
+            }
         }
     }
 }

package/dist/license/advisory.js

@@ -0,0 +1,109 @@
+import { readLicense, readCheckState, } from './store.js';
+import { evaluateEntitlement, GRACE_MS, REFRESH_AFTER_MS, } from './entitlement.js';
+export const PRO_RESTART_TO_LOAD = 'Your Pro license is active again, but this session started without it. ' +
+    'Restart your MCP client to load the Pro tools.';
+function isoDay(ms) {
+    if (!Number.isFinite(ms))
+        return null;
+    let iso;
+    try {
+        iso = new Date(ms).toISOString();
+    }
+    catch {
+        return null;
+    }
+    return /^\d{4}-/.test(iso) ? iso.slice(0, 10) : null;
+}
+export function licenseAdvisory(opts = {}) {
+    const now = (opts.now ?? Date.now)();
+    const rec = readLicense(opts);
+    if (!rec)
+        return null;
+    const entitlement = evaluateEntitlement(rec, now);
+    const last = Date.parse(rec.last_validated_at);
+    const stale = !Number.isFinite(last) || now - last > REFRESH_AFTER_MS;
+    const retryAfter = readCheckState(opts).validate_retry_after;
+    const checksFailing = retryAfter !== undefined && retryAfter > now;
+    if (entitlement.entitled && !(stale && checksFailing) && opts.moduleUpdateFailed !== true) {
+        return null;
+    }
+    return advisoryText(rec, entitlement, now, {
+        checksFailing,
+        checksNotCompleting: stale && checksFailing,
+    });
+}
+const NOT_UNLOCKING = 'Pro is not unlocking.';
+const RESTART_LOOP_CAUSE_AND_FIX = 'Most likely cause: this client is restarting faster than the license check can finish. ' +
+    'Fix: quit the client fully, wait a minute, then start it once and leave it running.';
+const GIVE_IT_TIME = 'Pro may take a few hours to come back rather than returning at the next start, so leave ' +
+    'the client alone instead of restarting it again.';
+function waitCaveat(facts) {
+    return facts.checksFailing ? ` ${GIVE_IT_TIME}` : '';
+}
+const RESTART_TO_LOAD = 'restart your MCP client, because the Pro tools only load when it starts';
+const MODULE_UPDATE_FAILED = 'Pro is unlocked, but an update to its module did not finish. The version already ' +
+    'installed keeps working and the update is tried again on its own, so there is nothing to ' +
+    'do now. If the Pro tools do stop working, run `editmamei repair` in a terminal and then ' +
+    'restart your MCP client.';
+const SUPPORT_TAIL = 'If that does not bring Pro back, run `editmamei license` in a terminal and send the output ' +
+    'to support@editmamei.com.';
+function checkInWindow(rec, now, entitled) {
+    const last = Date.parse(rec.last_validated_at);
+    const graceEndsAt = last + GRACE_MS;
+    const lastDay = isoDay(last);
+    const graceDay = isoDay(graceEndsAt);
+    if (lastDay === null || graceDay === null)
+        return '';
+    return entitled
+        ? ` Your license last checked in on ${lastDay}, and Pro locks on ` +
+            `${graceDay} if it cannot check in before then.`
+        : ` Your license last checked in on ${lastDay} and the offline grace window ` +
+            `${graceEndsAt <= now ? 'closed' : 'closes'} on ${graceDay}.`;
+}
+function endedSentence(rec) {
+    const day = rec.expires_at === null ? null : isoDay(Date.parse(rec.expires_at));
+    return day === null
+        ? 'This license has an end date that has passed, and restarting on its own will not extend it.'
+        : `This license ended on ${day}, and restarting on its own will not extend it.`;
+}
+function clockIsBehind(rec, now) {
+    const last = Date.parse(rec.last_validated_at);
+    return Number.isFinite(last) && last + GRACE_MS >= now;
+}
+const CLOCK_BEHIND = `${NOT_UNLOCKING} This machine's clock is set earlier than a date Editmamei has already ` +
+    'recorded here, usually because it was once set ahead, so the license stored on it cannot be ' +
+    'read as current. Fix: correct the system clock, ' +
+    'then, while connected to the internet, run `editmamei deactivate` followed by ' +
+    `\`editmamei activate YOUR-KEY\` in a terminal and ${RESTART_TO_LOAD}. Running activate on ` +
+    `its own is not enough here, because it keeps the stored record. ${SUPPORT_TAIL}`;
+function advisoryText(rec, entitlement, now, facts) {
+    if (entitlement.entitled) {
+        if (!facts.checksNotCompleting)
+            return MODULE_UPDATE_FAILED;
+        return ('Pro is unlocked, but its background license and update checks are not completing.' +
+            `${checkInWindow(rec, now, true)} ${RESTART_LOOP_CAUSE_AND_FIX}` +
+            `${waitCaveat(facts)} ${SUPPORT_TAIL}`);
+    }
+    switch (entitlement.reason) {
+        case 'revoked':
+        case 'disabled':
+            return (`${NOT_UNLOCKING} This license is no longer active, and restarting on its own will not ` +
+                'bring it back. Fix: check your subscription status. Once it is running again, run ' +
+                '`editmamei license` in a terminal to re-check the license and update this machine, ' +
+                `then ${RESTART_TO_LOAD}. If it should be running already, send that output to ` +
+                'support@editmamei.com.');
+        case 'expired':
+            return (`${NOT_UNLOCKING} ${endedSentence(rec)} Fix: renew it, then run ` +
+                `\`editmamei activate YOUR-KEY\` in a terminal and ${RESTART_TO_LOAD}. If the renewal ` +
+                'has already gone through, run `editmamei license` instead to re-check the license and ' +
+                'update this machine, then restart the client; if Pro is still missing, send that ' +
+                'output to support@editmamei.com.');
+        case 'grace-expired':
+        case 'granted':
+        case 'no-license':
+            if (clockIsBehind(rec, now))
+                return CLOCK_BEHIND;
+            return (`${NOT_UNLOCKING}${checkInWindow(rec, now, false)} ${RESTART_LOOP_CAUSE_AND_FIX}` +
+                `${waitCaveat(facts)} ${SUPPORT_TAIL}`);
+    }
+}

package/dist/license/entitlement.js

@@ -1,13 +1,16 @@
 import { resolvePolarConfig } from './config.js';
 import { computeDeviceHash } from './device-hash.js';
-import { readLicense, writeLicense, clearLicense, nextHighWaterMark, } from './store.js';
-import { PolarLicenseClient, PolarLicenseError } from './polar-client.js';
+import { readLicense, writeLicense, clearLicense, readCheckState, updateCheckState, nextHighWaterMark, } from './store.js';
+import { PolarLicenseClient, PolarLicenseError, unrefSleep, } from './polar-client.js';
 import { Logger } from '../utils/logger.js';
 const logger = new Logger('License');
 export const GRACE_MS = 7 * 24 * 60 * 60 * 1000;
 export const REFRESH_AFTER_MS = 24 * 60 * 60 * 1000;
 export const EXPIRED_REFRESH_TIMEOUT_MS = 5_000;
 export const CLOCK_SKEW_TOLERANCE_MS = 24 * 60 * 60 * 1000;
+export const VALIDATE_BACKOFF_MIN_MS = 60_000;
+export const VALIDATE_BACKOFF_DEFAULT_MS = 15 * 60_000;
+export const VALIDATE_BACKOFF_MAX_MS = 6 * 60 * 60 * 1000;
 export function evaluateEntitlement(rec, now) {
     if (!rec)
         return { entitled: false, reason: 'no-license' };
@@ -37,7 +40,18 @@ function makeClient(ops) {
         throw new PolarLicenseError(`Licensing is not configured for the '${cfg.env}' environment. ` +
             `Set EDITMAMEI_POLAR_ENV=sandbox to test against the sandbox org.`, 0, 'not_configured');
     }
-    return { polar: new PolarLicenseClient(cfg, ops.fetchImpl ?? defaultFetch), cfg };
+    return {
+        polar: new PolarLicenseClient(cfg, ops.fetchImpl ?? defaultFetch, ops.client ?? {}),
+        cfg,
+    };
+}
+function noteValidateFailure(err, ops) {
+    if (err instanceof PolarLicenseError && err.code === 'not_configured')
+        return;
+    const now = (ops.now ?? Date.now)();
+    const supplied = err instanceof PolarLicenseError ? err.retryAfterMs : undefined;
+    const waitMs = Math.min(Math.max(supplied ?? VALIDATE_BACKOFF_DEFAULT_MS, VALIDATE_BACKOFF_MIN_MS), VALIDATE_BACKOFF_MAX_MS);
+    updateCheckState({ validate_retry_after: now + waitMs }, ops);
 }
 export function isProEntitled(ops = {}) {
     return evaluateEntitlement(readLicense(ops), Date.now()).entitled;
@@ -70,6 +84,7 @@ export async function activate(key, ops = {}) {
         high_water_mark: nextHighWaterMark(existing, nowMs),
     };
     writeLicense(rec, ops);
+    updateCheckState({ validate_retry_after: null }, ops);
     return rec;
 }
 export async function refreshIfStale(ops = {}) {
@@ -89,16 +104,28 @@ export async function refreshIfStale(ops = {}) {
     const clockSkewed = age < -CLOCK_SKEW_TOLERANCE_MS;
     if (!clockSkewed && age <= REFRESH_AFTER_MS)
         return;
+    const backoffUntil = readCheckState(ops).validate_retry_after;
+    if (backoffUntil !== undefined) {
+        const waitMs = backoffUntil - now;
+        if (waitMs > 0 && waitMs <= VALIDATE_BACKOFF_MAX_MS)
+            return;
+        updateCheckState({ validate_retry_after: null }, ops);
+    }
+    const bootOps = {
+        ...ops,
+        client: { sleep: unrefSleep, ...ops.client },
+    };
     if (clockSkewed || age <= GRACE_MS) {
-        refresh(ops).catch((err) => {
+        refresh(bootOps).catch((err) => {
+            noteValidateFailure(err, ops);
             logger.warn(`Background license refresh failed (grace covers offline use): ` +
                 `${err instanceof Error ? err.message : String(err)}`);
         });
         return;
     }
     const timeoutMs = ops.expiredRefreshTimeoutMs ?? EXPIRED_REFRESH_TIMEOUT_MS;
-    const attempt = refresh(ops);
-    attempt.catch(() => { });
+    const attempt = refresh(bootOps);
+    attempt.catch((err) => noteValidateFailure(err, ops));
     let timer;
     try {
         const winner = await Promise.race([
@@ -138,6 +165,7 @@ export async function refresh(ops = {}) {
         high_water_mark: nextHighWaterMark(rec, nowMs),
     };
     writeLicense(updated, ops);
+    updateCheckState({ validate_retry_after: null }, ops);
     return updated;
 }
 export async function deactivate(ops = {}) {

package/dist/license/polar-client.js

@@ -1,26 +1,35 @@
 export class PolarLicenseError extends Error {
     httpStatus;
     code;
-    constructor(message, httpStatus, code) {
+    retryAfterMs;
+    constructor(message, httpStatus, code, retryAfterMs) {
         super(message);
         this.httpStatus = httpStatus;
         this.code = code;
+        this.retryAfterMs = retryAfterMs;
         this.name = 'PolarLicenseError';
     }
 }
 const USER_AGENT = 'editmamei-license-client/1';
+const DEFAULT_RETRY = { attempts: 3, baseDelayMs: 1000, maxDelayMs: 65_000 };
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export const unrefSleep = (ms) => new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    timer.unref?.();
+});
 export class PolarLicenseClient {
     cfg;
     fetchImpl;
-    constructor(cfg, fetchImpl) {
+    retry;
+    sleep;
+    constructor(cfg, fetchImpl, opts = {}) {
         this.cfg = cfg;
         this.fetchImpl = fetchImpl;
+        this.retry = { ...DEFAULT_RETRY, ...opts.retry };
+        this.sleep = opts.sleep ?? defaultSleep;
     }
     async validate(key) {
-        return this.post('/customer-portal/license-keys/validate', {
-            key,
-            organization_id: this.cfg.organizationId,
-        });
+        return this.post('/customer-portal/license-keys/validate', { key, organization_id: this.cfg.organizationId }, { retry: true });
     }
     async activate(key, label) {
         return this.post('/customer-portal/license-keys/activate', {
@@ -36,7 +45,38 @@ export class PolarLicenseClient {
             activation_id: activationId,
         });
     }
-    async post(path, body) {
+    async post(path, body, opts = {}) {
+        const once = () => this.postOnce(path, body);
+        return opts.retry === true ? this.withRetry(once) : once();
+    }
+    async withRetry(fn) {
+        const attempts = Math.max(1, this.retry.attempts);
+        let lastErr;
+        for (let attempt = 1; attempt <= attempts; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (err) {
+                lastErr = err;
+                const transient = err instanceof PolarLicenseError && (err.code === 'network' || err.code === 'transient');
+                if (!transient || attempt === attempts)
+                    throw err;
+                const retryAfter = err instanceof PolarLicenseError ? err.retryAfterMs : undefined;
+                const delay = retryAfter ?? this.retry.baseDelayMs * 2 ** (attempt - 1);
+                const wait = Math.min(Math.max(delay, this.retry.baseDelayMs), this.retry.maxDelayMs);
+                await this.sleep(wait);
+            }
+        }
+        throw lastErr;
+    }
+    retryAfterMsOf(res) {
+        const raw = res.headers?.get('retry-after');
+        if (!raw)
+            return undefined;
+        const secs = Number(raw);
+        return Number.isFinite(secs) && secs >= 0 ? Math.round(secs * 1000) : undefined;
+    }
+    async postOnce(path, body) {
         let res;
         try {
             res = await this.fetchImpl(`${this.cfg.baseUrl}${path}`, {
@@ -57,6 +97,9 @@ export class PolarLicenseClient {
                 '`editmamei deactivate` on one of them, or remove a device in your account portal ' +
                 "(the 'Manage' link in your purchase email).", 403, 'seat_limit_reached');
         }
+        if (res.status === 429 || res.status >= 500) {
+            throw new PolarLicenseError(`License check could not complete (HTTP ${res.status}).`, res.status, 'transient', this.retryAfterMsOf(res));
+        }
         throw new PolarLicenseError(`License check failed (HTTP ${res.status}).`, res.status, 'invalid_license');
     }
 }

package/dist/license/store.js

@@ -4,6 +4,7 @@ import { settingsDir } from '../core/settings.js';
 import { Logger } from '../utils/logger.js';
 const logger = new Logger('License');
 const LICENSE_FILENAME = 'license.json';
+const CHECK_STATE_FILENAME = 'license-check.json';
 export function licensePath(opts = {}) {
     return join(settingsDir(opts), LICENSE_FILENAME);
 }
@@ -56,4 +57,62 @@ export function clearLicense(opts = {}) {
     const path = licensePath(opts);
     if (existsSync(path))
         rmSync(path, { force: true });
+    clearCheckState(opts);
+}
+export function checkStatePath(opts = {}) {
+    return join(settingsDir(opts), CHECK_STATE_FILENAME);
+}
+export function readCheckState(opts = {}) {
+    const path = checkStatePath(opts);
+    if (!existsSync(path))
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (err) {
+        logger.debug(`license-check.json unreadable (ignoring): ${err instanceof Error ? err.message : String(err)}`);
+        return {};
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return {};
+    const raw = parsed;
+    const out = {};
+    if (typeof raw.validate_retry_after === 'number' && Number.isFinite(raw.validate_retry_after)) {
+        out.validate_retry_after = raw.validate_retry_after;
+    }
+    if (typeof raw.module_retry_after === 'number' && Number.isFinite(raw.module_retry_after)) {
+        out.module_retry_after = raw.module_retry_after;
+    }
+    return out;
+}
+export function updateCheckState(patch, opts = {}) {
+    const next = { ...readCheckState(opts) };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === null)
+            delete next[key];
+        else
+            next[key] = value;
+    }
+    const path = checkStatePath(opts);
+    const dir = dirname(path);
+    try {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const tmp = join(dir, `.license-check.${process.pid}.tmp`);
+        writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        logger.debug(`license-check.json not written (ignoring): ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export function clearCheckState(opts = {}) {
+    const path = checkStatePath(opts);
+    try {
+        if (existsSync(path))
+            rmSync(path, { force: true });
+    }
+    catch (err) {
+        logger.debug(`license-check.json not removed (ignoring): ${err instanceof Error ? err.message : String(err)}`);
+    }
 }