@respira/wordpress-mcp-server 8.3.7 → 8.3.9

package/dist/__tests__/agent-signature-clientinfo.test.js

@@ -21,6 +21,17 @@ test('claude-code self-identification stays claude-code', () => {
     setMcpClientInfo('claude-code', '2.0.0');
     assert.strictEqual(detectRespiraAgentSignature().client, 'claude-code');
 });
+test('hermes agent normalizes to hermes however it names itself', () => {
+    setMcpClientInfo('hermes', '0.1');
+    assert.strictEqual(detectRespiraAgentSignature().client, 'hermes');
+    setMcpClientInfo('Hermes Agent 0.5 (desktop)', '0.5');
+    const sig = detectRespiraAgentSignature();
+    assert.strictEqual(sig.client, 'hermes');
+    assert.strictEqual(sig.source, 'client-info');
+    assert.strictEqual(sig.version, '0.5');
+    setMcpClientInfo('hermes-probe', '0.1');
+    assert.strictEqual(detectRespiraAgentSignature().client, 'hermes');
+});
 test('unknown but self-declared clients keep their sanitized name', () => {
     setMcpClientInfo('SomeNew Agent!', null);
     const sig = detectRespiraAgentSignature();

package/dist/__tests__/agent-signature-clientinfo.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-signature-clientinfo.test.js","sourceRoot":"","sources":["../../src/__tests__/agent-signature-clientinfo.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,2BAA2B,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEtF,IAAI,CAAC,qDAAqD,EAAE,GAAG,EAAE;IAC/D,OAAO,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;IACxC,OAAO,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;IACpC,OAAO,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IAEnC,gBAAgB,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;IAC5C,MAAM,GAAG,GAAG,2BAA2B,EAAE,CAAC;IAC1C,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACjD,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC9C,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,mDAAmD,EAAE,GAAG,EAAE;IAC7D,gBAAgB,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IACzC,MAAM,CAAC,WAAW,CAAC,2BAA2B,EAAE,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC1E,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,6DAA6D,EAAE,GAAG,EAAE;IACvE,gBAAgB,CAAC,gBAAgB,EAAE,IAAW,CAAC,CAAC;IAChD,MAAM,GAAG,GAAG,2BAA2B,EAAE,CAAC;IAC1C,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC9C,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AACjD,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,gDAAgD,EAAE,GAAG,EAAE;IAC1D,gBAAgB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAClC,OAAO,CAAC,GAAG,CAAC,oBAAoB,GAAG,eAAe,CAAC;IACnD,MAAM,GAAG,GAAG,2BAA2B,EAAE,CAAC;IAC1C,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAChD,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACtC,OAAO,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;AAC1C,CAAC,CAAC,CAAC"}
+{"version":3,"file":"agent-signature-clientinfo.test.js","sourceRoot":"","sources":["../../src/__tests__/agent-signature-clientinfo.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,2BAA2B,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEtF,IAAI,CAAC,qDAAqD,EAAE,GAAG,EAAE;IAC/D,OAAO,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;IACxC,OAAO,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;IACpC,OAAO,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IAEnC,gBAAgB,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;IAC5C,MAAM,GAAG,GAAG,2BAA2B,EAAE,CAAC;IAC1C,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACjD,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC9C,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,mDAAmD,EAAE,GAAG,EAAE;IAC7D,gBAAgB,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IACzC,MAAM,CAAC,WAAW,CAAC,2BAA2B,EAAE,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAC1E,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,2DAA2D,EAAE,GAAG,EAAE;IACrE,gBAAgB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAClC,MAAM,CAAC,WAAW,CAAC,2BAA2B,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAEnE,gBAAgB,CAAC,4BAA4B,EAAE,KAAK,CAAC,CAAC;IACtD,MAAM,GAAG,GAAG,2BAA2B,EAAE,CAAC;IAC1C,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACzC,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC9C,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAEvC,gBAAgB,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACxC,MAAM,CAAC,WAAW,CAAC,2BAA2B,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AACrE,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,6DAA6D,EAAE,GAAG,EAAE;IACvE,gBAAgB,CAAC,gBAAgB,EAAE,IAAW,CAAC,CAAC;IAChD,MAAM,GAAG,GAAG,2BAA2B,EAAE,CAAC;IAC1C,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAC9C,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AACjD,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,gDAAgD,EAAE,GAAG,EAAE;IAC1D,gBAAgB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAClC,OAAO,CAAC,GAAG,CAAC,oBAAoB,GAAG,eAAe,CAAC;IACnD,MAAM,GAAG,GAAG,2BAA2B,EAAE,CAAC;IAC1C,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAChD,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACtC,OAAO,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;AAC1C,CAAC,CAAC,CAAC"}

package/dist/__tests__/stale-build-and-refresh-silence.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=stale-build-and-refresh-silence.test.d.ts.map

package/dist/__tests__/stale-build-and-refresh-silence.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-build-and-refresh-silence.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/stale-build-and-refresh-silence.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/stale-build-and-refresh-silence.test.js

@@ -0,0 +1,76 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { readFileSync } from 'node:fs';
+import { RespiraVersionChecker } from '../version-checker.js';
+/**
+ * Two silences that cost a customer an afternoon, reported 2026-08-20.
+ *
+ * She added sites on the dashboard and Claude never saw them. Only deleting
+ * and reinstalling the connector worked, so she and her AI concluded the
+ * connector had a bug. They were right, and it had been fixed eleven days
+ * earlier in 8.2.4. She was running 7.1.2.
+ *
+ * The update notice fired on every single tool call the whole time. It said
+ * "a newer MCP version is available", which is true, generic, and ignorable.
+ * It never said that the thing she was fighting was the thing the update
+ * fixed, so there was nothing to connect the two.
+ *
+ * The second silence is the same shape one layer down: when the site list
+ * cannot be refreshed at all, the refresh returned 0 exactly as it does when
+ * there is genuinely nothing new. "Your new site is missing" and "I never
+ * looked" were indistinguishable.
+ */
+const PKG = '@respira/wordpress-mcp-server';
+test('a build predating the site-refresh fix is told what it is missing', () => {
+    const checker = new RespiraVersionChecker(PKG, '7.1.2');
+    const missing = checker.missingFixesFor('7.1.2');
+    assert.ok(missing.length > 0, 'a 7.1.2 build must be told it is missing behaviour');
+    const joined = missing.join(' ');
+    // Phrased as the symptom she would recognise, not as a changelog entry.
+    assert.match(joined, /added on the dashboard do not appear/i);
+    assert.match(joined, /deleted and reinstalled/i);
+});
+test('the symptom is named, not just the version number', () => {
+    const checker = new RespiraVersionChecker(PKG, '7.1.2');
+    const joined = checker.missingFixesFor('7.1.2').join(' ');
+    // The whole failure was a notice that described itself instead of the user's
+    // problem. Guard against sliding back to that.
+    assert.ok(!/^\s*a newer (mcp )?version is available/i.test(joined), 'the gap text must describe the user-visible symptom, not restate that an update exists');
+});
+test('a current build is told nothing, so the notice stays meaningful', () => {
+    const checker = new RespiraVersionChecker(PKG, '99.0.0');
+    assert.deepEqual(checker.missingFixesFor('99.0.0'), []);
+});
+test('gaps apply by version order, not by listing order', () => {
+    const checker = new RespiraVersionChecker(PKG, '8.2.4');
+    const at824 = checker.missingFixesFor('8.2.4');
+    const at712 = checker.missingFixesFor('7.1.2');
+    // 8.2.4 already HAS the site-refresh fix, so it must not be told it lacks it.
+    assert.ok(!at824.join(' ').match(/added on the dashboard do not appear/i), '8.2.4 must not be told it is missing its own fix');
+    assert.ok(at712.length > at824.length, 'an older build is missing strictly more');
+});
+test('the notice leads with the missing behaviour when there is any', () => {
+    const src = readFileSync(new URL('../../src/server.ts', import.meta.url), 'utf8');
+    assert.match(src, /missing behaviour you may be working around right now/, 'the message must lead with consequence, not with the version delta');
+    assert.match(src, /missing_fixes: update\.missingFixes/, 'the payload must carry the list');
+});
+test('a refresh that could not run is reported, not silently treated as empty', () => {
+    const src = readFileSync(new URL('../../src/server.ts', import.meta.url), 'utf8');
+    // Every bail-out branch must record a cause.
+    for (const status of ['no_account_token', 'unreachable', 'backend_error', 'disabled']) {
+        assert.ok(src.includes(`this.lastSiteRefreshStatus = '${status}'`), `the ${status} branch must record why the refresh produced nothing`);
+    }
+    // And the success path must clear it, or one failure would poison every
+    // later response.
+    assert.ok(src.includes("this.lastSiteRefreshStatus = 'ok'"), 'a successful refresh must clear the status');
+});
+test('list_sites explains the silence, and stays quiet when healthy', () => {
+    const src = readFileSync(new URL('../../src/server.ts', import.meta.url), 'utf8');
+    assert.ok(src.includes('describeSiteRefreshStatus()'), 'list_sites must consult the refresh status');
+    assert.ok(src.includes('...(refreshNotice ? { site_refresh: refreshNotice } : {})'), 'the notice must be attached only when there is something to say');
+    // A healthy refresh must add no noise, or the signal stops being read.
+    assert.match(src, /case 'never_run':\s*\n\s*case 'ok':\s*\n\s*default:\s*\n\s*return null;/, 'ok and never_run must produce no notice');
+    // The no-token case is the permanent one, so it must name the fix.
+    assert.match(src, /npx @respira\/wordpress-mcp-server --setup/, 'the permanent case must name the action');
+});
+//# sourceMappingURL=stale-build-and-refresh-silence.test.js.map

package/dist/__tests__/stale-build-and-refresh-silence.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-build-and-refresh-silence.test.js","sourceRoot":"","sources":["../../src/__tests__/stale-build-and-refresh-silence.test.ts"],"names":[],"mappings":"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"}

package/dist/agent-signature.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-signature.d.ts","sourceRoot":"","sources":["../src/agent-signature.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,KAAK,GAAG,aAAa,GAAG,WAAW,GAAG,SAAS,CAAC;CACzD;AAkCD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAQvE;AAgHD,wBAAgB,2BAA2B,IAAI,qBAAqB,CA4BnE;AAiBD,wBAAgB,sBAAsB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAkB/D"}
+{"version":3,"file":"agent-signature.d.ts","sourceRoot":"","sources":["../src/agent-signature.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,KAAK,GAAG,aAAa,GAAG,WAAW,GAAG,SAAS,CAAC;CACzD;AAuCD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAQvE;AAuHD,wBAAgB,2BAA2B,IAAI,qBAAqB,CA4BnE;AAiBD,wBAAgB,sBAAsB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAkB/D"}

package/dist/agent-signature.js

@@ -43,6 +43,12 @@ function normalizeClientInfoName(raw) {
         return n.includes('antigravity') ? 'antigravity' : 'gemini';
     if (n.includes('opencode'))
         return 'opencode';
+    // Hermes Agent (Nous Research). It already arrives as a bare "hermes" over
+    // stdio, so this branch is not what makes it attributable today: it is what
+    // keeps it attributable when the name grows ("Hermes Agent 0.5 (desktop)",
+    // "hermes-probe"), instead of minting a new slug per release.
+    if (n.includes('hermes'))
+        return 'hermes';
     // Unknown but self-declared: keep the sanitized raw name rather than
     // guessing. It surfaces new clients in telemetry instead of hiding them.
     return sanitizeHeaderToken(n);
@@ -142,6 +148,13 @@ function detectClientFromHeuristics() {
         return 'copilot';
     if (fingerprint.includes('gemini'))
         return 'gemini';
+    // No hermes branch on purpose. Hermes Agent spawns stdio MCP servers through
+    // _build_safe_env(), which copies only PATH/HOME/USER/LANG/LC_ALL/TERM/SHELL/
+    // TMPDIR, XDG_*, Windows location vars, and user-declared secrets: no
+    // HERMES_* marker survives. It also rewrites argv to
+    // `python -m tools.mcp_stdio_watchdog <real command>`, so the ps parent does
+    // not name Hermes either. There is nothing real to match on, and inventing a
+    // pattern would only mislabel someone else. clientInfo covers it instead.
     return 'unknown';
 }
 function detectVersion(client) {

package/dist/agent-signature.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-signature.js","sourceRoot":"","sources":["../src/agent-signature.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-signature.js","sourceRoot":"","sources":["../src/agent-signature.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -81,6 +81,11 @@ export declare class RespiraWordPressServer {
     private versionWarningShown;
     /** Epoch ms of the last site-list self-heal against respira.press (throttle). */
     private lastSiteRefreshAt;
+    /**
+     * Why the last site refresh produced what it produced. Surfaced by
+     * list_sites so "your new site is not here" always comes with a reason.
+     */
+    private lastSiteRefreshStatus;
     /** Dedupe concurrent self-heals so parallel list_sites calls share one fetch. */
     private siteRefreshInFlight;
     /**
@@ -201,6 +206,15 @@ export declare class RespiraWordPressServer {
      * @returns number of newly added sites.
      */
     private maybeSelfHealSiteList;
+    /**
+     * Explain a site refresh that did not confirm the list, or stay quiet.
+     *
+     * Returns null on the happy path, so a healthy response carries no noise.
+     * Every other branch names the cause and the one action that resolves it,
+     * because the symptom the user reports is always the same sentence: the site
+     * I added is not here.
+     */
+    private describeSiteRefreshStatus;
     private performSiteRefresh;
     /** Normalize a site URL for cross-config dedupe: scheme/host only, no www, lowercase. */
     private normalizeSiteUrl;

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/server.js

@@ -380,6 +380,11 @@ export class RespiraWordPressServer {
     versionWarningShown = false;
     /** Epoch ms of the last site-list self-heal against respira.press (throttle). */
     lastSiteRefreshAt = 0;
+    /**
+     * Why the last site refresh produced what it produced. Surfaced by
+     * list_sites so "your new site is not here" always comes with a reason.
+     */
+    lastSiteRefreshStatus = 'never_run';
     /** Dedupe concurrent self-heals so parallel list_sites calls share one fetch. */
     siteRefreshInFlight = null;
     /**
@@ -1402,6 +1407,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
      */
     async maybeSelfHealSiteList(force = false) {
         if (process.env.RESPIRA_DISABLE_SITE_REFRESH === '1') {
+            this.lastSiteRefreshStatus = 'disabled';
             return 0;
         }
         const throttleMs = Number(process.env.RESPIRA_SITE_REFRESH_THROTTLE_MS) || 60_000;
@@ -1416,6 +1422,42 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
         });
         return this.siteRefreshInFlight;
     }
+    /**
+     * Explain a site refresh that did not confirm the list, or stay quiet.
+     *
+     * Returns null on the happy path, so a healthy response carries no noise.
+     * Every other branch names the cause and the one action that resolves it,
+     * because the symptom the user reports is always the same sentence: the site
+     * I added is not here.
+     */
+    describeSiteRefreshStatus() {
+        switch (this.lastSiteRefreshStatus) {
+            case 'no_account_token':
+                return {
+                    status: 'no_account_token',
+                    detail: 'The site list could not be checked against your account, because none of the configured sites holds a dashboard-issued token (respira_site_...). Sites added on the dashboard will not appear here until this config is refreshed. Run: npx @respira/wordpress-mcp-server --setup, or reconnect a site from https://www.respira.press/dashboard/sites.',
+                };
+            case 'unreachable':
+                return {
+                    status: 'unreachable',
+                    detail: 'respira.press could not be reached to confirm the site list, so this is the list this server started with. A site added recently may be missing. Usually a network, proxy, or firewall issue; it retries by itself.',
+                };
+            case 'backend_error':
+                return {
+                    status: 'backend_error',
+                    detail: 'respira.press was reached but did not return a usable site list, so this is the list this server started with. A site added recently may be missing.',
+                };
+            case 'disabled':
+                return {
+                    status: 'disabled',
+                    detail: 'Automatic site-list refresh is switched off by RESPIRA_DISABLE_SITE_REFRESH=1, so newly added sites will not appear here until this server restarts with an updated config.',
+                };
+            case 'never_run':
+            case 'ok':
+            default:
+                return null;
+        }
+    }
     async performSiteRefresh() {
         // Any one live dashboard site token identifies the account. OAuth
         // per-site tokens (rsp_at_) are not account-wide and are skipped.
@@ -1431,6 +1473,11 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
         // retry the loop on every single list_sites call.
         this.lastSiteRefreshAt = Date.now();
         if (!token) {
+            // Returning 0 here used to be indistinguishable from "checked, nothing
+            // new". On an OAuth-only or hand-edited config that silence is permanent:
+            // the list can never grow and nothing ever says why. Record it so
+            // list_sites can explain instead of just looking wrong.
+            this.lastSiteRefreshStatus = 'no_account_token';
             return 0;
         }
         const apiBase = process.env.RESPIRA_API_BASE || 'https://www.respira.press';
@@ -1445,18 +1492,24 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 signal: AbortSignal.timeout(timeoutMs),
             });
             if (!response.ok) {
+                this.lastSiteRefreshStatus = 'backend_error';
                 return 0;
             }
             payload = await response.json();
         }
         catch {
+            this.lastSiteRefreshStatus = 'unreachable';
             // Offline / proxy / firewall / timeout: never block list_sites on this.
             return 0;
         }
         const sites = payload?.config?.sites;
         if (!Array.isArray(sites)) {
+            this.lastSiteRefreshStatus = 'backend_error';
             return 0;
         }
+        // Reached the account inventory. Anything not added past this point is
+        // genuinely "nothing new", which is a different thing from "could not look".
+        this.lastSiteRefreshStatus = 'ok';
         const knownUrls = new Set();
         for (const client of this.sites.values()) {
             knownUrls.add(this.normalizeSiteUrl(client.getSiteUrl()));
@@ -1876,12 +1929,20 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
         if (!update) {
             return result;
         }
+        // Lead with what this build is missing, not with the fact that a number
+        // changed. A customer on 7.1.2 received the old generic sentence on every
+        // call for weeks while fighting a bug that a newer build had already fixed,
+        // and neither she nor her AI had any reason to connect the two.
+        const message = update.missingFixes.length > 0
+            ? `This MCP build (${update.currentVersion}) is behind ${update.latestVersion} and is missing behaviour you may be working around right now: ${update.missingFixes.join(' ')} Update with: npm i -g @respira/wordpress-mcp-server@latest`
+            : `A newer MCP version is available (${update.currentVersion} -> ${update.latestVersion}). Please update your local MCP package.`;
         const noticePayload = {
             package: update.packageName,
             current_version: update.currentVersion,
             latest_version: update.latestVersion,
             checked_at: update.checkedAt,
-            message: `A newer MCP version is available (${update.currentVersion} -> ${update.latestVersion}). Please update your local MCP package.`,
+            ...(update.missingFixes.length > 0 ? { missing_fixes: update.missingFixes } : {}),
+            message,
             upgrade_command: 'npm i -g @respira/wordpress-mcp-server@latest',
             rerun_setup_command: 'npx @respira/wordpress-mcp-server --setup',
         };
@@ -2237,7 +2298,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             },
             {
                 name: 'wordpress_read_post',
-                description: 'Get full content of a specific post. Response includes author object ({id, login, display_name}), taxonomies map ({category, post_tag, ...} each with term {id, name, slug}), and featured_media ({id, url}) alongside title/content/slug/status/date/url/meta.',
+                description: 'Get full content of a specific post. Returns title/content/slug/status/date/url/meta by default. author ({id, login, display_name}), taxonomies map ({category, post_tag, ...} each with term {id, name, slug}) and featured_media ({id, url}) are each opt-in via include, e.g. include="author,taxonomies,featured_media". Multiple values are comma-separated in one call.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -4845,7 +4906,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             },
             {
                 name: 'wordpress_list_custom_posts',
-                description: 'List posts of a custom post type. Each row includes author ({id, login, display_name}), taxonomies map, and featured_media alongside id/title/slug/status/date/url.',
+                description: 'List posts of a custom post type. Each row returns id/title/slug/status/date/url by default. author ({id, login, display_name}), taxonomies map and featured_media ({id, url}) are each opt-in via include, e.g. include="author,featured_media". Multiple values are comma-separated in one call.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -7474,6 +7535,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                 // started shows up here without a reinstall or re-paste (throttled,
                 // best-effort, never throws).
                 await this.maybeSelfHealSiteList();
+                const refreshNotice = this.describeSiteRefreshStatus();
                 const allSites = Array.from(this.sites.values());
                 const visibleSites = allSites.filter((site) => this.isSiteAllowed(site));
                 // v6.17.2: surface hidden sites so the AI can explain
@@ -7492,6 +7554,11 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                             filter_note: `${hiddenSites.length} site${hiddenSites.length === 1 ? '' : 's'} hidden by RESPIRA_SITES env var (allow-list: ${this.allowedSites ? [...this.allowedSites].join(', ') : 'none'}). To show, remove or update RESPIRA_SITES in claude_desktop_config.json.`,
                         }
                         : {}),
+                    // Present only when the list could NOT be confirmed against the
+                    // account. "A site I just added is missing" and "the refresh never
+                    // ran" look identical without this, and the user is left concluding
+                    // the connector is broken when it simply never looked.
+                    ...(refreshNotice ? { site_refresh: refreshNotice } : {}),
                 };
             }
             case 'wordpress_get_active_site':