@salesforce/graphiti 11.15.0 → 11.16.0

package/src/lib/__tests__/query-builder.spec.ts

@@ -8,10 +8,14 @@ import { parse } from "graphql";
 import { describe, expect, it } from "vitest";
 import { makeSession, TEST_SCHEMA } from "../../__tests__/helpers/schema.js";
 import { selectLeafInSession } from "../../commands/query.js";
+import { UserInputError } from "../errors.js";
 import { renderQuery } from "../query-builder.js";
 import {
 	addVariable,
 	createSiblingFieldInstance,
+	deepSetArg,
+	type FieldProjectionNode,
+	type FragmentProjectionNode,
 	selectLeaf,
 	setAliasOnPath,
 	setArg,
@@ -160,4 +164,388 @@ describe("query-builder", () => {
 			);
 		});
 	});
+
+	// W-23204027: the render layer asserts every emitted GraphQL Name is valid,
+	// making "the renderer never emits an injectable identifier" a system-wide
+	// invariant layered under the per-builder guards. These tests drive raw,
+	// unguarded names directly into the projection tree (bypassing every builder
+	// and zod guard) to prove the renderer is the last line of defense, and
+	// confirm legitimate output is never over-blocked.
+	describe("render-layer GraphQL Name fail-safe (W-23204027)", () => {
+		// The selection-set-breakout payload from the parent bug W-22735537: a raw
+		// fieldName closes the enclosing block early and hoists a sibling selection.
+		const INJECTION = "Id } injectedAlias: Name { value";
+
+		it("throws when a field node carries a raw, unguarded fieldName", () => {
+			const session = makeSession();
+			const injected: FieldProjectionNode = {
+				id: "fld_injected",
+				kind: "field",
+				parentId: null, // top-level → rendered by renderChildren(session, null, 1)
+				schemaPath: [INJECTION],
+				fieldName: INJECTION,
+				args: {},
+				directives: [],
+			};
+			session.nodes.push(injected);
+			// Pinned to the emitter so the test can't pass for the wrong reason
+			// (e.g. a future upstream guard throwing elsewhere).
+			expect(() => renderQuery(session)).toThrow(
+				/renderField: fieldName .* is not a valid GraphQL Name/,
+			);
+		});
+
+		it("throws when selectLeaf stores a raw injection string as the leaf fieldName", () => {
+			// Proves the actual residual sink: selectLeaf stores the final path
+			// segment verbatim as node.fieldName with no assert of its own.
+			const session = makeSession();
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", INJECTION]);
+			expect(() => renderQuery(session)).toThrow(
+				/renderField: fieldName .* is not a valid GraphQL Name/,
+			);
+		});
+
+		it("throws when an alias is a raw, unguarded name", () => {
+			const session = makeSession();
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", "name"]);
+			setAliasOnPath(session, ["accounts", "edges", "node", "name"], "evil { injected }");
+			expect(() => renderQuery(session)).toThrow(
+				/renderField: alias .* is not a valid GraphQL Name/,
+			);
+		});
+
+		it("throws when an inline-fragment type condition is a raw, unguarded name", () => {
+			const session = makeSession();
+			const frag: FragmentProjectionNode = {
+				id: "frag_injected",
+				kind: "fragment",
+				parentId: null,
+				schemaPath: ["[Account] { id } ... on Contact"],
+				onType: "Account { id } ... on Contact",
+				directives: [],
+			};
+			session.nodes.push(frag);
+			expect(() => renderQuery(session)).toThrow(
+				/renderInlineFragment: onType .* is not a valid GraphQL Name/,
+			);
+		});
+
+		it("throws when a directive name is a raw, unguarded name", () => {
+			const session = makeSession();
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", "name"]);
+			const node = session.nodes.find(
+				(n): n is FieldProjectionNode => n.kind === "field" && n.fieldName === "name",
+			)!;
+			node.directives.push({ name: "skip } injected @", args: {} });
+			expect(() => renderQuery(session)).toThrow(
+				/renderDirective: directiveName .* is not a valid GraphQL Name/,
+			);
+		});
+
+		it("throws when an operation name is a raw, unguarded name", () => {
+			const session = makeSession();
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", "name"]);
+			session.operationName = "Evil { injected } query X";
+			expect(() => renderQuery(session)).toThrow(
+				/renderQuery: operationName .* is not a valid GraphQL Name/,
+			);
+		});
+
+		it("throws when a variable name is a raw, unguarded name", () => {
+			const session = makeSession();
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", "name"]);
+			// Bypass addVariable's normalization to plant a raw name (the CLI `define`
+			// path only strips a leading `$`, so a hyphenated name reaches the renderer).
+			session.variables.push({ name: "foo-bar", type: "Int" });
+			expect(() => renderQuery(session)).toThrow(
+				/renderQuery: variableName .* is not a valid GraphQL Name/,
+			);
+		});
+
+		it("does not over-block legitimate output: framework fields, aliases, and type conditions parse to one operation", () => {
+			const session = makeSession();
+			// Connection framework fields (edges/node) + a valid alias.
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", "name"]);
+			setAliasOnPath(session, ["accounts", "edges", "node", "name"], "accountName");
+			// Inline-fragment type condition (... on Account). selectLeafInSession
+			// resolves relative to navigationPath, so reset to the query root first.
+			session.navigationPath = ["query"];
+			selectLeafInSession(session, "search.[Account].name");
+
+			const query = renderQuery(session);
+			expect(() => renderQuery(session)).not.toThrow();
+
+			const doc = parse(query);
+			expect(doc.definitions).toHaveLength(1);
+			expect(doc.definitions[0].kind).toBe("OperationDefinition");
+			expect(query).toMatch(/accountName: name/);
+			expect(query).toMatch(/\.\.\. on Account \{/);
+		});
+	});
+
+	// W-23204027 (PR #694 review): argument KEYS are emitted verbatim as
+	// `<key>: <value>` and are NOT validated at the builder or zod layer
+	// (filter/orderBy are z.record(z.unknown()) with no key charset). A hostile
+	// filter key can close the argument object early and inject a sibling
+	// selection — reproduced as a fully parseable, schema-valid second connection
+	// (a silent selection-set injection). The render-layer assert on every
+	// emitted key is the universal choke point that closes it.
+	describe("render-layer argument-key fail-safe (W-23204027 / PR#694)", () => {
+		it("throws on a malicious filter object key emitted via the buildList path (the live sink)", () => {
+			// Mirrors buildList: JSON.stringify(spec.filter) stored as the `where`
+			// arg value, then rendered via jsonToGraphQL -> valueToGraphQL.
+			const session = makeSession();
+			session.navigationPath = ["query", "accounts"];
+			// A clean-breakout key: closes the object + field selection and opens an
+			// attacker-controlled second connection. Without the guard this renders
+			// fully parseable, schema-valid GraphQL.
+			const filter = {
+				'Name: {eq:"x"} }) { edges { node { Id } } } evilAlias: accounts(where: { Industry': {
+					eq: "1",
+				},
+			};
+			deepSetArg(session, ["accounts"], "where", [], JSON.stringify(filter));
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", "name"]);
+			expect(() => renderQuery(session)).toThrow(
+				/valueToGraphQL: argumentKey .* is not a valid GraphQL Name/,
+			);
+		});
+
+		it("throws on a filter key that injects only an extra where-condition", () => {
+			const session = makeSession();
+			session.navigationPath = ["query", "accounts"];
+			const filter = { 'Name: { eq: "hack" }, Industry': { eq: "1" } };
+			deepSetArg(session, ["accounts"], "where", [], JSON.stringify(filter));
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", "name"]);
+			expect(() => renderQuery(session)).toThrow(
+				/valueToGraphQL: argumentKey .* is not a valid GraphQL Name/,
+			);
+		});
+
+		it("throws on a raw, unguarded top-level argument key", () => {
+			const session = makeSession();
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", "name"]);
+			// A top-level arg name is normally a hardcoded builder literal, but
+			// sf_gql_raw's `set <path> @args/<key>` can plant an arbitrary one.
+			const node = session.nodes.find(
+				(n): n is FieldProjectionNode => n.kind === "field" && n.fieldName === "accounts",
+			)!;
+			node.args["first) { edges } evil"] = "1";
+			expect(() => renderQuery(session)).toThrow(
+				/renderField: argumentKey .* is not a valid GraphQL Name/,
+			);
+		});
+
+		it("throws on a raw, unguarded directive argument key", () => {
+			const session = makeSession();
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", "name"]);
+			const node = session.nodes.find(
+				(n): n is FieldProjectionNode => n.kind === "field" && n.fieldName === "name",
+			)!;
+			node.directives.push({ name: "include", args: { "if) evil(x": "true" } });
+			expect(() => renderQuery(session)).toThrow(
+				/renderDirective: argumentKey .* is not a valid GraphQL Name/,
+			);
+		});
+
+		it("does not over-block a realistic complex filter (nested and/or/not, Custom__c fields, enums)", () => {
+			const session = makeSession();
+			session.navigationPath = ["query", "accounts"];
+			// Every key here is a legitimate GraphQL Name: logical operators, field
+			// operators, an SF custom field API name, and connection args.
+			const filter = {
+				and: [
+					{ Name: { like: "Acme%" } },
+					{ Custom_Field__c: { eq: "widget" } },
+					{ or: [{ AnnualRevenue: { gt: 1000 } }, { NumberOfEmployees: { lt: 50 } }] },
+					{ not: { Status: { in: ["Open", "Closed"] } } },
+				],
+			};
+			deepSetArg(session, ["accounts"], "where", [], JSON.stringify(filter));
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", "name"]);
+
+			expect(() => renderQuery(session)).not.toThrow();
+			const query = renderQuery(session);
+			expect(() => parse(query)).not.toThrow();
+			// Custom__c field key and logical operators all survive the guard.
+			expect(query).toMatch(/Custom_Field__c: \{ eq: "widget" \}/);
+			expect(query).toMatch(/and: \[/);
+			expect(query).toMatch(/not: \{ Status:/);
+		});
+	});
+
+	// W-23204027 (PR #694 review): a variable's default VALUE was emitted raw
+	// (`$name: Type = <defaultValue>`) — the last unformatted value position in the
+	// renderer. Raw emission both breaks legitimate output (a multi-word string
+	// default fails to parse) and is a live selection-set/operation injection sink
+	// reachable via sf_gql_raw's `var $x <path> '<default>'`. The default now goes
+	// through formatArgValue. NOTE: the reviewer's literal suggestion (route through
+	// formatArgValue) was necessary but NOT sufficient on its own — formatArgValue's
+	// quoted-string passthrough (`startsWith('"') && endsWith('"')`) let a payload
+	// that merely starts and ends with a quote break out anyway, so that branch was
+	// tightened to pass only a single well-formed literal. The passthrough test
+	// below is the regression guard for that hole.
+	describe("render-layer variable-default fail-safe (W-23204027 / PR#694)", () => {
+		function withDefault(type: string, defaultValue: string): string {
+			const session = makeSession();
+			addVariable(session, "w", type, defaultValue);
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", "name"]);
+			return renderQuery(session);
+		}
+
+		// The security property is structural, not textual: an injection payload may
+		// still appear verbatim *inside a quoted string literal* (that's the point —
+		// it's been neutralized into a scalar value), so a naive substring check would
+		// misfire. Instead, assert the parsed document is exactly one operation whose
+		// only top-level field is the legitimate `accounts` — proving nothing broke
+		// out into the selection set or a second operation.
+		function topLevelFieldNames(query: string): string[] {
+			const doc = parse(query);
+			expect(doc.definitions).toHaveLength(1);
+			const op = doc.definitions[0];
+			if (op.kind !== "OperationDefinition") throw new Error(`not an operation: ${op.kind}`);
+			return op.selectionSet.selections.map((sel) =>
+				sel.kind === "Field" ? (sel.alias?.value ?? sel.name.value) : `<${sel.kind}>`,
+			);
+		}
+
+		it("quotes a legitimate multi-word string default so the query still parses", () => {
+			// Was: `= Acme Corp` -> "Syntax Error: Expected \"$\", found Name \"Corp\"".
+			const query = withDefault("String", "Acme Corp");
+			expect(query).toContain('$w: String = "Acme Corp"');
+			expect(topLevelFieldNames(query)).toEqual(["accounts"]);
+		});
+
+		it("neutralizes an unquoted operation-injection default (no second operation)", () => {
+			// Raw: `= 5) { stolen { Id } } query Decoy($z: Int` -> two operations.
+			// After the fix the payload is confined to one quoted scalar default, so
+			// the document stays a single operation with only the `accounts` field.
+			const query = withDefault("Int", "5) { stolen { Id } } query Decoy($z: Int");
+			expect(topLevelFieldNames(query)).toEqual(["accounts"]);
+		});
+
+		it("neutralizes a QUOTED-passthrough breakout default (the reviewer's fix alone would miss this)", () => {
+			// This payload both starts and ends with `"`, so a bare quoted-string
+			// passthrough would emit it verbatim and render two operations / a sibling
+			// `stolen` field. The tightened passthrough re-encodes it into one safe
+			// literal instead, so `accounts` remains the only top-level field.
+			const query = withDefault("String", '"a") { stolen } query Y($q: String = "b"');
+			expect(topLevelFieldNames(query)).toEqual(["accounts"]);
+		});
+
+		it("does not over-block legitimate scalar/enum defaults", () => {
+			// Numbers, bools, and bare enum tokens must stay unquoted; a real quoted
+			// string literal must pass through untouched.
+			expect(withDefault("Int", "10")).toContain("$w: Int = 10");
+			expect(withDefault("Boolean", "true")).toContain("$w: Boolean = true");
+			expect(withDefault("SortOrder", "DESC")).toContain("$w: SortOrder = DESC");
+			expect(withDefault("String", '"hello world"')).toContain('$w: String = "hello world"');
+			const legit: Record<string, string> = {
+				Int: "10",
+				Boolean: "true",
+				SortOrder: "DESC",
+				String: '"hello world"',
+			};
+			for (const [type, value] of Object.entries(legit)) {
+				expect(() => parse(withDefault(type, value))).not.toThrow();
+			}
+		});
+
+		it("routes an input-object default through the arg-key guard (throws on a hostile key)", () => {
+			// An object default is JSON.stringify'd, so its keys flow through the same
+			// valueToGraphQL arg-key assert — a malicious input-object field name in a
+			// default is closed by the render-layer fail-safe, same as in `where`.
+			const evil: Record<string, unknown> = {};
+			evil["x } ) { stolen } q("] = 1;
+			expect(() => withDefault("AccountFilter", JSON.stringify(evil))).toThrow(
+				/valueToGraphQL: argumentKey .* is not a valid GraphQL Name/,
+			);
+			// ...while a well-formed object default renders fine.
+			const ok = withDefault("AccountFilter", JSON.stringify({ minRevenue: 100 }));
+			expect(ok).toContain("$w: AccountFilter = { minRevenue: 100 }");
+			expect(() => parse(ok)).not.toThrow();
+		});
+
+		// W-23204027 (PR #694 review, Round 3): the tests above only ever fed
+		// *valid* JSON to a `{`/`[` default, so they exercised jsonToGraphQL's
+		// success path. Its `catch` branch — hit when a `{`/`[`-prefixed default is
+		// NOT well-formed JSON — used to `return jsonStr` verbatim, skipping
+		// valueToGraphQL's arg-key guard entirely. That was a live injection sink:
+		// a GraphQL input-object literal like `{ minRevenue: 0 }` has an UNQUOTED
+		// key, so it fails JSON.parse and hit the catch. With a named operation and
+		// a wired-in decoy variable it rendered a fully parse- AND validate-clean
+		// second operation. The fix REJECTS (throws a typed UserInputError) instead
+		// of emitting raw. No legitimate producer reaches this branch — the builders
+		// JSON.stringify their objects (valid JSON), and the CLI set/assign path
+		// JSON-validates `{`/`[` literals before storing.
+		it("throws UserInputError on an invalid-JSON object default (the jsonToGraphQL catch sink)", () => {
+			// Unquoted key ⇒ invalid JSON ⇒ jsonToGraphQL catch. The reviewer's
+			// escalation payload: closes the arg + selection, opens a second op.
+			const payload =
+				"{ minRevenue: 0 }) { edges { node { id } } } } query Decoy($z: AccountFilter";
+			expect(() => withDefault("AccountFilter", payload)).toThrow(UserInputError);
+			expect(() => withDefault("AccountFilter", payload)).toThrow(
+				/is not valid JSON and cannot be rendered as a GraphQL literal/,
+			);
+		});
+
+		it("throws UserInputError on an invalid-JSON array default too", () => {
+			// The `[`-prefixed branch of formatArgValue routes here as well.
+			expect(() => withDefault("AccountFilter", "[1, 2) { stolen } q(")).toThrow(UserInputError);
+		});
+	});
+
+	// W-23204027 (PR #694 review, Round 3): a variable's TYPE is emitted verbatim
+	// as `$name: <type>`. It is NOT a bare Name (it carries `!`/`[]`), so it's
+	// guarded structurally by assertGraphqlType — peel the wrappers, then assert
+	// the innermost NamedType is a valid GraphQL Name. This is a defense-in-depth
+	// backstop: no current builder feeds a raw agent-controlled type (schema
+	// inference / createInputTypeName / hardcoded scalars only; CLI var/define set
+	// the NAME, not the type), but a tampered/migrated on-disk session or a future
+	// builder could. Without the guard, a type like `Int) { evil } query Decoy($z: Int`
+	// breaks out into a second operation with no default value needed.
+	describe("render-layer variable-type fail-safe (W-23204027 / PR#694)", () => {
+		function withRawType(type: string): () => string {
+			const session = makeSession();
+			// Bypass addVariable so the raw type reaches the renderer verbatim.
+			session.variables.push({ name: "v", type });
+			session.navigationPath = ["query", "accounts", "edges", "node"];
+			selectLeaf(session, ["accounts", "edges", "node", "name"]);
+			return () => renderQuery(session);
+		}
+
+		it("throws when the innermost type is a breakout string", () => {
+			expect(withRawType("Int) { evil { id } } query Decoy($z: Int")).toThrow(
+				/renderQuery: variableType .* is not a valid GraphQL Name/,
+			);
+		});
+
+		it("throws when a non-null/list wrapper hides a breakout inner type", () => {
+			// The `!`/`[]` wrappers are peeled; the innermost NamedType is asserted.
+			expect(withRawType("[Int) { evil } q(!]!")).toThrow(
+				/renderQuery: variableType .* is not a valid GraphQL Name/,
+			);
+		});
+
+		it("does not over-block legitimate type references (scalars, non-null, lists, list-of-non-null)", () => {
+			for (const type of ["Int", "ID!", "[String]", "[ID!]!", "AccountFilter", "Custom__c"]) {
+				expect(withRawType(type)).not.toThrow();
+				const query = withRawType(type)();
+				expect(query).toContain(`$v: ${type}`);
+				expect(() => parse(query)).not.toThrow();
+			}
+		});
+	});
 });

package/src/lib/errors.ts

@@ -14,6 +14,119 @@
  * Everything unmatched falls through to `Internal:`.
  */
 
+/**
+ * Retryability disposition for a `Schema:` failure (W-23148365). Surfaced to the
+ * MCP host as a closed-set `[retry=...]` token appended to the error text so an
+ * agent can decide whether to retry, back off, or give up:
+ *  - `"now"`     — retry immediately; the failure involved no live org round-trip
+ *                  (a priming-lock wait timeout), so an instant retry is likely to
+ *                  succeed.
+ *  - `"backoff"` — the introspection request failed transiently (HTTP 5xx/429/420
+ *                  or a network errno) AND the connection layer already exhausted
+ *                  its one built-in retry, so wait with increasing backoff before
+ *                  retrying — some org-side conditions (e.g. an API rate limit) may
+ *                  take longer than a second or two to clear.
+ *  - `"no"`      — permanent: a 4xx, a malformed/absent `__schema`, GraphQL errors
+ *                  in the introspection body, or no cached schema. Don't retry —
+ *                  fix the request, re-authenticate, or (re)prime via `sf_gql_connect`.
+ * `Auth` / `UserInput` / `Internal` errors are uniformly non-retryable and never
+ * carry a token; only `SchemaError` / `SchemaRefreshError` carry `retry`.
+ */
+export type RetryHint = "now" | "backoff" | "no";
+
+// HTTP statuses worth a backoff-then-retry. Mirrors the connection layer's own
+// retry set (introspect.ts INTROSPECTION_REQUEST_OPTIONS): 420 (Salesforce
+// REQUEST_LIMIT_EXCEEDED legacy), 429 (Too Many Requests), 5xx gateway/server.
+const TRANSIENT_STATUS = new Set([420, 429, 500, 502, 503, 504]);
+// Deterministic client/redirect failures: retrying the identical request won't help.
+const PERMANENT_STATUS = new Set([400, 401, 403, 404, 405, 409, 410, 422]);
+// Node network errnos that typically clear on retry (transient org round-trip
+// failures). These are org-reachability problems, so `backoff` correctly tells
+// the agent to wait for the org/network to recover.
+const TRANSIENT_ERRNO = new Set([
+	"ECONNRESET",
+	"ETIMEDOUT",
+	"EAI_AGAIN",
+	"ECONNREFUSED",
+	"EPIPE",
+	"ESOCKETTIMEDOUT",
+]);
+// Errnos that won't clear on a short retry: a wrong host (ENOTFOUND — deliberately
+// treated as permanent since a typo'd instance URL is the common case, not a DNS
+// hiccup), a missing path, or a permissions/read-only-fs failure — PLUS local
+// resource-exhaustion errnos raised by the cache write (`atomicWriteJson`), which
+// shares the download `try`: ENOSPC (disk full), EMFILE (fd exhaustion), and EAGAIN.
+// These are host-side ops problems, not org round-trips, so a `backoff` hint would
+// both mislead the agent ("the org was unreachable") and mask the real failure;
+// classify them `no` so the operator sees the raw error instead of burned retries.
+const PERMANENT_ERRNO = new Set([
+	"ENOTFOUND",
+	"ENOENT",
+	"EACCES",
+	"EROFS",
+	"ENOSPC",
+	"EMFILE",
+	"EAGAIN",
+]);
+
+/**
+ * Classify the underlying cause of a Schema failure into a {@link RetryHint}.
+ *
+ * Defensive by construction: inspects an untyped `cause` (the jsforce /
+ * `@salesforce/core` error that bubbled up from `connection.request`, or a Node
+ * `ErrnoException` from a cache write) without assuming a type. Reads three shapes,
+ * in order: a numeric HTTP `statusCode`, a parsed `errorCode` / `name` (e.g.
+ * `ERROR_HTTP_503`, `REQUEST_LIMIT_EXCEEDED`), then the network/IO `code` errno.
+ * For a real jsforce HTTP failure the `ERROR_HTTP_<nnn>` regex on `errorCode`/`name`
+ * is the load-bearing path — jsforce-node's `HttpApiError` sets string `name`/
+ * `errorCode` but NOT a numeric `.statusCode`, so the first branch is a defensive
+ * fallback for other cause shapes (and the contract tests' `statusCode`-bearing
+ * doubles), not the production trigger. Anything unrecognized returns `"no"` — we
+ * never INVENT retryability, and the connection layer has already spent its one
+ * transient retry before the error reaches us, so an unknown failure that survived
+ * that retry is treated as permanent.
+ *
+ * Every property read is wrapped so a `cause` with a throwing accessor cannot
+ * escape (this runs inside `runTool`'s catch, where an escaped throw would drop
+ * the sanitized `<Category>: <message>` envelope and leak a raw SDK error). Real
+ * causes (jsforce/`@salesforce/core`/`fs` errors) carry plain-data fields, so this
+ * is a defensive backstop, not a live path; a throw simply falls back to `"no"`.
+ */
+export function classifyCause(cause: unknown): RetryHint {
+	if (typeof cause !== "object" || cause === null) return "no";
+	const c = cause as Record<string, unknown>;
+
+	try {
+		const status = typeof c.statusCode === "number" ? c.statusCode : undefined;
+		if (status !== undefined) {
+			if (TRANSIENT_STATUS.has(status)) return "backoff";
+			if (PERMANENT_STATUS.has(status)) return "no";
+		}
+
+		const codeStr = typeof c.errorCode === "string" ? c.errorCode : "";
+		const nameStr = typeof c.name === "string" ? c.name : "";
+		const httpMatch = /ERROR_HTTP_(\d{3})/.exec(`${codeStr} ${nameStr}`);
+		if (httpMatch) {
+			const httpStatus = Number(httpMatch[1]);
+			if (TRANSIENT_STATUS.has(httpStatus)) return "backoff";
+			if (PERMANENT_STATUS.has(httpStatus)) return "no";
+		}
+		if (codeStr === "REQUEST_LIMIT_EXCEEDED" || nameStr === "REQUEST_LIMIT_EXCEEDED") {
+			return "backoff";
+		}
+
+		// Network/IO errno (`code` is the errno string for a NodeJS.ErrnoException).
+		const errno = typeof c.code === "string" ? c.code : "";
+		if (TRANSIENT_ERRNO.has(errno)) return "backoff";
+		if (PERMANENT_ERRNO.has(errno)) return "no";
+	} catch {
+		// A throwing getter on the cause → treat as unclassifiable (permanent).
+		return "no";
+	}
+
+	return "no";
+}
+
 /** Credential/auth resolution failure (e.g. unknown org, expired token). → `Auth:` */
 export class AuthError extends Error {
 	constructor(message: string, opts?: { cause?: unknown }) {
@@ -36,10 +149,20 @@ export class UserInputError extends Error {
 	}
 }
 
-/** Schema introspection / priming / build failure. → `Schema:` */
+/**
+ * Schema introspection / priming / build failure. → `Schema:`
+ *
+ * Carries a {@link RetryHint} (`retry`, default `"no"`) stamped at the throw site
+ * from the underlying cause (W-23148365). The MCP adapter reads this field to
+ * append the `[retry=...]` token; throw sites that know the disposition (a
+ * permanent missing-`__schema`, a transient lock timeout) set it explicitly,
+ * and the lazy-prime wrap derives it via {@link classifyCause}.
+ */
 export class SchemaError extends Error {
-	constructor(message: string, opts?: { cause?: unknown }) {
+	readonly retry: RetryHint;
+	constructor(message: string, opts?: { cause?: unknown; retry?: RetryHint }) {
 		super(message, opts?.cause !== undefined ? { cause: opts.cause } : undefined);
 		this.name = "SchemaError";
+		this.retry = opts?.retry ?? "no";
 	}
 }

package/src/lib/introspect.ts

@@ -278,12 +278,17 @@ export async function downloadSchema(auth: OrgAuth): Promise<SchemaMetadata> {
 		const messages = (rawResult.errors as any[])
 			.map((e: any) => e.message ?? JSON.stringify(e))
 			.join("\n  ");
-		throw new SchemaError(`Introspection query returned errors:\n  ${messages}`);
+		// GraphQL errors in a 200 body are deterministic — retrying the identical
+		// query won't help (W-23148365).
+		throw new SchemaError(`Introspection query returned errors:\n  ${messages}`, { retry: "no" });
 	}
 
 	const rawSchema = rawResult?.data?.__schema ?? rawResult?.__schema;
 	if (!rawSchema) {
-		throw new SchemaError("Introspection query did not return a __schema field");
+		// A well-formed 200 with no __schema is a permanent shape problem.
+		throw new SchemaError("Introspection query did not return a __schema field", {
+			retry: "no",
+		});
 	}
 
 	const { result, removedCount } = stripDataCloudTypes(rawResult);
@@ -318,8 +323,11 @@ export async function downloadSchema(auth: OrgAuth): Promise<SchemaMetadata> {
 export function loadIntrospectionResult(instanceUrl: string): any {
 	const fp = schemaPathForInstanceUrl(normalizeInstanceUrl(instanceUrl));
 	if (!fs.existsSync(fp)) {
+		// Retrying this read won't help — the org was never primed. The fix is to
+		// prime (a different action), so this is permanent (W-23148365).
 		throw new SchemaError(
 			`No cached schema for "${instanceUrl}". Run \`graphiti connect <org>\` first.`,
+			{ retry: "no" },
 		);
 	}
 	return JSON.parse(fs.readFileSync(fp, "utf-8"));

package/src/lib/prime-schema.ts

@@ -7,7 +7,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { getOrgAuth as realGetOrgAuth, type OrgAuth } from "./auth.js";
-import { SchemaError } from "./errors.js";
+import { classifyCause, type RetryHint, SchemaError } from "./errors.js";
 import {
 	downloadSchema as realDownloadSchema,
 	getSchemaMetadata,
@@ -96,8 +96,13 @@ export async function withSchemaLock<T>(
 			}
 
 			if (Date.now() - startedWaitingAt > MAX_WAIT_MS) {
+				// Pure filesystem contention — another holder was downloading; an
+				// immediate retry likely finds a fresh cache. No live org round-trip
+				// occurred, so retry=now (W-23148365). Not covered by the connection
+				// layer's built-in retry, so the host's retry is the only one left.
 				throw new SchemaError(
 					`Timed out waiting ${MAX_WAIT_MS}ms for schema priming lock at ${lockPath}`,
+					{ retry: "now" },
 				);
 			}
 			await new Promise((r) => setTimeout(r, POLL_MS));
@@ -157,18 +162,27 @@ export interface PrimeResult {
  * returns null for a corrupt file, which correctly degrades to a hard failure
  * (a corrupt cache is not usable). `instanceUrl` is always the resolved org URL
  * (known before the download).
+ *
+ * Carries a {@link RetryHint} (`retry`, default `"no"`) for the MCP error surface
+ * (W-23148365), derived from the underlying cause via {@link classifyCause}. Note
+ * the surviving-cache case never reaches the MCP token surface: `buildConnect`
+ * intercepts a `SchemaRefreshError` with a defined `staleSince` (i.e. a cache
+ * survived) and returns a soft `warnings[]` success before `runTool` can stamp a
+ * token — so `retry` is only ever observed for the no-surviving-cache hard failure.
  */
 export class SchemaRefreshError extends Error {
 	staleSince?: string;
 	instanceUrl: string;
+	readonly retry: RetryHint;
 	constructor(
 		message: string,
-		opts: { instanceUrl: string; staleSince?: string; cause?: unknown },
+		opts: { instanceUrl: string; staleSince?: string; cause?: unknown; retry?: RetryHint },
 	) {
 		super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined);
 		this.name = "SchemaRefreshError";
 		this.staleSince = opts.staleSince;
 		this.instanceUrl = opts.instanceUrl;
+		this.retry = opts.retry ?? "no";
 	}
 }
 
@@ -286,20 +300,34 @@ export async function primeSchemaWithLock(
 				// the underlying failure (FR-13.5/13.6). Wrap untyped causes (e.g. a
 				// raw @salesforce/core/jsforce network error from connection.request)
 				// in SchemaError so the MCP boundary classifies priming failures as
-				// `Schema:`; a cause that is already SchemaError passes through.
+				// `Schema:`; a cause that is already SchemaError passes through. The
+				// retry hint is derived from the cause (W-23148365): a 5xx/network
+				// failure that outlived the connection layer's one retry → backoff;
+				// a 4xx / unrecognized failure → no (permanent).
 				if (!forceRefresh) {
 					if (cause instanceof SchemaError) throw cause;
 					const msg = cause instanceof Error ? cause.message : String(cause);
-					throw new SchemaError(`Schema priming failed for "${orgAlias}": ${msg}`, { cause });
+					throw new SchemaError(`Schema priming failed for "${orgAlias}": ${msg}`, {
+						cause,
+						retry: classifyCause(cause),
+					});
 				}
 				// Forced refresh: atomic writes mean the old JSON is still on
 				// disk, so surface a staleness-aware error and leave every cache
 				// untouched.
 				const surviving = getSchemaMetadata(instanceUrl);
+				// The `retry` disposition is the raw cause disposition. When a cache
+				// survives, `buildConnect` intercepts this error (it keys on a defined
+				// `staleSince`) and returns a soft `warnings[]` success *before* the MCP
+				// adapter stamps a token — so `retry` is only ever surfaced on the
+				// no-surviving-cache hard failure, where the cause disposition is exactly
+				// what the host should act on. (Do not reintroduce a `surviving`-floored
+				// "now": it would be dead code on the MCP surface and no consumer reads it.)
 				throw new SchemaRefreshError(buildStaleMessage(orgAlias, surviving), {
 					staleSince: surviving?.downloadedAt,
 					instanceUrl,
 					cause,
+					retry: classifyCause(cause),
 				});
 			}
 			typeCount = meta.typeCount;