@respira/wordpress-mcp-server 8.3.21 → 8.3.23

package/dist/wordpress-client.js

@@ -13,6 +13,7 @@ import { randomUUID } from 'node:crypto';
 import { getRespiraAgentHeaders } from './agent-signature.js';
 import { CONFIG_FILE, isTlsInsecureEnv } from './config.js';
 import { makeHttpsAgent } from './system-ca.js';
+import { normalizePatchOperations } from './patch-identifier.js';
 /** `C:\...` or `C:/...`. Windows drive-letter absolute path. */
 const WINDOWS_DRIVE_PATH_RE = /^[a-zA-Z]:[\\/]/;
 /**
@@ -536,27 +537,167 @@ function normalizeDeleteResponse(res, resourceType, id) {
  * entirely. Two different payloads produced identical errors, because neither
  * payload was ever delivered.
  *
- * 307 and 308 preserve the method and the body, so they are followed normally.
- * Only the method-rewriting statuses are refused, and only for writes.
+ * 307 and 308 preserve the method and the body, so they are followed normally
+ * while they stay on the same origin.
+ *
+ * A redirect of a write to a DIFFERENT origin (scheme, host or port) is refused
+ * whatever its status, with its own code. Following it would replay the write,
+ * API key header included, against an address nobody configured: a 307/308 is
+ * re-sent as-is, and follow-redirects keeps PUT and DELETE on a 301/302 too
+ * (only POST is downgraded). Tickets dfe2d236, 6e94282d, addc289e, 77aae005,
+ * c2dd9d87 (staging3.naa.edu, which 301s every request to its www host).
+ *
+ * The hook is called by follow-redirects as (options, responseDetails,
+ * requestDetails), after `options` has already been rewritten to the redirect
+ * target, so the origin of the request being redirected is only knowable from
+ * `requestDetails.url`. Without it, only the downgrade check can run.
+ *
+ * What is thrown here never reaches the caller as-is: follow-redirects wraps it
+ * in a RedirectionError and axios turns that into an AxiosError with no
+ * `response`. handleError() finds it again through `.cause` (see
+ * findRedirectRefusal) so the message is not rewritten into "no response
+ * received".
  *
  * @since mcp 8.3.18
  */
 export function guardAgainstMethodDowngrade(originalMethod) {
-    const isWrite = !['GET', 'HEAD', 'OPTIONS'].includes((originalMethod || 'GET').toUpperCase());
-    return (options, responseDetails) => {
+    const method = (originalMethod || 'GET').toUpperCase();
+    const isWrite = !['GET', 'HEAD', 'OPTIONS'].includes(method);
+    return (options, responseDetails, requestDetails) => {
         if (!isWrite)
             return;
         const status = responseDetails?.statusCode;
-        if (status !== 301 && status !== 302 && status !== 303)
-            return;
-        const target = responseDetails?.headers?.location ||
+        const downgrades = status === 301 || status === 302 || status === 303;
+        const fromUrl = requestDetails?.url ? String(requestDetails.url) : null;
+        const rawLocation = responseDetails?.headers?.location;
+        let target = rawLocation ||
             `${options?.protocol || ''}//${options?.host || ''}${options?.path || ''}`;
-        const err = new Error(`Refusing to follow a ${status} redirect on a ${originalMethod.toUpperCase()} request: it would be re-sent as a GET with the body discarded, so the write would silently become a read. ` +
-            `The site redirected to ${target}. Configure this site in Respira with the URL WordPress itself considers canonical (the Site Address in Settings > General) and the write will go straight through.`);
-        err.code = 'respira_write_redirect_downgrade';
+        try {
+            if (rawLocation && fromUrl)
+                target = new URL(String(rawLocation), fromUrl).href;
+        }
+        catch {
+            // Keep the raw Location if it cannot be resolved.
+        }
+        const originChange = describeOriginChange(fromUrl, target);
+        if (!downgrades && !originChange)
+            return;
+        const err = originChange
+            ? new Error(`Refusing to follow a ${status} redirect on a ${method} request: the site sent it to a different address (${originChange.to_origin}), ` +
+                'and a write is only ever sent to the site URL Respira was configured with. ' +
+                (downgrades
+                    ? `A ${status} would also re-send it as a GET with the body discarded, so the write would silently become a read. `
+                    : '') +
+                'Configure this site in Respira with the URL WordPress itself considers canonical (the Site Address in Settings > General) and the write will go straight through.')
+            : new Error(`Refusing to follow a ${status} redirect on a ${method} request: it would be re-sent as a GET with the body discarded, so the write would silently become a read. ` +
+                `The site redirected to ${target}. Configure this site in Respira with the URL WordPress itself considers canonical (the Site Address in Settings > General) and the write will go straight through.`);
+        err.code = originChange ? 'respira_site_url_redirects' : 'respira_write_redirect_downgrade';
+        err.redirectStatus = status;
+        err.redirectLocation = target;
+        err.redirectFrom = fromUrl;
+        err.redirectMethod = method;
         throw err;
     };
 }
+/**
+ * The origin change between two URLs, or null when they share an origin or
+ * either cannot be parsed. `toUrl` may be relative to `fromUrl`.
+ */
+function describeOriginChange(fromUrl, toUrl) {
+    if (!fromUrl || !toUrl)
+        return null;
+    try {
+        const from = new URL(String(fromUrl));
+        const to = new URL(String(toUrl), from);
+        if (from.protocol === to.protocol && from.host === to.host)
+            return null;
+        return { from_origin: from.origin, to_origin: to.origin };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The site URL to configure instead: the redirect target's origin, keeping the
+ * path of the configured URL (a WordPress in a subdirectory stays there).
+ */
+function suggestedSiteUrl(configuredUrl, location) {
+    try {
+        const configured = new URL(configuredUrl);
+        const target = new URL(location, configured);
+        return `${target.origin}${configured.pathname.replace(/\/+$/, '')}`;
+    }
+    catch {
+        return null;
+    }
+}
+const REDIRECT_REFUSAL_CODES = new Set(['respira_site_url_redirects', 'respira_write_redirect_downgrade']);
+/**
+ * The guardAgainstMethodDowngrade() error behind an axios error, if that is
+ * what ended the request. follow-redirects wraps it (RedirectionError, code
+ * ERR_FR_REDIRECTION_FAILURE) and axios wraps that again, each keeping the
+ * previous one as `.cause`.
+ */
+function findRedirectRefusal(error) {
+    let current = error;
+    for (let depth = 0; current && depth < 6; depth += 1) {
+        if (REDIRECT_REFUSAL_CODES.has(String(current.code || '')))
+            return current;
+        current = current.cause;
+    }
+    return null;
+}
+/** Verbs WordPress lets a POST stand in for via `_method` / X-HTTP-Method-Override. */
+const METHOD_OVERRIDE_VERBS = new Set(['PUT', 'PATCH', 'DELETE']);
+function headerValue(headers, name) {
+    if (!headers)
+        return '';
+    if (typeof headers.get === 'function') {
+        const value = headers.get(name);
+        if (value !== undefined && value !== null && value !== false)
+            return String(value);
+    }
+    const lower = name.toLowerCase();
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === lower && value !== undefined && value !== null)
+            return String(value);
+    }
+    return '';
+}
+/**
+ * Did WordPress answer this write with a READ handler?
+ *
+ * Ticket 953dde4e. Some hosts rewrite PUT/PATCH/DELETE into a request WordPress
+ * dispatches as GET. On a route that also has a GET handler (pages, posts,
+ * media...) the read handler answers 200 and the write silently did nothing.
+ *
+ * The plugin's reliability layer (class-respira-mcp-reliability.php, since
+ * plugin 8.0) says which case this is. On every /respira/ response it sends
+ * `X-Respira-Idempotency-Supported: 1`. On a request it treats as a write
+ * (a write verb as WordPress saw it) that carries a valid Idempotency-Key it
+ * takes the lock before routing and answers with `X-Respira-Call-Id`, on
+ * success, on error, on rest_no_route and on replay alike. Both headers are
+ * set in the same function, on the same response object, since the same
+ * commit. So a 2xx that has the first header and not the second, for a write
+ * that sent a valid key, was dispatched by WordPress as GET/HEAD/OPTIONS: only
+ * a read handler ran, and re-sending it as a write cannot write twice.
+ * Verified live on withmaroua.com (PUT /respira/v1/ping: 200, Supported: 1, no
+ * Call-Id, Allow: GET) and on a local 8.8.34 site (a real PUT gets a Call-Id,
+ * a GET does not). Plugins older than 8.0 send neither header and are never
+ * second-guessed.
+ */
+function writeWasAnsweredAsRead(response, sentMethod) {
+    if (!METHOD_OVERRIDE_VERBS.has(String(sentMethod || '').toUpperCase()))
+        return false;
+    const status = Number(response?.status);
+    if (!(status >= 200 && status < 300))
+        return false;
+    if (headerValue(response?.headers, 'x-respira-idempotency-supported') !== '1')
+        return false;
+    if (headerValue(response?.headers, 'x-respira-call-id'))
+        return false;
+    return /^[A-Za-z0-9._:-]{8,128}$/.test(headerValue(response?.config?.headers, 'Idempotency-Key'));
+}
 export class WordPressClient {
     client;
     rootClient;
@@ -784,6 +925,19 @@ export class WordPressClient {
                 return instance.request(config);
             }
             const handledError = await this.handleError(error);
+            // Ticket 953dde4e: a PUT/PATCH/DELETE WordPress answered with
+            // rest_no_route (the host rewrote the verb before WordPress saw it), or
+            // a PATCH/DELETE rejected or dropped in front of WordPress. Re-send it
+            // once as a POST that names the original verb. PUT's non_wordpress
+            // shapes stay with putWithPostFallback, unchanged.
+            if (this.methodOverrideFallbackApplies(config, handledError)) {
+                try {
+                    return await this.retryWithMethodOverride(config);
+                }
+                catch (retryError) {
+                    throw this.noteMethodOverrideFailure(handledError, method, retryError);
+                }
+            }
             throw handledError;
         };
         // Success interceptor: detect HTML masquerading as JSON on Respira REST routes.
@@ -845,8 +999,34 @@ export class WordPressClient {
             }
             throw this.buildHtmlInsteadOfJsonError(observation, requestConfig);
         };
-        this.client.interceptors.response.use(htmlGuard, errorInterceptor);
-        this.rootClient.interceptors.response.use(htmlGuard, errorInterceptor);
+        // Ticket 953dde4e: the same verb-rewriting host, on a route that also has
+        // a GET handler, answers the write 200 from the READ handler. See
+        // writeWasAnsweredAsRead(). Only a read ran, so re-sending the write once
+        // with the method override cannot write twice.
+        const rescueWriteAnsweredAsRead = async (response) => {
+            const config = response?.config || {};
+            const method = String(config.method || '').toUpperCase();
+            if (config._respiraMethodOverride || !writeWasAnsweredAsRead(response, method))
+                return response;
+            if (!isReplayableBody(config.data)) {
+                throw this.codedError(`${method} ${config.url || ''} was answered by a read handler: this site rewrote the ${method} into a GET before WordPress saw it, so nothing was written. ` +
+                    'The request body is a stream and cannot be sent twice, so it was not retried.', 'respira_write_answered_as_read');
+            }
+            try {
+                return await this.retryWithMethodOverride(config);
+            }
+            catch (retryError) {
+                if (retryError instanceof Error && retryError.name !== 'respira_write_answered_as_read') {
+                    retryError.message +=
+                        `\n\n(This site rewrote the ${method} into a GET before WordPress saw it, so the first attempt was answered by a read handler and wrote nothing. ` +
+                            `Respira re-sent it once as POST with X-HTTP-Method-Override: ${method}; the error above is WordPress's answer to that retry.)`;
+                }
+                throw retryError;
+            }
+        };
+        const successInterceptor = async (response) => rescueWriteAnsweredAsRead(await htmlGuard(response));
+        this.client.interceptors.response.use(successInterceptor, errorInterceptor);
+        this.rootClient.interceptors.response.use(successInterceptor, errorInterceptor);
     }
     /**
      * Inspect a response for the "HTML instead of JSON" failure mode on Respira
@@ -1087,6 +1267,10 @@ export class WordPressClient {
             },
             validateStatus: (s) => s >= 200 && s < 300,
             maxRedirects: 5,
+            // This goes out through the global axios, so it does not get the guard
+            // the two instances install per request. Without it a write retried
+            // here would follow a redirect to another host (tickets dfe2d236 et al.).
+            beforeRedirect: guardAgainstMethodDowngrade(String(originalConfig.method || 'get')),
             _restRouteFallback: true,
         };
         return axios.request(retryConfig);
@@ -1411,12 +1595,15 @@ export class WordPressClient {
      *
      * This is safe for the whole set because the plugin registers all of them
      * with `WP_REST_Server::EDITABLE`, which is literally `'POST, PUT, PATCH'`:
-     * the fallback POST reaches the identical handler. It is deliberately NOT
-     * extended to DELETE. Those routes are registered `DELETABLE`, so a fallback
-     * POST would return `rest_no_route` — a 404 that reads like "the plugin is
-     * too old" and would be a worse diagnosis than the honest 405. Making delete
-     * survive a blocked verb needs a plugin-side route change, not a connector
-     * change; see the ticket for the enumerated list.
+     * the fallback POST reaches the identical handler. A bare POST cannot stand
+     * in for DELETE the same way: those routes are registered `DELETABLE`, so it
+     * would hit `rest_no_route`, or the route's POST handler where there is one.
+     * DELETE and PATCH are covered instead by the method-override retry in the
+     * response interceptor (retryWithMethodOverride, ticket 953dde4e): a POST
+     * carrying `_method` and `X-HTTP-Method-Override`, which WordPress core
+     * (WP_REST_Server::serve_request) dispatches to the original verb's
+     * handler. This function is unchanged by that and still sends a plain POST,
+     * so the hosts it already rescues see exactly the request they did before.
      */
     async putWithPostFallback(client, url, data, config = {}) {
         const callId = randomUUID();
@@ -1440,6 +1627,103 @@ export class WordPressClient {
             return client.post(url, data, fallbackAttempt);
         }
     }
+    /**
+     * Should this failed write be re-sent as a POST with the method override?
+     *
+     * - PUT, PATCH or DELETE, sent once, with a body that can be sent again.
+     * - Either WordPress answered `rest_no_route`, or (PATCH/DELETE only) the
+     *   failure is one of the shapes isRetryableAsPost() already accepts for
+     *   PUT: a 403/404/405 from something in front of WordPress, or a dropped
+     *   connection. PUT's version of those stays in putWithPostFallback.
+     *
+     * A 403/404/405 raised BY WordPress for any other reason is still a decision
+     * and still not retried; only `rest_no_route` is singled out, because it is
+     * what WordPress says when the verb it received has no handler, which is
+     * exactly what a rewritten verb produces.
+     */
+    methodOverrideFallbackApplies(config, handled) {
+        const method = String(config?.method || '').toUpperCase();
+        if (!METHOD_OVERRIDE_VERBS.has(method))
+            return false;
+        if (!config || config._respiraMethodOverride || config.url === undefined || !isReplayableBody(config.data)) {
+            return false;
+        }
+        if (handled?.name === 'rest_no_route')
+            return true;
+        return method !== 'PUT' && isRetryableAsPost(handled);
+    }
+    /**
+     * Re-send a PUT, PATCH or DELETE once as a POST that tells WordPress which
+     * verb it stands for. Ticket 953dde4e.
+     *
+     * WordPress core supports this for exactly this situation.
+     * WP_REST_Server::serve_request() builds the request with the wire method,
+     * then replaces it with `$_GET['_method']` if present, else with the
+     * `X-HTTP-Method-Override` header, before dispatch; match_request_to_handler()
+     * then picks the handler registered for THAT method (verified in core 7.0.2,
+     * class-wp-rest-server.php serve_request / match_request_to_handler, and live:
+     * a POST to a DELETABLE route with either form reaches the DELETE handler).
+     * Both forms are sent. `_method` wins in core and survives a host that strips
+     * unknown headers, which matters for DELETE: a bare POST on a route that is
+     * DELETABLE and EDITABLE would land on the update handler.
+     *
+     * Why this is not a double write:
+     * - After `rest_no_route`: core returns that error from
+     *   match_request_to_handler() and dispatch() hands it back without calling
+     *   respond_to_request(), so no permission_callback and no route callback
+     *   ran. (rest_pre_dispatch filters do run before routing. Respira's own
+     *   idempotency lock is one: when WordPress saw a GET it does nothing, and
+     *   when it saw the real verb it cached the 404, which the retry, sent with
+     *   the same Idempotency-Key and ORIGINAL_METHOD_HEADER, gets replayed.)
+     * - After a write answered by a read handler: see writeWasAnsweredAsRead().
+     * - After an edge rejection or a dropped connection: the same Idempotency-Key
+     *   and ORIGINAL_METHOD_HEADER that make PUT's fallback safe.
+     *
+     * Exactly one attempt. The retry is marked so neither interceptor retries it
+     * again.
+     */
+    async retryWithMethodOverride(config) {
+        const method = String(config?.method || '').toUpperCase();
+        const raw = config?.headers;
+        const headers = raw && typeof raw.toJSON === 'function' ? { ...raw.toJSON() } : { ...(raw || {}) };
+        for (const key of Object.keys(headers)) {
+            const lower = key.toLowerCase();
+            if (lower === 'content-length' || lower === 'x-http-method-override' || lower === ORIGINAL_METHOD_HEADER.toLowerCase()) {
+                delete headers[key];
+            }
+        }
+        headers['X-HTTP-Method-Override'] = method;
+        headers[ORIGINAL_METHOD_HEADER] = method;
+        const retryConfig = {
+            ...config,
+            method: 'post',
+            headers,
+            // Folded into the URL by computeRestRouteFallbackUrl in ?rest_route= mode.
+            params: { ...(config?.params || {}), _method: method },
+            _respiraMethodOverride: true,
+        };
+        const instance = typeof config?.baseURL === 'string' && config.baseURL.includes('/wp-json/respira/v1') ? this.client : this.rootClient;
+        const response = await instance.request(retryConfig);
+        if (writeWasAnsweredAsRead(response, method)) {
+            throw this.codedError(`${method} ${config?.url || ''} was answered by a read handler twice. This site rewrites ${method} into a GET before WordPress sees it, ` +
+                `and the retry as POST with X-HTTP-Method-Override: ${method} was not honoured either. Nothing was written. ` +
+                `Ask the host to allow ${method} for /wp-json/respira/*.`, 'respira_write_answered_as_read');
+        }
+        return response;
+    }
+    /**
+     * The method-override retry did not help: surface the ORIGINAL error, which
+     * is WordPress's answer to what was actually asked, and say the retry ran.
+     */
+    noteMethodOverrideFailure(original, method, retryError) {
+        const retryCode = String(retryError?.name || retryError?.code || 'error');
+        const retryLine = String(retryError?.message || retryError || '').split('\n')[0].slice(0, 300);
+        original.message +=
+            `\n\nRespira also retried this once as POST with X-HTTP-Method-Override: ${method}, because some hosts rewrite or block ${method} before WordPress sees it. ` +
+                `That retry failed too (${retryCode}: ${retryLine}), so the error above is the answer to the original ${method}.`;
+        original.methodOverrideRetry = { attempted: true, retry_error_code: retryCode };
+        return original;
+    }
     /**
      * Generic v1 REST caller for endpoints under /wp-json/respira/v1/.
      * Mirror of callRestV2 but for the existing v1 surface — useful for new tools
@@ -1832,6 +2116,17 @@ export class WordPressClient {
             return apiError;
         }
         else if (error.request) {
+            // A write refused by guardAgainstMethodDowngrade() lands here too: the
+            // site DID answer, with a redirect, but follow-redirects reports the
+            // refusal as a request error and axios gives it no `response`. Left to
+            // the branch below it was described as "no response received" and an
+            // unknown write outcome, in a few hundred milliseconds, while the real
+            // cause (the configured URL redirects to another host) was in the
+            // error's `.cause` the whole time. Tickets dfe2d236, 6e94282d, addc289e,
+            // 77aae005, c2dd9d87.
+            const redirectRefusal = findRedirectRefusal(error);
+            if (redirectRefusal)
+                return this.redirectRefusalError(redirectRefusal);
             // No response received at all — DNS failure, connection refused, timeout, SSL error, etc.
             const code = error.code;
             let hint = '';
@@ -1907,6 +2202,47 @@ export class WordPressClient {
         }
         return this.codedError(`Unknown error: ${error.message}`, 'unknown_error');
     }
+    /**
+     * Describe a write that guardAgainstMethodDowngrade() refused.
+     *
+     * The outcome is known, which is the point: the site answered with a
+     * redirect instead of running the request (Respira's handlers never answer
+     * a write with a redirect), and the redirect was not followed, so nothing
+     * was written anywhere.
+     */
+    redirectRefusalError(refusal) {
+        const method = String(refusal?.redirectMethod || 'write').toUpperCase();
+        const status = refusal?.redirectStatus;
+        const location = String(refusal?.redirectLocation || '');
+        const configured = String(this.siteConfig.url || '').replace(/\/+$/, '');
+        if (refusal?.code !== 'respira_site_url_redirects') {
+            return this.codedError(String(refusal?.message || 'Refused a redirect on a write.'), 'respira_write_redirect_downgrade', {
+                code: 'respira_write_redirect_downgrade',
+                data: { redirect_status: status, redirect_location: location, configured_url: configured },
+            });
+        }
+        let targetOrigin = location;
+        try {
+            targetOrigin = new URL(location).origin;
+        }
+        catch {
+            // Keep the raw Location.
+        }
+        const suggested = suggestedSiteUrl(configured, location) || targetOrigin;
+        const where = this.siteConfig.id === 'env-site' ? 'the WORDPRESS_URL setting' : CONFIG_FILE;
+        return this.codedError(`Your site URL redirects to ${targetOrigin}. ${configured} answered this ${method} with a ${status} redirect to ${location}. ` +
+            `Update the URL for this site in your Respira config to ${suggested} (${where}). It should match the Site Address in WordPress under Settings > General.\n\n` +
+            `Nothing was written. The site answered with a redirect instead of running the ${method}, and Respira does not re-send a write to an address other than the configured one, so it was not sent to ${targetOrigin} either. ` +
+            'It is safe to retry once the URL is updated. Reads keep working because they follow the redirect, which is why only writes fail on this site.', 'respira_site_url_redirects', {
+            code: 'respira_site_url_redirects',
+            data: {
+                redirect_status: status,
+                redirect_location: location,
+                configured_url: configured,
+                suggested_url: suggested,
+            },
+        });
+    }
     /**
      * Create a telemetry-safe Error while preserving the structured WP_Error
      * envelope. Every HTTP/proxy/upstream branch must use this helper so useful
@@ -3380,7 +3716,10 @@ export class WordPressClient {
      */
     async applyBuilderPatch(builder, postId, operations, include, editTarget) {
         await this.ensureV2();
-        const payload = { operations };
+        // Ticket 9dee06c4: send find_element's vocabulary ({ type: "id", value })
+        // in the canonical shape ({ id }), so it resolves on plugins that predate
+        // the plugin-side reading of it too.
+        const payload = { operations: normalizePatchOperations(operations) };
         if (include) {
             payload.include = include;
         }
@@ -3500,6 +3839,23 @@ export class WordPressClient {
         // Helper: capture only the response shape we care about.
         const probe = async (label, method, url, extraHeaders = {}) => {
             const headers = { ...this.defaultHeaders, ...extraHeaders };
+            // Tickets dfe2d236 et al.: the probes follow redirects, so a site whose
+            // configured URL 301s to another host came back all green while every
+            // write failed. Record each hop so the redirect itself is reported.
+            const redirects = [];
+            const recordRedirect = (_options, responseDetails, requestDetails) => {
+                const from = requestDetails?.url ? String(requestDetails.url) : null;
+                const raw = String(responseDetails?.headers?.location || '');
+                let location = raw;
+                try {
+                    if (raw && from)
+                        location = new URL(raw, from).href;
+                }
+                catch {
+                    // Keep the raw Location.
+                }
+                redirects.push({ status: Number(responseDetails?.statusCode), from, location });
+            };
             try {
                 const resp = await axios.request({
                     method,
@@ -3511,6 +3867,7 @@ export class WordPressClient {
                     // Pass through raw body so we can inspect content-type vs payload.
                     transformResponse: (raw) => raw,
                     maxRedirects: 5,
+                    beforeRedirect: recordRedirect,
                 });
                 const respHeaders = {};
                 Object.entries(resp.headers || {}).forEach(([k, v]) => {
@@ -3549,6 +3906,7 @@ export class WordPressClient {
                     method,
                     url,
                     status: resp.status,
+                    ...(redirects.length ? { redirects } : {}),
                     content_type: ct || null,
                     looks_like_html: looksHtml,
                     title_text: titleText,
@@ -3575,6 +3933,7 @@ export class WordPressClient {
                     url,
                     error: err?.message || String(err),
                     code: err?.code ?? null,
+                    ...(redirects.length ? { redirects } : {}),
                 });
             }
         };
@@ -3696,6 +4055,39 @@ export class WordPressClient {
         // An HTML 4xx/5xx is something in front of WordPress answering instead.
         const putReachedWordPress = !!putProbe && typeof putProbe.status === 'number' && putProbe.looks_like_html === false;
         const putBlockedAtEdge = !!putProbe && typeof putProbe.status === 'number' && putProbe.status >= 400 && !putReachedWordPress;
+        // Ticket 953dde4e. /respira/v1/ping registers a GET handler and nothing
+        // else (class-respira-api.php), so the healthy answer to the PUT probe is
+        // a JSON 404 rest_no_route. A 2xx JSON answer means WordPress dispatched
+        // the PUT as a GET: the host rewrote the verb. It used to count as
+        // `put_reached_wordpress` and grade the site `not_blocked`.
+        const putDispatchedAsRead = !!putProbe &&
+            typeof putProbe.status === 'number' &&
+            putProbe.status >= 200 &&
+            putProbe.status < 300 &&
+            putProbe.looks_like_html === false;
+        // Tickets dfe2d236, 6e94282d, addc289e, 77aae005, c2dd9d87. The first
+        // redirect hop of any probe that leaves the configured origin. Reads follow
+        // it and work; every write is refused (guardAgainstMethodDowngrade), so a
+        // site like this is not healthy however green the GET probes look.
+        const siteUrlRedirect = (() => {
+            for (const p of probes) {
+                const first = Array.isArray(p.redirects) ? p.redirects[0] : null;
+                if (!first)
+                    continue;
+                const change = describeOriginChange(first.from || `${baseUrl}/`, first.location);
+                if (!change)
+                    continue;
+                return {
+                    status: first.status,
+                    from: first.from,
+                    location: first.location,
+                    target_origin: change.to_origin,
+                    suggested_url: suggestedSiteUrl(baseUrl, first.location),
+                    seen_on_probe: p.label,
+                };
+            }
+            return null;
+        })();
         // Ticket 44fcf6b5. A 401/407 is not a method block, it is the server
         // asking for a credential, and the two need opposite fixes. Grading an
         // authentication challenge as "the edge is blocking non-GET methods"
@@ -3711,6 +4103,10 @@ export class WordPressClient {
         const optionsAuthChallenged = authChallenged(optionsProbe);
         const httpAuthConfigured = !!(this.siteConfig.httpAuth?.username && this.siteConfig.httpAuth?.password);
         const writeMethodVerdict = (() => {
+            // First, and regardless of the GET probes: they followed the redirect,
+            // which is exactly why they look healthy.
+            if (siteUrlRedirect)
+                return 'site_url_redirects';
             // If plain GET is not healthy, nothing can be concluded about writes
             // specifically — the whole connection is the problem.
             if (!getOk)
@@ -3723,6 +4119,8 @@ export class WordPressClient {
                 return 'auth_challenge';
             if (optionsBlocked || putBlockedAtEdge)
                 return 'blocked';
+            if (putDispatchedAsRead)
+                return 'verb_rewritten';
             if (putDropped || optionsDropped)
                 return 'unknown';
             if (putReachedWordPress)
@@ -3733,7 +4131,17 @@ export class WordPressClient {
         // check still means "proven blocked" and never accidentally fires on the
         // unknown case. null = could not tell — which is the honest answer for an
         // auth challenge as well as for a dropped probe.
-        const writeMethodBlocked = writeMethodVerdict === 'blocked' ? true : writeMethodVerdict === 'not_blocked' ? false : null;
+        // true also covers the two states where the write verb provably does not
+        // arrive as sent: the site URL redirects (every write is refused) and the
+        // host rewrites the verb (the connector works around it, see
+        // retryWithMethodOverride, but the verb itself is not getting through).
+        const writeMethodBlocked = writeMethodVerdict === 'blocked' ||
+            writeMethodVerdict === 'site_url_redirects' ||
+            writeMethodVerdict === 'verb_rewritten'
+            ? true
+            : writeMethodVerdict === 'not_blocked'
+                ? false
+                : null;
         const forceWriteMethodHint = ' Unblock this connection immediately without touching the host: add ' +
             `"forceWriteMethod": "post" to the site object in ${CONFIG_FILE}. The Respira plugin ` +
             'registers the same handler on PUT and POST for every updatable resource, so POST does ' +
@@ -3802,6 +4210,21 @@ export class WordPressClient {
                     forceWriteMethodHint);
             }
         }
+        if (writeMethodVerdict === 'verb_rewritten') {
+            recommendations.push(`PUT /wp-json/respira/v1/ping returned ${putProbe?.status} with the ping response, but /ping only registers a GET handler: ` +
+                'something in front of WordPress rewrote the PUT into a GET. Every PUT, PATCH and DELETE on this site reaches WordPress as a read. ' +
+                'On a route with no GET handler WordPress answers rest_no_route; on a route that has one (pages, posts, media) the read handler answers and nothing is written. ' +
+                'This connector detects both and re-sends the write once as POST with X-HTTP-Method-Override and _method set to the original verb, which WordPress core honours, ' +
+                'so writes work without a config change. The host is still worth asking to stop rewriting PUT/PATCH/DELETE for /wp-json/respira/*.');
+        }
+        if (siteUrlRedirect) {
+            const where = this.siteConfig.id === 'env-site' ? 'the WORDPRESS_URL setting' : CONFIG_FILE;
+            recommendations.unshift(`Your site URL redirects: ${baseUrl} answered with a ${siteUrlRedirect.status} to ${siteUrlRedirect.target_origin} ` +
+                `(${siteUrlRedirect.seen_on_probe}: ${siteUrlRedirect.location}). Reads follow the redirect and work, but Respira does not re-send a write ` +
+                'to a different address than the one configured, so every write (create, update, delete) fails on this site. ' +
+                `Update the URL for this site in your Respira config to ${siteUrlRedirect.suggested_url || siteUrlRedirect.target_origin} (${where}). ` +
+                'It should match the Site Address in WordPress under Settings > General.');
+        }
         if (restRouteFallbackWorked) {
             this.lastRestRouteFallbackWorked = true;
             recommendations.push('Pretty `/wp-json/respira/...` path returned HTML but `?rest_route=/respira/...` returned JSON. ' +
@@ -3834,6 +4257,9 @@ export class WordPressClient {
             // `write_method_verdict` for the named state; never treat null as false.
             write_method_blocked: writeMethodBlocked,
             write_method_verdict: writeMethodVerdict,
+            // The configured URL redirects to another origin: { status, from,
+            // location, target_origin, suggested_url, seen_on_probe }, or null.
+            site_url_redirect: siteUrlRedirect,
             // Ticket 44fcf6b5: whether a credential was configured and sent is part
             // of the evidence, not background knowledge the reader is assumed to
             // have. Without it, "401 on PUT" and "401 on PUT with the password
@@ -3847,6 +4273,7 @@ export class WordPressClient {
                 put_dropped: putDropped,
                 put_auth_challenged: putAuthChallenged,
                 put_reached_wordpress: putReachedWordPress,
+                put_dispatched_as_read: putDispatchedAsRead,
                 put_error: putProbe?.error ?? null,
                 put_error_code: putProbe?.code ?? null,
                 put_www_authenticate: putProbe?.headers?.['www-authenticate'] ?? null,