@skyramp/mcp 0.3.3 → 0.3.4

package/build/utils/utils.d.ts

@@ -1,6 +1,51 @@
 import { CallToolResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
 export declare function readDiffFile(diffFilePath: string | undefined): string | undefined;
 export declare function toolError(message: string): CallToolResult;
+/**
+ * Build a successful tool result whose payload is delivered on BOTH MCP result
+ * channels — `structuredContent` and `content[]` — carrying the identical text.
+ * The counterpart to `toolError` for any tool that returns a large text payload.
+ *
+ * Use this for every non-error return of such a tool, and declare a matching
+ * `outputSchema`. Two separate failures make that necessary:
+ *
+ * 1. A result with no `structuredContent` is persisted by the agent harness as a
+ *    pretty-printed `.json` spill, which buries the payload inside an escaped
+ *    JSON string. Coming through `structuredContent` instead lands it as a
+ *    `.txt`. Measured on eval runs 32227152533 and 32283973875: the extension
+ *    follows the result shape, with no exceptions either way.
+ *
+ *    The extension is not cosmetic: it changes how the payload TOKENIZES. The
+ *    reader refuses any spill over 25,000 tokens, and pretty-printed JSON with
+ *    escaped quotes and newlines costs 2-3x the tokens of the same bytes in raw
+ *    form. Measured on one payload either way: 141.2KB of `.json` counted 72,318
+ *    tokens and was refused, while the same result at 142.0KB of `.txt` was read
+ *    back in full. A second: 54,085 tokens as `.json`, 26,950 as `.txt`.
+ *
+ *    So the shape raises the deliverable size ceiling by roughly 3x, but does not
+ *    remove it. That second payload still missed the cap by 1,950 tokens, and
+ *    `skyramp_actions` results of 178-621KB are 45,598-158,997 tokens even as
+ *    `.txt` — the agent then falls back to slicing the file with `head -c`. The
+ *    check covers the whole file, so a `limit:` on the read cannot evade it.
+ *    Payloads that big have to shrink (SKYR-4188 and its sibling); this shape is
+ *    what lets a shrunk payload actually arrive.
+ *
+ * 2. Each agent CLI testbot supports reads a different channel and none falls
+ *    back to the other: Claude Code takes `structuredContent` and drops
+ *    `content[]`; Cursor takes `content[]` and ignores `structuredContent`;
+ *    GitHub Copilot CLI surfaces both and de-duplicates them only when the text
+ *    is the literal JSON serialization of `structuredContent` (MCP spec 5.2.6),
+ *    otherwise it concatenates. Hence `JSON.stringify` rather than the raw text,
+ *    which would deliver the payload twice there. Trimming either channel
+ *    silently starves a client.
+ *
+ * Declaring the outputSchema also obliges every non-error return to come through
+ * here: the SDK rejects a successful result without `structuredContent`
+ * ("has an output schema but no structured content was provided"). Error results
+ * are exempt — that check returns early on `isError` — so they keep using
+ * `toolError`.
+ */
+export declare function dualChannelResult(structuredContent: Record<string, string>): CallToolResult;
 /**
  * Does `candidate` (an LLM- or caller-supplied name/path) identify `fullPath` (a known,
  * absolute test file path)? Exact match first, then a real path-segment boundary match

package/build/utils/utils.js

@@ -18,6 +18,56 @@ export function toolError(message) {
         isError: true,
     };
 }
+/**
+ * Build a successful tool result whose payload is delivered on BOTH MCP result
+ * channels — `structuredContent` and `content[]` — carrying the identical text.
+ * The counterpart to `toolError` for any tool that returns a large text payload.
+ *
+ * Use this for every non-error return of such a tool, and declare a matching
+ * `outputSchema`. Two separate failures make that necessary:
+ *
+ * 1. A result with no `structuredContent` is persisted by the agent harness as a
+ *    pretty-printed `.json` spill, which buries the payload inside an escaped
+ *    JSON string. Coming through `structuredContent` instead lands it as a
+ *    `.txt`. Measured on eval runs 32227152533 and 32283973875: the extension
+ *    follows the result shape, with no exceptions either way.
+ *
+ *    The extension is not cosmetic: it changes how the payload TOKENIZES. The
+ *    reader refuses any spill over 25,000 tokens, and pretty-printed JSON with
+ *    escaped quotes and newlines costs 2-3x the tokens of the same bytes in raw
+ *    form. Measured on one payload either way: 141.2KB of `.json` counted 72,318
+ *    tokens and was refused, while the same result at 142.0KB of `.txt` was read
+ *    back in full. A second: 54,085 tokens as `.json`, 26,950 as `.txt`.
+ *
+ *    So the shape raises the deliverable size ceiling by roughly 3x, but does not
+ *    remove it. That second payload still missed the cap by 1,950 tokens, and
+ *    `skyramp_actions` results of 178-621KB are 45,598-158,997 tokens even as
+ *    `.txt` — the agent then falls back to slicing the file with `head -c`. The
+ *    check covers the whole file, so a `limit:` on the read cannot evade it.
+ *    Payloads that big have to shrink (SKYR-4188 and its sibling); this shape is
+ *    what lets a shrunk payload actually arrive.
+ *
+ * 2. Each agent CLI testbot supports reads a different channel and none falls
+ *    back to the other: Claude Code takes `structuredContent` and drops
+ *    `content[]`; Cursor takes `content[]` and ignores `structuredContent`;
+ *    GitHub Copilot CLI surfaces both and de-duplicates them only when the text
+ *    is the literal JSON serialization of `structuredContent` (MCP spec 5.2.6),
+ *    otherwise it concatenates. Hence `JSON.stringify` rather than the raw text,
+ *    which would deliver the payload twice there. Trimming either channel
+ *    silently starves a client.
+ *
+ * Declaring the outputSchema also obliges every non-error return to come through
+ * here: the SDK rejects a successful result without `structuredContent`
+ * ("has an output schema but no structured content was provided"). Error results
+ * are exempt — that check returns early on `isError` — so they keep using
+ * `toolError`.
+ */
+export function dualChannelResult(structuredContent) {
+    return {
+        structuredContent,
+        content: [{ type: "text", text: JSON.stringify(structuredContent) }],
+    };
+}
 /**
  * Does `candidate` (an LLM- or caller-supplied name/path) identify `fullPath` (a known,
  * absolute test file path)? Exact match first, then a real path-segment boundary match

package/build/utils/versions.d.ts

@@ -1,4 +1,4 @@
-export declare const SKYRAMP_IMAGE_VERSION = "v1.3.38";
-export declare const EXECUTOR_DOCKER_IMAGE = "skyramp/executor:v1.3.38";
-export declare const WORKER_DOCKER_IMAGE = "skyramp/worker:v1.3.38";
+export declare const SKYRAMP_IMAGE_VERSION = "v1.3.40";
+export declare const EXECUTOR_DOCKER_IMAGE = "skyramp/executor:v1.3.40";
+export declare const WORKER_DOCKER_IMAGE = "skyramp/worker:v1.3.40";
 export declare const WORKER_CONTROL_PORT = 35142;

package/build/utils/versions.js

@@ -1,4 +1,4 @@
-export const SKYRAMP_IMAGE_VERSION = "v1.3.38";
+export const SKYRAMP_IMAGE_VERSION = "v1.3.40";
 export const EXECUTOR_DOCKER_IMAGE = `skyramp/executor:${SKYRAMP_IMAGE_VERSION}`;
 export const WORKER_DOCKER_IMAGE = `skyramp/worker:${SKYRAMP_IMAGE_VERSION}`;
 // Control port the Skyramp worker listens on (SDK `CONTAINER_PORT`).

package/build/utils/workspaceAuth.d.ts

@@ -1,3 +1,4 @@
+import { type ScopedQueryParams } from "../workspace/queryParamResolution.js";
 /**
  * Reads `.skyramp/workspace.yml`.
  *
@@ -133,20 +134,6 @@ export declare function getWorkspaceAuthConfig(repositoryPath: string): Promise<
 /** True when any workspace service declares api.skipTLSVerify — the SUT serves
  *  self-signed TLS and generated tests must skip cert verification (SKYR-3961). */
 export declare function getWorkspaceSkipTLSVerify(repositoryPath: string): Promise<boolean>;
-/**
- * Resolve api.defaultQueryParams for test generation — query params always
- * attached to every generated request for this service (e.g. RBAC context
- * an authorization layer requires beyond the auth header). Same
- * first-matching-service convention as getWorkspaceAuthConfig (SKYR-4050).
- *
- * Unlike readWorkspaceConfigRaw (which delegates to WorkspaceConfigManager and
- * resolves EXACTLY `<repositoryPath>/.skyramp/workspace.yml`), this walks up
- * from `repositoryPath` to find the nearest `.skyramp/workspace.yml` — both
- * call sites pass a nested test-output directory (e.g. `<repo>/tests/skyramp`),
- * not the repo root, so an exact-match lookup would silently never find the
- * config. Mirrors the sync fs.existsSync walk-up in
- * generateBatchScenarioRestTool.ts.
- */
 /**
  * Walk up from `startDir` to find the nearest `.skyramp/workspace.yml`, checking
  * `startDir` itself first and continuing through every ancestor INCLUDING the
@@ -156,7 +143,20 @@ export declare function getWorkspaceSkipTLSVerify(repositoryPath: string): Promi
  * `existsSync` is injectable for testing; defaults to the real filesystem.
  */
 export declare function findWorkspaceConfigPath(startDir: string, existsSync?: (p: string) => boolean): string | null;
-export declare function getWorkspaceDefaultQueryParams(repositoryPath: string): Promise<Record<string, string> | undefined>;
+/**
+ * Resolve api.defaultQueryParams together with api.queryParamOverrides for test
+ * generation (SKYR-4127). Same first-matching-service convention as
+ * getWorkspaceAuthConfig: the first service declaring EITHER key wins.
+ *
+ * Reads the YAML directly rather than through the Zod schema — the walk-up must
+ * stay cheap, and hand-rolled fixtures routinely omit fields the strict schema
+ * requires. normalizeOverrides therefore validates the override list itself,
+ * once per load rather than per request.
+ *
+ * Returns undefined when no config is found or no service declares either key,
+ * so callers can skip the merge entirely.
+ */
+export declare function getWorkspaceScopedQueryParams(repositoryPath: string): Promise<ScopedQueryParams | undefined>;
 /**
  * Merge workspace-declared default query params into a comma-separated
  * "key=value,key2=value2" queryParams string (the format used by

package/build/utils/workspaceAuth.js

@@ -2,6 +2,7 @@ import * as fs from "fs";
 import path from "path";
 import yaml from "js-yaml";
 import { WorkspaceConfigManager } from "../workspace/workspace.js";
+import { normalizeBaseMap, normalizeOverrides } from "../workspace/queryParamResolution.js";
 import { logger } from "./logger.js";
 /**
  * Reads `.skyramp/workspace.yml`.
@@ -363,20 +364,6 @@ export async function getWorkspaceSkipTLSVerify(repositoryPath) {
         return false;
     return (rawConfig.services ?? []).some((s) => s.api?.skipTLSVerify === true);
 }
-/**
- * Resolve api.defaultQueryParams for test generation — query params always
- * attached to every generated request for this service (e.g. RBAC context
- * an authorization layer requires beyond the auth header). Same
- * first-matching-service convention as getWorkspaceAuthConfig (SKYR-4050).
- *
- * Unlike readWorkspaceConfigRaw (which delegates to WorkspaceConfigManager and
- * resolves EXACTLY `<repositoryPath>/.skyramp/workspace.yml`), this walks up
- * from `repositoryPath` to find the nearest `.skyramp/workspace.yml` — both
- * call sites pass a nested test-output directory (e.g. `<repo>/tests/skyramp`),
- * not the repo root, so an exact-match lookup would silently never find the
- * config. Mirrors the sync fs.existsSync walk-up in
- * generateBatchScenarioRestTool.ts.
- */
 /**
  * Walk up from `startDir` to find the nearest `.skyramp/workspace.yml`, checking
  * `startDir` itself first and continuing through every ancestor INCLUDING the
@@ -398,15 +385,43 @@ export function findWorkspaceConfigPath(startDir, existsSync = fs.existsSync) {
         searchDir = parentDir;
     }
 }
-export async function getWorkspaceDefaultQueryParams(repositoryPath) {
+/**
+ * Resolve api.defaultQueryParams together with api.queryParamOverrides for test
+ * generation (SKYR-4127). Same first-matching-service convention as
+ * getWorkspaceAuthConfig: the first service declaring EITHER key wins.
+ *
+ * Reads the YAML directly rather than through the Zod schema — the walk-up must
+ * stay cheap, and hand-rolled fixtures routinely omit fields the strict schema
+ * requires. normalizeOverrides therefore validates the override list itself,
+ * once per load rather than per request.
+ *
+ * Returns undefined when no config is found or no service declares either key,
+ * so callers can skip the merge entirely.
+ */
+export async function getWorkspaceScopedQueryParams(repositoryPath) {
     const wsConfigPath = findWorkspaceConfigPath(repositoryPath);
     if (!wsConfigPath)
         return undefined;
     try {
         const raw = fs.readFileSync(wsConfigPath, "utf-8");
         const parsed = yaml.load(raw);
-        const svc = parsed?.services?.find((s) => s.api?.defaultQueryParams !== undefined);
-        return svc?.api?.defaultQueryParams;
+        const declaring = (parsed?.services ?? []).filter((s) => s?.api?.defaultQueryParams !== undefined || s?.api?.queryParamOverrides !== undefined);
+        const svc = declaring[0];
+        if (!svc)
+            return undefined;
+        // First-wins is deliberate (same convention as getWorkspaceAuthConfig) —
+        // but silently discarding a later service's config is easy to miss, so
+        // name what's being ignored (Finding 3, SKYR-4127 final review).
+        if (declaring.length > 1) {
+            logger.warning("Multiple services declare defaultQueryParams/queryParamOverrides — using the first, ignoring the rest", {
+                used: svc.serviceName,
+                ignored: declaring.slice(1).map((s) => s.serviceName),
+            });
+        }
+        return {
+            base: normalizeBaseMap(svc.api.defaultQueryParams),
+            overrides: normalizeOverrides(svc.api.queryParamOverrides),
+        };
     }
     catch {
         return undefined;

package/build/workspace/queryParamResolution.d.ts

@@ -0,0 +1,93 @@
+export interface QueryParamOverride {
+    /** picomatch glob matched against the request URL pathname. OpenAPI-style
+     *  `{param}` placeholders are treated as a single-segment wildcard. */
+    pathPattern: string;
+    /**
+     * Known wart (Finding 6, SKYR-4127 final review): `values: {}` is a valid,
+     * deliberately-typed empty map. If its pathPattern is the single most
+     * specific match for a request, it wins and contributes nothing — silently
+     * suppressing a broader override that would otherwise have applied. Not
+     * validated against because an intentionally no-op override (e.g. "no
+     * extra params for this path, unlike its siblings") is a legitimate use.
+     */
+    values: Record<string, string>;
+}
+export interface ScopedQueryParams {
+    /** api.defaultQueryParams — applied to every request for the service. */
+    base: Record<string, string>;
+    /** api.queryParamOverrides — at most one applies to any given request. */
+    overrides: QueryParamOverride[];
+}
+/** Pathname of a full endpoint URL, or undefined if unparseable.
+ *  `endpointURL` is contractually base URL + path, so the result includes any
+ *  base-path prefix: `https://host/api/v1/persons/42` -> `/api/v1/persons/42`.
+ *
+ *  Delegates to the shared helper so this module and the plan guard cannot
+ *  disagree about what an endpointURL's path is — the shared version also
+ *  restores `{param}` placeholders that `new URL()` percent-encodes, which
+ *  patterns are authored with. */
+export declare function extractPathname(endpointURL: string | undefined): string | undefined;
+/** True when a resolved config would contribute no query params at all.
+ *  Both call sites skip the merge entirely in that case, so an empty
+ *  declaration leaves queryParams untouched rather than setting it to an empty
+ *  value. Defined once so the two sites cannot drift on what "empty" means. */
+export declare function contributesNothing(config: ScopedQueryParams): boolean;
+/** Batch-scenario steps carry a bare path that may or may not be rooted. */
+export declare function ensureLeadingSlash(p: string): string;
+/** Rank for most-specific-wins: length of the literal prefix before the first
+ *  wildcard, computed on the ORIGINAL pattern so `{id}` still counts. */
+export declare function patternSpecificity(pathPattern: string): number;
+/**
+ * Validate and coerce the raw `api.queryParamOverrides` value read from YAML.
+ *
+ * The read path in workspaceAuth.ts parses workspace.yml directly rather than
+ * through the Zod schema (the walk-up read must stay cheap), so nothing has
+ * validated this yet. Malformed entries are dropped with a warning instead of
+ * failing generation. Called once per load, not per request.
+ */
+export declare function normalizeOverrides(raw: unknown): QueryParamOverride[];
+/**
+ * Validate and coerce the raw `api.defaultQueryParams` value read from YAML.
+ *
+ * Same reason `normalizeOverrides` exists: this read path deliberately bypasses
+ * the Zod schema, so nothing has checked the shape. Without this, a scalar
+ * declaration (`defaultQueryParams: just-a-string`) is spread by key and yields
+ * one query param per character — `0=j&1=u&2=s&…` sent to the server. A list
+ * behaves the same way, and a map with non-string values would reach
+ * mergeQueryParams* and be dropped there with a less specific warning.
+ *
+ * Anything that is not a plain object of string values degrades to an empty
+ * base map with a warning naming what was found.
+ */
+export declare function normalizeBaseMap(raw: unknown): Record<string, string>;
+/**
+ * Effective query params for one request path: the base map with the single
+ * most-specific matching override layered on top.
+ *
+ * Overrides never merge with each other — at most one wins. Ranking is by
+ * literal prefix length, then total pattern length, then document order.
+ *
+ * Whenever the patterns differ in specificity the result is independent of how
+ * the YAML list is ordered. Document order is only reached when two patterns
+ * tie on BOTH earlier criteria, and reordering the list does change the winner
+ * in that case — which is why a tie emits an ambiguity warning naming both
+ * patterns rather than resolving silently.
+ */
+export declare function resolveQueryParamsForPath(config: ScopedQueryParams, pathname: string): Record<string, string>;
+/** Environment variables this workspace's query params defer to, in declaration
+ *  order and deduplicated (SKYR-4127).
+ *
+ *  These references resolve where the test RUNS, so under Testbot they resolve
+ *  inside the executor container — whose environment is a fixed allowlist. A
+ *  name that never reaches the container resolves to nothing, and an unresolved
+ *  query param is dropped from the request silently, producing a passing test
+ *  that exercised the wrong identity. The executor uses this list to forward
+ *  exactly what the workspace asked for.
+ *
+ *  Deliberately derived from the declarations rather than from the ambient
+ *  environment: nothing is forwarded that workspace.yml did not name.
+ *
+ *  Both maps are read even though `defaultQueryParams` documents itself as
+ *  literal-only — that is a doc contract the core loader does not enforce, and
+ *  a declaration there would otherwise reproduce the original silent failure. */
+export declare function extractEnvVarNames(config: ScopedQueryParams): string[];

package/build/workspace/queryParamResolution.js

@@ -0,0 +1,201 @@
+/**
+ * Path-scoped resolution for workspace-declared query params (SKYR-4127).
+ *
+ * SKYR-4050 shipped a single flat `api.defaultQueryParams` map applied
+ * identically to every generated request. That is too coarse for APIs whose
+ * authorization context is per-endpoint (e.g. an RBAC role validated against a
+ * different allow-list per path). `api.queryParamOverrides` layers path-scoped
+ * values on top of that base map.
+ *
+ * Deliberately free of filesystem access so it unit-tests directly — reading
+ * workspace.yml lives in utils/workspaceAuth.ts.
+ */
+import picomatch from "picomatch";
+import { logger } from "../utils/logger.js";
+import { pathFromEndpointURL } from "../utils/urlPath.js";
+/** Characters that terminate a pattern's literal prefix.
+ *
+ *  `{` counts because an OpenAPI-style `{id}` placeholder becomes `*` before
+ *  matching. `[` and `(` count because picomatch also treats character classes
+ *  (`[0-9]`) and extglobs (`+(a|b)`) as wildcards — without them a pattern like
+ *  `/v1/users/[0-9]*` would be ranked as though `[` were literal, scoring it
+ *  more specific than it is and letting it beat a genuinely narrower pattern. */
+const WILDCARD_CHARS = ["*", "?", "{", "[", "("];
+/** Pathname of a full endpoint URL, or undefined if unparseable.
+ *  `endpointURL` is contractually base URL + path, so the result includes any
+ *  base-path prefix: `https://host/api/v1/persons/42` -> `/api/v1/persons/42`.
+ *
+ *  Delegates to the shared helper so this module and the plan guard cannot
+ *  disagree about what an endpointURL's path is — the shared version also
+ *  restores `{param}` placeholders that `new URL()` percent-encodes, which
+ *  patterns are authored with. */
+export function extractPathname(endpointURL) {
+    return pathFromEndpointURL(endpointURL);
+}
+/** True when a resolved config would contribute no query params at all.
+ *  Both call sites skip the merge entirely in that case, so an empty
+ *  declaration leaves queryParams untouched rather than setting it to an empty
+ *  value. Defined once so the two sites cannot drift on what "empty" means. */
+export function contributesNothing(config) {
+    return Object.keys(config.base).length === 0 && config.overrides.length === 0;
+}
+/** Batch-scenario steps carry a bare path that may or may not be rooted. */
+export function ensureLeadingSlash(p) {
+    return p.startsWith("/") ? p : `/${p}`;
+}
+/** Rank for most-specific-wins: length of the literal prefix before the first
+ *  wildcard, computed on the ORIGINAL pattern so `{id}` still counts. */
+export function patternSpecificity(pathPattern) {
+    let earliest = pathPattern.length;
+    for (const ch of WILDCARD_CHARS) {
+        const idx = pathPattern.indexOf(ch);
+        if (idx !== -1 && idx < earliest)
+            earliest = idx;
+    }
+    return earliest;
+}
+/** Rewrite OpenAPI-style `{param}` placeholders to a single-segment wildcard.
+ *  Without this, picomatch reads `{id}` as brace alternation and matches only
+ *  the literal string `/v1/persons/id`. Brace alternation is therefore not
+ *  supported in patterns — an accepted trade. */
+function toGlob(pathPattern) {
+    return pathPattern.replace(/\{[^/}]*\}/g, "*");
+}
+function isStringMap(v) {
+    if (!v || typeof v !== "object" || Array.isArray(v))
+        return false;
+    return Object.values(v).every((x) => typeof x === "string");
+}
+/**
+ * Validate and coerce the raw `api.queryParamOverrides` value read from YAML.
+ *
+ * The read path in workspaceAuth.ts parses workspace.yml directly rather than
+ * through the Zod schema (the walk-up read must stay cheap), so nothing has
+ * validated this yet. Malformed entries are dropped with a warning instead of
+ * failing generation. Called once per load, not per request.
+ */
+export function normalizeOverrides(raw) {
+    if (!Array.isArray(raw)) {
+        if (raw !== undefined) {
+            logger.warning("Ignoring api.queryParamOverrides — expected a list", { got: typeof raw });
+        }
+        return [];
+    }
+    const result = [];
+    for (const entry of raw) {
+        const e = entry;
+        if (!e || typeof e !== "object" || typeof e.pathPattern !== "string" || e.pathPattern.length === 0) {
+            logger.warning("Skipping api.queryParamOverrides entry with a missing or empty pathPattern");
+            continue;
+        }
+        if (!isStringMap(e.values)) {
+            logger.warning("Skipping api.queryParamOverrides entry whose values are not a string map", {
+                pathPattern: e.pathPattern,
+            });
+            continue;
+        }
+        result.push({ pathPattern: e.pathPattern, values: e.values });
+    }
+    return result;
+}
+/**
+ * Validate and coerce the raw `api.defaultQueryParams` value read from YAML.
+ *
+ * Same reason `normalizeOverrides` exists: this read path deliberately bypasses
+ * the Zod schema, so nothing has checked the shape. Without this, a scalar
+ * declaration (`defaultQueryParams: just-a-string`) is spread by key and yields
+ * one query param per character — `0=j&1=u&2=s&…` sent to the server. A list
+ * behaves the same way, and a map with non-string values would reach
+ * mergeQueryParams* and be dropped there with a less specific warning.
+ *
+ * Anything that is not a plain object of string values degrades to an empty
+ * base map with a warning naming what was found.
+ */
+export function normalizeBaseMap(raw) {
+    if (raw === undefined || raw === null)
+        return {};
+    if (isStringMap(raw))
+        return raw;
+    logger.warning("Ignoring api.defaultQueryParams — expected a map of string values", { got: Array.isArray(raw) ? "array" : typeof raw });
+    return {};
+}
+/**
+ * Effective query params for one request path: the base map with the single
+ * most-specific matching override layered on top.
+ *
+ * Overrides never merge with each other — at most one wins. Ranking is by
+ * literal prefix length, then total pattern length, then document order.
+ *
+ * Whenever the patterns differ in specificity the result is independent of how
+ * the YAML list is ordered. Document order is only reached when two patterns
+ * tie on BOTH earlier criteria, and reordering the list does change the winner
+ * in that case — which is why a tie emits an ambiguity warning naming both
+ * patterns rather than resolving silently.
+ */
+export function resolveQueryParamsForPath(config, pathname) {
+    const matches = config.overrides
+        .map((override, index) => ({ override, index }))
+        .filter(({ override }) => picomatch.isMatch(pathname, toGlob(override.pathPattern)));
+    if (matches.length === 0)
+        return { ...config.base };
+    matches.sort((a, b) => {
+        const specDiff = patternSpecificity(b.override.pathPattern) - patternSpecificity(a.override.pathPattern);
+        if (specDiff !== 0)
+            return specDiff;
+        // Known limitation (Finding 5, SKYR-4127 final review): at equal literal-
+        // prefix length, this tiebreak prefers the LONGER total pattern — which
+        // is not always the narrower one. E.g. "/v1/persons/**" (14 chars) beats
+        // "/v1/persons/*" (13 chars) even though "**" matches strictly more paths
+        // than "*". Length is a proxy for specificity, not a guarantee of it; not
+        // fixed here since it would change ranking behavior for existing configs.
+        const lenDiff = b.override.pathPattern.length - a.override.pathPattern.length;
+        if (lenDiff !== 0)
+            return lenDiff;
+        return a.index - b.index;
+    });
+    const [winner, runnerUp] = matches;
+    if (runnerUp &&
+        patternSpecificity(winner.override.pathPattern) === patternSpecificity(runnerUp.override.pathPattern) &&
+        winner.override.pathPattern.length === runnerUp.override.pathPattern.length) {
+        logger.warning("Ambiguous api.queryParamOverrides — two equally specific patterns match this path; using the first", {
+            pathname,
+            patterns: [winner.override.pathPattern, runnerUp.override.pathPattern],
+        });
+    }
+    return { ...config.base, ...winner.override.values };
+}
+/** `env.VAR` / legacy `envs.VAR`, anchored so a literal that merely contains
+ *  the prefix (`prod.env.HOST`) is not mistaken for a reference, and requiring
+ *  at least one character of variable name. Case-sensitive, matching the
+ *  schema's documented behavior: `ENV.VAR` is an ordinary literal. */
+const ENV_REFERENCE = /^envs?\.(.+)$/;
+/** Environment variables this workspace's query params defer to, in declaration
+ *  order and deduplicated (SKYR-4127).
+ *
+ *  These references resolve where the test RUNS, so under Testbot they resolve
+ *  inside the executor container — whose environment is a fixed allowlist. A
+ *  name that never reaches the container resolves to nothing, and an unresolved
+ *  query param is dropped from the request silently, producing a passing test
+ *  that exercised the wrong identity. The executor uses this list to forward
+ *  exactly what the workspace asked for.
+ *
+ *  Deliberately derived from the declarations rather than from the ambient
+ *  environment: nothing is forwarded that workspace.yml did not name.
+ *
+ *  Both maps are read even though `defaultQueryParams` documents itself as
+ *  literal-only — that is a doc contract the core loader does not enforce, and
+ *  a declaration there would otherwise reproduce the original silent failure. */
+export function extractEnvVarNames(config) {
+    const names = new Set();
+    const collect = (values) => {
+        for (const value of Object.values(values)) {
+            const match = typeof value === "string" ? ENV_REFERENCE.exec(value) : null;
+            if (match)
+                names.add(match[1]);
+        }
+    };
+    collect(config.base);
+    for (const override of config.overrides)
+        collect(override.values);
+    return [...names];
+}