@wickedevolutions/abilities-mcp 1.6.2 → 1.6.4

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to Abilities MCP are documented here.
 
+## [Unreleased]
+
+## [1.6.4] - 2026-05-17
+
+### Added
+
+- **Opt-in silent sliding-renewal OAuth (Issue [#90](https://github.com/Wicked-Evolutions/abilities-mcp/issues/90); depends on [#89](https://github.com/Wicked-Evolutions/abilities-mcp/issues/89)).** A new per-site `auth.sliding_renewal` flag in `wp-sites.json` (default **off**). When **off / absent / any value that is not strictly `true`**, behavior is byte-identical to today: the refresh token stays bounded (~90 days from initial authorization) and `reauth` is required after that, regardless of use. When **on**, every successful token refresh advances the on-disk `refresh_token_expires_at` to mirror the fresh TTL the adapter re-issues on rotation (`abilities-mcp-adapter` `TokenStore::REFRESH_TTL` = 90d), so an **actively-used** site renews indefinitely and never forces reauth; it still lapses normally if left untouched past the window (no refresh within ~90d → next use hits the #89 reauth path). The slide is gated end-to-end: `token-manager.js` only advances the expiry when `siteAuth.slidingRenewal === true`; the transport only invokes the new `onTokensRenewed` persist callback for opt-in sites — **flag-off sites get no new write path** (no new disk writes vs. today). `list-sites` already surfaces the live `refresh_token_expires_at` (added in #89) so the window is operator-visible. Bridge-only; adapter untouched. The bridge mirrors the adapter's `REFRESH_TTL` constant in code (documented as a contract mirror); a split, non-blocking follow-up to have the adapter emit `refresh_expires_in` so the bridge reads the server's effective TTL instead of mirroring is tracked at [abilities-mcp-adapter#120](https://github.com/Wicked-Evolutions/abilities-mcp-adapter/issues/120). No released ability contract change (Principle 10 — opt-in flag + additive callback; default path unchanged).
+  - **⚠️ Security trade-off (explicit per-site operator choice, documented at enable-time + in the README).** Sliding renewal extends the refresh window indefinitely for actively-used sites, so a leaked/exfiltrated refresh token has a **longer blast radius** than the default bounded credential (which self-expires ≤90 days after initial authorization no matter what). It is never enabled implicitly, by migration, or by `add-site`/`reauth` — the operator must set the flag deliberately. Chosen over a very-long static TTL / app-password mode precisely because only *actively-used* sites stay alive (idle sites still lapse → smaller exposure).
+  - Proven against the bridge's own harness (`test/auth/token-manager.test.js` + `test/transports/oauth-http-transport.test.js` + `test/manual/repro-90.js`), not the MCP path: flag-on slides indefinitely while used; flag-off `refresh_token_expires_at` byte-identical across refreshes (default-preserved guard); idle-past-window lapses to reauth (#89 path); REVOKED / terminal-4xx unaffected (sliding acts only on a successful refresh); flag-off never reaches the persist callback. Full `node --test`: 427/427.
+
+### Fixed
+
+- **Sticky `auth_status="expired"` no longer blocks refresh when the refresh token is still valid (Issue [#89](https://github.com/Wicked-Evolutions/abilities-mcp/issues/89); structural root deferred from [#76](https://github.com/Wicked-Evolutions/abilities-mcp/issues/76)).** A single transient 4xx during token refresh flipped `auth_status` to `expired` on disk; from then on `refresh()` short-circuited on the cached enum and never called the token endpoint again — even though the refresh token was valid for months — so sites got stuck "expired" until manual reauth (the wickedevolutions / helenawillow incident; root-caused and Path-A live-validated in #76, 2026-05-09). Two coupled defects in `lib/auth/token-manager.js`, fixed minimally: **(1)** `refresh()` now consults the on-disk `refreshTokenExpiresAt` — it only short-circuits a cached `authStatus === "expired"` when the refresh token is *genuinely* past/missing expiry; otherwise it lets the token endpoint be the authority (new `_refreshTokenActuallyExpired()` helper). **(2)** the 4xx→`expired` persist is gated on **strong evidence** (B-orchestrator-approved minimal gate): an explicitly-terminal OAuth error (`invalid_client` / `unauthorized_client` / `revoked`) **or** a genuinely past/missing `refresh_token_expires_at`. A lone transient `invalid_grant` while the refresh token is still valid is now surfaced as a **retryable** error with no `auth_status` write, so the next use/boot re-attempts instead of staying stuck. The genuine-expiry terminal path (real 4xx with a past refresh-token expiry → `expired` + reauth hint) is preserved and explicitly regression-guarded; `REVOKED` stays terminal. `list-sites` now annotates each OAuth site with the actual `refresh_token_expires_at` so the discrepancy between a stale cached badge and underlying validity is operator-visible and self-recoverable. No cross-boot failure counter and no schema-v2 change (composes later via #90 if wanted). Adapter untouched; bridge-only. No released ability contract change (Principle 10 — internal refresh behavior + additive CLI annotation). Proven against the bridge's own units (`test/auth/token-manager.test.js` incl. Case 1 / Case 4 / REVOKED / transient-gate; `test/cli/list-sites.test.js`; `test/manual/repro-89.js`), not the MCP path; full `node --test` suite green (421/421).
+
+- **Single (default) site's request-time refresh expiry no longer blanket-degrades the whole bridge; degraded mode is no longer sticky for the recoverable single-site case (Issue [#87](https://github.com/Wicked-Evolutions/abilities-mcp/issues/87) S1/S2).** The #76 request-time follow-up (v1.6.2, PR #82) intercepted a failed cached-`initialize` forward and called `enterDegradedMode([defaultSite])` — flipping the **entire router** to degraded for a single default-site refresh-token expiry, with no per-site fallback and no recovery path. Because OAuth `transport.connect()` does not pre-validate refresh tokens, `connectDefault`'s boot-time per-site fallback never fired (the default site "connects" cleanly and only fails when the cached `initialize` is forwarded), so a single expired default-site token took down healthy non-default sites too: every `tools/call` — including `mcp-adapter-execute-ability {site: <healthy-site>}`, which routes through an independent per-site lazy transport — was blanket-refused `-32603 "bridge is running in degraded mode"` (S1, blast-radius coupling). The whole-router `degraded` flag was set once and never cleared, so the running bridge process never recovered after reauth — only a brand-new client conversation (new process) did (S2, sticky per-session stale catalog). `lib/router.js` now mirrors the boot path at the request-time boundary: on a cached-`initialize` forward failure it attempts a healthy fallback site (`lib/connection-pool.js#connectFallback` — tears down the failed site's stale transport, marks it degraded in-memory, connects the first healthy *other* site and promotes it to runtime default), re-forwards the cached `initialize` through it so the client gets a real `InitializeResult` and the tool catalog populates normally, and enters degraded mode **only** when no site can serve. The genuine all-sites-down case still synthesizes a valid `InitializeResult` and enters degraded mode — the #76 init-death gate is preserved and explicitly regression-guarded. **Convergence (PR #88 reviewer blocker):** because `transport.connect()` does not validate refresh tokens, a freshly-connected fallback can itself fail the re-forwarded `initialize`; the router now accumulates every site that has failed the *cached initialize* (`McpRouter._initFailedSites`) and `connectFallback` excludes that whole set, so the candidate pool strictly shrinks and the chain provably terminates — once every configured site has failed the initialize the #76 all-sites-down gate fires instead of two bad-token OAuth sites alternating forever. No released ability contract changes (Principle 10): this is internal bridge recovery behavior only. Proven against the bridge's own units (`test/router-degraded-mode.test.js` incl. the two-OAuth-sites convergence guard, `test/manual/repro-87.js`), not the MCP tool path; full `node --test` suite green (417/417).
+
+## [1.6.3] - 2026-05-12
+
+### Fixed
+
+- **Sanitizer normalizes array-shaped `inputSchema.properties` (Issue [#83](https://github.com/Wicked-Evolutions/abilities-mcp/issues/83), Sprint C 2026-05-11).** Extends `validateToolSchema` in `lib/sanitizer.js` so that when a tool's `inputSchema.properties` is an array (PHP `'properties' => array()` JSON-encodes to `[]`), `null`, a string, or any other non-plain-object value, it is normalized to `{}` before client emission. The previous v1.6.2 fix (#78/#79) normalized broken top-level `inputSchema` but left malformed nested `properties` untouched — the value passed `typeof === 'object'` (arrays are objects in JS) and reached the `Object.entries()` loop unchanged. Anthropic's draft 2020-12 validator rejects the entire `tools/list` payload on the first invalid schema (`/properties must be object`), so a single vendor-registered `properties: []` shape breaks the whole catalog. Defends against the entire class of vendor-registered ability schema slips that share the `properties: []` shape; SureCart's `surecart/get-store-info` was the trigger case (live capture from helenawillow.com 2026-05-11, 1 of 789 tools failing) but the fix is name-agnostic. Boundary discipline binding: `inputSchema: { type: "object" }` shapes that omit the `properties` key entirely remain byte-unchanged (early-return on `schema.properties === undefined` before the malformed-shape normalize). Already-valid object-shaped `properties` pass through byte-identical (regression-guarded with reference-equality assertion in `test/sanitizer.test.js`).
+
+- **Bridge orientation: `mcp-adapter-*` reliably visible as the cross-site discovery path when filtering is enabled; `wp_browse_tools` / `wp_load_tools` describe themselves honestly (Issue [#85](https://github.com/Wicked-Evolutions/abilities-mcp/issues/85), Sprint C-follow-up 2026-05-12).** Surfaced during v1.6.3 release validation: AI clients were orienting around the bridge-local meta-tools first, treating their default-site catalog as the full ability surface and missing abilities registered only on non-default sites (e.g., `surecart/get-store-info` on helenawillow when `defaultSite=wickedevolutions`). The cross-site execution path via `mcp-adapter-discover-abilities` / `mcp-adapter-get-ability-info` / `mcp-adapter-execute-ability` already worked correctly — it just wasn't the path clients reached for. Three minimal changes restore orientation without changing architecture: (1) `lib/tool-catalog.js` — when `toolFilter.enabled === true` and the operator has not set their own `alwaysIncludeCategories`, default to `['mcp-adapter']` so the five `mcp-adapter-*` tools are always callable without a prior `wp_load_tools` step. Explicit operator override (including `[]`) is honored — guarded against the `[] || ['mcp-adapter']` truthy-array pitfall with an explicit `undefined`/`null` check. (2) `lib/bridge-tools.js` — `wp_browse_tools` and `wp_load_tools` descriptions now explicitly state they operate on the direct-tool catalog scoped to the default site, not full cross-site ability discovery. (3) `lib/router.js` — `wp_browse_tools` response leads with a `Scope:` line; `wp_load_tools` computes which requested categories are missing from the catalog and returns a structured pointer ("Not in the direct-tool catalog (scoped to defaultSite `<site>`): `<category>`. To call abilities in this category on another site, use `mcp-adapter-discover-abilities` with `{site, category}` then `mcp-adapter-execute-ability` with `{site, ability_name, parameters}`") instead of the prior silent "No changes — categories may already be active" zero-activation. No union-catalog architecture introduced; no `defaultSite`-switching workaround required; adapter unchanged. Acceptance pin: with `defaultSite = wickedevolutions` and `toolFilter.enabled = true`, a fresh session can discover and execute `surecart/get-store-info` on `helenawillow` through the adapter meta-tool path without changing `defaultSite` (empirically verified, MD5-pinned behavior-reversal cycle, 415/415 tests passing).
+
+### Compatibility & operator notes
+
+- **No protocol semantics change** for valid schemas. Healthy operators see no behavioral difference. The fix activates only on the malformed-`properties` shape it closes.
+- **No operator action required** — passive defensive normalization on next bridge restart.
+- **Coordinated release wave** — held for joint release with abilities-mcp-adapter v1.4.8 per the cross-sprint coupling decision.
+
 ## [1.6.2] - 2026-05-10
 
 Schema validity polish + boot fragility MVP + multisite topology gate. Four Bridge fixes ship together as a bundled release closing the operator-side schema-400 + the silent-bridge-death-on-expired-refresh-token (both connect-time and request-time refresh boundaries) + the misplaced-multisite-block-cross-product issues.

package/README.md

@@ -272,6 +272,27 @@ Bare `abilities-mcp` (no subcommand) starts the MCP STDIO server — the mode ev
 
 OAuth-managed sites added through `abilities-mcp add-site` are written to `~/.abilities-mcp/wp-sites.json` automatically — they carry an `auth.method: "oauth"` block with keychain references rather than inline secrets.
 
+### Sliding-renewal OAuth (opt-in, off by default)
+
+By default an OAuth credential is bounded: the refresh token expires roughly **90 days after the initial authorization**, regardless of how often the site is used, after which `reauth` is required. This is unchanged and remains the default for every site.
+
+You can opt a site into **silent sliding renewal** by setting `"sliding_renewal": true` inside that site's `auth` block in `wp-sites.json`:
+
+```json
+"sites": {
+  "mysite": {
+    "url": "https://example.com",
+    "auth": { "method": "oauth", "sliding_renewal": true, "...": "..." }
+  }
+}
+```
+
+With it enabled, every successful token refresh advances the refresh-token expiry, so a site that is **actively used keeps renewing indefinitely and never forces reauth**. It still lapses normally if the site is left untouched past the window (no refresh within ~90 days → next use requires `reauth`).
+
+> ⚠️ **Security trade-off — explicit operator choice.** Sliding renewal extends the refresh window indefinitely for actively-used sites. A leaked or exfiltrated refresh token therefore has a **longer blast radius** than the default bounded credential (which self-expires ≤90 days after initial authorization no matter what). Enable it only per-site, deliberately, for sites where uninterrupted automation outweighs that exposure. It is never enabled implicitly, never by migration, and never by `add-site`/`reauth` — you must set the flag yourself.
+
+It is per-site: sites without the flag keep the default bounded behavior, byte-for-byte. `abilities-mcp list-sites` shows each OAuth site's actual `refresh_token_expires_at` so you can see the live window.
+
 ### Config search order
 
 1. `--config=/path/to/wp-sites.json` (explicit)

package/lib/auth/token-manager.js

@@ -55,6 +55,12 @@ const { AUTH_STATUS } = require('./events');
  * @property {string} accessTokenExpiresAt      ISO 8601
  * @property {string} refreshTokenExpiresAt     ISO 8601
  * @property {string} authStatus                'active' | 'expired' | 'revoked' | 'pending-reauth'
+ * @property {boolean} [slidingRenewal]         Issue #90: opt-in. When true,
+ *                                              a successful refresh advances
+ *                                              refreshTokenExpiresAt to mirror
+ *                                              the adapter's re-issued TTL
+ *                                              (sliding window). Absent/false
+ *                                              = default bounded behavior.
  *
  * Copyright (C) 2026 Influencentricity | Wicked Evolutions
  * @license GPL-2.0-or-later
@@ -65,6 +71,35 @@ const HTTP_TIMEOUT_MS = 30_000;
 const MAX_RETRIES = 2;
 const SECRET_SERVICE = 'abilities-mcp';
 
+// Issue #89: OAuth token-endpoint `error` codes that are STRONG terminal
+// evidence — the grant is really gone, reauth is genuinely required. A bare
+// `invalid_grant` is intentionally NOT here: it can occur on a transient
+// server-state hiccup, and treating it as terminal while the refresh token is
+// still valid for months is exactly the sticky-expired trap (#76/#89). Such a
+// transient is gated by actual on-disk refresh-token expiry instead.
+const TERMINAL_OAUTH_ERRORS = new Set([
+  'invalid_client',
+  'unauthorized_client',
+  'revoked',
+]);
+
+// Issue #90 (opt-in sliding renewal): explicit ADAPTER-CONTRACT MIRROR, not a
+// bare bridge constant. The adapter (abilities-mcp-adapter,
+// src/Auth/OAuth/TokenStore.php) defines `REFRESH_TTL = 7776000` (90d) and
+// re-issues a brand-new refresh token with a fresh REFRESH_TTL on EVERY
+// `refresh_token` grant (TokenStore::rotate() → issue(... REFRESH_TTL ...)).
+// So while a site is actively used the server-side credential already slides;
+// the bridge just needs to persist that slid expiry instead of the frozen
+// issuance value — but ONLY when the operator opts in per-site.
+//
+// The adapter does not yet emit `refresh_expires_in` in the token response, so
+// the bridge cannot read the server's effective TTL and mirrors the constant
+// here. Tracked as a split, non-blocking follow-up:
+//   https://github.com/Wicked-Evolutions/abilities-mcp-adapter/issues/120
+// Keep this value in sync with the adapter's TokenStore::REFRESH_TTL until
+// that follow-up lands and the bridge can compute the slide from the response.
+const ADAPTER_REFRESH_TTL_SECONDS = 90 * 24 * 3600; // mirror: TokenStore::REFRESH_TTL (7776000)
+
 class TokenManager {
   /**
    * @param {object} args
@@ -126,6 +161,27 @@ class TokenManager {
     return msUntilExpiry <= REFRESH_WINDOW_SECONDS * 1000;
   }
 
+  /**
+   * Issue #89: is the refresh token genuinely past its on-disk expiry (or has
+   * no usable expiry recorded)? This is the trust signal for deciding whether
+   * a cached `authStatus === "expired"` enum is believable, and whether a 4xx
+   * from the token endpoint is strong terminal evidence.
+   *
+   * A missing or unparseable `refreshTokenExpiresAt` is treated as expired
+   * (conservative — preserves the genuine-expiry terminal path when the field
+   * is absent; never makes a stuck site stickier than before).
+   *
+   * @param {SiteAuthState} siteAuth
+   * @returns {boolean} true when the refresh token is past/has-no expiry.
+   */
+  _refreshTokenActuallyExpired(siteAuth) {
+    const raw = siteAuth && siteAuth.refreshTokenExpiresAt;
+    if (!raw) return true;
+    const expiresAt = Date.parse(raw);
+    if (Number.isNaN(expiresAt)) return true;
+    return expiresAt <= this._now();
+  }
+
   // ---------------------------------------------------------------------
   // Refresh
   // ---------------------------------------------------------------------
@@ -144,7 +200,16 @@ class TokenManager {
    * @returns {Promise<{tokens: TokenSet, updatedAuth: SiteAuthState}>}
    */
   async refresh(siteAuth) {
-    if (siteAuth.authStatus === AUTH_STATUS.EXPIRED) {
+    // Issue #76/#89: do NOT trust a cached `authStatus === "expired"` enum on
+    // its own. A single transient 4xx can have flipped it on disk while the
+    // refresh token is still valid for months; short-circuiting here is what
+    // made the state sticky (only manual reauth recovered). Consult the
+    // on-disk `refreshTokenExpiresAt`: only short-circuit when the refresh
+    // token is genuinely past/missing expiry. Otherwise fall through and let
+    // the token endpoint be the authority — it returns a real 4xx if the
+    // token is actually dead (the genuine-expiry terminal path, preserved).
+    if (siteAuth.authStatus === AUTH_STATUS.EXPIRED &&
+        this._refreshTokenActuallyExpired(siteAuth)) {
       throw new RefreshError(
         `Refresh token expired for site "${siteAuth.siteId}". ` +
         `Run: abilities-mcp reauth ${siteAuth.siteId}`,
@@ -201,23 +266,45 @@ class TokenManager {
           { code: 'server_error', state: 'refreshing', cause: { statusCode: res.statusCode, body: res.body } }
         );
       }
-      // 4xx → never retry.
+      // 4xx → never retry the HTTP call. But Issue #89: gate the *terminal*
+      // `authStatus="expired"` persist on STRONG evidence (minimal gate,
+      // B-orchestrator-approved option a):
+      //   - an explicitly-terminal OAuth error (invalid_client /
+      //     unauthorized_client / revoked), OR
+      //   - the on-disk refresh_token_expires_at is genuinely past/missing.
+      // A lone transient `invalid_grant` while the refresh token is still
+      // valid for months must NOT flip the sticky flag — that evidence-free
+      // write is what armed the #76/#89 trap. In that case surface a
+      // retryable error and leave `auth_status` untouched so the next use /
+      // boot re-attempts against the token endpoint.
       if (res.statusCode >= 400 && res.statusCode <= 499) {
         const oauthError = res.json && res.json.error ? res.json.error : 'invalid_grant';
         const description = res.json && res.json.error_description;
-        // Mark the site as expired so the caller can route the operator to reauth.
-        const updatedAuth = { ...siteAuth, authStatus: AUTH_STATUS.EXPIRED };
+        const terminal =
+          TERMINAL_OAUTH_ERRORS.has(oauthError) ||
+          this._refreshTokenActuallyExpired(siteAuth);
+
         const err = new RefreshError(
-          `Refresh rejected (${oauthError}${description ? ': ' + description : ''}). ` +
-          `Run: abilities-mcp reauth ${siteAuth.siteId}`,
+          `Refresh rejected (${oauthError}${description ? ': ' + description : ''}).` +
+          (terminal
+            ? ` Run: abilities-mcp reauth ${siteAuth.siteId}`
+            : ' Transient server-state — refresh token still valid; will retry on next use.'),
           {
             code: oauthError,
             state: 'refreshing',
             cause: { statusCode: res.statusCode, body: res.body },
           }
         );
-        err.updatedAuth = updatedAuth;
-        err.reauthHint = { siteId: siteAuth.siteId, command: `abilities-mcp reauth ${siteAuth.siteId}` };
+        if (terminal) {
+          // Strong evidence — route the operator to reauth and persist the
+          // terminal state (the genuine-expiry path, preserved).
+          err.updatedAuth = { ...siteAuth, authStatus: AUTH_STATUS.EXPIRED };
+          err.reauthHint = { siteId: siteAuth.siteId, command: `abilities-mcp reauth ${siteAuth.siteId}` };
+        } else {
+          // Transient — do NOT attach updatedAuth (the wp-sites.json persist
+          // trigger). Mark retryable so callers/logs can distinguish it.
+          err.retryable = true;
+        }
         throw err;
       }
       // 2xx
@@ -255,6 +342,20 @@ class TokenManager {
       authStatus: AUTH_STATUS.ACTIVE,
     };
 
+    // Issue #90: opt-in silent sliding renewal. Default (flag absent/false):
+    // `refreshTokenExpiresAt` is carried unchanged from `...siteAuth` above —
+    // byte-identical to today's bounded ~90-days-from-initial-auth behavior,
+    // and `slidingRenewal` is left on updatedAuth so the persistence layer
+    // can tell this rotation must NOT open a new write path. When the
+    // operator has enabled it for this site, advance the on-disk refresh-token
+    // expiry to mirror the fresh TTL the adapter just re-issued on rotation,
+    // so an actively-used site renews indefinitely (it still lapses if left
+    // untouched past the window — the next refresh hits the #89 expiry path).
+    if (siteAuth.slidingRenewal === true) {
+      updatedAuth.refreshTokenExpiresAt =
+        new Date(this._now() + ADAPTER_REFRESH_TTL_SECONDS * 1000).toISOString();
+    }
+
     return { tokens, updatedAuth };
   }
 

package/lib/bridge-tools.js

@@ -23,7 +23,8 @@ const BRIDGE_TOOLS = [
   },
   {
     name: 'wp_browse_tools',
-    description: 'List available WordPress tool categories with tool counts. Shows which categories are currently loaded. Use wp_load_tools to activate categories.',
+    description:
+      'List categories in the bridge\'s direct-tool catalog (scoped to defaultSite) with tool counts and load-state. This is the local-catalog control surface — not full cross-site ability discovery. For abilities on another site, or in a category not listed here, use mcp-adapter-discover-abilities / mcp-adapter-execute-ability with { site }.',
     inputSchema: {
       type: 'object',
       properties: {},
@@ -31,14 +32,16 @@ const BRIDGE_TOOLS = [
   },
   {
     name: 'wp_load_tools',
-    description: 'Activate WordPress tool categories to make their tools available. After loading, the tools list is automatically refreshed.',
+    description:
+      'Activate categories in the bridge\'s direct-tool catalog (scoped to defaultSite) to expose their tools in tools/list. This is the local-catalog control surface — not full cross-site ability discovery. If a requested category is not in the local catalog, the response points to mcp-adapter-discover-abilities + mcp-adapter-execute-ability for the cross-site path.',
     inputSchema: {
       type: 'object',
       properties: {
         categories: {
           type: 'array',
           items: { type: 'string' },
-          description: 'Category names to activate (e.g. ["fluent-crm", "content", "media"]). Use wp_browse_tools to see available categories.',
+          description:
+            'Category names to activate from the direct-tool catalog (e.g. ["fluent-crm", "content", "media"]). Use wp_browse_tools to see available categories. Categories not in the local catalog return a pointer to mcp-adapter-discover-abilities instead of silently activating nothing.',
         },
         deactivate: {
           type: 'array',

package/lib/cli/commands/list-sites.js

@@ -64,6 +64,18 @@ async function run(args, ctx) {
       statusBadge += ' +apppassword-fallback';
     }
 
+    // Issue #89: surface the ACTUAL refresh-token expiry so the discrepancy
+    // between a (possibly stale) cached status badge and the underlying
+    // refresh-token validity is operator-visible and self-recoverable. The
+    // EXPIRES column is the access token; this annotation is the refresh
+    // token (the 90-day "authorize once" window).
+    let refreshExpiresAnnotation = null;
+    if (isOAuth && auth.refresh_token_expires_at) {
+      refreshExpiresAnnotation =
+        `refresh token: valid until ${auth.refresh_token_expires_at} ` +
+        `(${expiresLabel(auth.refresh_token_expires_at, nowMs)})`;
+    }
+
     let downgradeAnnotation = null;
     if (site.force_downgrade) {
       const expiresAt = Date.parse(site.force_downgrade.expires_at);
@@ -82,6 +94,7 @@ async function run(args, ctx) {
       scopesShort,
       expires,
       statusBadge,
+      refreshExpiresAnnotation,
       downgradeAnnotation,
     });
   }

package/lib/cli/output.js

@@ -114,6 +114,9 @@ function renderSiteTable(rows, opts = {}) {
     lines.push(fmt([
       r.siteId, r.url, r.authMethod, r.user, r.scopesShort, r.expires, r.statusBadge,
     ]));
+    if (r.refreshExpiresAnnotation) {
+      lines.push(`  ${r.refreshExpiresAnnotation}`);
+    }
     if (r.downgradeAnnotation) {
       lines.push(`  ${r.downgradeAnnotation}`);
     }

package/lib/connection-pool.js

@@ -24,6 +24,16 @@ function _siteAuthFromConfig(siteId, siteConfig, asMetadata) {
     accessTokenExpiresAt: siteConfig.auth.access_token_expires_at,
     refreshTokenExpiresAt: siteConfig.auth.refresh_token_expires_at,
     authStatus: siteConfig.auth_status || 'active',
+    // Issue #90: opt-in sliding renewal. Strictly === true so any
+    // missing/false/truthy-but-not-true value is the default bounded path.
+    //
+    // SECURITY TRADE-OFF (operator chose this per-site by setting
+    // auth.sliding_renewal:true in wp-sites.json): an actively-used site's
+    // refresh window then extends indefinitely, so a leaked refresh token has
+    // a longer blast radius than the default ≤90-days-from-initial-auth cap.
+    // Never enabled implicitly / by migration / by add-site|reauth. See
+    // README "Sliding-renewal OAuth (opt-in, off by default)".
+    slidingRenewal: siteConfig.auth.sliding_renewal === true,
   };
 }
 
@@ -50,6 +60,11 @@ class ConnectionPool {
    *                                          Persists to wp-sites.json. Defaults to
    *                                          atomic write via config-migration._atomicWrite
    *                                          when config._configPath is set.
+   * @param {function} [deps.persistSlidingRenewal] (siteId, updatedAuth) => void
+   *                                          Issue #90. Persists the slid
+   *                                          refresh expiry + rotated refs for
+   *                                          opt-in sites only. Defaults to an
+   *                                          atomic write when _configPath set.
    * @param {boolean} [deps.allowInsecure]    For local-dev OAuth over HTTP
    */
   constructor(config, logger, deps = {}) {
@@ -66,6 +81,7 @@ class ConnectionPool {
     this._discover = deps.discover || null;
     this._allowInsecure = !!deps.allowInsecure;
     this._persistAuthStatus = deps.persistAuthStatus || null;
+    this._persistSlidingRenewal = deps.persistSlidingRenewal || null;
 
     // Cache of OAuth AS metadata per site URL — avoids re-probing .well-known
     // on every transport rebuild. Refreshed when the transport is recreated.
@@ -187,6 +203,69 @@ class ConnectionPool {
     return null;
   }
 
+  /**
+   * Issue #87 (S1/S2): request-time per-site fallback.
+   *
+   * OAuth `transport.connect()` does NOT pre-validate refresh tokens
+   * (lib/transports/oauth-http-transport.js — sets ready, returns). So a
+   * default site with an expired refresh token connects cleanly at boot and
+   * `connectDefault` never falls back; the failure only surfaces when the
+   * cached `initialize` is forwarded and the refresh throws. This mirrors
+   * `connectDefault`'s boot-time fallback at request time: tear down the
+   * known-failed sites' stale transports, then connect the first site NOT in
+   * the exclude list and promote it to runtime default. Returns the new
+   * transport, or `null` when no non-excluded site can serve (the genuine
+   * "all sites failed" condition — the caller then enters degraded mode per
+   * the #76 gate).
+   *
+   * The caller (router) accumulates every site that has failed the
+   * re-forwarded cached initialize and passes the full set here, because
+   * `transport.connect()` does not validate tokens — a freshly-connected
+   * fallback can itself fail the initialize. Excluding the accumulated set
+   * makes the candidate pool strictly shrink so the chain converges (reviewer
+   * blocker, PR #88).
+   *
+   * @param {string|string[]} excludeSiteIds  Site id(s) already known to have
+   *   failed the cached initialize/connect — never re-tried here.
+   * @param {function} onMessage   Per-site message router callback.
+   * @returns {Promise<Transport|null>}
+   */
+  async connectFallback(excludeSiteIds, onMessage) {
+    const excluded = new Set(
+      Array.isArray(excludeSiteIds) ? excludeSiteIds : [excludeSiteIds]
+    );
+
+    for (const siteId of excluded) {
+      const stale = this.transports.get(siteId);
+      if (stale) {
+        try { await stale.shutdown(); } catch { /* best effort — stale anyway */ }
+        this.transports.delete(siteId);
+      }
+    }
+
+    const tryOrder = Object.keys(this.config.sites).filter((k) => !excluded.has(k));
+    for (const key of tryOrder) {
+      try {
+        const transport = await this._createTransport(key, null);
+        transport.onMessage = onMessage;
+        await transport.connect();
+        this.transports.set(key, transport);
+        this.config.defaultSite = key;
+        this.log(
+          `Default failed at request time (excluded: ${[...excluded].join(', ')}); ` +
+          `runtime default fell back to "${key}". Excluded sites are marked ` +
+          `degraded in-memory; reauth to restore.`
+        );
+        return transport;
+      } catch (err) {
+        this.log(`Fallback site "${key}" failed to connect: ${err.message}`);
+        this._markSiteDegraded(key, err);
+      }
+    }
+
+    return null;
+  }
+
   /**
    * Mark a site degraded in the in-memory config so other lookups (tools/list,
    * resources/read wp-abilities://sites, per-call routing) can surface it
@@ -480,6 +559,27 @@ class ConnectionPool {
             .catch((err) => this.log(`OAuth auth_status persist failed: ${err.message}`));
         }
       },
+      // Issue #90: opt-in sliding renewal. The transport invokes this ONLY
+      // after a successful refresh of a site whose siteAuth.slidingRenewal ===
+      // true — flag-off (default) sites never reach this callback, so no new
+      // write path is created for them (binding guardrail 1).
+      onTokensRenewed: (updatedAuth) => {
+        try {
+          siteConfig.auth.refresh_token_expires_at = updatedAuth.refreshTokenExpiresAt;
+          siteConfig.auth.access_token_expires_at = updatedAuth.accessTokenExpiresAt;
+          siteConfig.auth.access_token_ref = updatedAuth.accessTokenRef;
+          siteConfig.auth.refresh_token_ref = updatedAuth.refreshTokenRef;
+        } catch { /* siteConfig may be frozen in tests — ignore */ }
+        this.log(`OAuth sliding renewal: ${compositeKey} → refresh window slid to ${updatedAuth.refreshTokenExpiresAt}`);
+        if (this._persistSlidingRenewal) {
+          Promise.resolve()
+            .then(() => this._persistSlidingRenewal(compositeKey, updatedAuth))
+            .catch((err) => this.log(`OAuth sliding-renewal persist failed: ${err.message}`));
+        } else if (this.config && this.config._configPath) {
+          this._defaultPersistSlidingRenewal(compositeKey, updatedAuth)
+            .catch((err) => this.log(`OAuth sliding-renewal persist failed: ${err.message}`));
+        }
+      },
       logger: this.log,
     });
   }
@@ -510,6 +610,41 @@ class ConnectionPool {
     }
   }
 
+  /**
+   * Issue #90: default sliding-renewal persistor — atomic rewrite of the slid
+   * refresh-token expiry and rotated refs. Reached ONLY via the transport's
+   * onTokensRenewed callback, which fires solely for opt-in sites
+   * (siteAuth.slidingRenewal === true) after a successful refresh — flag-off
+   * sites never get here, so the default bounded behavior writes nothing new
+   * (binding guardrail 1 & 2). Best-effort: a write failure must not break the
+   * request path that triggered the renewal.
+   */
+  async _defaultPersistSlidingRenewal(siteId, updatedAuth) {
+    const { _atomicWrite } = require('./auth/config-migration');
+    const fs = require('node:fs');
+    const filePath = this.config._configPath;
+    if (!filePath) return;
+    let raw;
+    try {
+      raw = await fs.promises.readFile(filePath, 'utf8');
+    } catch (err) {
+      throw new Error(`read ${filePath}: ${err.message}`);
+    }
+    let parsed;
+    try { parsed = JSON.parse(raw); }
+    catch (err) {
+      throw new Error(`parse ${filePath}: ${err.message}`);
+    }
+    if (parsed && parsed.sites && parsed.sites[siteId] && parsed.sites[siteId].auth) {
+      const auth = parsed.sites[siteId].auth;
+      auth.refresh_token_expires_at = updatedAuth.refreshTokenExpiresAt;
+      auth.access_token_expires_at = updatedAuth.accessTokenExpiresAt;
+      auth.access_token_ref = updatedAuth.accessTokenRef;
+      auth.refresh_token_ref = updatedAuth.refreshTokenRef;
+      await _atomicWrite(filePath, parsed);
+    }
+  }
+
   /**
    * Check if a composite key resolves to the same HTTP endpoint as an
    * already-connected transport. Returns { key, transport } or null.

package/lib/router.js

@@ -63,6 +63,14 @@ class McpRouter {
     // tools/call surfaces a per-call error naming the degraded sites.
     this.degraded = false;
     this.degradedSites = [];  // [{ siteId, reason }]
+
+    // Issue #87: sites that have failed the *re-forwarded cached initialize*
+    // (not merely connect — OAuth connect() does not validate tokens). Used to
+    // exclude already-failed sites from request-time fallback so the chain
+    // strictly converges: when every configured site is in this map there is
+    // no untried site left, and the #76 all-sites-down gate fires instead of
+    // alternating between bad OAuth sites forever. siteId → failure reason.
+    this._initFailedSites = new Map();
   }
 
   /**
@@ -227,10 +235,15 @@ class McpRouter {
       const reason = (parsedMsg.error && parsedMsg.error.message) || 'unknown';
       this.log(
         `Initialize forward failed for "${failedSite || '(unknown)'}": ${reason} — ` +
-        `synthesizing degraded-mode InitializeResult to satisfy MCP runtime`
+        `attempting per-site fallback before degrading (Issue #87 S1/S2)`
       );
-      this._sendSynthesizedInitializeResult(this.cachedInitRequest);
-      this.enterDegradedMode([{ siteId: failedSite || '(unknown)', reason }]);
+      // Issue #87 (S1/S2): a single (default) site's request-time refresh
+      // failure must NOT blanket-degrade the whole bridge. Mirror the boot
+      // path's per-site fallback; degrade only when no site can serve (the
+      // genuine "all sites failed" condition the #76 gate is about). Async,
+      // fire-and-forget like _handleToolsCall; the promise is exposed for
+      // deterministic test sequencing.
+      this._initFailurePromise = this._handleInitializeForwardFailure(failedSite, reason);
       return;
     }
 
@@ -353,6 +366,85 @@ class McpRouter {
     this.earlyQueue.push(line);
   }
 
+  // ---------------------------------------------------------------------------
+  // Internal — degraded mode (Issue #76) + request-time fallback (Issue #87)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Issue #87 (S1/S2): the cached `initialize` forward failed for the runtime
+   * default site (request-time refresh-token expiry). Try a fallback site that
+   * has NOT already failed the cached initialize and re-forward the cached
+   * initialize through it so the client gets a real InitializeResult and the
+   * tool catalog populates normally — the bridge stays healthy and the failed
+   * site is marked degraded (visible via wp_bridge_health).
+   *
+   * Convergence (reviewer blocker, PR #88): OAuth `transport.connect()` does
+   * NOT validate refresh tokens, so a freshly-connected fallback can itself
+   * fail the re-forwarded initialize. Without bookkeeping, two bad-token OAuth
+   * sites alternate forever and the #76 gate never fires. We accumulate every
+   * site that has failed the *cached initialize* in `this._initFailedSites`
+   * and exclude all of them from the next fallback. Each round adds the
+   * just-failed runtime default to that set, so the candidate pool strictly
+   * shrinks; once every configured site has failed the initialize there is no
+   * untried site left and the #76 all-sites-down gate fires (synthesized
+   * InitializeResult + degraded mode). Termination is guaranteed.
+   *
+   * @param {string} failedSite  Runtime default site whose initialize failed.
+   * @param {string} reason      Error message from the failed forward.
+   */
+  async _handleInitializeForwardFailure(failedSite, reason) {
+    if (failedSite) this._initFailedSites.set(failedSite, reason);
+
+    let fallback = null;
+    try {
+      fallback = await this.pool.connectFallback(
+        Array.from(this._initFailedSites.keys()),
+        (parsedMsg, rawLine) => {
+          this.handleTransportMessage(parsedMsg, rawLine);
+        }
+      );
+    } catch (err) {
+      this.log(`Per-site fallback connect threw: ${err.message}`);
+      fallback = null;
+    }
+
+    if (fallback) {
+      this.setDefaultTransport(fallback);
+      this.log(
+        `Per-site fallback succeeded; re-forwarding cached initialize via ` +
+        `"${this.config.defaultSite}" (excluded: ` +
+        `${Array.from(this._initFailedSites.keys()).join(', ')}). ` +
+        `Bridge NOT degraded (Issue #87 S1).`
+      );
+      this._forwardToDefault(JSON.stringify(this.cachedInitRequest));
+      return;
+    }
+
+    // No untried site — every configured site has failed the cached
+    // initialize (or connect). Genuine all-sites-down: preserve the #76 gate
+    // — synthesize a valid InitializeResult locally and enter degraded mode so
+    // the MCP runtime stays connectable and wp_bridge_health can report
+    // per-site status. degradedSites carries the recorded per-site initialize
+    // failure reason; sites that only failed connect fall back to their
+    // in-memory `_degraded_reason`.
+    this.log(
+      `No untried fallback site — every configured site failed the cached ` +
+      `initialize. Entering degraded mode (all sites failed, #76 gate).`
+    );
+    const degradedSites = Object.entries((this.config && this.config.sites) || {}).map(
+      ([siteId, site]) => ({
+        siteId,
+        reason: this._initFailedSites.get(siteId) ||
+          (site && site._degraded_reason) || 'connect failed',
+      })
+    );
+    if (degradedSites.length === 0) {
+      degradedSites.push({ siteId: failedSite || '(unknown)', reason });
+    }
+    this._sendSynthesizedInitializeResult(this.cachedInitRequest);
+    this.enterDegradedMode(degradedSites);
+  }
+
   // ---------------------------------------------------------------------------
   // Internal — degraded mode (Issue #76)
   // ---------------------------------------------------------------------------
@@ -463,14 +555,26 @@ class McpRouter {
       }
 
       const summary = this.catalog.getCategorySummary();
-      const lines = summary.map(c =>
-        `${c.active ? '[LOADED]' : '       '} ${c.name} (${c.toolCount} tools)`
+      const lines = [];
+      lines.push(
+        `Scope: direct-tool catalog scoped to defaultSite (${this.config.defaultSite}). ` +
+          `Not full cross-site ability discovery.`
       );
       lines.push('');
+      for (const c of summary) {
+        lines.push(`${c.active ? '[LOADED]' : '       '} ${c.name} (${c.toolCount} tools)`);
+      }
+      lines.push('');
       lines.push(`Total: ${this.catalog.fullTools.length} tools in ${summary.length} categories`);
       lines.push(`Loaded: ${summary.filter(c => c.active).reduce((n, c) => n + c.toolCount, 0)} tools`);
       lines.push('');
       lines.push('Use wp_load_tools with categories array to activate.');
+      lines.push('');
+      lines.push(
+        'For abilities on another site, or in a category not listed here, use ' +
+          'mcp-adapter-discover-abilities { site, category } and ' +
+          'mcp-adapter-execute-ability { site, ability_name, parameters }.'
+      );
 
       this.sendToClient(JSON.stringify({
         jsonrpc: '2.0', id: msg.id,
@@ -496,6 +600,7 @@ class McpRouter {
       }
 
       const activated = this.catalog.activateCategories(toActivate);
+      const missing = toActivate.filter((c) => !this.catalog.categories[c]);
       const lines = [];
 
       if (activated.length > 0) {
@@ -504,8 +609,25 @@ class McpRouter {
       if (toDeactivate.length > 0) {
         lines.push(`Deactivated: ${toDeactivate.join(', ')}`);
       }
-      if (activated.length === 0 && toDeactivate.length === 0) {
-        lines.push('No changes — categories may already be active or not found.');
+      if (missing.length > 0) {
+        lines.push(
+          `Not in the direct-tool catalog (scoped to defaultSite "${this.config.defaultSite}"): ` +
+            missing.join(', ') +
+            '.'
+        );
+        lines.push(
+          'For abilities on another site, or in a category not in this catalog, use the ' +
+            'adapter meta-tools instead:'
+        );
+        for (const cat of missing) {
+          lines.push(`  mcp-adapter-discover-abilities { site: "<site>", category: "${cat}" }`);
+        }
+        lines.push(
+          '  mcp-adapter-execute-ability { site: "<site>", ability_name: "<ability>", parameters: { ... } }'
+        );
+      }
+      if (activated.length === 0 && toDeactivate.length === 0 && missing.length === 0) {
+        lines.push('No changes — categories may already be active.');
       }
 
       const filtered = this.catalog.getFilteredTools();

package/lib/sanitizer.js

@@ -29,7 +29,19 @@ function validateToolSchema(toolName, schema, log) {
     log(`SCHEMA WARN [${toolName}]: invalid top-level type "${schema.type}"`);
   }
 
-  if (!schema.properties || typeof schema.properties !== 'object') return;
+  // Boundary: properties key absent — leave inputSchema byte-unchanged.
+  if (schema.properties === undefined) return;
+
+  // Normalize malformed `properties` shapes (PHP `array()` JSON-encodes to `[]`,
+  // strings, null, primitives) to `{}` before downstream validation. Anthropic's
+  // draft 2020-12 validator rejects the entire tools/list payload on the first
+  // invalid schema, so a single vendor-registered `properties: []` breaks the
+  // whole catalog. Mirror of the top-level inputSchema normalize one frame up.
+  if (schema.properties === null || typeof schema.properties !== 'object' || Array.isArray(schema.properties)) {
+    log(`SCHEMA NORMALIZE [${toolName}]: inputSchema.properties not a plain object — normalized to {}`);
+    schema.properties = {};
+    return;
+  }
 
   for (const [prop, def] of Object.entries(schema.properties)) {
     if (!def || typeof def !== 'object') {

package/lib/tool-catalog.js

@@ -32,11 +32,22 @@ class ToolCatalog {
     // Active (loaded) categories
     this.activeCategories = new Set();
 
-    // Initialize always-included categories from config
-    if (this.filterConfig && this.filterConfig.alwaysIncludeCategories) {
-      for (const cat of this.filterConfig.alwaysIncludeCategories) {
-        this.activeCategories.add(cat);
-      }
+    // Resolve "always-include" categories once. Explicit operator config wins
+    // (including an explicit empty list, which preserves the operator's choice).
+    // When filtering is enabled and the operator hasn't set their own list,
+    // default to ['mcp-adapter'] so the cross-site adapter meta-tools
+    // (mcp-adapter-discover-abilities / -get-ability-info / -execute-ability)
+    // are always visible without requiring a prior wp_load_tools call.
+    const explicit = this.filterConfig && this.filterConfig.alwaysIncludeCategories;
+    const resolved =
+      explicit !== undefined && explicit !== null
+        ? explicit
+        : this.isEnabled()
+        ? ['mcp-adapter']
+        : [];
+    this.effectiveAlwaysInclude = new Set(resolved);
+    for (const cat of this.effectiveAlwaysInclude) {
+      this.activeCategories.add(cat);
     }
   }
 
@@ -104,12 +115,11 @@ class ToolCatalog {
    * Deactivate categories (return to compact mode).
    */
   deactivateCategories(categoryNames) {
-    // Don't deactivate always-included categories
-    const alwaysIncluded = new Set(
-      (this.filterConfig && this.filterConfig.alwaysIncludeCategories) || []
-    );
+    // Don't deactivate always-included categories (single source of truth:
+    // the set resolved at construction, so the default mcp-adapter inclusion
+    // is treated the same as an explicit operator-configured entry).
     for (const name of categoryNames) {
-      if (!alwaysIncluded.has(name)) {
+      if (!this.effectiveAlwaysInclude.has(name)) {
         this.activeCategories.delete(name);
       }
     }

package/lib/transports/oauth-http-transport.js

@@ -72,6 +72,15 @@ const MAX_QUEUE = 100;
  *                                            (newStatus, { reason, siteId })
  *                                            when transport detects a terminal
  *                                            auth failure. Caller persists.
+ * @param {function} opts.onTokensRenewed     Optional. Issue #90 (opt-in
+ *                                            sliding renewal). Called with
+ *                                            (updatedAuth) after a successful
+ *                                            refresh ONLY when
+ *                                            siteAuth.slidingRenewal === true.
+ *                                            Caller persists the slid
+ *                                            refresh_token_expires_at + rotated
+ *                                            refs + access expiry. Never
+ *                                            invoked for default sites.
  * @param {function} opts.logger              Logger function
  *
  * Copyright (C) 2026 Influencentricity | Wicked Evolutions
@@ -95,6 +104,10 @@ class OAuthHttpTransport {
     this._tokenManager = opts.tokenManager;
     this._siteAuth = opts.siteAuth;
     this._onAuthStatusChange = opts.onAuthStatusChange || null;
+    // Issue #90: opt-in sliding renewal. Invoked ONLY on a successful refresh
+    // of a site whose siteAuth.slidingRenewal === true, so flag-off sites
+    // never reach a new write path. Caller persists the slid expiry + refs.
+    this._onTokensRenewed = opts.onTokensRenewed || null;
     this.log = opts.logger || function noop() {};
 
     const parsedUrl = new URL(this.endpoint);
@@ -416,6 +429,19 @@ class OAuthHttpTransport {
           accessTokenExpiresAt: tok.updatedAuth.accessTokenExpiresAt,
           authStatus: tok.updatedAuth.authStatus,
         };
+        // Issue #90: opt-in sliding renewal ONLY. For default (flag
+        // absent/false) sites this branch is skipped entirely — no extra
+        // in-memory expiry adoption, no persist callback, no new write path.
+        // For opt-in sites, adopt the slid refresh-token expiry in-memory and
+        // ask the caller to persist it (+ rotated refs + access expiry).
+        if (this._siteAuth.slidingRenewal === true) {
+          this._siteAuth.refreshTokenExpiresAt = tok.updatedAuth.refreshTokenExpiresAt;
+          if (this._onTokensRenewed) {
+            try {
+              this._onTokensRenewed(tok.updatedAuth);
+            } catch { /* observer must not break the request path */ }
+          }
+        }
       }
     } catch (err) {
       // Refresh failure (e.g. RefreshError 4xx → expired). Emit auth status

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wickedevolutions/abilities-mcp",
-  "version": "1.6.2",
+  "version": "1.6.4",
   "description": "Open-source MCP bridge connecting AI clients to WordPress through the Abilities API — multi-site routing, zero dependencies",
   "main": "abilities-mcp.js",
   "bin": {