wicked-garden 12.44.0 → 12.46.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.44.0"}], "version": "12.44.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.46.0"}], "version": "12.46.0"}

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-garden",
-  "version": "12.44.0",
+  "version": "12.46.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,18 @@
 
 ## [Unreleased]
 
+## [12.46.0] — 2026-10-09
+
+### Fixed
+- **`mcp-scaffold` TypeScript template: a server with generated tools starts (wicked-garden#1249, PR #1251).** `src/tools/generated.ts` handed each `tools.json` entry's plain JSON Schema to fastmcp 4.22, which accepts only a Standard Schema, so any non-empty `tools.json` (branch A, the conversion-service path) made the server exit at startup ("parameters must implement Standard Schema") and the conformance tests time out. Each schema is now wrapped in fastmcp's `jsonSchemaAdapter`, validated with `ajv` + `ajv-formats` (now direct dependencies instead of fastmcp's optional peers). The example `echo` tool is registered only while `tools.json` is empty, so a generated server exposes exactly its generated tools. An upstream 4xx/5xx reaches the caller as `HTTP <status>: <excerpt>` with every credential the server sent scrubbed and the excerpt bounded to 300 characters. `<KEY>_BASE_URL` may change the path but never the origin: the credential follows the base URL, so another host is an edit to `mcp-server.config.json`. Tests: the template's vitest suite boots a copy of the built server with a one-tool `tools.json` against a local stub (lists only that tool, calls it, rejects a call missing a required argument) and `test/hardening.test.ts` pins the scrubbing and the origin rule; `tests/mcp/test_mcp_scaffold.py`'s npm end-to-end also probes the built server with a generated tool and now runs in CI.
+- **`mcp-scaffold` install: a key held by a different registry server is refused, not "updated" (wicked-garden#1250, PR #1251).** `scripts/mcp/install.py` reads `GET /api/v1/mcp/servers` before staging and again right before the save: an entry under the key that is not this install (another `kind`, command or args — e.g. a REST server with the same name) exits 1 naming it and the two ways out (another key, or remove that server first), writing nothing to the registry; an unreadable registry (not a 404) refuses too. The skill's scope phase lists the registry's keys before picking one.
+- **Walkthrough probes learn the fixture's port (wicked-garden#1248, PR #1251).** The recorder starts the fixture on a free port but spawned probes with only `DATA_DIR`, so a probe reading the app over HTTP could not reach it (curl exit 7, the chapter FAILed while the app was right). Probes now also get `PORT` and `BASE_URL` (`http://127.0.0.1:$PORT`). The lint flags a probe argv with a literal loopback port (`probe_port`) and a `fixture.env` that pins `PORT` or `BASE_URL` (`fixture_env`); `refs/walkthrough-author.md` documents the probe environment and the `["sh", "-c", "curl -sf \"$BASE_URL/..\""]` pattern.
+
+## [12.45.0] — 2026-10-08
+
+### Fixed
+- **Walkthrough: `record` re-runs the storyline lint before it records (wicked-garden#1240, DES-walkthrough-proof §4.4 step 1).** The storyline may have been edited since the `walkthrough_plan` step linted it, so `scripts/demo/walkthrough.mjs record` now runs `lintStoryline` on the storyline it loaded, against the tree it staged (`git archive` of `WICKED_TREE` plus the `fixture.reuse` links, so a `fixture.start` script must be one the tree under review declares), after staging and before the fixture starts. Any finding refuses: `result.json` `{overall: "INCONCLUSIVE", cause: "storyline_refused", reason: "lint: <rule> at <where>: <detail>; ..."}` with every chapter listed INCONCLUSIVE, `progress.json` and the seal line written, exit 0 — nothing is started, filmed or captured. Without `jq` the lint cannot run a check's negative samples and fails closed (`negative_unverified`). Recorder test storylines now pass the lint through `tests/demo/fixtures/lint_complete.mjs` (a negative sample on every check, plus passing pad checks — a `#status` locator, a `probe.mjs` probe, their join, one guard — for any class a chapter lacks, checked after the chapter's own `run()`); tests that pinned a path the lint now refuses first assert the named refusal, and three new tests pin it (a tautology negative, the unpadded fixture, a `fixture.start` script not in the tree). The demo skill and `refs/walkthrough-author.md` say record re-runs the lint.
+
 ## [12.44.0] — 2026-10-08
 
 ### Added
@@ -994,7 +1006,9 @@ 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.44.0...HEAD
+[Unreleased]: https://github.com/mikeparcewski/wicked-garden/compare/v12.46.0...HEAD
+[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
 [12.44.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.43.0...v12.44.0
 [12.43.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.42.0...v12.43.0
 [12.42.0]: https://github.com/mikeparcewski/wicked-garden/compare/v12.41.0...v12.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-garden",
-  "version": "12.44.0",
+  "version": "12.46.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/walkthrough-lint.mjs

@@ -47,6 +47,10 @@ const SECRET_ENV = /(SECRET|TOKEN|PASSWORD|PASSWD|PASSPHRASE|API_?KEY|ACCESS_?KE
 // Inline-code flags: `node -e`, `python -c`, `sh -c`, ... — the fixture must be a script the tree declares.
 const INLINE_FLAGS = new Set(["-e", "-c", "--eval", "-p", "--print", "--command"]);
 const SCRIPT_LIKE = /\.(?:m?js|cjs|ts|mts|py|sh|rb|pl)$/i;
+// The recorder starts the fixture on a FREE port and hands PORT + BASE_URL to the fixture's probes
+// (garden#1248): a storyline that pins either, or a probe URL with a literal loopback port, cannot pass.
+const RECORDER_ENV = new Set(["PORT", "BASE_URL"]);
+const LITERAL_PORT = /(?:127\.0\.0\.1|localhost|0\.0\.0\.0|\[::1\]):\d+/i;
 
 /** The first line of a thrown value's message; never throws itself (a storyline can throw anything). */
 function why(e) {
@@ -103,11 +107,19 @@ export function lintStoryline(story, { tree = null, steps = null, jq = "jq" } =
       } else {
         for (const name of Object.keys(fixture.env)) {
           if (SECRET_ENV.test(name)) add("secret_env", `fixture.env.${name}`, "a secret-shaped env name is refused: no credential reaches the jailed app");
+          if (RECORDER_ENV.has(name)) add("fixture_env", `fixture.env.${name}`, `${name} is set by the recorder (the fixture runs on a free port): read it, do not pin it`);
         }
       }
     }
     if (fixture.probes !== undefined && (!fixture.probes || typeof fixture.probes !== "object" || Array.isArray(fixture.probes))) {
       add("fixture_probes", "fixture.probes", "fixture.probes must be an object of name: argv");
+    } else if (fixture.probes) {
+      for (const [name, argv] of Object.entries(fixture.probes)) {
+        const literal = Array.isArray(argv) ? argv.find((a) => typeof a === "string" && LITERAL_PORT.test(a)) : undefined;
+        if (literal !== undefined) {
+          add("probe_port", `fixture.probes.${name}`, `${JSON.stringify(literal)} hard-codes a port, but the recorder starts the fixture on a free one: read $BASE_URL (or $PORT), e.g. ["sh", "-c", "curl -sf \\"$BASE_URL/charges\\""]`);
+        }
+      }
     }
   }
   const probes = fixture && typeof fixture.probes === "object" && fixture.probes ? fixture.probes : {};

package/scripts/demo/walkthrough.mjs

@@ -9,6 +9,7 @@
 // The storyline: --storyline <path>, else $WICKED_WALKTHROUGH_AUTHOR/storyline.mjs (the walkthrough_plan step's
 // author dir, which the engine hands the record tool); with neither, record refuses (storyline_refused).
 // lint (walkthrough-lint.mjs, DES §4.5) is the walkthrough_plan step's pinned validator: exit 0 = no finding.
+// record re-runs it on the storyline it loaded (DES §4.4 step 1): any finding refuses (storyline_refused).
 // Safety: WICKED_WALKTHROUGH_JAIL must be set; without it writes INCONCLUSIVE(unjailed_host) and exits 0.
 //
 // What the proof root holds is ONE contract with crew's walkthrough view and acceptance
@@ -43,7 +44,7 @@ import { tmpdir } from "node:os";
 import { makeSegmentRecorder, failedAtInVideo, stitchParts, extractFrame, SEGMENT_TRIM_START } from "./record.mjs";
 import { fixtureOrigin } from "./readonly.mjs";
 import { crewRunStamp } from "../qe/lib/crew-run.mjs";
-import { lintAction } from "./walkthrough-lint.mjs";
+import { lintAction, lintStoryline } from "./walkthrough-lint.mjs";
 
 // ---- arg parsing ---------------------------------------------------------------
 const [action, ...rawArgs] = process.argv.slice(2);
@@ -438,7 +439,7 @@ function evidenceListForCapture(capture, def) {
 
 // ---- collector -----------------------------------------------------------------
 
-async function runCollector(def, { stage, root, dataDir, seg, id, priorCaptures, consoleErrors }) {
+async function runCollector(def, { stage, root, dataDir, seg, id, priorCaptures, consoleErrors, probeEnv = {} }) {
   const captureDir = path.join(root, "capture");
   fs.mkdirSync(captureDir, { recursive: true });
 
@@ -462,7 +463,9 @@ async function runCollector(def, { stage, root, dataDir, seg, id, priorCaptures,
       try {
         result = spawnSync(probeArgv[0], probeArgv.slice(1), {
           cwd: path.join(root, "app"),
-          env: { ...process.env, DATA_DIR: dataDir },
+          // PORT + BASE_URL: the fixture runs on a free port, so a probe that reads the app over
+          // HTTP learns where from these (garden#1248), never from a literal in its argv.
+          env: { ...process.env, DATA_DIR: dataDir, ...probeEnv },
           encoding: "utf8",
           timeout: 15_000,
         });
@@ -950,6 +953,23 @@ async function main() {
     }
   }
 
+  // Re-run the lint (DES-walkthrough-proof §4.4 step 1): the storyline may have been edited since the
+  // walkthrough_plan step linted it, so a storyline the lint refuses is never started or recorded. It
+  // runs on the staged tree (with its fixture.reuse links), so fixture.start must name a script the tree
+  // under review declares.
+  let lint;
+  try { lint = lintStoryline(story, { tree: appDir }); } catch (e) {
+    lint = { findings: [{ rule: "storyline_unreadable", where: storyPath, detail: String(e?.message ?? e).split("\n")[0] }] };
+  }
+  if (lint.findings.length) {
+    const shown = lint.findings.slice(0, 5).map((f) => `${f.rule} at ${f.where}: ${f.detail}`);
+    const more = lint.findings.length > shown.length ? ` (+${lint.findings.length - shown.length} more)` : "";
+    writeResult(ROOT, { overall: "INCONCLUSIVE", cause: "storyline_refused", reason: `lint: ${shown.join("; ")}${more}`, chapters: allChapters });
+    writeProgress(ROOT, { overall: "INCONCLUSIVE", cause: "storyline_refused" });
+    finishWithSeal(ROOT, { tree: TREE, storyline_sha: storySha, contract_shas: {}, overall: "INCONCLUSIVE", cause: "storyline_refused", chapters: allChapters });
+    process.exit(0);
+  }
+
   // 3. Spawn fixture, poll ready
   const dataDir = path.join(ROOT, "data");
   fs.mkdirSync(dataDir, { recursive: true });
@@ -1041,6 +1061,7 @@ async function main() {
               stage, root: ROOT, dataDir, seg, id,
               priorCaptures: segCaptures,
               consoleErrors: consoleErrBuf.current,
+              probeEnv: { PORT: String(fixturePort), BASE_URL: fixtureOriginStr },
             });
           } catch (e) {
             capture = { _verifier_error: e.message };

package/scripts/mcp/install.py

@@ -20,7 +20,11 @@
    ``node <root>/<key>/current/dist/server.js`` is stable across updates.
 5. **Register** with wicked-crew (``POST /api/v1/mcp/servers/preview`` with
    ``auth: {ref: "env:<SERVER>_TOKEN"}`` — a reference, never a value — then
-   ``POST /api/v1/mcp/servers {previewHash}``); saving over the same key is the update.
+   ``POST /api/v1/mcp/servers {previewHash}``); saving over the same key is the update — but
+   only of THIS install: before anything is staged, a registry entry under the key that is a
+   different server (another ``kind``, command or args — e.g. a REST server named the same)
+   refuses the install (exit 1) naming it, and nothing is written; the check runs again right
+   before the save, so a key claimed while staging is never overwritten either.
 6. **CLI configs** through ``wicked-installer mcp upsert`` (never written here); an installer
    without the verb is reported, not failed.
 7. **Record** ``<root>/<key>/installed.json`` and print one JSON record.
@@ -207,6 +211,48 @@ def smoke(server_js: Path, var: str) -> tuple[str, dict]:
     return "failed", report
 
 
+# ── 0. key collision ───────────────────────────────────────────────────────────────────────
+
+def installed_rel(npm_spec: str | None) -> Path:
+    """server.js relative to ``current/`` — known before staging, so the registry check runs first."""
+    if npm_spec:
+        pkg = NPM_SPEC_RE.match(npm_spec).group("pkg")
+        return Path("node_modules", *pkg.split("/"), "dist", "server.js")
+    return Path("dist", "server.js")
+
+
+def check_key(origin: str, key: str, server_js: Path) -> dict | None:
+    """Refuse when the registry holds a DIFFERENT server under ``key`` (garden#1250).
+
+    The same key is the update only when the entry is this install (``mcp-stdio``, ``node``,
+    the same staged path). No daemon: nothing to collide with here (registration reports it).
+    Answers the existing entry's identity when it is this install, else None."""
+    try:
+        status, body = http_json("GET", f"{origin}/api/v1/mcp/servers")
+    except (urllib.error.URLError, OSError):
+        return None
+    if status == 404:  # a daemon without the registry list route: registration will say so
+        return None
+    if status >= 400:
+        raise Failure(1, f"cannot read the registry to check the key {key!r} (HTTP {status}): "
+                         f"{_message(body)}; nothing was installed")
+    servers = body.get("servers") if isinstance(body.get("servers"), list) else []
+    existing = next((s for s in servers if isinstance(s, dict) and s.get("name") == key), None)
+    if existing is None:
+        return None
+    ours = {"kind": "mcp-stdio", "command": "node", "args": [str(server_js)]}
+    theirs = {k: existing.get(k) for k in ours}
+    if theirs == ours:
+        return theirs
+    what = existing.get("kind") or "unknown-kind"
+    where = existing.get("url") or " ".join([str(existing.get("command") or ""),
+                                             *map(str, existing.get("args") or [])]).strip()
+    raise Failure(1, f"the registry already holds a different server under the key {key!r} "
+                     f"({what}{': ' + where if where else ''}); refusing to replace it. Pick "
+                     f"another key in {CONFIG_NAME}, or remove the existing server first "
+                     f"(studio MCP tools, or install.py --uninstall {key}); nothing was installed")
+
+
 # ── 5. register ────────────────────────────────────────────────────────────────────────────
 
 def register(origin: str, key: str, server_js: Path, var: str) -> dict:
@@ -350,6 +396,8 @@ def do_install(args) -> tuple[int, dict]:
     root = install_root(args.install_root)
     key_root = root / key
     next_dir = key_root / "next"
+    origin = crew_origin(args.crew_url)
+    check_key(origin, key, key_root / "current" / installed_rel(args.from_npm))
     if next_dir.is_symlink():
         next_dir.unlink()
     elif next_dir.exists():
@@ -372,7 +420,10 @@ def do_install(args) -> tuple[int, dict]:
               "installedAt": _now()}
     code = 0
     try:
-        reg = register(crew_origin(args.crew_url), key, current_js, var)
+        # Again right before the save: the key may have been claimed while this staged, or the
+        # first check found no daemon to ask (the registry has no conditional save to lean on).
+        check_key(origin, key, current_js)
+        reg = register(origin, key, current_js, var)
     except Failure as err:
         reg = {"registered": False, "error": str(err)}
         code = 1

package/skills/demo/SKILL.md

@@ -191,7 +191,8 @@ again until it exits 0. The rules, in short: `baseUrl: "fixture"`; `fixture.star
 the tree declares (no `-e`/`-c`, nothing outside the tree, no secret-shaped env name); every chapter `proves` plan
 step ids and has a `locator` check, a `probe` or `artifact` check, and a `join` of the two; the walkthrough has a
 `guard` check; every check carries `negative` samples its `jq_pred` verifier FAILS on. The record tool
-(`walkthrough_review`) reads the same file through `WICKED_WALKTHROUGH_AUTHOR`. Full rules and a passing
+(`walkthrough_review`) reads the same file through `WICKED_WALKTHROUGH_AUTHOR` and re-runs the lint first: a
+finding refuses the recording (`storyline_refused`). Full rules and a passing
 example: `refs/walkthrough-author.md`.
 
 ### Probe selectors (read-only)

package/skills/demo/refs/walkthrough-author.md

@@ -13,7 +13,9 @@ review and judges every check through the vault. No model judges a check.
   `wicked-garden run scripts/demo/walkthrough.mjs lint --root <author dir>`. It denies the step until the
   lint exits 0.
 - The record step reads the same file through `WICKED_WALKTHROUGH_AUTHOR` (the author dir the engine hands
-  it). Outside a run, pass `--storyline <path>` to `record` and `lint`.
+  it) and re-runs the lint before it records anything: a finding refuses the recording
+  (`INCONCLUSIVE`, cause `storyline_refused`, the rules in `reason`). Outside a run, pass
+  `--storyline <path>` to `record` and `lint`.
 
 ## Lint rules
 
@@ -26,6 +28,8 @@ finding, 1 with any, 2 on a usage error. Each rule id below is what a finding ca
 | `base_url` | `baseUrl: "fixture"` — the tool films the fixture it starts, never a live system |
 | `fixture_start` | `fixture.start` is an argv of strings; no inline code (`-e`, `-c`, `--eval`, `-p`, `--print`, `--command`); no absolute path or `..`; with `--tree <dir>`, every script-like argument exists in the tree |
 | `secret_env` | no `fixture.env` name looks like a credential (`TOKEN`, `SECRET`, `PASSWORD`, `API_KEY`, `PRIVATE_KEY`, `CREDENTIAL`, `AUTH`, ...) |
+| `fixture_env` | `fixture.env` does not set `PORT` or `BASE_URL`: the recorder sets both (the fixture runs on a free port) |
+| `probe_port` | no probe argv hard-codes a loopback port (`127.0.0.1:<port>`, `localhost:<port>`): read `$BASE_URL` / `$PORT` instead (see Probes below) |
 | `segments` | at least one chapter (a non-`intro` segment): an empty plan proves nothing |
 | `segment_key` / `segment_run` | keys match `^[a-z0-9][a-z0-9-]*$` and are unique; `run(ctx)` is a function |
 | `proves` | every chapter names plan step ids in `proves[]`; with `--steps a,b`, each id is one of them |
@@ -42,6 +46,27 @@ source non-null. The verifier reads the capture the tool records: a locator `{in
 `{raw: {argv, exit_code, stdout, stderr}, parsed}`, an artifact `{path, sha256}`, a guard
 `{foreign_writes, console_errors}`, a join `{joined: {<source id>: value}}`.
 
+## Probes
+
+A probe is an argv the record tool runs with `cwd` = the app (the tree under review) and this
+environment on top of its own:
+
+| Variable | Value |
+|---|---|
+| `DATA_DIR` | the fixture's data directory (the same one the app writes to) |
+| `PORT` | the port the record tool started the fixture on — a FREE port, chosen per recording |
+| `BASE_URL` | the fixture's origin, `http://127.0.0.1:$PORT` |
+
+Never write the port into the storyline: `fixture.env.PORT` is overridden and a literal
+`http://127.0.0.1:4173/...` in a probe reaches nothing (curl exit 7, the chapter FAILs while the app
+is right). A probe that reads the app over HTTP expands the variable through a shell or a script:
+
+```
+probes: {
+  charges: ["sh", "-c", "curl -sf \"$BASE_URL/charges\""],   // or ["node", "scripts/probe-charges.mjs"] reading process.env.BASE_URL
+},
+```
+
 ## A storyline that passes
 
 ```js

package/skills/mcp-scaffold/SKILL.md

@@ -62,8 +62,9 @@ wicked-garden run scripts/mcp/scaffold.py --name <server-name> [--lang typescrip
 
 The one-file templates answer `initialize` (negotiating the protocol version), `ping`,
 `tools/list` and `tools/call`, ignore notifications, and ship two example tools: `echo`
-(read) and `counter_increment` (write). The TypeScript template ships `echo` (read) plus
-whatever `tools.json` holds. Replace the examples with your own.
+(read) and `counter_increment` (write). The TypeScript template registers what `tools.json`
+holds, and its example `echo` (read) only while `tools.json` is empty. Replace the examples
+with your own.
 
 ## 2. Generate tools from an OpenAPI document (`openapi`)
 
@@ -99,7 +100,9 @@ external `$ref`s are not followed.
   instruments, the per-tool rate limit (`rateLimitPerMin`) and `canAccess: requireSession`.
   Throw `UserError` for a failure the caller should see — it comes back as `isError`.
 - **Generated tools (branch A)** come from `tools.json`: `src/tools/generated.ts` registers
-  each entry with its JSON Schema and the annotations its class implies; calls go through
+  each entry with its JSON Schema (wrapped in fastmcp's `jsonSchemaAdapter` — fastmcp rejects
+  a raw JSON Schema and the server would not start) and the annotations its class implies;
+  an upstream error reaches the caller bounded, with the credential scrubbed; calls go through
   `src/rest.ts` — pinned to `baseUrl`, allowlisted arguments only, no redirects, auth and
   hop-by-hop headers never settable by an argument. **Hand-written tools (branch B)** follow
   `src/tools/example.ts`: a zod schema validated before the handler runs, honest annotations.
@@ -212,7 +215,10 @@ config's `key`:
    variable answers `secret_missing`: the record says `registered: false`, `missing`, and two
    remedies (export it in the daemon's environment and re-run; or studio **MCP tools → Add
    existing** with the secret, stored in the OS keychain). No daemon: `registered: false`
-   with the reason. Re-registering the same key is the update (`registered: "updated"`).
+   with the reason. Re-registering the same key is the update (`registered: "updated"`) —
+   of THIS install only: before anything is staged, a registry entry under the key that is a
+   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.
 7. **Record** `<root>/<key>/installed.json` `{key, version, source, command, args,
@@ -261,7 +267,9 @@ run. Follow `wicked-garden-governed-worker`, and:
 - **scope** — settle what to expose, the auth scheme, the transport (stdio unless a remote
   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. Record whether an OpenAPI
+  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
+  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).
 - **source-discovery** — with an OpenAPI document, run the `openapi` action (step 2) and

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

@@ -35,7 +35,8 @@ registry inject exactly one environment variable into a stdio server. See `.env.
 
 Optional overrides: `MCP_TRANSPORT` (`stdio` | `httpStream`), `MCP_HOST` (default
 `127.0.0.1`), `MCP_PORT`,
-`__SERVER_ENV___BASE_URL`. httpStream requires `MCP_SERVER_BEARER`: every request must carry
+`__SERVER_ENV___BASE_URL` (the path may change, the origin may not: the secret follows the base
+URL, so a different host is a reviewed edit to `mcp-server.config.json`). httpStream requires `MCP_SERVER_BEARER`: every request must carry
 `Authorization: Bearer <it>` or is refused with 401.
 
 ## Telemetry
@@ -50,8 +51,11 @@ Off by default: the OpenTelemetry SDK runs with no exporter unless
 - **Generated (branch A):** `tools.json` holds the tools wicked-crew's conversion service
   derived from an OpenAPI 3 document — run
   `wicked-garden run scripts/mcp/openapi.py --name __SERVER_NAME__ --base-url <url> --spec-url <url> --out .`
-  `src/tools/generated.ts` registers each one; calls go through `src/rest.ts`, pinned to
-  `baseUrl`, allowlisted arguments only, no redirects.
+  `src/tools/generated.ts` registers each one (its JSON Schema wrapped in fastmcp's
+  `jsonSchemaAdapter`, validated with `ajv`); calls go through `src/rest.ts`, pinned to
+  `baseUrl`, allowlisted arguments only, no redirects. An upstream 4xx/5xx reaches the caller
+  as a tool error carrying the status and a bounded body excerpt with the credential scrubbed.
+  The example `echo` tool is registered only while `tools.json` is empty.
 - **Hand-written (branch B):** add a file like `src/tools/example.ts`: a zod schema, honest
   annotations, registered through `defineTool` (span, child logger, metrics, rate limit and
   `canAccess` come with it).

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

@@ -31,6 +31,8 @@
     "@opentelemetry/exporter-trace-otlp-http": "^0.223.0",
     "@opentelemetry/sdk-logs": "^0.223.0",
     "@opentelemetry/sdk-node": "^0.223.0",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
     "fastmcp": "^4.22.4",
     "loglayer": "^9.4.0",
     "zod": "^4.6.5"

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

@@ -62,9 +62,17 @@ export function secretVar(key: string): string {
   return `${envPrefix(key)}_TOKEN`;
 }
 
+function originOf(url: string): string | null {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Load mcp-server.config.json, apply the env overrides (MCP_TRANSPORT, MCP_HOST, MCP_PORT,
- * <SERVER>_BASE_URL) and validate. Fails naming the field — never a value.
+ * <SERVER>_BASE_URL, same origin only) and validate. Fails naming the field — never a value.
  */
 export function loadConfig(env: NodeJS.ProcessEnv = process.env, root: string = SERVER_ROOT): ServerConfig {
   const file = join(root, "mcp-server.config.json");
@@ -79,7 +87,15 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env, root: string =
   if (env.MCP_PORT) raw.port = Number(env.MCP_PORT);
   if (env.MCP_HOST) raw.host = env.MCP_HOST;
   const baseOverride = key ? env[`${envPrefix(key)}_BASE_URL`] : undefined;
-  if (baseOverride) raw.baseUrl = baseOverride;
+  if (baseOverride) {
+    // The upstream credential follows baseUrl, so an override may change the path but never
+    // the origin: repinning egress to another host is a reviewed edit to the committed config.
+    const committed = typeof raw.baseUrl === "string" ? originOf(raw.baseUrl) : null;
+    if (committed === null || originOf(baseOverride) !== committed) {
+      throw new Error(`${envPrefix(key)}_BASE_URL must keep the committed baseUrl origin; edit mcp-server.config.json to change the host`);
+    }
+    raw.baseUrl = baseOverride;
+  }
   const parsed = ConfigSchema.safeParse(raw);
   if (!parsed.success) {
     const issue = parsed.error.issues[0];

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

@@ -27,7 +27,9 @@ async function main(): Promise<void> {
   });
 
   const generated = registerGeneratedTools(server, config, () => upstreamHeaders(config, secret));
-  registerExampleTools(server, config);
+  // 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);
   root.withMetadata({ generated, transport: config.transport }).info("starting");
 
   const stop = async () => {

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

@@ -2,7 +2,7 @@
 // SPDX-FileCopyrightText: __YEAR__ the __SERVER_NAME__ authors
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { UserError, type FastMCP, type ToolParameters } from "fastmcp";
+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";
@@ -34,6 +34,24 @@ export function readToolsJson(root: string = SERVER_ROOT): GeneratedTool[] {
   return Array.isArray(doc.tools) ? doc.tools : [];
 }
 
+/** The most of an upstream error body a caller sees. */
+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.
+ */
+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]");
+  }
+  if (text.length > ERROR_BODY_MAX) text = `${text.slice(0, ERROR_BODY_MAX)}… (truncated)`;
+  return text ? `HTTP ${status}: ${text}` : `HTTP ${status}`;
+}
+
 /** Register every tools.json entry; each call goes through callRest, pinned to the base URL. */
 export function registerGeneratedTools(
   server: FastMCP<Session>,
@@ -45,8 +63,10 @@ export function registerGeneratedTools(
     defineTool(server, config, {
       name: t.name,
       description: t.description ?? t.name,
-      // A plain JSON Schema, exactly as the conversion service derived it from the OpenAPI document.
-      parameters: t.inputSchema as unknown as ToolParameters,
+      // fastmcp takes a Standard Schema, not a plain JSON Schema: a raw schema here makes the
+      // server refuse to start. jsonSchemaAdapter validates the conversion service's schema
+      // with ajv (a direct dependency of this server).
+      parameters: jsonSchemaAdapter(t.inputSchema as JsonSchemaObject) as unknown as ToolParameters,
       annotations: annotationsFor(t.class),
       execute: async (args) => {
         const result = await callRest(t.rest, (args ?? {}) as Record<string, unknown>, {
@@ -55,7 +75,7 @@ export function registerGeneratedTools(
           readOnly: t.class === "read",
         });
         const text = typeof result.body === "string" ? result.body : JSON.stringify(result.body);
-        if (result.status >= 400) throw new UserError(`HTTP ${result.status}: ${text}`);
+        if (result.status >= 400) throw new UserError(upstreamError(result.status, text, await headers()));
         return text;
       },
     });

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

@@ -1,6 +1,8 @@
 // SPDX-License-Identifier: MIT
 // SPDX-FileCopyrightText: __YEAR__ the __SERVER_NAME__ authors
 import { spawn } from "node:child_process";
+import { cpSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createServer as createHttpServer } from "node:http";
 import { createServer } from "node:net";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -15,13 +17,22 @@ function minimalEnv(extra: Record<string, string> = {}): NodeJS.ProcessEnv {
 }
 
 /** Send frames over stdio; resolve with every reply by id once `want` ids answered. */
-function converse(env: NodeJS.ProcessEnv, frames: object[], want: number[]): Promise<Map<number, any>> {
+function converse(env: NodeJS.ProcessEnv, frames: object[], want: number[], server: string = SERVER): Promise<Map<number, any>> {
   return new Promise((resolve, reject) => {
-    const child = spawn(process.execPath, [SERVER], { env, stdio: ["pipe", "pipe", "pipe"] });
+    const child = spawn(process.execPath, [server], { env, stdio: ["pipe", "pipe", "pipe"] });
     const replies = new Map<number, any>();
     let buf = "";
     // Generous: loading fastmcp + the OpenTelemetry SDK takes seconds on a loaded host.
     const timer = setTimeout(() => { child.kill(); reject(new Error(`timed out; got ${[...replies.keys()]}`)); }, 60_000);
+    let stderr = "";
+    child.stderr.on("data", (c: Buffer) => (stderr += c.toString("utf8")));
+    // A server that dies before answering fails fast, naming why (not a 60 s timeout).
+    child.on("exit", (code) => {
+      if (!want.every((id) => replies.has(id))) {
+        clearTimeout(timer);
+        reject(new Error(`server exited (${code}) before answering: ${stderr.slice(0, 500)}`));
+      }
+    });
     child.stdout.on("data", (chunk: Buffer) => {
       buf += chunk.toString("utf8");
       let nl: number;
@@ -83,6 +94,49 @@ describe("stdio conformance", () => {
   });
 });
 
+describe("generated tools (branch A)", () => {
+  // A copy of the built server with a one-tool tools.json, beside node_modules so imports
+  // resolve: proves the server STARTS with generated tools, lists exactly them, and calls one.
+  it("starts with a non-empty tools.json, lists only the generated tools and calls one", async () => {
+    const upstream = createHttpServer((req, res) => {
+      if (req.url === "/v1/notes/n1") res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ id: "n1" }));
+      else res.writeHead(404).end("not found");
+    });
+    await new Promise<void>((r) => upstream.listen(0, "127.0.0.1", r));
+    const dir = mkdtempSync(join(ROOT, ".branch-a-"));
+    try {
+      cpSync(join(ROOT, "dist"), join(dir, "dist"), { recursive: true });
+      const config = JSON.parse(readFileSync(join(ROOT, "mcp-server.config.json"), "utf8"));
+      config.baseUrl = `http://127.0.0.1:${(upstream.address() as { port: number }).port}/v1`;
+      writeFileSync(join(dir, "mcp-server.config.json"), JSON.stringify(config));
+      writeFileSync(join(dir, "tools.json"), JSON.stringify({ tools: [{
+        name: "get_note", description: "Read one note", class: "read",
+        inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+        rest: { method: "GET", pathTemplate: "/notes/{id}", pathMap: { id: "id" }, queryMap: {}, headerMap: {},
+          bodyMap: null, bodyArg: null, argAllowlist: ["id"], timeoutMs: 5000 },
+      }] }));
+      const replies = await converse(minimalEnv({ [SECRET]: "dummy" }), [
+        { id: 1, method: "initialize", params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "conformance", version: "0" } } },
+        { method: "notifications/initialized" },
+        { id: 2, method: "tools/list", params: {} },
+        { id: 3, method: "tools/call", params: { name: "get_note", arguments: { id: "n1" } } },
+        { id: 4, method: "tools/call", params: { name: "get_note", arguments: {} } },
+      ], [1, 2, 3, 4], join(dir, "dist", "server.js"));
+      const tools = replies.get(2).result.tools as Array<{ name: string; inputSchema: { required?: string[] }; annotations?: { readOnlyHint?: boolean } }>;
+      expect(tools.map((t) => t.name)).toEqual(["get_note"]);
+      expect(tools[0]?.annotations?.readOnlyHint).toBe(true);
+      expect(tools[0]?.inputSchema.required).toEqual(["id"]);
+      expect(JSON.parse(replies.get(3).result.content[0].text)).toEqual({ id: "n1" });
+      // The schema is enforced: a call missing a required argument never reaches the upstream.
+      const bad = replies.get(4);
+      expect(bad.error !== undefined || bad.result?.isError === true).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+      await new Promise<void>((r) => upstream.close(() => r()));
+    }
+  });
+});
+
 describe("httpStream", () => {
   it("refuses a request without the bearer with 401", async () => {
     const port = await freePort();

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

@@ -0,0 +1,33 @@
+// 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";
+
+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" });
+    expect(text).toBe("HTTP 401: bad header: [redacted] ([redacted])");
+  });
+
+  it("bounds the body a caller sees", () => {
+    const text = upstreamError(500, "x".repeat(ERROR_BODY_MAX * 3), {});
+    expect(text.length).toBeLessThan(ERROR_BODY_MAX + 40);
+    expect(text).toContain("(truncated)");
+  });
+});
+
+describe("base URL override", () => {
+  const committed = new URL(loadConfig({}).baseUrl);
+
+  it("may move the path on the committed origin", () => {
+    const moved = `${committed.origin}/v2`;
+    expect(loadConfig({ [BASE_VAR]: moved }).baseUrl).toBe(moved);
+  });
+
+  it("refuses another origin: the credential would follow it", () => {
+    expect(() => loadConfig({ [BASE_VAR]: "https://elsewhere.invalid/v1" })).toThrow(/committed baseUrl origin/);
+  });
+});