editmamei 1.5.0 → 1.5.1

package/README.md

@@ -150,6 +150,7 @@ The source in this repository is the same code published to npm, so none of the
 - **Install:** [docs/installation.md](docs/installation.md)
 - **Getting started:** [docs/getting-started.md](docs/getting-started.md)
 - **FAQ:** [docs/faq.md](docs/faq.md)
+- **Troubleshooting:** [docs/troubleshooting.md](docs/troubleshooting.md)
 - **Pro features:** [docs/pro-features.md](docs/pro-features.md)
 - **Roadmap:** [docs/roadmap.md](docs/roadmap.md)
 - **Bugs and feature requests:** [the issue tracker](https://github.com/editmamei/editmamei/issues). If something's broken, ask your assistant to "report a problem" (or run `editmamei report`) to drop an anonymized diagnostic bundle in your Downloads folder, then attach it to the issue.

package/dist/core/server.js

@@ -19,6 +19,7 @@ import { createHash } from 'node:crypto';
 import { GoSnippetClient, coreBinaryName } from '../api/snippet-client.js';
 import { isProEntitled } from '../license/entitlement.js';
 import { createPingLicenseRefresher } from '../license/ping-refresh.js';
+import { licenseAdvisory } from '../license/advisory.js';
 import { runScript } from '../utils/run-script.js';
 import { listTemplates } from '../utils/template-storage.js';
 import { toolErrorResult } from '../utils/tool-helpers.js';
@@ -84,7 +85,12 @@ export class EditmameiServer {
     updateNoticeShown = false;
     snippetClient = new GoSnippetClient();
     refreshLicenseOnPing = createPingLicenseRefresher();
+    moduleUpdateFailed = false;
+    licenseAdvisorySource;
+    licenseStoreOptions;
+    licenseAdvisoryShown = false;
     constructor(opts = {}) {
+        this.licenseStoreOptions = opts.licenseStore ?? {};
         this.logger = new Logger('EditmameiServer');
         this.session = new Session();
         this.sessionLog = new SessionLog(this.session.getSessionId());
@@ -189,9 +195,29 @@ export class EditmameiServer {
                 capRoots: caps?.roots != null,
             });
         };
+        this.licenseAdvisorySource =
+            opts.licenseAdvisory ??
+                ((advisoryOpts) => {
+                    if (process.env.VITEST !== undefined || process.env.NODE_ENV === 'test')
+                        return null;
+                    return licenseAdvisory(advisoryOpts);
+                });
         this.registerTools();
         this.setupHandlers();
     }
+    buildLicenseAdvisoryNote() {
+        if (this.licenseAdvisoryShown)
+            return { note: '', stamp: () => { } };
+        const text = this.licenseAdvisorySource({ moduleUpdateFailed: this.moduleUpdateFailed });
+        if (!text)
+            return { note: '', stamp: () => { } };
+        return {
+            note: ' ' + text,
+            stamp: () => {
+                this.licenseAdvisoryShown = true;
+            },
+        };
+    }
     registerTools() {
         this.toolRegistry.register('ps_ping', {
             tool: {
@@ -274,9 +300,14 @@ export class EditmameiServer {
         this.moduleLifecycle = new ModuleLifecycle({
             toolRegistry: this.toolRegistry,
             logger: this.logger,
+            licenseStore: this.licenseStoreOptions,
             assertToolsClassified: () => this.assertToolsClassified(),
             classifyTool: (name) => this.classifyTool(name),
-            onModuleUpdate: (outcome) => this.telemetry.setModuleUpdate(outcome),
+            onModuleUpdate: (outcome) => {
+                if (outcome === 'failed')
+                    this.moduleUpdateFailed = true;
+                this.telemetry.setModuleUpdate(outcome);
+            },
         });
         const proModule = this.moduleLifecycle.resolveProModule();
         this.kernel = new Kernel({
@@ -425,6 +456,11 @@ export class EditmameiServer {
         if (this.updateCheck)
             await this.updateCheck;
         const update = await this.buildUpdateNotice();
+        const advisory = this.buildLicenseAdvisoryNote();
+        const withAdvisory = (text) => {
+            advisory.stamp();
+            return text + advisory.note;
+        };
         const connection = this.session.getConnection();
         let version = 'Unknown';
         let actionSetsCount = 0;
@@ -451,8 +487,8 @@ export class EditmameiServer {
                 content: [
                     {
                         type: 'text',
-                        text: 'Photoshop does not appear to be running. Start Photoshop, then call ps_ping again.' +
-                            update.note,
+                        text: withAdvisory('Photoshop does not appear to be running. Start Photoshop, then call ps_ping again.' +
+                            update.note),
                     },
                 ],
                 structuredContent: {
@@ -478,7 +514,7 @@ export class EditmameiServer {
                     content: [
                         {
                             type: 'text',
-                            text: (reason ?? 'Photoshop did not respond') + update.note,
+                            text: withAdvisory((reason ?? 'Photoshop did not respond') + update.note),
                         },
                     ],
                     structuredContent: {
@@ -501,7 +537,12 @@ export class EditmameiServer {
                 this.lastDocDepth = null;
                 this.lastDocMode = null;
                 return {
-                    content: [{ type: 'text', text: 'Photoshop did not respond' + update.note }],
+                    content: [
+                        {
+                            type: 'text',
+                            text: withAdvisory('Photoshop did not respond' + update.note),
+                        },
+                    ],
                     structuredContent: {
                         connected: false,
                         update_available: this.updateInfo,
@@ -567,11 +608,11 @@ export class EditmameiServer {
             content: [
                 {
                     type: 'text',
-                    text: `Connected to Photoshop (v${version}). ` +
+                    text: withAdvisory(`Connected to Photoshop (v${version}). ` +
                         `${actionSetsCount} custom action set(s), ${userTemplates} saved template(s), ` +
                         `${openDocuments.length} open document(s)${openDocuments.length ? ': ' + openDocuments.join(', ') : ''}` +
                         `${degradedNote}.` +
-                        update.note,
+                        update.note),
                 },
             ],
             structuredContent: {

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,7 +196,7 @@ 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.');
@@ -209,14 +258,22 @@ export class ModuleLifecycle {
     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, {
@@ -249,6 +306,9 @@ export class ModuleLifecycle {
                 `${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);

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)}`);
+    }
 }

package/dist/telemetry/client.js

@@ -7,7 +7,7 @@ import { READ_ONLY_TOOLS, KEPT_WORK_TOOLS, nodeMajor, archToken, osMajor, boundM
 import { buildClientConnected, buildDiagnosticEvent, buildModuleStatus, buildSessionStart, buildSessionSummary, buildUsageEvent, dayBucket, normalizeDayBucket, isContentSafe, PS_VERSION_UNKNOWN, } from './events.js';
 import { sanitizeMessage, sanitizeSnippet, sanitizeStderrTail } from './sanitize.js';
 import { httpTransport, resolveEndpoint } from './transport.js';
-import { appendOutboxSync, clearOutbox, clearSessionState, readOutbox, readSessionState, writeSessionStateSync, } from './outbox.js';
+import { appendOutboxSync, clearOutbox, clearSessionState, readOutboxWithDiscards, readSessionState, rewriteOutbox, writeSessionStateSync, } from './outbox.js';
 const MAX_BATCH_SIZE = 100;
 const MAX_QUEUE_SIZE = 500;
 const DEFAULT_FLUSH_INTERVAL_MS = 5 * 60_000;
@@ -43,6 +43,9 @@ export class TelemetryClient {
     editsOk = 0;
     keptWork = 0;
     droppedEvents = 0;
+    droppedOutbox = 0;
+    droppedUnsafe = 0;
+    usageCallsSent = 0;
     behindLatest = null;
     moduleUpdate = 'none';
     installAssets = {};
@@ -156,6 +159,9 @@ export class TelemetryClient {
             kept_work: this.keptWork,
             ...(this.behindLatest !== null ? { behind_latest: this.behindLatest } : {}),
             dropped_events: this.droppedEvents,
+            dropped_outbox: this.droppedOutbox,
+            dropped_unsafe: this.droppedUnsafe,
+            usage_calls_sent: this.usageCallsSent,
             ...(moduleStatus !== null ? { module_update: this.moduleUpdate } : {}),
             ...(this.installAssets.templates_saved !== undefined
                 ? { templates_saved: this.installAssets.templates_saved }
@@ -241,15 +247,18 @@ export class TelemetryClient {
     async flush() {
         if (!this.active || this.queue.length === 0)
             return;
-        const batch = this.restampPsVersion(this.queue.splice(0, this.maxBatchSize)).filter(isContentSafe);
+        const picked = this.restampPsVersion(this.queue.splice(0, this.maxBatchSize));
+        const batch = picked.filter(isContentSafe);
+        this.droppedUnsafe += picked.length - batch.length;
         if (batch.length === 0)
             return;
         try {
             await this.transport(this.endpoint, JSON.stringify({ events: batch }));
+            this.usageCallsSent += countUsageCalls(batch);
         }
         catch (err) {
             this.logger.debug(`telemetry flush failed, persisting ${batch.length} event(s) to outbox: ${errMsg(err)}`);
-            appendOutboxSync(batch, this.outboxOpts);
+            this.droppedOutbox += appendOutboxSync(batch, this.outboxOpts);
         }
     }
     shutdown() {
@@ -264,16 +273,26 @@ export class TelemetryClient {
         }
         if (!this.active)
             return;
-        if (this.settings.telemetry.usage && this.toolCallCount > 0) {
-            this.enqueue(buildSessionSummary(this.dims, {
+        if (this.queue.length > 0) {
+            const picked = this.restampPsVersion(this.queue.splice(0));
+            const batch = picked.filter(isContentSafe);
+            this.droppedUnsafe += picked.length - batch.length;
+            this.droppedOutbox += appendOutboxSync(batch, this.outboxOpts);
+        }
+        const hasLossToReport = this.droppedEvents > 0 || this.droppedOutbox > 0 || this.droppedUnsafe > 0;
+        if (this.settings.telemetry.usage && (this.toolCallCount > 0 || hasLossToReport)) {
+            const summary = buildSessionSummary(this.dims, {
                 tool_call_count: this.toolCallCount,
                 distinct_tools: this.distinctTools.size,
                 any_failures: this.anyFailures,
                 ...this.summaryFields(),
-            }, this.ensureStartDayBucket(), this.now()));
-        }
-        if (this.queue.length > 0) {
-            appendOutboxSync(this.restampPsVersion(this.queue.splice(0)).filter(isContentSafe), this.outboxOpts);
+            }, this.ensureStartDayBucket(), this.now());
+            if (isContentSafe(summary)) {
+                const lost = appendOutboxSync([summary], this.outboxOpts);
+                if (lost > 0) {
+                    this.logger.debug(`outbox discarded ${lost} event(s) while writing the session summary`);
+                }
+            }
         }
         clearSessionState(this.outboxOpts);
     }
@@ -286,7 +305,8 @@ export class TelemetryClient {
                 appendOutboxSync([summaryFromState(stale)], this.outboxOpts);
             }
             clearSessionState(this.outboxOpts);
-            const pending = readOutbox(this.outboxOpts);
+            const { events: pending, discarded } = readOutboxWithDiscards(this.outboxOpts);
+            this.droppedOutbox += discarded;
             if (pending.length === 0) {
                 clearOutbox(this.outboxOpts);
                 return;
@@ -295,22 +315,27 @@ export class TelemetryClient {
                 clearOutbox(this.outboxOpts);
                 return;
             }
-            let allAccepted = true;
-            for (let i = 0; i < pending.length; i += this.maxBatchSize) {
-                const batch = pending.slice(i, i + this.maxBatchSize).filter(isContentSafe);
-                if (batch.length === 0)
-                    continue;
+            const sendable = pending.filter(isContentSafe);
+            this.droppedUnsafe += pending.length - sendable.length;
+            let settled = 0;
+            for (let i = 0; i < sendable.length; i += this.maxBatchSize) {
+                const batch = sendable.slice(i, i + this.maxBatchSize);
                 try {
                     await this.transport(this.endpoint, JSON.stringify({ events: batch }));
+                    this.usageCallsSent += countUsageCalls(batch);
                 }
                 catch (err) {
                     this.logger.debug(`startup outbox flush failed: ${errMsg(err)}`);
-                    allAccepted = false;
                     break;
                 }
+                settled = i + batch.length;
             }
-            if (allAccepted)
+            if (settled >= sendable.length) {
                 clearOutbox(this.outboxOpts);
+            }
+            else {
+                rewriteOutbox(sendable.slice(settled), this.outboxOpts);
+            }
         }
         catch (err) {
             this.logger.debug(`startup outbox flush error: ${errMsg(err)}`);
@@ -342,6 +367,9 @@ function summaryFromState(s) {
         ...(s.kept_work !== undefined ? { kept_work: s.kept_work } : {}),
         ...(s.behind_latest !== undefined ? { behind_latest: s.behind_latest } : {}),
         ...(s.dropped_events !== undefined ? { dropped_events: s.dropped_events } : {}),
+        ...(s.dropped_outbox !== undefined ? { dropped_outbox: s.dropped_outbox } : {}),
+        ...(s.dropped_unsafe !== undefined ? { dropped_unsafe: s.dropped_unsafe } : {}),
+        ...(s.usage_calls_sent !== undefined ? { usage_calls_sent: s.usage_calls_sent } : {}),
         ...(s.module_update !== undefined ? { module_update: s.module_update } : {}),
         ...(templatesSaved !== null ? { templates_saved: templatesSaved } : {}),
         ...(actionSets !== null ? { action_sets: actionSets } : {}),
@@ -350,6 +378,16 @@ function summaryFromState(s) {
 function errMsg(err) {
     return err instanceof Error ? err.message : String(err);
 }
+function countUsageCalls(events) {
+    let n = 0;
+    for (const event of events) {
+        if (event.type !== 'usage')
+            continue;
+        const count = event.count;
+        n += typeof count === 'number' && Number.isInteger(count) && count > 0 ? count : 1;
+    }
+    return n;
+}
 function clampCount(n) {
     if (!Number.isFinite(n))
         return null;

package/dist/telemetry/events.js

@@ -61,6 +61,11 @@ export function buildSessionSummary(dims, summary, tsBucket, now) {
         ...(summary.kept_work !== undefined ? { kept_work: summary.kept_work } : {}),
         ...(summary.behind_latest !== undefined ? { behind_latest: summary.behind_latest } : {}),
         ...(summary.dropped_events !== undefined ? { dropped_events: summary.dropped_events } : {}),
+        ...(summary.dropped_outbox !== undefined ? { dropped_outbox: summary.dropped_outbox } : {}),
+        ...(summary.dropped_unsafe !== undefined ? { dropped_unsafe: summary.dropped_unsafe } : {}),
+        ...(summary.usage_calls_sent !== undefined
+            ? { usage_calls_sent: summary.usage_calls_sent }
+            : {}),
         ...(summary.module_update !== undefined ? { module_update: summary.module_update } : {}),
         ...(summary.templates_saved !== undefined ? { templates_saved: summary.templates_saved } : {}),
         ...(summary.action_sets !== undefined ? { action_sets: summary.action_sets } : {}),

package/dist/telemetry/outbox.js

@@ -6,8 +6,8 @@ const logger = new Logger('TelemetryOutbox');
 const DIRNAME = '.editmamei';
 const OUTBOX_FILENAME = 'telemetry-outbox.ndjson';
 const SESSION_STATE_FILENAME = 'telemetry-session.json';
-export const MAX_OUTBOX_EVENTS = 1000;
-const MAX_OUTBOX_BYTES = 2_000_000;
+export const MAX_OUTBOX_EVENTS = 5_000;
+export const MAX_OUTBOX_BYTES = 2_000_000;
 function baseDir(opts) {
     return opts.dir ?? join(homedir(), DIRNAME);
 }
@@ -22,27 +22,31 @@ function ensureDir(path) {
 }
 export function appendOutboxSync(events, opts = {}) {
     if (events.length === 0)
-        return;
+        return 0;
     const path = outboxPath(opts);
+    let discarded = 0;
     try {
         ensureDir(path);
         if (existsSync(path) && statSync(path).size > MAX_OUTBOX_BYTES) {
-            compactOutbox(opts);
+            discarded += compactOutbox(opts);
         }
         const lines = events.map((e) => JSON.stringify(e)).join('\n') + '\n';
         appendFileSync(path, lines, { encoding: 'utf8', mode: 0o600 });
     }
     catch (err) {
         logger.debug(`outbox append dropped ${events.length} event(s): ${errMsg(err)}`);
+        discarded += events.length;
     }
+    return discarded;
 }
-export function readOutbox(opts = {}) {
+export function readOutboxWithDiscards(opts = {}) {
     const path = outboxPath(opts);
     if (!existsSync(path))
-        return [];
+        return { events: [], discarded: 0 };
     try {
         const raw = readFileSync(path, 'utf8');
         const events = [];
+        let discarded = 0;
         for (const line of raw.split('\n')) {
             const trimmed = line.trim();
             if (trimmed.length === 0)
@@ -51,17 +55,23 @@ export function readOutbox(opts = {}) {
                 events.push(JSON.parse(trimmed));
             }
             catch {
+                discarded += 1;
             }
         }
-        return events.length > MAX_OUTBOX_EVENTS
-            ? events.slice(events.length - MAX_OUTBOX_EVENTS)
-            : events;
+        if (events.length > MAX_OUTBOX_EVENTS) {
+            const over = events.length - MAX_OUTBOX_EVENTS;
+            return { events: events.slice(over), discarded: discarded + over };
+        }
+        return { events, discarded };
     }
     catch (err) {
         logger.debug(`outbox read failed: ${errMsg(err)}`);
-        return [];
+        return { events: [], discarded: 0 };
     }
 }
+export function readOutbox(opts = {}) {
+    return readOutboxWithDiscards(opts).events;
+}
 export function clearOutbox(opts = {}) {
     try {
         rmSync(outboxPath(opts), { force: true });
@@ -70,24 +80,39 @@ export function clearOutbox(opts = {}) {
         logger.debug(`outbox clear failed: ${errMsg(err)}`);
     }
 }
-function compactOutbox(opts = {}) {
-    const kept = readOutbox(opts);
+export function rewriteOutbox(events, opts = {}) {
+    if (events.length === 0) {
+        clearOutbox(opts);
+        return;
+    }
     const path = outboxPath(opts);
     try {
-        if (kept.length === 0) {
-            clearOutbox(opts);
-            return;
-        }
+        ensureDir(path);
         const tmp = join(dirname(path), `.outbox.${process.pid}.tmp`);
-        writeFileSync(tmp, kept.map((e) => JSON.stringify(e)).join('\n') + '\n', {
+        writeFileSync(tmp, events.map((e) => JSON.stringify(e)).join('\n') + '\n', {
             encoding: 'utf8',
             mode: 0o600,
         });
         renameSync(tmp, path);
     }
     catch (err) {
-        logger.debug(`outbox compaction failed: ${errMsg(err)}`);
+        logger.debug(`outbox rewrite failed: ${errMsg(err)}`);
+    }
+}
+function compactOutbox(opts = {}) {
+    const { events, discarded } = readOutboxWithDiscards(opts);
+    const target = MAX_OUTBOX_BYTES / 2;
+    let bytes = 0;
+    let firstKept = Math.max(events.length - 1, 0);
+    for (let i = events.length - 1; i >= 0; i--) {
+        bytes += Buffer.byteLength(JSON.stringify(events[i]), 'utf8') + 1;
+        if (bytes > target)
+            break;
+        firstKept = i;
     }
+    const kept = events.slice(firstKept);
+    rewriteOutbox(kept, opts);
+    return discarded + (events.length - kept.length);
 }
 export function writeSessionStateSync(state, opts = {}) {
     const path = sessionStatePath(opts);

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '1.5.0';
+export const VERSION = '1.5.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "editmamei",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "Photoshop MCP server: natural-language AI photo editing in desktop Photoshop (Community Edition)",
   "mcpName": "io.github.editmamei/editmamei",
   "editmamei": {