drupal-mcp-connector 2.15.0 → 2.15.2

package/.agents/commands/drupal-get-paragraph.md

@@ -1,11 +1,11 @@
 ---
-description: "Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph (fields include drupal_internal__revision_id) plus a `ref` ({ type: 'paragraph--<bundle>', id, meta: { target_revision_id } }) you can use to embed it in a host entity's paragraph / ERR field. Pass langcode to read an unpublished working translation via Sentinel. Paragraphs are referenced from a host field rather than queried standalone in production. Governed by the site security policy."
+description: "Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph (fields include drupal_internal__revision_id) plus a `ref` ({ type: 'paragraph--<bundle>', id, meta: { target_revision_id } }) you can use to embed it in a host entity's paragraph / ERR field. Pass revisionId (the host pin) to read that revision via JSON:API resourceVersion=id:<vid>; a mismatch or miss is an error, not a silent default-revision fallback. Pass langcode to read an unpublished working translation via Sentinel. Paragraphs are referenced from a host field rather than queried standalone in production. Governed by the site security policy."
 argument-hint: "<paragraphType> <id> [site] [langcode] [revisionId]"
 ---
 
 Call the MCP tool `drupal_get_paragraph`.
 
-Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph (fields include drupal_internal__revision_id) plus a `ref` ({ type: 'paragraph--<bundle>', id, meta: { target_revision_id } }) you can use to embed it in a host entity's paragraph / ERR field. Pass langcode to read an unpublished working translation via Sentinel. Paragraphs are referenced from a host field rather than queried standalone in production. Governed by the site security policy.
+Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph (fields include drupal_internal__revision_id) plus a `ref` ({ type: 'paragraph--<bundle>', id, meta: { target_revision_id } }) you can use to embed it in a host entity's paragraph / ERR field. Pass revisionId (the host pin) to read that revision via JSON:API resourceVersion=id:<vid>; a mismatch or miss is an error, not a silent default-revision fallback. Pass langcode to read an unpublished working translation via Sentinel. Paragraphs are referenced from a host field rather than queried standalone in production. Governed by the site security policy.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
@@ -16,6 +16,6 @@ Parse the arguments supplied with this command into this tool's parameters:
 **Optional:**
 - `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
 - `langcode` (string): Target language for the unpublished working translation (e.g. 'es').
-- `revisionId` (string): Paragraph revision id the host already pins.
+- `revisionId` (string): Paragraph revision id the host already pins (ERR meta.target_revision_id). Honored on the read; a different served vid is an error.
 
 If a required parameter is missing, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/.agents/commands/drupal-list-nodes.md

@@ -1,11 +1,11 @@
 ---
-description: "List nodes of a given content type. Supports status filtering, pagination, sorting, and structured filter descriptors."
+description: "List nodes of a given content type. Supports status filtering, pagination, sorting, and structured filter descriptors. Drupal core JSON:API caps page[limit] at 50; a larger requested limit is filled by following links.next (up to 1000). When the site does not expose meta.count, total is exact only if this window reached the end of the collection; otherwise approximate is true and hasNext is set."
 argument-hint: "<type> [site] [status] [limit] [offset] [filters] [sort]"
 ---
 
 Call the MCP tool `drupal_list_nodes`.
 
-List nodes of a given content type. Supports status filtering, pagination, sorting, and structured filter descriptors.
+List nodes of a given content type. Supports status filtering, pagination, sorting, and structured filter descriptors. Drupal core JSON:API caps page[limit] at 50; a larger requested limit is filled by following links.next (up to 1000). When the site does not expose meta.count, total is exact only if this window reached the end of the collection; otherwise approximate is true and hasNext is set.
 
 Parse the arguments supplied with this command into this tool's parameters:
 

package/.agents/commands/drupal-list-revisions.md

@@ -1,11 +1,11 @@
 ---
-description: "Surface the addressable revisions of a content node: the latest default revision and the working-copy (forward) revision, with their version ids and links. workingCopy: null is not an all-clear — Drupal core can still reject PATCH when a revision row sits above the default without a content_moderation working copy (#201). The payload includes possiblyPatchBlocked (true when default changed is later than its revision_timestamp) plus changed and revisionTimestamp on latestVersion. Probe the host (this flag, then dryRun on the update) before creating dependent paragraphs. NOTE: JSON:API cannot enumerate full chronological revision history. Full history enumeration requires the Drush bridge."
+description: "Surface the latest default and working node revisions. When the core working-copy alias is absent or echoes live, consult Sentinel translation inventory; workingCopy then includes source and language-specific translations instead of a misleading aggregate status. Continue an unpublished translation with explicit langcode. workingCopy: null is not an all-clear — Drupal core can still reject PATCH when a revision row sits above the default without a content_moderation working copy (#201). The payload includes possiblyPatchBlocked (true when default changed is later than its revision_timestamp) plus changed and revisionTimestamp on latestVersion. Probe the host (this flag, then dryRun on the update) before creating dependent paragraphs. NOTE: JSON:API cannot enumerate full chronological revision history. Full history enumeration requires the Drush bridge."
 argument-hint: "<type> <id> [site]"
 ---
 
 Call the MCP tool `drupal_list_revisions`.
 
-Surface the addressable revisions of a content node: the latest default revision and the working-copy (forward) revision, with their version ids and links. workingCopy: null is not an all-clear — Drupal core can still reject PATCH when a revision row sits above the default without a content_moderation working copy (#201). The payload includes possiblyPatchBlocked (true when default changed is later than its revision_timestamp) plus changed and revisionTimestamp on latestVersion. Probe the host (this flag, then dryRun on the update) before creating dependent paragraphs. NOTE: JSON:API cannot enumerate full chronological revision history. Full history enumeration requires the Drush bridge.
+Surface the latest default and working node revisions. When the core working-copy alias is absent or echoes live, consult Sentinel translation inventory; workingCopy then includes source and language-specific translations instead of a misleading aggregate status. Continue an unpublished translation with explicit langcode. workingCopy: null is not an all-clear — Drupal core can still reject PATCH when a revision row sits above the default without a content_moderation working copy (#201). The payload includes possiblyPatchBlocked (true when default changed is later than its revision_timestamp) plus changed and revisionTimestamp on latestVersion. Probe the host (this flag, then dryRun on the update) before creating dependent paragraphs. NOTE: JSON:API cannot enumerate full chronological revision history. Full history enumeration requires the Drush bridge.
 
 Parse the arguments supplied with this command into this tool's parameters:
 

package/.agents/commands/drupal-update-node.md

@@ -1,11 +1,11 @@
 ---
-description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Pass langcode to continue an unpublished working translation (Sentinel X-MCP-Draft-Langcode); this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#166); dryRun uses that same target. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents."
+description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Pass langcode to continue an unpublished working translation (Sentinel X-MCP-Draft-Langcode); this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. Existing node drafts use Sentinel's governed draft endpoint with verified live/working revision preconditions; translation-only drafts are discovered through Sentinel inventory (#297). Pass explicit langcode to continue an unpublished translation. Published languages are not converted into drafts; dryRun uses the same target. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents."
 argument-hint: "<type> <id> [site] [title] [body] [summary] [format] [status] [moderationState] [langcode] [fields] [relationships] [dryRun] [returning]"
 ---
 
 Call the MCP tool `drupal_update_node`.
 
-Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Pass langcode to continue an unpublished working translation (Sentinel X-MCP-Draft-Langcode); this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#166); dryRun uses that same target. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents.
+Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Pass langcode to continue an unpublished working translation (Sentinel X-MCP-Draft-Langcode); this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. Existing node drafts use Sentinel's governed draft endpoint with verified live/working revision preconditions; translation-only drafts are discovered through Sentinel inventory (#297). Pass explicit langcode to continue an unpublished translation. Published languages are not converted into drafts; dryRun uses the same target. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents.
 
 Parse the arguments supplied with this command into this tool's parameters:
 

package/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.15.2] - 2026-09-11
+
+### Fixed
+- **Discover and continue translation-only forward revisions (#297).** When core's
+  working-copy alias is absent or echoes live, node revision listing and guarded
+  updates consult Sentinel's translation inventory. Existing unpublished languages
+  continue through the governed endpoint with explicit language and live/working
+  preconditions. Published languages and ambiguous multilingual edits remain refused.
+  Permission and transport failures stop discovery rather than becoming “no draft”.
+  Update responses preserve the saved translation instead of replacing it with live
+  English. An unresolved revision conflict no longer prescribes revision surgery.
+
+## [2.15.1] - 2026-09-10
+
+### Fixed
+- **`drupal_get_paragraph` honors `revisionId` and refuses a default-revision fallback (#292).**
+  Passing the host pin without `langcode` now reads JSON:API
+  `?resourceVersion=id:<vid>`. If Drupal serves a different
+  `drupal_internal__revision_id` (or nothing), the tool errors instead of
+  returning the live default revision. `ref.meta.target_revision_id` is the
+  served vid. `langcode` still uses Sentinel's draft read.
+- **`drupal_list_nodes` no longer reports a Drupal-capped page as the exact collection total (#291).**
+  Core JSON:API silently caps `page[limit]` at 50 and does not send `meta.count`.
+  The connector was treating that page length as `total` with `approximate: false`,
+  so a `limit: 100` call on a 54-item collection returned 50 and looked complete.
+  `listEntities` now follows `links.next` to fill a larger requested limit (up to
+  1000) and only reports an exact `total` when `meta.count` is present or the
+  window reached the end. Otherwise `approximate` is true and `hasNext` is
+  returned on the tool result.
+
 ## [2.15.0] - 2026-09-10
 
 ### Fixed
@@ -1553,6 +1583,9 @@ The connector is now **dual-protocol**: every tool runs against an abstract back
 - User tools gained explicit PII-access assertions.
 - Whole tree lint-clean (`npm run lint`) with object-injection sinks rewritten to safe lookups.
 
+[2.15.2]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.15.2
+[2.15.1]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.15.1
+[2.15.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.15.0
 [2.14.2]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.14.2
 [2.14.1]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.14.1
 [2.14.0]: https://github.com/Wilkes-Liberty/drupal-mcp-connector/releases/tag/v2.14.0

package/README.md

@@ -1,6 +1,6 @@
 # drupal-mcp-connector
 
-> A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL access, governed content tools, audit reports, and an SSH Drush bridge.
+> A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL access, governed draft translations, content tools, audit reports, and an SSH Drush bridge.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20-green)](https://nodejs.org)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.15.0",
-  "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL.",
+  "version": "2.15.2",
+  "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL access, governed draft translations, content tools, audit reports, and an SSH Drush bridge.",
   "type": "module",
   "main": "src/index.js",
   "bin": {

package/src/lib/backends/jsonapi.js

@@ -24,14 +24,30 @@ import { isPositiveNid, normalizeAlias, PATH_ALIAS_ENTITY_TYPE } from "../path-a
 // governed read/write workflows explicitly need.
 const INTERNAL_ATTR_RE = /^drupal_internal__/;
 
-// countEntities() pagination. Drupal core JSON:API returns no total in `meta`,
-// so an exact count is obtained by walking pages until `links.next` is gone.
-// COUNT_PAGE_SIZE is Drupal's default max page size; COUNT_MAX_RECORDS bounds
-// the walk so a huge collection can't issue unbounded requests (mirrors the
-// GraphQL backend's MAX_CLIENT_RECORDS) — past it the count is approximate.
+// countEntities() / listEntities() pagination. Drupal core JSON:API returns no
+// total in `meta` and silently caps `page[limit]` at OffsetPage::SIZE_MAX
+// (50 by default). COUNT_PAGE_SIZE matches that default; COUNT_MAX_RECORDS
+// bounds a walk so a huge collection can't issue unbounded requests (mirrors
+// the GraphQL backend's MAX_CLIENT_RECORDS) — past it the count is approximate.
 const COUNT_PAGE_SIZE = 50;
 const COUNT_MAX_RECORDS = 1000;
 
+/**
+ * Whether a JSON:API collection document advertises another page.
+ * `links.next` may be a string href or a `{ href }` link object.
+ * @param {?object} data JSON:API document.
+ * @returns {boolean}
+ */
+function jsonApiHasNext(data) {
+  const next = data?.links?.next;
+  if (next === undefined || next === null || next === false) return false;
+  if (typeof next === "string") return next.length > 0;
+  if (typeof next === "object" && next.href !== undefined && next.href !== null) {
+    return String(next.href).length > 0;
+  }
+  return Boolean(next);
+}
+
 /**
  * Detect the JSON:API error Drupal returns when a write attempts to set the
  * `status` (published) field on a content_moderation-governed entity. Such
@@ -268,24 +284,72 @@ export class JsonApiBackend extends Backend {
   }
 
   /**
-   * List entities for a descriptor. Server-side filter/sort/paging means the
-   * result is always exact (`approximate`/`truncated` are false).
+   * List entities for a descriptor.
+   *
+   * Drupal core JSON:API has no `meta.count` (jsonapi_extras can add it) and
+   * silently caps `page[limit]` at OffsetPage::SIZE_MAX (50 by default). When
+   * the caller asks for more rows than one Drupal page returns and
+   * `links.next` is present, this method follows that link until the requested
+   * window is filled, the collection ends, or COUNT_MAX_RECORDS is hit.
+   * `page.total` is exact when `meta.count` is present or this window reached
+   * the end; otherwise it is the number of rows seen so far and `approximate`
+   * is true. Never report a single page's length as an exact collection total.
+   *
    * @param {import("../canonical.js").QueryDescriptor} descriptor
    * @returns {Promise<import("./backend-interface.js").ListResult>}
    */
   async listEntities(descriptor) {
-    const params = this.compileQuery(descriptor);
-    const qs = params.toString();
-    const base = this.resourcePath(descriptor.entityType, descriptor.bundle);
-    const path = qs ? `${base}?${qs}` : base;
-    const data = await drupalFetch(this.site, path);
-    const entities = (data.data || []).map((r) => this.toCanonical(r));
-    const total = data.meta?.count ?? entities.length;
+    const requestedLimit = descriptor.page?.limit;
+    const startOffset = descriptor.page?.offset ?? 0;
+    const fillTo = typeof requestedLimit === "number"
+      ? Math.min(Math.max(0, requestedLimit), COUNT_MAX_RECORDS)
+      : null;
+
+    const entities = [];
+    let offset = startOffset;
+    let hasNext = false;
+    let metaCount = null;
+
+    for (;;) {
+      const remaining = fillTo === null ? requestedLimit : fillTo - entities.length;
+      const page = {
+        ...descriptor.page,
+        offset,
+        ...(typeof remaining === "number" ? { limit: remaining } : {}),
+      };
+      const params = this.compileQuery({ ...descriptor, page });
+      const qs = params.toString();
+      const base = this.resourcePath(descriptor.entityType, descriptor.bundle);
+      const path = qs ? `${base}?${qs}` : base;
+      const data = await drupalFetch(this.site, path);
+      if (metaCount === null && typeof data?.meta?.count === "number") {
+        metaCount = data.meta.count;
+      }
+      const pageEntities = (data.data || []).map((r) => this.toCanonical(r));
+      entities.push(...pageEntities);
+      hasNext = jsonApiHasNext(data);
+
+      if (fillTo === null) break;
+      if (!hasNext || pageEntities.length === 0) break;
+      if (entities.length >= fillTo) break;
+      offset += pageEntities.length;
+    }
+
+    const truncated = fillTo !== null
+      && typeof requestedLimit === "number"
+      && entities.length < requestedLimit
+      && hasNext;
+    const seen = startOffset + entities.length;
+    const exact = typeof metaCount === "number" || !hasNext;
     return {
       entities,
-      page: { total, hasNext: Boolean(data.links?.next), cursor: null },
-      approximate: false,
-      truncated: false,
+      page: {
+        total: typeof metaCount === "number" ? metaCount : seen,
+        hasNext,
+        cursor: null,
+      },
+      approximate: !exact,
+      truncated,
     };
   }
 

package/src/lib/node-draft-inventory.js

@@ -0,0 +1,47 @@
+/** Sentinel discovery for translation-only node revisions (#297). */
+import { readTranslationInventory } from "./draft-write.js";
+
+/**
+ * Read optional inventory, falling back only when the endpoint is unsupported.
+ * Permission, transport and malformed-response failures are not absence.
+ * @param {object} backend
+ * @param {{entityType: string, bundle: string, id: string}} ref
+ * @returns {Promise<object|null>}
+ */
+export async function readNodeDraftInventory(backend, ref) {
+  if (ref.entityType !== "node" || typeof backend.rawQuery !== "function"
+    || typeof backend.resourcePath !== "function") return null;
+  let inventory;
+  try {
+    inventory = await readTranslationInventory(backend, ref);
+  } catch (error) {
+    if (/does not provide Sentinel's governed draft-translation endpoint/.test(error.message)) return null;
+    throw error;
+  }
+  const validVid = (vid) => /^[1-9]\d*$/.test(String(vid ?? "")) && Number.isSafeInteger(Number(vid));
+  if (!validVid(inventory.live?.vid)
+    || (inventory.working && (!validVid(inventory.working.vid)
+      || !Array.isArray(inventory.working.translations)
+      || inventory.working.translations.some((row) => !row || typeof row.langcode !== "string"
+        || typeof row.status !== "boolean")))) {
+    throw new Error("Sentinel returned an invalid node revision inventory. Re-read before updating.");
+  }
+  return inventory;
+}
+
+/**
+ * Ensure inventory discovery does not turn a published language into a draft.
+ * Sentinel still validates the revision pair and language on every request.
+ * @param {object} inventory
+ * @param {string|undefined} langcode
+ */
+export function assertInventoryDraftLanguage(inventory, langcode) {
+  const rows = inventory.working?.translations ?? [];
+  if (!langcode && rows.length !== 1) {
+    throw new Error("This working revision contains translations. Pass an explicit langcode for an existing unpublished language; no draft was created.");
+  }
+  const row = langcode ? rows.find((item) => item.langcode === langcode) : rows[0];
+  if (!row || row.status !== false) {
+    throw new Error("The requested language is not an existing unpublished working draft. Published languages and other drafts were left unchanged.");
+  }
+}

package/src/lib/patch-preflight.js

@@ -16,8 +16,8 @@
  *   Sentinel's /mcp-draft endpoint with verified live/working revision IDs.
  *   Core rejects resourceVersion on PATCH. Never retry the canonical URL.
  * - **#201** — the working-copy alias does not resolve, but core still
- *   blocks. That is a stray revision row. Refuse with revision-surgery
- *   language. `workingCopy: null` is not proof the node is writable.
+ *   blocks. Consult Sentinel inventory for translation-only revisions before
+ *   refusing the unresolved revision conflict. `workingCopy: null` is not proof the node is writable.
  *
  * Unsupported endpoints and stale revisions fail closed, without discard.
  */
@@ -25,6 +25,7 @@
 import { entityLooksModerated, hasExplicitModerationState } from "./moderation-default.js";
 import { entityRevisionId } from "./write-revision.js";
 import { writeDraft } from "./draft-write.js";
+import { readNodeDraftInventory, assertInventoryDraftLanguage } from "./node-draft-inventory.js";
 
 /** Stable error code for a core working-copy / not-latest-revision block. */
 export const PATCH_BLOCKED_CODE = "PATCH_BLOCKED";
@@ -48,7 +49,7 @@ export const PATCH_BLOCKED_MESSAGE =
   "This entity cannot be updated over JSON:API because the stored entity is not " +
   "the latest revision (Drupal core #2795279). The JSON:API aliases " +
   "rel:latest-version and rel:working-copy cannot show the blocking row. " +
-  "Clearing it requires revision surgery outside JSON:API (Drush / the entity API). " +
+  "Inspect the translation inventory and revision history before considering repair; do not delete drafts. " +
   "See connector #201. Do not retry the same canonical PATCH.";
 
 /**
@@ -248,17 +249,32 @@ export async function loadWorkingCopy(backend, { entityType, bundle, id }) {
  */
 export async function resolveWorkingCopyPatchTarget(backend, { entityType, bundle, id, existing }) {
   const workingCopy = await loadWorkingCopy(backend, { entityType, bundle, id });
+  if (workingCopy?.id && workingCopy.id !== id) {
+    throw new PatchTargetAmbiguousError(id, workingCopy.id);
+  }
   let liveVid = entityRevisionId(existing);
   if (workingCopy && (liveVid === null || liveVid === undefined) && typeof backend?.getEntity === "function") {
     const live = await backend.getEntity({ entityType, bundle, id }).catch(() => null);
     liveVid = entityRevisionId(live);
   }
+  const aliasVid = entityRevisionId(workingCopy);
+  if (!workingCopy || (liveVid !== null && String(aliasVid) === String(liveVid))) {
+    const inventory = await readNodeDraftInventory(backend, { entityType, bundle, id });
+    if (inventory) {
+      if (liveVid !== null && String(liveVid) !== String(inventory.live.vid)) {
+        throw new WorkingCopyStaleError(new Error("Sentinel's live revision changed during discovery."));
+      }
+      liveVid = Number(inventory.live.vid);
+      const workingVid = inventory.working ? Number(inventory.working.vid) : null;
+      if (workingVid !== null && workingVid !== liveVid) {
+        return { resourceVersion: `id:${workingVid}`, workingCopy: null,
+          liveVid, workingVid, inventory };
+      }
+    }
+  }
   if (!workingCopy) {
     return { resourceVersion: undefined, workingCopy: null, liveVid, workingVid: null };
   }
-  if (workingCopy.id && workingCopy.id !== id) {
-    throw new PatchTargetAmbiguousError(id, workingCopy.id);
-  }
   const workingVid = entityRevisionId(workingCopy);
   if (workingVid !== null && liveVid !== null && String(workingVid) === String(liveVid)) {
     return { resourceVersion: undefined, workingCopy, liveVid, workingVid };
@@ -402,6 +418,7 @@ export async function prepareGuardedPatch(backend, {
       throw new StaleCopyError();
     }
   }
+  if (target.inventory) assertInventoryDraftLanguage(target.inventory, langcode);
   if (langcode) {
     if (!target.workingVid || !target.liveVid || String(target.workingVid) === String(target.liveVid)) {
       throw new Error(

package/src/lib/write-revision.js

@@ -65,7 +65,10 @@ export async function attachWrittenRevisionPair({
   backend, entityType, bundle, id, entity, liveVid,
 }) {
   if (liveVid === null || liveVid === undefined || !entity) return entity;
-  let workingVid = null;
+  let workingVid = entityRevisionId(entity);
+  if (workingVid !== null && String(workingVid) !== String(liveVid)) {
+    return attachRevisionPair(entity, { live: liveVid, working: workingVid });
+  }
   if (typeof backend?.getEntity === "function") {
     try {
       const wc = await backend.getEntity({
@@ -93,12 +96,16 @@ export async function attachWrittenRevisionPair({
  *   for the write (e.g. `rel:working-copy`). PreferCanonical re-reads this
  *   resource instead of the default revision so a draft PATCH is not
  *   replaced by the live body.
+ * @param {?string} [args.langcode] Language returned by governed draft continuation.
  * @returns {Promise<object>} Entity to return, with `_revision` when relevant.
  */
 export async function readWrittenRevision({
   backend, entityType, bundle, id, relationshipsSent, patchResult = null, preferCanonical = false,
-  resourceVersion,
+  resourceVersion, langcode,
 }) {
+  // Sentinel returned the requested translation; a canonical read would replace
+  // it with live English, and the core working-copy alias may not address it.
+  if (langcode && patchResult) return patchResult;
   if (!relationshipsSent) {
     if (preferCanonical && typeof backend.getEntity === "function") {
       const fresh = await backend.getEntity({

package/src/tools/entities.js

@@ -136,6 +136,7 @@ async function updateEntity({ site: siteName, entityType, bundle, id, attributes
   const written = await readWrittenRevision({
     backend, entityType, bundle, id,
     relationshipsSent: relationshipsWereSent(resolvedRelationships),
+    langcode,
     patchResult: result,
     preferCanonical: false,
   });

package/src/tools/nodes.js

@@ -280,8 +280,9 @@ async function getNode({ site: siteName, type, id, langcode, resourceVersion })
  *
  * @param {object} args - { site?, type, status?, filters?, limit?, offset?, sort? }.
  *   A `status` boolean is appended to `filters` as a status equality descriptor.
- * @returns {Promise<{total: number, approximate: boolean, offset: number,
- *   nextOffset: number, nodes: object[]}>} Paged, redacted node list.
+ * @returns {Promise<{total: number, approximate: boolean, truncated: boolean,
+ *   offset: number, nextOffset: number, hasNext: boolean, nodes: object[]}>}
+ *   Paged, redacted node list. `hasNext` is the backend's `links.next` signal.
  */
 async function listNodes({ site: siteName, type, status, filters = [], limit = 20, offset = 0, sort = [{ field: "changed", dir: "desc" }] }) {
   const site = getSiteConfig(siteName);
@@ -295,8 +296,10 @@ async function listNodes({ site: siteName, type, status, filters = [], limit = 2
   return {
     total: res.page?.total ?? nodes.length,
     approximate: res.approximate ?? false,
+    truncated: res.truncated ?? false,
     offset,
     nextOffset: offset + nodes.length,
+    hasNext: Boolean(res.page?.hasNext),
     nodes,
   };
 }
@@ -466,16 +469,18 @@ async function updateNode({ site: siteName, type, id, title, body, summary, form
   let fresh = await readWrittenRevision({
     backend, entityType: "node", bundle: type, id,
     relationshipsSent: relationshipsWereSent(resolvedRelationships),
+    langcode,
     patchResult: patched,
     preferCanonical: true,
     resourceVersion: patchTarget.resourceVersion,
   });
   const intendedAlias = pathAttr?.alias ? normalizeAlias(pathAttr.alias) : null;
   if (intendedAlias) {
-    fresh = await assertAliasPersisted({
+    const aliasChecked = await assertAliasPersisted({
       backend, sec, type, id, intendedAlias,
       resourceVersion: patchTarget.resourceVersion, written: fresh,
     });
+    fresh = langcode ? { ...fresh, url: aliasChecked.url } : aliasChecked;
   }
   // Redirect only after the new alias is what re-reads show (#274).
   const redirectResult = redirect ? await createRenameRedirect(backend, sec, redirect) : null;
@@ -528,7 +533,7 @@ export const definitions = [
   },
   {
     name: "drupal_list_nodes",
-    description: "List nodes of a given content type. Supports status filtering, pagination, sorting, and structured filter descriptors.",
+    description: "List nodes of a given content type. Supports status filtering, pagination, sorting, and structured filter descriptors. Drupal core JSON:API caps page[limit] at 50; a larger requested limit is filled by following links.next (up to 1000). When the site does not expose meta.count, total is exact only if this window reached the end of the collection; otherwise approximate is true and hasNext is set.",
     inputSchema: {
       type: "object", required: ["type"],
       properties: {
@@ -579,7 +584,7 @@ export const definitions = [
   },
   {
     name: "drupal_update_node",
-    description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Pass langcode to continue an unpublished working translation (Sentinel X-MCP-Draft-Langcode); this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. An addressable node draft uses Sentinel's governed draft endpoint with live/working revision preconditions (#166); dryRun uses that same target. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents.",
+    description: "Update an existing node. Only include fields you want to change. For moderated content types, use moderationState (e.g. 'published') rather than status. When the target is published and moderated and you omit moderationState, the connector defaults the write to moderation_state 'draft' (forward revision) so live default revisions are not mutated by accident. Pass langcode to continue an unpublished working translation (Sentinel X-MCP-Draft-Langcode); this does not PATCH canonical langcode and will not create a missing translation — use drupal_create_translation first. Entity-reference fields go in `relationships`, not `fields`. Paragraph / ERR identifiers are resolved to include meta.target_revision_id before PATCH; the write fails if any ref cannot be resolved (an unresolved identifier persists as an empty field). On moderated targets a non-saving PATCH preflight runs first — including on dryRun — against the same URL the write will hit. Existing node drafts use Sentinel's governed draft endpoint with verified live/working revision preconditions; translation-only drafts are discovered through Sentinel inventory (#297). Pass explicit langcode to continue an unpublished translation. Published languages are not converted into drafts; dryRun uses the same target. workingCopy:null from drupal_list_revisions is not proof the node is writable (possiblyPatchBlocked / #201). Preflight here does not un-orphan paragraphs already created; probe the host before creating dependents.",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {

package/src/tools/paragraphs.js

@@ -145,24 +145,85 @@ async function updateParagraph({ site: siteName, paragraphType, id, attributes =
   return { paragraph, ref, relationshipData: ref, note: EMBED_NOTE };
 }
 
+/**
+ * JSON:API `resourceVersion` selector for a paragraph host pin.
+ * Accepts a numeric vid, a numeric string, or an explicit `id:<vid>`.
+ * @param {string|number} revisionId Host pin / paragraph revision id.
+ * @returns {string} e.g. `id:6654`.
+ * @throws {Error} If the value is not a usable revision id.
+ */
+export function paragraphResourceVersion(revisionId) {
+  if (typeof revisionId === "number" && Number.isFinite(revisionId) && revisionId > 0) {
+    return `id:${revisionId}`;
+  }
+  if (typeof revisionId === "string" && revisionId.length) {
+    if (/^id:[1-9]\d*$/.test(revisionId)) return revisionId;
+    if (/^[1-9]\d*$/.test(revisionId)) return `id:${revisionId}`;
+  }
+  throw new Error(
+    `Invalid paragraph revisionId "${revisionId}". Use a numeric vid (the host pin).`,
+  );
+}
+
+/**
+ * Numeric vid from a host pin (`6654` or `id:6654`).
+ * @param {string|number} revisionId
+ * @returns {?number}
+ */
+function requestedParagraphVid(revisionId) {
+  const raw = String(revisionId).replace(/^id:/, "");
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+/**
+ * Fail closed when a requested paragraph revision was not the one served.
+ * Silent substitution of the default revision is the defect this guards (#292).
+ * @param {?object} entity Canonical paragraph, or null if the read missed.
+ * @param {string|number} requested Host pin that was asked for.
+ * @param {string} id Paragraph UUID.
+ * @returns {object} `entity` when the served vid matches.
+ * @throws {Error} On a miss or a mismatched vid.
+ */
+function requireServedParagraphRevision(entity, requested, id) {
+  const wanted = requestedParagraphVid(requested);
+  const served = paragraphRevisionId(entity);
+  if (!entity || wanted === null || served === null || served !== wanted) {
+    const got = !entity || served === null ? "no revision" : String(served);
+    throw new Error(
+      `Requested paragraph revision ${wanted ?? requested} for ${id} but the backend served ${got}. ` +
+      "Refusing to substitute a different revision.",
+    );
+  }
+  return entity;
+}
+
 /**
  * Fetch a single paragraph by bundle + UUID, redacted per the site policy, and
  * annotate it with the embedding ref (including `meta.target_revision_id`).
  *
- * @param {object} args - { site?, paragraphType, id }.
+ * When `revisionId` is set (the host's `meta.target_revision_id`), the read
+ * addresses that revision via JSON:API `?resourceVersion=id:<vid>` and errors
+ * if Drupal serves a different vid. Omitting `revisionId` still reads the
+ * default revision.
+ *
+ * @param {object} args - { site?, paragraphType, id, langcode?, revisionId? }.
  * @returns {Promise<(object & {ref: object})|null>}
- *   The redacted paragraph with an embedding `ref`, or null if not found.
+ *   The redacted paragraph with an embedding `ref`, or null if not found and
+ *   no `revisionId` was requested.
  * @throws {SecurityError} If reading paragraphs of this bundle is not permitted.
+ * @throws {Error} If a requested `revisionId` cannot be served.
  */
 async function getParagraph({ site: siteName, paragraphType, id, langcode, revisionId }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertReadAllowed(sec, "paragraph", paragraphType);
   const backend = await resolveBackend(site);
+  const pinRequested = revisionId !== undefined && revisionId !== null && revisionId !== "";
   let entity;
   if (langcode) {
     const targetLang = assertDraftLangcode(langcode);
-    const pinned = revisionId ?? paragraphRevisionId(
+    const pinned = pinRequested ? revisionId : paragraphRevisionId(
       await backend.getEntity({ entityType: "paragraph", bundle: paragraphType, id }),
     );
     if (pinned === null || pinned === undefined || pinned === "") {
@@ -172,12 +233,18 @@ async function getParagraph({ site: siteName, paragraphType, id, langcode, revis
       entityType: "paragraph", bundle: paragraphType, id, langcode: targetLang,
       draftRevision: { revisionId: pinned },
     });
+  } else if (pinRequested) {
+    const resourceVersion = paragraphResourceVersion(revisionId);
+    entity = await backend.getEntity({
+      entityType: "paragraph", bundle: paragraphType, id, resourceVersion,
+    });
+    requireServedParagraphRevision(entity, revisionId, id);
   } else {
     entity = await backend.getEntity({ entityType: "paragraph", bundle: paragraphType, id });
   }
   if (!entity) return null;
   const redacted = redactCanonicalEntity(entity, sec, "paragraph");
-  const resolvedRevisionId = paragraphRevisionId(entity) ?? paragraphRevisionId(redacted) ?? revisionId;
+  const resolvedRevisionId = paragraphRevisionId(entity) ?? paragraphRevisionId(redacted);
   return { ...redacted, ref: embedRef(redacted.bundle || paragraphType, redacted.id, resolvedRevisionId) };
 }
 
@@ -219,7 +286,7 @@ export const definitions = [
   {
     name: "drupal_get_paragraph",
     description:
-      "Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph (fields include drupal_internal__revision_id) plus a `ref` ({ type: 'paragraph--<bundle>', id, meta: { target_revision_id } }) you can use to embed it in a host entity's paragraph / ERR field. Pass langcode to read an unpublished working translation via Sentinel. Paragraphs are referenced from a host field rather than queried standalone in production. Governed by the site security policy.",
+      "Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph (fields include drupal_internal__revision_id) plus a `ref` ({ type: 'paragraph--<bundle>', id, meta: { target_revision_id } }) you can use to embed it in a host entity's paragraph / ERR field. Pass revisionId (the host pin) to read that revision via JSON:API resourceVersion=id:<vid>; a mismatch or miss is an error, not a silent default-revision fallback. Pass langcode to read an unpublished working translation via Sentinel. Paragraphs are referenced from a host field rather than queried standalone in production. Governed by the site security policy.",
     inputSchema: {
       type: "object", required: ["paragraphType", "id"],
       properties: {
@@ -227,7 +294,7 @@ export const definitions = [
         paragraphType: { type: "string", description: "Paragraph type / bundle machine name" },
         id:            { type: "string", description: "Paragraph UUID" },
         langcode:      { type: "string", description: "Target language for the unpublished working translation (e.g. 'es')." },
-        revisionId:    { type: "string", description: "Paragraph revision id the host already pins." },
+        revisionId:    { type: "string", description: "Paragraph revision id the host already pins (ERR meta.target_revision_id). Honored on the read; a different served vid is an error." },
       },
     },
   },

package/src/tools/revisions.js

@@ -23,6 +23,7 @@ import { resolveBackend } from "../lib/backends/index.js";
 import {
   resolveSecurityConfig, assertReadAllowed, assertWriteAllowed, redactCanonicalEntity,
 } from "../lib/security.js";
+import { readNodeDraftInventory } from "../lib/node-draft-inventory.js";
 import { assertDraftLangcode, readDraftTranslation, readTranslationInventory } from "../lib/draft-write.js";
 import { omitLiveComputedMetatag } from "../lib/entity-response.js";
 
@@ -177,13 +178,28 @@ async function listRevisions({ site: siteName, type, id }) {
 
   // The working-copy alias only resolves on entities under a content_moderation
   // workflow with a pending forward revision; absence is expected, not an error.
-  const workingCopy = await fetchRevisionResource(backend, "node", type, id, "rel:working-copy")
+  let workingCopy = await fetchRevisionResource(backend, "node", type, id, "rel:working-copy")
     .then(summarizeRevision)
     .catch(() => null);
 
+  if (!workingCopy || String(workingCopy.vid) === String(latestVersion?.vid)) {
+    const inventory = await readNodeDraftInventory(backend, { entityType: "node", bundle: type, id });
+    if (inventory?.working && String(inventory.working.vid) !== String(inventory.live.vid)) {
+      if (latestVersion && String(latestVersion.vid) !== String(inventory.live.vid)) {
+        throw new Error("The live revision changed during discovery. Re-read the revision inventory.");
+      }
+      // No aggregate publication flag: English may be published while Spanish is draft.
+      workingCopy = { vid: Number(inventory.working.vid), source: "sentinel-inventory",
+        translations: inventory.working.translations.map(({ langcode, status, moderation_state, default: isDefault }) => ({
+          langcode, status, moderation_state, default: isDefault,
+        })) };
+    }
+  }
+
   const possiblyPatchBlocked = Boolean(latestVersion && changedAheadOfRevision(latestVersion));
   let note = LIST_REVISIONS_BASE_NOTE;
   if (!workingCopy) note += LIST_REVISIONS_NULL_WC_NOTE;
+  if (workingCopy?.source === "sentinel-inventory") note += " Working revision discovered through Sentinel; publication state is language-specific. Continue an unpublished translation with explicit langcode.";
   if (possiblyPatchBlocked) note += LIST_REVISIONS_FINGERPRINT_NOTE;
 
   return {
@@ -332,7 +348,7 @@ export const definitions = [
   {
     name: "drupal_list_revisions",
     description:
-      "Surface the addressable revisions of a content node: the latest default revision and the working-copy (forward) revision, with their version ids and links. workingCopy: null is not an all-clear — Drupal core can still reject PATCH when a revision row sits above the default without a content_moderation working copy (#201). The payload includes possiblyPatchBlocked (true when default changed is later than its revision_timestamp) plus changed and revisionTimestamp on latestVersion. Probe the host (this flag, then dryRun on the update) before creating dependent paragraphs. NOTE: JSON:API cannot enumerate full chronological revision history. Full history enumeration requires the Drush bridge.",
+      "Surface the latest default and working node revisions. When the core working-copy alias is absent or echoes live, consult Sentinel translation inventory; workingCopy then includes source and language-specific translations instead of a misleading aggregate status. Continue an unpublished translation with explicit langcode. workingCopy: null is not an all-clear — Drupal core can still reject PATCH when a revision row sits above the default without a content_moderation working copy (#201). The payload includes possiblyPatchBlocked (true when default changed is later than its revision_timestamp) plus changed and revisionTimestamp on latestVersion. Probe the host (this flag, then dryRun on the update) before creating dependent paragraphs. NOTE: JSON:API cannot enumerate full chronological revision history. Full history enumeration requires the Drush bridge.",
     inputSchema: {
       type: "object", required: ["type", "id"],
       properties: {