wicked-garden 12.47.0 → 12.48.0

package/.claude-plugin/marketplace.json

@@ -1 +1 @@
-{"name": "wicked-garden", "owner": {"name": "Mike Parcewski"}, "plugins": [{"name": "wicked-garden", "source": "./", "description": "Your coding agent already plans and swarms \u2014 Wicked Garden is the curated toolkit for what it can't: proof-not-claims gates, code links grep can't see, deterministic refactor, cross-session memory, real multi-model second opinions. Don't fight the harness; fill its gaps. The gate needs wicked-vault (a self-contained infra peer, installed directly) and re-derives through garden's built-in engine; estate/bus are opt-in layers (wicked-testing and wicked-brain are retired \u2014 QE ships in-catalog as the qe domain, memory lives in wicked-estate).", "version": "12.47.0"}], "version": "12.47.0"}
+{"name": "wicked-garden", "owner": {"name": "Mike Parcewski"}, "plugins": [{"name": "wicked-garden", "source": "./", "description": "Your coding agent already plans and swarms \u2014 Wicked Garden is the curated toolkit for what it can't: proof-not-claims gates, code links grep can't see, deterministic refactor, cross-session memory, real multi-model second opinions. Don't fight the harness; fill its gaps. The gate needs wicked-vault (a self-contained infra peer, installed directly) and re-derives through garden's built-in engine; estate/bus are opt-in layers (wicked-testing and wicked-brain are retired \u2014 QE ships in-catalog as the qe domain, memory lives in wicked-estate).", "version": "12.48.0"}], "version": "12.48.0"}

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-garden",
-  "version": "12.47.0",
+  "version": "12.48.0",
   "description": "Your coding agent's harness already plans and swarms; Wicked Garden is the curated toolkit for what it can't do alone. Proof, not claims \u2014 gates re-derive 'done' through the internal loom engine (fail-closed, independently attested via wicked-vault), so a self-asserted pass can't lie its way green. Relationships grep can't see \u2014 the wicked-estate code graph + injected bus/dispatch/capability/archetype edges power blast-radius & lineage. Plus deterministic multi-file refactor (wicked-patch), cross-session memory + knowledge (the mem domain over wicked-estate), real multi-model second opinions (jam:council), portable expertise as on-demand skill-refs, and evidence-gated testing (the in-catalog qe domain). It reads the shape of your work to apply the right rigor \u2014 steering, not a pipeline \u2014 then gets out of the way. The compiler stamps a self-contained evidence gate into any repo that runs with no wicked-garden installed. Don't fight the harness; fill its gaps. The evidence gate requires wicked-vault, a self-contained infra peer wicked-garden installs directly; wicked-bus is an opt-in layer \u2014 install what you'll use, the toolkit works without the rest.",
   "wicked_vault_version": "^0.5.0",
   "wicked_ledger_version": "^0.4.0",

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [12.48.0] — 2026-10-09
+
+### Added
+- **mcp install: `--target worker|operator` and `--dry-run` (wicked-core#820, PR #1263).** Per the operator ruling, `install.py` registers a server only in program-owned places by default (`--target worker`): the staged copy under the install root, the crew MCP tools registry, and the worker seats' CLI configs under the worker home (`$WICKED_WORKER_HOME`, else `~/.wicked-worker`). `--target operator` also writes the operator's own CLI configs. `--dry-run` writes nothing and prints the consent gate's plan as one JSON line: each choice with its exact absolute write list and `operator_owned` flags, from the installer's own dry run. It never downloads the installer.
+- **mcp TypeScript template: query-parameter API keys (wicked-garden#1261, PR #1263).** `auth.queryParam` (api-key scheme only) sends the key as a query parameter, added after the boundary check and never settable by an argument. One credentials carrier feeds both the request and the error scrub, which removes every credential sent (raw, URL-encoded, JSON-escaped) from upstream error bodies and from transport errors before the span or the caller sees them.
+
+### Fixed
+- **mcp scripts no longer default to `:7701` (wicked-garden#1258, PR #1263).** `install.py` and `openapi.py` take the daemon only from `--crew-url` or `$WICKED_CREW_URL`, and exit 2 naming the remedy when neither is set. A guessed port had sent a worker to another daemon's registry. The skill text lists keys on `$WICKED_CREW_URL`.
+- **demo walkthrough: a `join` over an `artifact` source can pass (wicked-garden#1246, PR #1262).** An artifact source now joins as its sha256. Before, it always joined as `null`, so a lint-clean storyline could never pass that chapter.
+
+### Changed
+- Dependencies: TypeScript 7 for the MCP scaffold and the site (#1259), playwright 1.64.0 (#1257), motion 14.1.0 (#1260), werkzeug 3.1.9 / astro 7.3.8 / sharp 0.35.5 (#1256), wicked-ci 1.4.1 (#1241).
+
 ## [12.47.0] — 2026-10-09
 
 ### Changed
@@ -1011,7 +1024,8 @@ through `v9.2.18`. Major themes across that span:
 
 For each of those releases, see the corresponding tag in git history.
 
-[Unreleased]: https://github.com/mikeparcewski/wicked-garden/compare/v12.47.0...HEAD
+[Unreleased]: https://github.com/mikeparcewski/wicked-garden/compare/v12.48.0...HEAD
+[12.48.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.47.0...v12.48.0
 [12.47.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.46.0...v12.47.0
 [12.46.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.45.0...v12.46.0
 [12.45.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.44.0...v12.45.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-garden",
-  "version": "12.47.0",
+  "version": "12.48.0",
   "type": "module",
   "description": "Curated toolkit for what AI coding agents can't do alone: evidence-gated work, codegraph relationships, deterministic multi-file refactor, multi-model second opinions, and cross-session memory. Installs as a Claude Code plugin.",
   "keywords": [

package/scripts/demo/package-lock.json

@@ -14,12 +14,12 @@
       }
     },
     "node_modules/playwright": {
-      "version": "1.63.0",
-      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.63.0.tgz",
-      "integrity": "sha512-+7ziBLidS4NaNCdt57SUDT+wYmmd5fmiQejUic/kb+YsYSCPyOOE9sebzMjNmQrsnNpDJqd4WHvV/8lfKfUDUg==",
+      "version": "1.64.0",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.64.0.tgz",
+      "integrity": "sha512-kVzTnYFYEyQ9RGzBjNCd2+yEqWmVbxl3AHPynv3qQ6JTjv4a+kwRcnqQwIpuP3NnrnIrE/Q6wWAIAvMfIE2/Yg==",
       "license": "Apache-2.0",
       "dependencies": {
-        "playwright-core": "1.63.0"
+        "playwright-core": "1.64.0"
       },
       "bin": {
         "playwright": "cli.js"
@@ -29,9 +29,9 @@
       }
     },
     "node_modules/playwright-core": {
-      "version": "1.63.0",
-      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.63.0.tgz",
-      "integrity": "sha512-rYCsBF/M5HjUch52bbtVONEFjv6Xu8sm8h72dNlR5bzIE1fvC/bxgspzkjSfU+MweEMmPM8KJebG6nnyxo5mCg==",
+      "version": "1.64.0",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.64.0.tgz",
+      "integrity": "sha512-T9r+MZkTECl2+oUcZ26YgZzTrYidTsIhYYkJix+6iDOymOb1FB2RLLSOxRGnZGv5DStt+aduIVbt+E8WygXYpg==",
       "license": "Apache-2.0",
       "bin": {
         "playwright-core": "cli.js"

package/scripts/demo/walkthrough.mjs

@@ -531,7 +531,8 @@ async function runCollector(def, { stage, root, dataDir, seg, id, priorCaptures,
       const joined = {};
       for (const srcId of (def.sources ?? [])) {
         const cap = (priorCaptures ?? {})[srcId];
-        joined[srcId] = cap?.parsed ?? cap?.inner_text ?? null;
+        // An artifact source joins as its sha256 — present iff the artifact verifier passed it (garden#1246).
+        joined[srcId] = cap?.parsed ?? cap?.inner_text ?? cap?.sha256 ?? null;
       }
       return { joined };
     }

package/scripts/mcp/install.py

@@ -2,9 +2,23 @@
 """The ``install`` action: install or update a built MCP server for running, idempotent by key.
 
     wicked-garden run scripts/mcp/install.py (--from-run | --dir <server dir>) [--key <key>]
-        [--from-npm <pkg>@<version>] [--cli all|claude,codex,opencode,antigravity,pi|none]
+        [--from-npm <pkg>@<version>] [--target worker|operator] [--dry-run]
+        [--cli all|claude,codex,opencode,antigravity,pi|none]
         [--crew-url <origin>] [--install-root <dir>] [--json]
-    wicked-garden run scripts/mcp/install.py --uninstall <key> [--cli ...] [--crew-url ...]
+    wicked-garden run scripts/mcp/install.py --uninstall <key> [--target ...] [--cli ...] [--crew-url ...]
+
+**Target** (core#820, operator ruling 2026-10-09): ``--target worker`` (the default) writes only
+program-owned places: the staged copy under the install root, the crew registry, and the worker
+seats' CLI configs under the worker home (``$WICKED_WORKER_HOME``, else ``~/.wicked-worker``:
+``claude/.claude.json``, ``codex/config.toml``, ``opencode/config/opencode/``). ``--target
+operator`` does all of that AND registers the server in the operator's own CLI configs.
+``--dry-run`` writes nothing and prints ONE JSON line, the plan the consent gate shows:
+``{"dry_run": true, "key", "choices": [{"id", "label", "default"?, "writes": [{"path", "what",
+"cli"?, "operator_owned"}]}], "skipped": [{"cli", "why"}]}``.
+
+**Daemon origin** (garden#1258): ``--crew-url``, else ``$WICKED_CREW_URL`` (crew sets it to its own
+bound URL for every governed unit). There is no port default: a guessed ``:7701`` reached another
+daemon's registry. Neither set exits 2 naming the remedy.
 
 1. **Locate** the server: ``--from-run`` finds the one ``mcp-server.config.json`` under
    ``$WICKED_TREE`` (else the cwd), outside node_modules/dist; ``--dir`` names it. The key and
@@ -51,7 +65,6 @@ from pathlib import Path
 
 HERE = Path(__file__).resolve().parent
 PROBE = HERE / "probe.py"
-DEFAULT_ORIGIN = "http://127.0.0.1:7701"
 CONFIG_NAME = "mcp-server.config.json"
 NAME_RE = re.compile(r"^[a-z][a-z0-9-]{0,63}$")
 NPM_SPEC_RE = re.compile(r"^(?P<pkg>(?:@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*)@(?P<version>[^@\s]+)$")
@@ -82,7 +95,50 @@ def env_name_for(key: str) -> str:
 
 
 def crew_origin(flag: str | None) -> str:
-    return (flag or os.environ.get("WICKED_CREW_URL") or DEFAULT_ORIGIN).rstrip("/")
+    """The daemon THIS run belongs to — never a guessed port (garden#1258)."""
+    origin = flag or os.environ.get("WICKED_CREW_URL")
+    if not origin:
+        raise Failure(2, "no wicked-crew origin: $WICKED_CREW_URL is unset (crew sets it for every "
+                         "governed unit) and no --crew-url was given; pass --crew-url <the daemon's "
+                         "URL> — never assume a port")
+    return origin.rstrip("/")
+
+
+TARGETS = ("worker", "operator")
+CHOICE_LABELS = {"worker": "Install for workers", "operator": "Also install into my CLIs"}
+
+
+def worker_home() -> Path:
+    """The ONE worker home every daemon's seats run from (``$WICKED_WORKER_HOME``)."""
+    env = os.environ.get("WICKED_WORKER_HOME")
+    return Path(env) if env else Path.home() / ".wicked-worker"
+
+
+def worker_home_args() -> list[str]:
+    """wicked-installer's per-CLI home flags pointed at the worker seats' config roots — the
+    layout the engine spawns seats with (wicked-apps-core ``seat_config_in``): claude's
+    ``CLAUDE_CONFIG_DIR``, codex's ``CODEX_HOME``, opencode's ``XDG_CONFIG_HOME/opencode``,
+    pi's agent dir, antigravity's root."""
+    base = worker_home()
+    return ["--claude-home", str(base / "claude"), "--codex-home", str(base / "codex"),
+            "--opencode-home", str(base / "opencode" / "config" / "opencode"),
+            "--pi-home", str(base / "pi"), "--gemini-home", str(base / "agy")]
+
+
+def operator_owned(path: str, root: Path) -> bool:
+    """Is ``path`` outside the program-owned roots (``~/.wicked*``, the worker home, the install
+    root)? A URL (the registry) is the daemon's, never the operator's files."""
+    if "://" in path:
+        return False
+    p = Path(os.path.abspath(os.path.expanduser(path)))
+    owned = [worker_home(), root, Path.home() / ".wicked"]
+    if any(p == o or o in p.parents for o in (Path(os.path.abspath(x)) for x in owned)):
+        return False
+    try:
+        rel = p.relative_to(Path.home())
+    except ValueError:
+        return True
+    return not (rel.parts and rel.parts[0].startswith(".wicked"))
 
 
 def install_root(flag: Path | None) -> Path:
@@ -288,9 +344,12 @@ def register(origin: str, key: str, server_js: Path, var: str) -> dict:
 
 # ── 6. CLI configs ─────────────────────────────────────────────────────────────────────────
 
-def installer(argv: list[str]):
-    """Run ``wicked-installer <argv> --json``: its envelope, or the reportable condition."""
+def installer(argv: list[str], download: bool = True):
+    """Run ``wicked-installer <argv> --json``: its envelope, or the reportable condition.
+    ``download=False`` (the dry run) never falls back to ``npx -y``, which would install it."""
     exe = shutil.which("wicked-installer")
+    if exe is None and not download:
+        return "skipped: wicked-installer is not on PATH (the dry run never downloads it)"
     cmd = [exe, *argv] if exe else [shutil.which("npx") or "npx", "-y", "wicked-installer", *argv]
     try:
         done = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
@@ -433,11 +492,72 @@ def do_install(args) -> tuple[int, dict]:
 
     out = {**record, **reg, "probe": probe_report}
     out.setdefault("registry", None)
-    out["clis"] = "skipped: --cli none" if clis == "none" else installer(
-        ["mcp", "upsert", key, "--command", "node", "--arg", str(current_js), "--cli", clis, "--json"])
+    upsert = ["mcp", "upsert", key, "--command", "node", "--arg", str(current_js), "--cli", clis, "--json"]
+    out["target"] = args.target
+    if clis == "none":
+        out["clis"] = "skipped: --cli none"
+    else:
+        out["clis"] = installer([*upsert, *worker_home_args()])
+        if args.target == "operator":
+            out["operatorClis"] = installer(upsert)
     return code, out
 
 
+def _cli_rows(envelope, root: Path, writes: list, skipped: list) -> None:
+    """Split one installer dry-run envelope into planned writes and skipped CLIs."""
+    if not isinstance(envelope, list):
+        raise Failure(1, f"cannot plan the CLI configs: {envelope}")
+    for row in envelope:
+        if not isinstance(row, dict):
+            continue
+        cli, result, target = row.get("cli"), row.get("result"), row.get("target")
+        if result == "planned" and isinstance(target, str):
+            what = f"{cli} MCP config" + (" (codex mcp add)" if cli == "codex" else "")
+            writes.append({"path": os.path.abspath(os.path.expanduser(target)), "what": what,
+                           "cli": cli, "operator_owned": operator_owned(target, root)})
+        else:
+            why = str(result or "unknown")
+            if row.get("detail") and result not in ("unsupported",):
+                why = f"{why}: {row['detail']}"
+            if not any(s["cli"] == cli and s["why"] == why for s in skipped):
+                skipped.append({"cli": cli, "why": why})
+
+
+def do_plan(args) -> dict:
+    """``--dry-run``: what each target would write, from the installer's own dry run. Writes
+    nothing; the registry is only READ (the same key check the install runs first)."""
+    if args.from_npm and not NPM_SPEC_RE.match(args.from_npm):
+        raise Failure(2, f"--from-npm {args.from_npm!r}: use <pkg>@<version>")
+    server_dir, config = locate(args)
+    key = config.get("key") or args.key
+    if not key or not NAME_RE.match(key):
+        raise Failure(2, f"invalid or missing server key {key!r}")
+    if server_dir is None and not args.from_npm:
+        raise Failure(2, "pass --from-run or --dir <server dir> (or --from-npm with --key)")
+    clis = cli_list(args.cli)
+    root = install_root(args.install_root)
+    origin = crew_origin(args.crew_url)
+    current_js = root / key / "current" / installed_rel(args.from_npm)
+    check_key(origin, key, current_js)
+    base = [{"path": str(Path(os.path.abspath(root / key / "current"))), "what": "install root",
+             "operator_owned": operator_owned(str(root / key), root)},
+            {"path": f"{origin}/api/v1/mcp/servers/{key}", "what": "wicked-crew MCP tools registry entry",
+             "operator_owned": False}]
+    skipped: list = []
+    worker_writes = list(base)
+    operator_writes = list(base)
+    if clis != "none":
+        upsert = ["mcp", "upsert", key, "--command", "node", "--arg", str(current_js), "--cli", clis,
+                  "--dry-run", "--json"]
+        _cli_rows(installer([*upsert, *worker_home_args()], download=False), root, worker_writes, skipped)
+        operator_writes = list(worker_writes)
+        _cli_rows(installer(upsert, download=False), root, operator_writes, skipped)
+    return {"dry_run": True, "key": key, "choices": [
+        {"id": "worker", "label": CHOICE_LABELS["worker"], "default": True, "writes": worker_writes},
+        {"id": "operator", "label": CHOICE_LABELS["operator"], "writes": operator_writes}],
+        "skipped": skipped}
+
+
 def do_uninstall(args) -> tuple[int, dict]:
     key = args.uninstall
     if not NAME_RE.match(key):
@@ -458,7 +578,13 @@ def do_uninstall(args) -> tuple[int, dict]:
     except (urllib.error.URLError, OSError):
         out["registered"] = False
         out["reason"] = f"no daemon at {origin}"
-    out["clis"] = "skipped: --cli none" if clis == "none" else installer(["mcp", "remove", key, "--json"])
+    out["target"] = args.target
+    if clis == "none":
+        out["clis"] = "skipped: --cli none"
+    else:
+        out["clis"] = installer(["mcp", "remove", key, "--json", *worker_home_args()])
+        if args.target == "operator":
+            out["operatorClis"] = installer(["mcp", "remove", key, "--json"])
     key_root = install_root(args.install_root) / key
     out["removed"] = str(key_root) if key_root.exists() else None
     if key_root.exists():
@@ -476,10 +602,24 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--key", help="the server key (must equal the config's key)")
     parser.add_argument("--from-npm", metavar="PKG@VERSION", help="install a published package instead")
     parser.add_argument("--cli", default="all", help="all | none | " + ",".join(CLIS))
-    parser.add_argument("--crew-url", help=f"the wicked-crew origin (default $WICKED_CREW_URL, else {DEFAULT_ORIGIN})")
+    parser.add_argument("--crew-url", help="the wicked-crew origin (default $WICKED_CREW_URL; no port is assumed)")
+    parser.add_argument("--target", choices=TARGETS, default="worker",
+                        help="worker (default): program-owned places only; operator: also your own CLI configs")
+    parser.add_argument("--dry-run", action="store_true",
+                        help="write nothing; print the plan (each target's exact write list) as one JSON line")
     parser.add_argument("--install-root", type=Path, help="default $WICKED_MCP_INSTALL_ROOT, else ~/.wicked/mcp-servers")
     parser.add_argument("--json", action="store_true", help="print the record as one compact JSON line")
     args = parser.parse_args(argv)
+    if args.dry_run:
+        if args.uninstall:
+            print(json.dumps({"ok": False, "error": "--dry-run plans an install, not --uninstall"}))
+            return 2
+        try:
+            print(json.dumps(do_plan(args)))
+            return 0
+        except Failure as err:
+            sys.stderr.write(f"install.py --dry-run: {err}\n")
+            return err.code
     try:
         code, out = do_uninstall(args) if args.uninstall else do_install(args)
     except Failure as err:

package/scripts/mcp/openapi.py

@@ -6,7 +6,7 @@
 
 The conversion is wicked-crew's: this posts ``{name, kind: "rest", url, openapiUrl | openapi,
 operations?}`` to ``POST <origin>/api/v1/mcp/servers/preview`` (the origin is ``--crew-url``,
-else ``$WICKED_CREW_URL``, else http://127.0.0.1:7701), and writes the answer's ``tools`` and
+else ``$WICKED_CREW_URL`` — no port is assumed, garden#1258), and writes the answer's ``tools`` and
 ``skipped`` into ``<dir>/tools.json`` as ``{"source": {...}, "tools": [...], "skipped": [...]}``
 — one tool per operation, each with its ``class`` and ``rest`` request mapping — then sets
 ``baseUrl`` in ``<dir>/mcp-server.config.json``. It refuses to overwrite a ``tools.json``
@@ -30,7 +30,6 @@ import urllib.parse
 import urllib.request
 from pathlib import Path
 
-DEFAULT_ORIGIN = "http://127.0.0.1:7701"
 PREVIEW = "/api/v1/mcp/servers/preview"
 NAME_RE = re.compile(r"^[a-z][a-z0-9-]{0,63}$")
 TIMEOUT_S = 60
@@ -48,8 +47,10 @@ def _fail(code: int, message: str) -> int:
     return code
 
 
-def crew_origin(flag: str | None) -> str:
-    return (flag or os.environ.get("WICKED_CREW_URL") or DEFAULT_ORIGIN).rstrip("/")
+def crew_origin(flag: str | None) -> str | None:
+    """The daemon THIS run belongs to, or None — never a guessed port (garden#1258)."""
+    origin = flag or os.environ.get("WICKED_CREW_URL")
+    return origin.rstrip("/") if origin else None
 
 
 def _http_url(raw: str, what: str, bare: bool) -> str:
@@ -125,7 +126,7 @@ def main(argv: list[str] | None = None) -> int:
     spec.add_argument("--spec-url", help="an http(s) URL the daemon fetches the document from")
     parser.add_argument("--operations", help="comma-separated operationIds to keep (default all)")
     parser.add_argument("--out", required=True, type=Path, help="the server directory")
-    parser.add_argument("--crew-url", help=f"the wicked-crew daemon origin (default $WICKED_CREW_URL, else {DEFAULT_ORIGIN})")
+    parser.add_argument("--crew-url", help="the wicked-crew daemon origin (default $WICKED_CREW_URL; no port is assumed)")
     args = parser.parse_args(argv)
 
     if not NAME_RE.match(args.name):
@@ -160,6 +161,10 @@ def main(argv: list[str] | None = None) -> int:
         return _fail(err.code, str(err))
 
     origin = crew_origin(args.crew_url)
+    if origin is None:
+        return _fail(2, "no wicked-crew origin: $WICKED_CREW_URL is unset (crew sets it for every "
+                        "governed unit) and no --crew-url was given; pass --crew-url <the daemon's URL> "
+                        "— never assume a port")
     try:
         answer = post_json(origin + PREVIEW, body)
     except Refused as err:

package/skills/mcp-scaffold/SKILL.md

@@ -74,8 +74,9 @@ wicked-garden run scripts/mcp/openapi.py --name <key> --base-url <url> (--spec <
 
 The conversion service is wicked-crew's (`POST /api/v1/mcp/servers/preview`, kind `rest`) —
 the same one studio's *Wrap an API* uses, so there is one OpenAPI reading in the platform.
-The daemon origin is `--crew-url`, else `$WICKED_CREW_URL` (set in every governed unit),
-else `http://127.0.0.1:7701`. One tool per operation; the class comes from the method
+The daemon origin is `--crew-url`, else `$WICKED_CREW_URL` (crew sets it to its own URL in
+every governed unit). There is no port default: never type a port — a guessed one can
+be another daemon's registry. With neither set the scripts exit 2 naming the remedy. One tool per operation; the class comes from the method
 (GET/HEAD/OPTIONS read, POST write, PUT/PATCH/DELETE destructive); 1 MB and 10 s bounds;
 external `$ref`s are not followed.
 
@@ -111,6 +112,11 @@ external `$ref`s are not followed.
   basic user, token URL, scopes, client id, base URL, rate limit — is committed in
   `mcp-server.config.json`. A missing secret fails at startup naming the variable. One
   variable is the contract because crew's broker and registry inject exactly one.
+- **A query-parameter API key** (an OpenAPI `apiKey` scheme with `in: query`) is config, not a
+  hand extension: `"auth": {"scheme": "api-key", "queryParam": "<name>", ...}`. The server adds
+  it to the URL after the boundary check, no argument can set it, and it is scrubbed (raw and
+  URL-encoded) from upstream error bodies exactly like a header credential — every credential
+  the server sends goes through one carrier, `upstreamCredentials`.
 - **Logging goes to stderr only** (loglayer; the console transport is bound to stderr),
   with trace ids stamped by the OpenTelemetry plugin and secrets redacted by name.
 - **Telemetry is off by default:** the SDK arms its OTLP exporters only when
@@ -190,8 +196,8 @@ Then derive each tool's class by hand from the table in step 3.
 ## 5. Install for running (`install`)
 
 ```
-wicked-garden run scripts/mcp/install.py (--from-run | --dir <server dir>) [--key <key>] [--from-npm <pkg>@<version>] [--cli all|claude,codex,opencode,antigravity,pi|none] [--crew-url <origin>] [--install-root <dir>] [--json]
-wicked-garden run scripts/mcp/install.py --uninstall <key>
+wicked-garden run scripts/mcp/install.py (--from-run | --dir <server dir>) [--key <key>] [--from-npm <pkg>@<version>] [--target worker|operator] [--dry-run] [--cli all|claude,codex,opencode,antigravity,pi|none] [--crew-url <origin>] [--install-root <dir>] [--json]
+wicked-garden run scripts/mcp/install.py --uninstall <key> [--target worker|operator]
 ```
 
 Installs the built TypeScript server — or updates the installed copy — idempotent by the
@@ -220,7 +226,20 @@ config's `key`:
    different server (another `kind`, command or args — say a REST server with the same name)
    exits 1 naming it, with nothing written. Pick another key, or remove that server first.
 6. **CLI configs** through `wicked-installer mcp upsert` (never written by this script); an
-   installer without the verb is reported as `clis: "skipped: …"`, not failed.
+   installer without the verb is reported as `clis: "skipped: …"`, not failed. **`--target
+   worker`** (the default) registers the server only in the worker seats' CLI configs under
+   the worker home (`$WICKED_WORKER_HOME`, else `~/.wicked-worker`: `claude/.claude.json`,
+   `codex/config.toml`, `opencode/config/opencode/`); **`--target operator`** also writes the
+   operator's own CLI configs (`~/.claude.json`, `~/.codex/config.toml`, the opencode
+   config), reported as `operatorClis`. Only the operator chooses `operator`, at the install
+   gate.
+
+**`--dry-run`** writes nothing (it only reads the registry for the key check) and prints ONE
+JSON line, the plan the install gate shows: `{"dry_run": true, "key", "choices": [{"id":
+"worker" | "operator", "label", "default"?, "writes": [{"path", "what", "cli"?,
+"operator_owned"}]}], "skipped": [{"cli", "why"}]}` — every path absolute, each choice listing
+everything it would write, the CLI rows from `wicked-installer mcp upsert --dry-run`. It exits
+non-zero (the reason on stderr) when it cannot plan.
 7. **Record** `<root>/<key>/installed.json` `{key, version, source, command, args,
    envNames, installedAt, registered, smoke}` and print it with `probe`, `registry` and `clis`.
 
@@ -268,7 +287,8 @@ run. Follow `wicked-garden-governed-worker`, and:
   client needs httpStream) and the **target directory**: the root of a near-empty repo, or a
   subdirectory of an existing one. A repository that is not registered must be created and
   registered by the operator first — say so, do not create it. **List the registry's keys**
-  (`GET /api/v1/mcp/servers` on the crew daemon, or studio MCP tools) and pick a key no other
+  (`GET $WICKED_CREW_URL/api/v1/mcp/servers` — the daemon this run belongs to, never a typed
+  port; or studio MCP tools) and pick a key no other
   server holds: install refuses a key held by a different server. Record whether an OpenAPI
   document was given and whether to install when complete (the operator still decides at
   the install gate).
@@ -281,8 +301,9 @@ run. Follow `wicked-garden-governed-worker`, and:
 - **build** — scaffold (step 1), then branch A (generated tools from `tools.json`) or branch
   B (hand-written tools through `defineTool`), with a contract test per tool and
   `npm test` green; probe it (step 4).
-- **install** — a Tool phase runs `install.py --from-run` after an unconditional operator
-  gate (step 5). Read its record: `smoke` (`ok` or `pending_credential`), `registered`
+- **install-plan / install** — a Tool phase runs `install.py --from-run --dry-run --json`
+  (the plan), then the operator's consent gate offers its choices with their files, then a
+  Tool phase runs `install.py --from-run --target <the approved choice>` (step 5). Read its record: `smoke` (`ok` or `pending_credential`), `registered`
   (`true`, `"updated"`, or `false` with `missing`/`remedy` or `reason`) and `clis` (per-CLI
   results, or why they were skipped). Exit 0 means staged; a disclosed pending credential is
   not a failure.

package/skills/mcp-scaffold/assets/typescript/README.md

@@ -29,7 +29,10 @@ The probe starts the server with a minimal environment plus only the variables n
 The server reads exactly ONE secret: `__SERVER_ENV___TOKEN` — the bearer token, the API key, the
 basic-auth password or the OAuth2 client secret, as `auth.scheme` in `mcp-server.config.json`
 says. Everything else about auth (header name, basic user, token URL, scopes, client id) is
-committed, non-secret configuration in `mcp-server.config.json`. A missing secret fails at
+committed, non-secret configuration in `mcp-server.config.json`. An API key the upstream takes
+as a QUERY parameter is `"auth": {"scheme": "api-key", "queryParam": "<name>"}` — sent after the
+boundary check, never settable by an argument, and scrubbed from upstream error bodies like any
+header credential. A missing secret fails at
 startup naming the variable. One variable is the contract because wicked-crew's broker and
 registry inject exactly one environment variable into a stdio server. See `.env.example`.
 

package/skills/mcp-scaffold/assets/typescript/package.json

@@ -40,8 +40,9 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/node": "^24.0.0",
+    "@typescript/native": "npm:typescript@~7.0.2",
     "eslint": "^10.12.0",
-    "typescript": "~6.0.3",
+    "typescript": "npm:@typescript/typescript6@~6.0.2",
     "typescript-eslint": "^8.71.1",
     "vitest": "^5.0.3"
   }

package/skills/mcp-scaffold/assets/typescript/src/auth.ts

@@ -3,6 +3,7 @@
 import { timingSafeEqual } from "node:crypto";
 import type { IncomingMessage } from "node:http";
 import { secretVar, type ServerConfig } from "./config.js";
+import type { Credentials } from "./rest.js";
 
 /** The authenticated MCP client of an httpStream session. */
 export type Session = { principal: string };
@@ -24,26 +25,31 @@ export function loadSecret(config: ServerConfig, env: NodeJS.ProcessEnv = proces
 type FetchLike = typeof fetch;
 let cached: { key: string; token: string; expiresAt: number } | undefined;
 
-/** The header(s) the upstream API expects, built from the secret plus the committed config. */
-export async function upstreamHeaders(
+/**
+ * Every credential the upstream API expects — header(s), or a query parameter for an api-key
+ * with `auth.queryParam` — built from the secret plus the committed config. ONE carrier: the
+ * request builder sends exactly these, and the error scrub removes exactly these.
+ */
+export async function upstreamCredentials(
   config: ServerConfig,
   secret: string,
   fetchImpl: FetchLike = fetch,
-): Promise<Record<string, string>> {
+): Promise<Credentials> {
   const { auth } = config;
+  const header = (value: string): Credentials => ({ headers: { [auth.header]: value }, query: {} });
   switch (auth.scheme) {
     case "bearer":
-      return { [auth.header]: `Bearer ${secret}` };
+      return header(`Bearer ${secret}`);
     case "api-key":
-      return { [auth.header]: secret };
+      return auth.queryParam !== null ? { headers: {}, query: { [auth.queryParam]: secret } } : header(secret);
     case "basic":
-      return { [auth.header]: `Basic ${Buffer.from(`${auth.user}:${secret}`).toString("base64")}` };
+      return header(`Basic ${Buffer.from(`${auth.user}:${secret}`).toString("base64")}`);
     case "oauth2-client-credentials": {
       const key = `${auth.tokenUrl} ${auth.clientId} ${auth.scopes.join(" ")}`;
       if (!cached || cached.key !== key || cached.expiresAt <= Date.now()) {
         cached = { key, ...(await exchange(config, secret, fetchImpl)) };
       }
-      return { [auth.header]: `Bearer ${cached.token}` };
+      return header(`Bearer ${cached.token}`);
     }
   }
 }

package/skills/mcp-scaffold/assets/typescript/src/config.ts

@@ -15,6 +15,10 @@ const AuthSchema = z.object({
   tokenUrl: z.url({ protocol: /^https?$/ }).nullable(),
   scopes: z.array(z.string().min(1)),
   clientId: z.string().min(1).nullable(),
+  // api-key only: send the key as this QUERY parameter instead of the header (an OpenAPI
+  // `apiKey` scheme with `in: query`, garden#1261). The server adds it after the boundary check
+  // and scrubs it from upstream error bodies like any other credential it sends.
+  queryParam: z.string().min(1).nullable().default(null),
 });
 
 const ConfigSchema = z
@@ -35,6 +39,9 @@ const ConfigSchema = z
     if (u.username || u.password || u.search || u.hash) {
       ctx.addIssue({ code: "custom", path: ["baseUrl"], message: "no credentials, query or fragment" });
     }
+    if (cfg.auth.queryParam !== null && cfg.auth.scheme !== "api-key") {
+      ctx.addIssue({ code: "custom", path: ["auth", "queryParam"], message: "a query-parameter key is the api-key scheme only" });
+    }
     if (cfg.auth.scheme === "basic" && cfg.auth.user === null) {
       ctx.addIssue({ code: "custom", path: ["auth", "user"], message: "basic auth needs auth.user" });
     }

package/skills/mcp-scaffold/assets/typescript/src/rest.ts

@@ -16,10 +16,16 @@ export interface RestMapping {
   timeoutMs: number;
 }
 
+/** Every credential a request carries: header(s) and/or query parameter(s). */
+export interface Credentials {
+  headers: Record<string, string>;
+  query: Record<string, string>;
+}
+
 export interface RestContext {
   baseUrl: string;
-  /** The upstream auth header(s) — its name is also forbidden to arguments. */
-  headers: () => Promise<Record<string, string>>;
+  /** The upstream credentials — their header and query names are also forbidden to arguments. */
+  credentials: () => Promise<Credentials>;
   /** Read tools are retried on 429/5xx; write and destructive tools never are. */
   readOnly: boolean;
   fetchImpl?: typeof fetch;
@@ -28,6 +34,33 @@ export interface RestContext {
 export interface RestResult {
   status: number;
   body: unknown;
+  /** The exact credentials this request carried — what an error scrub must remove. */
+  sent: Credentials;
+}
+
+/**
+ * `text` with every credential in `sent` (header and query values; raw, after a `Bearer `-style
+ * scheme, and URL-encoded) replaced by `[redacted]`. The ONE scrub: upstream error bodies and
+ * transport errors (whose message may carry the request URL, query key included) both use it.
+ */
+export function scrubCredentials(text: string, sent: Credentials): string {
+  let out = text;
+  for (const value of [...Object.values(sent.headers), ...Object.values(sent.query)]) {
+    const bare = value.includes(" ") ? value.slice(value.indexOf(" ") + 1) : "";
+    const spellings = (v: string) => [
+      v,
+      encodeURIComponent(v),
+      new URLSearchParams({ v }).toString().slice(2),
+      JSON.stringify(v).slice(1, -1), // as an echoed JSON body serializes it
+    ];
+    const parts = [...spellings(value), ...(bare ? spellings(bare) : [])];
+    // Longest first, so a scrubbed prefix never leaves the rest of a longer spelling behind.
+    // Every non-empty spelling: a short key is still a key.
+    for (const part of [...new Set(parts)].sort((a, b) => b.length - a.length)) {
+      if (part.length > 0) out = out.split(part).join("[redacted]");
+    }
+  }
+  return out;
 }
 
 /** Headers an argument can never set: routing, auth and the hop-by-hop set. */
@@ -66,8 +99,9 @@ export function buildRequest(
   baseUrl: string,
   mapping: RestMapping,
   args: Record<string, unknown>,
-  authHeaders: Record<string, string>,
+  creds: Credentials = { headers: {}, query: {} },
 ): { url: URL; init: RequestInit } {
+  const authHeaders = creds.headers;
   const base = new URL(baseUrl);
   const allowed = new Set(mapping.argAllowlist);
   const sent = Object.fromEntries(Object.entries(args).filter(([k]) => allowed.has(k)));
@@ -84,9 +118,11 @@ export function buildRequest(
   url.pathname = `${basePath(base)}${filled}`;
   const escape = escapes(base, url);
   if (escape !== null) throw new BoundaryError(escape);
+  const authQuery = new Set(Object.keys(creds.query));
   for (const [arg, q] of Object.entries(mapping.queryMap)) {
     const v = sent[arg];
-    if (v === undefined || v === null) continue;
+    // An argument never sets (or doubles) the credential's query parameter.
+    if (v === undefined || v === null || authQuery.has(q)) continue;
     for (const item of Array.isArray(v) ? v : [v]) url.searchParams.append(q, scalar(item, `the query argument ${arg}`));
   }
   const deny = new Set(DENY_HEADERS);
@@ -109,6 +145,8 @@ export function buildRequest(
   }
   if (body !== undefined) headers["content-type"] = "application/json";
   Object.assign(headers, authHeaders);
+  // After the boundary check (a query never moves the origin or path): the credential last.
+  for (const [q, value] of Object.entries(creds.query)) url.searchParams.set(q, value);
   return { url, init: { method: mapping.method, headers, ...(body !== undefined ? { body } : {}) } };
 }
 
@@ -129,7 +167,8 @@ async function readBody(res: Response): Promise<unknown> {
  * 429/5xx twice for read tools only. One child span `http.client.request` per call.
  */
 export async function callRest(mapping: RestMapping, args: Record<string, unknown>, ctx: RestContext): Promise<RestResult> {
-  const { url, init } = buildRequest(ctx.baseUrl, mapping, args, await ctx.headers());
+  const sent = await ctx.credentials();
+  const { url, init } = buildRequest(ctx.baseUrl, mapping, args, sent);
   const fetchImpl = ctx.fetchImpl ?? fetch;
   return tracer.startActiveSpan(
     "http.client.request",
@@ -146,12 +185,17 @@ export async function callRest(mapping: RestMapping, args: Record<string, unknow
             continue;
           }
           if (res.status >= 400) span.setStatus({ code: SpanStatusCode.ERROR });
-          return { status: res.status, body: await readBody(res) };
+          return { status: res.status, body: await readBody(res), sent };
         }
       } catch (err) {
-        span.recordException(err as Error);
+        // A transport error can name the request URL — a query-parameter key with it. Neither
+        // the span nor the caller ever sees the raw message.
+        const e = err instanceof Error ? err : new Error(String(err));
+        const safe = new Error(scrubCredentials(e.message, sent));
+        safe.name = e.name;
+        span.recordException(safe);
         span.setStatus({ code: SpanStatusCode.ERROR });
-        throw err;
+        throw safe;
       } finally {
         span.end();
       }

package/skills/mcp-scaffold/assets/typescript/src/server.ts

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
 // SPDX-FileCopyrightText: __YEAR__ the __SERVER_NAME__ authors
 import { FastMCP } from "fastmcp";
-import { authenticate, configureAuth, loadSecret, upstreamHeaders, type Session } from "./auth.js";
+import { authenticate, configureAuth, loadSecret, upstreamCredentials, type Session } from "./auth.js";
 import { loadConfig, secretVar } from "./config.js";
 import { fastmcpLogger, initLogging } from "./logging.js";
 import { startTelemetry, stopTelemetry } from "./telemetry.js";
@@ -26,7 +26,7 @@ async function main(): Promise<void> {
     authenticate: config.transport === "httpStream" ? authenticate : undefined,
   });
 
-  const generated = registerGeneratedTools(server, config, () => upstreamHeaders(config, secret));
+  const generated = registerGeneratedTools(server, config, () => upstreamCredentials(config, secret));
   // The example `echo` tool only stands in while tools.json is empty: a server with generated
   // tools exposes exactly those (plus whatever you register by hand).
   if (generated === 0) registerExampleTools(server, config);

package/skills/mcp-scaffold/assets/typescript/src/tools/generated.ts

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { UserError, jsonSchemaAdapter, type FastMCP, type JsonSchemaObject, type ToolParameters } from "fastmcp";
 import type { Session } from "../auth.js";
 import { SERVER_ROOT, type ServerConfig } from "../config.js";
-import { callRest, type RestMapping } from "../rest.js";
+import { callRest, scrubCredentials, type Credentials, type RestMapping } from "../rest.js";
 import { defineTool } from "./registry.js";
 
 /** One tools.json entry, as wicked-crew's conversion service (`openapi` action) writes it. */
@@ -39,15 +39,12 @@ export const ERROR_BODY_MAX = 300;
 
 /**
  * The tool error for an upstream 4xx/5xx: the status plus a bounded excerpt of the body with
- * every credential this server sent scrubbed out, so an upstream that echoes its auth header
- * back cannot hand the secret to the caller.
+ * every credential this server sent — header AND query (garden#1261) — scrubbed out, raw and
+ * URL-encoded, so an upstream that echoes its auth header or request URL back cannot hand the
+ * secret to the caller.
  */
-export function upstreamError(status: number, body: string, sent: Record<string, string>): string {
-  let text = body;
-  for (const value of Object.values(sent)) {
-    const parts = [value, value.includes(" ") ? value.slice(value.indexOf(" ") + 1) : ""];
-    for (const part of parts) if (part.length >= 4) text = text.split(part).join("[redacted]");
-  }
+export function upstreamError(status: number, body: string, sent: Credentials): string {
+  let text = scrubCredentials(body, sent);
   if (text.length > ERROR_BODY_MAX) text = `${text.slice(0, ERROR_BODY_MAX)}… (truncated)`;
   return text ? `HTTP ${status}: ${text}` : `HTTP ${status}`;
 }
@@ -56,7 +53,7 @@ export function upstreamError(status: number, body: string, sent: Record<string,
 export function registerGeneratedTools(
   server: FastMCP<Session>,
   config: ServerConfig,
-  headers: () => Promise<Record<string, string>>,
+  credentials: () => Promise<Credentials>,
   tools: GeneratedTool[] = readToolsJson(),
 ): number {
   for (const t of tools) {
@@ -71,11 +68,13 @@ export function registerGeneratedTools(
       execute: async (args) => {
         const result = await callRest(t.rest, (args ?? {}) as Record<string, unknown>, {
           baseUrl: config.baseUrl,
-          headers,
+          credentials,
           readOnly: t.class === "read",
         });
         const text = typeof result.body === "string" ? result.body : JSON.stringify(result.body);
-        if (result.status >= 400) throw new UserError(upstreamError(result.status, text, await headers()));
+        // The credentials the request CARRIED, never a fresh fetch (an OAuth2 token may have
+        // rotated in between).
+        if (result.status >= 400) throw new UserError(upstreamError(result.status, text, result.sent));
         return text;
       },
     });

package/skills/mcp-scaffold/assets/typescript/test/contract/example.test.ts

@@ -48,7 +48,7 @@ function toolUnderTest(tool: GeneratedTool) {
   const config = { ...loadConfig({}), baseUrl };
   const added: any[] = [];
   const fake = { addTool: (t: unknown) => added.push(t) } as any;
-  registerGeneratedTools(fake, config, async () => ({ Authorization: "Bearer test-token" }), [tool]);
+  registerGeneratedTools(fake, config, async () => ({ headers: { Authorization: "Bearer test-token" }, query: {} }), [tool]);
   return added[0];
 }
 
@@ -70,6 +70,6 @@ describe("get_note contract", () => {
   });
 
   it("never leaves the base URL", () => {
-    expect(() => buildRequest(baseUrl, getNote.rest, { id: ".." }, {})).toThrow(BoundaryError);
+    expect(() => buildRequest(baseUrl, getNote.rest, { id: ".." })).toThrow(BoundaryError);
   });
 });

package/skills/mcp-scaffold/assets/typescript/test/global-setup.ts

@@ -2,9 +2,17 @@
 // SPDX-FileCopyrightText: __YEAR__ the __SERVER_NAME__ authors
 import { execFileSync } from "node:child_process";
 import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
 
-/** Build dist/ once before the suite: the conformance smoke speaks to the built server. */
+/**
+ * Build dist/ once before the suite: the conformance smoke speaks to the built server.
+ * The compiler is TypeScript 7, installed as `@typescript/native`; `typescript` is aliased to the
+ * TS 6 API package because typescript-eslint does not support TS 7 yet. TS 7 does not export
+ * `./bin/tsc`, so the bin is resolved through its manifest.
+ */
 export default function setup(): void {
-  const tsc = createRequire(import.meta.url).resolve("typescript/bin/tsc");
-  execFileSync(process.execPath, [tsc], { stdio: "inherit" });
+  const require = createRequire(import.meta.url);
+  const manifest = require.resolve("@typescript/native/package.json");
+  const { bin } = require(manifest) as { bin: { tsc: string } };
+  execFileSync(process.execPath, [join(dirname(manifest), bin.tsc)], { stdio: "inherit" });
 }

package/skills/mcp-scaffold/assets/typescript/test/hardening.test.ts

@@ -1,19 +1,44 @@
 // SPDX-License-Identifier: MIT
 // SPDX-FileCopyrightText: __YEAR__ the __SERVER_NAME__ authors
-import { describe, expect, it } from "vitest";
-import { loadConfig } from "../src/config.js";
-import { ERROR_BODY_MAX, upstreamError } from "../src/tools/generated.js";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { createServer, type Server } from "node:http";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { UserError } from "fastmcp";
+import { upstreamCredentials } from "../src/auth.js";
+import { loadConfig, SERVER_ROOT, type ServerConfig } from "../src/config.js";
+import { buildRequest, type RestMapping } from "../src/rest.js";
+import { ERROR_BODY_MAX, registerGeneratedTools, upstreamError } from "../src/tools/generated.js";
 
 const BASE_VAR = "__SERVER_ENV___BASE_URL";
 
 describe("upstream error text", () => {
   it("scrubs every credential the server sent, whole or after its scheme", () => {
-    const text = upstreamError(401, "bad header: Bearer tok-1234 (tok-1234)", { Authorization: "Bearer tok-1234" });
+    const text = upstreamError(401, "bad header: Bearer tok-1234 (tok-1234)", {
+      headers: { Authorization: "Bearer tok-1234" },
+      query: {},
+    });
     expect(text).toBe("HTTP 401: bad header: [redacted] ([redacted])");
   });
 
+  it("scrubs a query-parameter key too, raw and URL-encoded (garden#1261)", () => {
+    const sent = { headers: {}, query: { api_key: "k3y/with+chars" } };
+    const text = upstreamError(403, "bad key k3y/with+chars in /x?api_key=k3y%2Fwith%2Bchars", sent);
+    expect(text).not.toContain("k3y");
+    expect(text).toBe("HTTP 403: bad key [redacted] in /x?api_key=[redacted]");
+  });
+
+  it("scrubs a short key and a JSON-escaped key too (review r2)", () => {
+    expect(upstreamError(401, "?api_key=abc", { headers: {}, query: { api_key: "abc" } })).toBe("HTTP 401: ?api_key=[redacted]");
+    const quoted = 'k"ey\\x';
+    const body = JSON.stringify({ api_key: quoted });
+    const text = upstreamError(401, body, { headers: {}, query: { api_key: quoted } });
+    expect(text).toBe('HTTP 401: {"api_key":"[redacted]"}');
+  });
+
   it("bounds the body a caller sees", () => {
-    const text = upstreamError(500, "x".repeat(ERROR_BODY_MAX * 3), {});
+    const text = upstreamError(500, "x".repeat(ERROR_BODY_MAX * 3), { headers: {}, query: {} });
     expect(text.length).toBeLessThan(ERROR_BODY_MAX + 40);
     expect(text).toContain("(truncated)");
   });
@@ -31,3 +56,76 @@ describe("base URL override", () => {
     expect(() => loadConfig({ [BASE_VAR]: "https://elsewhere.invalid/v1" })).toThrow(/committed baseUrl origin/);
   });
 });
+
+describe("query-parameter API key (garden#1261)", () => {
+  const queryConfig = (base: string): ServerConfig => {
+    const c = loadConfig({});
+    return { ...c, baseUrl: base, auth: { ...c.auth, scheme: "api-key", queryParam: "api_key" } };
+  };
+  const search: RestMapping = {
+    method: "GET", pathTemplate: "/search", pathMap: {}, queryMap: { q: "q", key: "api_key" }, headerMap: {},
+    bodyMap: null, bodyArg: null, argAllowlist: ["q", "key"], timeoutMs: 5000,
+  };
+
+  it("sends the key as the query parameter, never a header, and no argument can set it", async () => {
+    const creds = await upstreamCredentials(queryConfig("https://api.example.com/v1"), "s3cret-key");
+    expect(creds).toEqual({ headers: {}, query: { api_key: "s3cret-key" } });
+    const { url, init } = buildRequest("https://api.example.com/v1", search, { q: "cats", key: "attacker" }, creds);
+    expect(url.searchParams.getAll("api_key")).toEqual(["s3cret-key"]);
+    expect(url.searchParams.get("q")).toBe("cats");
+    expect(Object.values(init.headers as Record<string, string>)).not.toContain("s3cret-key");
+  });
+
+  it("refuses a query key on any scheme but api-key", () => {
+    const dir = mkdtempSync(join(tmpdir(), "mcp-cfg-"));
+    const committed = JSON.parse(readFileSync(join(SERVER_ROOT, "mcp-server.config.json"), "utf8"));
+    writeFileSync(join(dir, "mcp-server.config.json"),
+      JSON.stringify({ ...committed, auth: { ...committed.auth, scheme: "bearer", queryParam: "api_key" } }));
+    expect(() => loadConfig({}, dir)).toThrow(/auth\.queryParam/);
+    writeFileSync(join(dir, "mcp-server.config.json"),
+      JSON.stringify({ ...committed, auth: { ...committed.auth, scheme: "api-key", queryParam: "api_key" } }));
+    expect(loadConfig({}, dir).auth.queryParam).toBe("api_key");
+  });
+
+  describe("an upstream that echoes the request URL in its error", () => {
+    let stub: Server;
+    let base = "";
+    beforeAll(async () => {
+      stub = createServer((req, res) => {
+        res.writeHead(401, { "content-type": "text/plain" }).end(`invalid key for ${req.url}`);
+      });
+      await new Promise<void>((r) => stub.listen(0, "127.0.0.1", r));
+      base = `http://127.0.0.1:${(stub.address() as { port: number }).port}/v1`;
+    });
+    afterAll(() => new Promise<void>((r) => stub.close(() => r())));
+
+    it("a transport error naming the URL is scrubbed before the span or the caller sees it", async () => {
+      const { callRest } = await import("../src/rest.js");
+      const creds = { headers: {}, query: { api_key: "s3cret-key" } };
+      const err = await callRest(search, { q: "x" }, {
+        baseUrl: base,
+        credentials: async () => creds,
+        readOnly: false,
+        fetchImpl: (async (u: URL) => {
+          throw new TypeError(`fetch failed for ${u.href}`);
+        }) as unknown as typeof fetch,
+      }).catch((e: unknown) => e);
+      expect((err as Error).message).toContain("api_key=[redacted]");
+      expect((err as Error).message).not.toContain("s3cret-key");
+    });
+
+    it("comes back scrubbed", async () => {
+      const config = queryConfig(base);
+      const added: any[] = [];
+      const fake = { addTool: (t: unknown) => added.push(t) } as any;
+      registerGeneratedTools(fake, config, () => upstreamCredentials(config, "s3cret-key"), [
+        { name: "search", inputSchema: { type: "object", properties: { q: { type: "string" } } }, class: "read", rest: search },
+      ]);
+      const ctx = { requestId: "r1", sessionId: "s1", log: {} } as any;
+      const err = await added[0].execute({ q: "cats" }, ctx).catch((e: unknown) => e);
+      expect(err).toBeInstanceOf(UserError);
+      expect((err as Error).message).toContain("HTTP 401: invalid key for /v1/search?q=cats&api_key=[redacted]");
+      expect((err as Error).message).not.toContain("s3cret-key");
+    });
+  });
+});

package/uv.lock

@@ -679,14 +679,14 @@ wheels = [
 
 [[package]]
 name = "werkzeug"
-version = "3.1.8"
+version = "3.1.9"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "markupsafe" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/dd/b2/381be8cfdee792dd117872481b6e378f85c957dd7c5bca38897b08f765fd/werkzeug-3.1.8.tar.gz", hash = "sha256:9bad61a4268dac112f1c5cd4630a56ede601b6ed420300677a869083d70a4c44", size = 875852, upload-time = "2026-04-02T18:49:14.268Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/a4/34/4dd12fc8bb7d61c91467ec3efe415ffa7d5456f799954b40c5bbaeae470e/werkzeug-3.1.9.tar.gz", hash = "sha256:55ca7c70a75689be937aa27f8ff4b018f06ff4838fc73045560bf0f5a1291060", size = 940188, upload-time = "2026-09-27T18:33:41.637Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/93/8c/2e650f2afeb7ee576912636c23ddb621c91ac6a98e66dc8d29c3c69446e1/werkzeug-3.1.8-py3-none-any.whl", hash = "sha256:63a77fb8892bf28ebc3178683445222aa500e48ebad5ec77b0ad80f8726b1f50", size = 226459, upload-time = "2026-04-02T18:49:12.72Z" },
+    { url = "https://files.pythonhosted.org/packages/a1/38/df03f564f43cec2684823f3cccae1a652ee7face1cbaa76fb223096e64d7/werkzeug-3.1.9-py3-none-any.whl", hash = "sha256:6392e50c78460ba618e5b21f08a71f59c99ce99cdc6cf6e3dd7e6ccca8754fab", size = 228700, upload-time = "2026-09-27T18:33:39.685Z" },
 ]
 
 [[package]]