@cyanheads/mcp-ts-core 0.13.9 → 0.13.11

package/framework-skills/api-utils/SKILL.md

@@ -4,7 +4,7 @@ description: >
   API reference for all utilities exported from `@cyanheads/mcp-ts-core/utils`. Use when looking up utility method signatures, options, peer dependencies, or usage patterns.
 metadata:
   author: cyanheads
-  version: "2.14"
+  version: "2.15"
   audience: external
   type: reference
 ---
@@ -85,7 +85,7 @@ The `utils` export includes two type guards. The full set of guards lives in the
 | Export | API | Notes |
 |:-------|:----|:------|
 | `Logger` | Class | The `Logger` class itself. Use `Logger.getInstance()` if needed; most consumers use the `logger` singleton. |
-| `logger` | `Logger` instance (wraps Pino). `.debug(msg, ctx?)` `.info(msg, ctx?)` `.notice(msg, ctx?)` `.warning(msg, ctx?)` `.error(msg, errorOrCtx, ctx?)` `.crit(msg, errorOrCtx, ctx?)` `.alert(msg, errorOrCtx, ctx?)` `.emerg(msg, errorOrCtx, ctx?)` `.fatal(msg, errorOrCtx, ctx?)` | Global structured logger. Use `ctx.log` in handlers instead. `logger` is for lifecycle/background contexts (startup, shutdown, `setup()`). Auto-redacts sensitive fields. The context's `extra` bag is flattened into the record, but a canonical field the context carries (`requestId`, `timestamp`, `traceId`, `spanId`, `sessionId`, `tenantId`, `operation`) always wins over an `extra` key of the same name. Records logged before the framework initializes the logger — anything in `setup()` — are held in a 250-record buffer and replayed once the sinks exist, filtered against the level the logger starts with. **Note:** `.error()` and higher accept `(msg, Error, ctx?)` or `(msg, ctx?)` — the second arg is overloaded. `.fatal()` is an alias for `.emerg()`. Full RFC 5424 severity set. |
+| `logger` | `Logger` instance (wraps Pino). `.debug(msg, ctx?)` `.info(msg, ctx?)` `.notice(msg, ctx?)` `.warning(msg, ctx?)` `.error(msg, errorOrCtx, ctx?)` `.crit(msg, errorOrCtx, ctx?)` `.alert(msg, errorOrCtx, ctx?)` `.emerg(msg, errorOrCtx, ctx?)` `.fatal(msg, errorOrCtx, ctx?)` `.isLevelEnabled(level) -> boolean` | Global structured logger. Use `ctx.log` in handlers instead. `logger` is for lifecycle/background contexts (startup, shutdown, `setup()`). Auto-redacts sensitive fields. The context's `extra` bag is flattened into the record, but a canonical field the context carries (`requestId`, `timestamp`, `traceId`, `spanId`, `sessionId`, `tenantId`, `operation`) always wins over an `extra` key of the same name. Records logged before the framework initializes the logger — anything in `setup()` — are held in a 250-record buffer and replayed once the sinks exist, filtered against the level the logger starts with. `isLevelEnabled(level)` is that filter: `true` when a record at `level` would be written, compared on the RFC 5424 order of all eight levels (a `notice` level drops `info` though pino emits both at `info`, a `crit` level drops `error`), and `true` for every level before initialization. The `ctx.log` mirror to the client is gated by the same check. **Note:** `.error()` and higher accept `(msg, Error, ctx?)` or `(msg, ctx?)` — the second arg is overloaded. `.fatal()` is an alias for `.emerg()`. Full RFC 5424 severity set. |
 | `McpLogLevel` | Type | Log level union type for typing level variables. |
 
 ---
@@ -175,7 +175,7 @@ Helper API only. For the catalog of what the framework auto-emits (span names, m
 
 ### `telemetry/attributes`
 
-MCP-specific `ATTR_*` constant exports for span and metric attributes. Covers: code execution (`code.function.name`, `code.namespace`), MCP tool execution (name, input/output bytes, duration, success, error code, error category, partial success, batch succeeded/failed counts), MCP resource (URI, name, MIME type, size, duration, success, error code), MCP request context (tenant ID, client ID), MCP session events, MCP storage, GenAI semantic conventions, speech, graph, auth, task, and error classification attributes.
+MCP-specific `ATTR_*` constant exports for span and metric attributes. Covers: code execution (`code.function.name`, `code.namespace`), MCP tool execution (name, input/output bytes, duration, success, error code, error category, partial success, batch succeeded/failed counts), MCP resource (URI, the uncut URI length when the recorded URI was capped, name, MIME type, size, duration, success, error code), MCP request context (tenant ID, client ID), MCP session events, MCP storage, GenAI semantic conventions, speech, graph, auth, task, and error classification attributes.
 
 Batch/partial success attributes (`mcp.tool.partial_success`, `mcp.tool.batch.succeeded_count`, `mcp.tool.batch.failed_count`) are set automatically by the framework when a tool handler returns a result containing a non-empty `failed` array — matching the batch response pattern from the design skill. A tool whose `output` is built with `partialResultSchema()` is read under its `failedKey`/`succeededKey` instead, including after `.extend()`, `.pick()`, `.omit()`, or a `.shape` spread.
 

package/framework-skills/api-workers/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Cloudflare Workers deployment using `createWorkerHandler` from `@cyanheads/mcp-ts-core/worker`. Covers the full handler signature, binding types, CloudflareBindings extensibility, runtime compatibility guards, and wrangler.toml requirements.
 metadata:
   author: cyanheads
-  version: "1.8"
+  version: "1.9"
   audience: external
   type: reference
 ---
@@ -204,6 +204,8 @@ export function getServerConfig() {
 
 **`in-memory` storage is volatile.** Data stored with the `in-memory` provider is lost between cold starts and is not shared across Worker instances. Use `cloudflare-kv`, `cloudflare-r2`, or `cloudflare-d1` for any state that must persist or be shared.
 
+**Multi-round-trip retries land on any isolate.** Each 2026-07-28 request builds its own `McpServer`, and the retry after an `input_required` result can be routed to a different isolate. Set `MCP_REQUEST_STATE_KEY` (≥ 32 bytes) as a Worker secret — it is a core binding, injected like the rest — so every isolate seals and verifies `requestState` with the same key, and keep a consent gate's record (`api-context` § *Consent gates*) in `cloudflare-d1`. `in-memory` loses it to the next isolate, so the retry asks again. Never `cloudflare-kv`: it is eventually consistent, so a retry served elsewhere may not see the record yet, and a deletion may not yet stop an immediate replay — it widens the window concurrent retries already have, since redeeming is not atomic on any provider until `ctx.state` gains a `take` ([#593](https://github.com/cyanheads/mcp-ts-core/issues/593)).
+
 **Node-only utilities throw in Workers.** `scheduler` (`node-cron`), `sanitizePath` (fs-based), and `filesystem` storage provider all throw `ConfigurationError` when called from a Worker. Guard with `runtimeCaps.isNode` or avoid entirely.
 
 **DataCanvas is unavailable in Workers.** DuckDB has no V8-isolate build, so `core.canvas` is always `undefined` on Workers. Setting `CANVAS_PROVIDER_TYPE=duckdb` (the only non-default value) in `wrangler.toml` triggers a fail-closed `ConfigurationError` at init time:

package/framework-skills/code-simplifier/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Cleanup pass that edits the working tree — over a session's uncommitted changes, or a named path or whole codebase. Reads `git diff` (or the named target) and simplifies, consolidates, and aligns code with the existing codebase — modernize syntax, cut unnecessary complexity and slop, consolidate duplicated logic, catch efficiency issues. Not a bug hunt: defects are reported, not fixed. Use after a substantive working session, or when asked to clean up, simplify, reduce slop, consolidate, modernize, tighten up, de-slop, or scan a codebase. For `@cyanheads/mcp-ts-core` projects, includes specific transformations for tool/resource/prompt definitions, the ctx pattern, error factories, and framework idioms.
 metadata:
   author: cyanheads
-  version: "1.6"
+  version: "1.7"
   audience: external
   type: workflow
 ---
@@ -75,7 +75,7 @@ Evaluate the changes across these dimensions. Not every dimension applies to eve
 - **Gate** — `bun run devcheck` plus the test suite (`bun run test`) is the project gate in Phase 2 step 4 and Phase 4 step 5.
 - **Framework-provided utilities** — Before hand-rolling, check `src/utils/` and `src/errors/` in the project and `node_modules/@cyanheads/mcp-ts-core/` for framework exports: pagination helpers, schema builders, retry primitives, and the `ATTR_*` OTel attribute constants are framework-provided. Raw OTel attribute keys should be `ATTR_*` imports from `@cyanheads/mcp-ts-core/utils`.
 - **Error throwing patterns** — Prefer framework error factories (`McpError`, `validationError`, `notFound`, `httpErrorFromResponse`) over raw `throw new Error()`. Tool handlers should throw — the framework catches, classifies, and instruments.
-- **Error codes** — `InvalidParams` only for malformed JSON-RPC params shape. `ValidationError` for domain validation. `NotFound` for missing entities. Don't conflate them.
+- **Error codes** — `InvalidParams` for input the schema rejects (the framework raises it before the handler runs) and for an upstream 400 mapped by `httpErrorFromResponse`. `ValidationError` for a business rule the schema cannot express. `NotFound` for missing entities. Don't conflate them.
 - **Ctx usage** — Use `ctx.log`, `ctx.state`, `ctx.enrich` — don't reach for global loggers or request-scoped storage directly. The `ctx` pattern carries tenant scope and OTel context.
 - **Zod schemas** — Every tool input/output field needs `.describe()`. Zod 4 requires `z.record(z.string(), z.string())` not `z.record(z.string())`. Use `.optional()` rather than `.nullish()` unless null is semantically distinct from absent.
 - **Tool annotations** — `readOnlyHint`, `idempotentHint`, `openWorldHint` should reflect reality. A read-only tool with `readOnlyHint: false` gives clients the wrong picture.

package/framework-skills/design-mcp-server/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Design the tool surface, resources, and service layer for a new MCP server. Use when starting a new server, planning a major feature expansion, or when the user describes a domain/API they want to expose via MCP. Produces a design doc at docs/design.md that drives implementation.
 metadata:
   author: cyanheads
-  version: "2.30"
+  version: "2.31"
   audience: external
   type: workflow
 ---
@@ -263,9 +263,9 @@ A reference tool is the surface's decoder ring: which codes exist, what they mea
 
 Tools that perform multi-step mutations (the Workflow shape) have two safety considerations beyond single-call tools. Both are about giving the agent — and the human behind it — a chance to catch a bad invocation before it commits.
 
-**Confirmation-gated destructive modes, with an annotation fallback.** When a workflow's `mode` parameter switches between safe and destructive arms (`draft` vs `send`, `plan` vs `apply`), gate the destructive arm on a confirmation the handler asks for via `ctx.requestInput(...)`, so a human approves before the irreversible step fires. The handler is re-entered with the answer on `ctx.inputs`; it does not `await` mid-call.
+**Confirmation-gated destructive modes, with an annotation fallback.** When a workflow's `mode` parameter switches between safe and destructive arms (`draft` vs `send`, `plan` vs `apply`), gate the destructive arm on a confirmation the handler asks for via `ctx.requestInput(...)`, so a human approves before the irreversible step fires. The handler is re-entered with the answer on `ctx.inputs`; it does not `await` mid-call. The answer alone does not prove the prompt was shown — a client can send one unasked, and any `requestState` replays within its lifetime — so the gate stores the operation, the caller, the confirmed target, and a hash of what it holds in a `ctx.state` record keyed by a random id, sends only that id as `requestState`, and redeems the record before the destructive arm runs (`api-context` § *Consent gates*). Plan shared storage for that record when a 2026-07-28 retry can reach another instance (`filesystem`, `supabase`, or `cloudflare-d1` — not `cloudflare-kv`), and set `MCP_REQUEST_STATE_KEY` so a retry can only carry state the server minted. Redeeming is not atomic — concurrent retries on one id can each pass the gate until `ctx.state` gains an atomic `take` ([#593](https://github.com/cyanheads/mcp-ts-core/issues/593)) — so an arm that must not run twice is idempotent per record.
 
-The gate is always *reachable* — `ctx.requestInput` is present on every transport and both protocol revisions (2025-11-25 legacy, 2026-07-28 current) — but it is not always *answerable*: a client that never fulfils the `input_required` result simply doesn't retry, and the destructive step never runs. The same holds for a 2025-11-25 HTTP client when the server runs `MCP_SESSION_MODE=stateless`: the legacy round-trip shim still runs, but its capability gate refuses because the serving instance never processed `initialize` — the destructive step never fires. That is the safe outcome, but it makes the tool unusable for those clients, so a server built around such a gate declares `createApp({ sessionMode: { default: 'stateful', require: 'stateful' } })` and refuses to start stateless rather than degrading (`api-context` § `ctx.requestInput`). Keep `destructiveHint: true` in annotations so those clients' own approval flows still surface the risk. A decline is terminal — the handler fails the call rather than re-asking, which would loop until the round budget runs out. The handler shape is in `api-context` § *The shape of a multi-round-trip handler*.
+The gate is always *reachable* — `ctx.requestInput` is present on every transport and both protocol revisions (2025-11-25 legacy, 2026-07-28 current) — but it is not always *answerable*: a client that never fulfils the `input_required` result simply doesn't retry, and — with the record pattern, which proceeds only on a record it redeemed — the destructive step never runs. The same holds for a 2025-11-25 HTTP client when the server runs `MCP_SESSION_MODE=stateless`: the legacy round-trip shim still runs, but its capability gate refuses because the serving instance never processed `initialize` — the destructive step never fires. That is the safe outcome, but it makes the tool unusable for those clients, so a server built around such a gate declares `createApp({ sessionMode: { default: 'stateful', require: 'stateful' } })` and refuses to start stateless rather than degrading (`api-context` § `ctx.requestInput`). Keep `destructiveHint: true` in annotations so those clients' own approval flows still surface the risk. A decline is terminal — the handler fails the call rather than re-asking, which would loop until the round budget runs out. `ctx.clientCapabilities` never decides whether to ask: a gate that skips its prompt when `elicitation` is undeclared is the bypass the gate exists to prevent.
 
 **Safe defaults on parameters that determine blast radius.** When a workflow accepts a parameter that controls how far-reaching a mutation is, default to the safer value. A bulk file-update tool defaulting `mode: 'preview'` (no writes) means a sloppy agent call shows a diff rather than blasting changes; an apply-plan tool defaulting `dryRun: true` means a misread plan previews rather than executes; an object-delete tool requiring an explicit `confirmCount` matching the result-set size means an unscoped query can't silently nuke a million rows. Agents that genuinely want the destructive behavior have to name it explicitly, which surfaces intent in the tool call and in logs.
 
@@ -423,7 +423,7 @@ Two params, two behaviors — keep them named distinctly:
 
 Errors are part of the tool's interface — design them during the design phase, not as an afterthought. Three aspects: **the contract** (which failures are public), **classification** (what error code), and **messaging** (what the LLM reads).
 
-**Declare a typed contract for domain failures.** When a tool has known failure modes the agent should plan around (`no_match`, `queue_full`, `vendor_down`), enumerate them as `errors: [{ reason, code, when, recovery, retryable? }]` on the definition. `recovery` is required metadata — the agent's next move when this failure fires (≥ 5 words, lint-validated; spread `ctx.recoveryFor('reason')` into the throw-site `data` to send it on the wire as `data.recovery.hint`). The framework types `ctx.fail(reason, …)` against the declared reason union (typos become TS errors) and auto-populates `data.reason` on the thrown error for stable observability. The error reaches clients with parity across both surfaces — `structuredContent.error` (Claude Code) and `content[]` text (Claude Desktop). Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble from anywhere and don't need to be enumerated. Mark an entry the service layer throws, rather than the handler, with `thrownBy: 'service'` so the conformance lint doesn't report it as a reason the handler never raises. See `api-errors` skill for the full pattern.
+**Declare a typed contract for domain failures.** When a tool has known failure modes the agent should plan around (`no_match`, `queue_full`, `vendor_down`), enumerate them as `errors: [{ reason, code, when, recovery, retryable? }]` on the definition. `recovery` is required metadata — the agent's next move when this failure fires (≥ 5 words, lint-validated; the framework sends it on the wire as `data.recovery.hint` with any failure carrying that reason and no hint of its own). The framework types `ctx.fail(reason, …)` against the declared reason union (typos become TS errors) and auto-populates `data.reason` on the thrown error for stable observability. The error reaches clients with parity across both surfaces — `structuredContent.error` (Claude Code) and `content[]` text (Claude Desktop). Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`, `RequestCancelled`) bubble from anywhere and don't need to be enumerated. Mark an entry the service layer throws, rather than the handler, with `thrownBy: 'service'` so the conformance lint doesn't report it as a reason the handler never raises. See `api-errors` skill for the full pattern.
 
 **Classify errors by origin.** Different error sources need different codes and different recovery guidance. Map the failure modes for each tool during design:
 
@@ -702,7 +702,7 @@ Items without an `If …:` prefix apply to every design. Conditional items only
 - [ ] **If the server has workflow tools:** call-flow documented (upstream sequence + mode arms) in design doc's Workflow Analysis
 - [ ] **If state-aware procedural guidance adds value:** instruction tool considered with `nextToolSuggestions` pre-filled from diagnostics
 - [ ] **If any tool is config-gated:** nothing routes to it while the gate is off — recovery strings, notices, and `guidance` name a callable target or state the capability is unavailable, and structured follow-ups naming it are emitted only under the config that registers it
-- [ ] **If workflow tools have destructive modes:** destructive arm gated on a `ctx.requestInput` confirmation read back from `ctx.inputs`, with `destructiveHint` annotation so clients that never fulfil the round still surface the risk
+- [ ] **If workflow tools have destructive modes:** destructive arm gated on a `ctx.requestInput` confirmation that redeems a `ctx.state` consent record bound to the operation, caller, and target (shared storage when retries can reach another instance, `MCP_REQUEST_STATE_KEY` set, an arm that must not run twice idempotent per record), with `destructiveHint` annotation so clients that never fulfil the round still surface the risk
 - [ ] **If any tool calls `ctx.requestInput`:** `createApp()` declares `sessionMode` with `require: 'stateful'`
 - [ ] **If any output carries text other people wrote:** those fields listed, `format()` quotes or fences free text and flattens CR/LF in inline slots, and the server instructions say the content is data
 - [ ] **If a parameter determines blast radius:** safe default set (e.g., `mode: 'preview'`, `dryRun: true`, `confirmCount` required)

package/framework-skills/field-test/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: field-test
 description: >
-  Exercise tools, resources, and prompts against a live HTTP server via MCP JSON-RPC over curl. Starts the server, surfaces the catalog, runs real and adversarial inputs, measures every call (bytes, token estimate, wall-clock) and weighs the catalog, and produces a tight report with concrete findings and numbered follow-up options. Use after adding or modifying definitions, or when the user asks to test, try out, or verify their MCP surface.
+  Exercise tools, resources, and prompts against a live HTTP server via MCP JSON-RPC over curl. Starts the server, surfaces the catalog, runs real and adversarial inputs, measures every call (bytes, token estimate, wall-clock) and weighs the catalog, renders app tools' views in a headless MCP Apps host, and produces a tight report with concrete findings and numbered follow-up options. Use after adding or modifying definitions, or when the user asks to test, try out, or verify their MCP surface.
 metadata:
   author: cyanheads
-  version: "2.17"
+  version: "2.19"
   audience: external
   type: debug
 ---
@@ -413,6 +413,7 @@ Treat any hit as a `ux` finding in the report. The authoring rule lives under *T
 | Tool declared an `errors: [...]` contract | Error contract (tool): trigger ≥1 declared failure mode. Verify `result.structuredContent.error.code` matches the contract entry, `result.structuredContent.error.data.reason` is the declared reason (only present when the handler threw an `McpError` — `ctx.fail` always does, plain `throw new Error(...)` does not), and `content[0].text` is actionable. Reasons declared but unreachable from any input are dead contract entries. |
 | Resource declared an `errors: [...]` contract | Error contract (resource): trigger ≥1 declared failure mode by reading a URI that exercises it. Resources re-throw errors at the JSON-RPC level — verify `error.code` matches the contract entry and `error.data.reason` is the declared reason. (Resources don't use the `result.isError` envelope — they fail the request itself.) |
 | Mutator (write/update/delete/append/patch verbs, or `destructiveHint: true`) | Mutator response observability: run an intentionally-ambiguous input (typo path, wrong ID, already-deleted target). Confirm the response carries enough state (pre/post values, state-change discriminator) for the agent to detect intent-effect divergence without re-fetching. |
+| `_meta.ui.resourceUri` on the tool (an app tool) | View rendering: Step 6. The curl calls see only the `format()` text and the view's raw HTML; whether the view runs is visible only when it is rendered. |
 
 **Resources.** Happy path, not-found URI (use a syntactically valid but non-existent ID — e.g., substitute a fake ID into the URI template), `list` if defined, pagination if used.
 **Prompts.** Happy path, defaults omitted, skim message quality.
@@ -430,28 +431,71 @@ Use `TaskCreate` — one task per definition. Mark complete as you go. Don't bat
 
 For each call, capture: input sent, the `⏱` line (bytes, split, ms), response (trim huge payloads to files), whether `isError: true` appeared, anything surprising (slow response, parity drift, unhelpful text, crash).
 
-When a call surprises you — slow, hangs, returns terse output, surfaces an unhelpful error — run `. /tmp/<project-name>-field-test-<ID>.sh && mcp_log <log>` to tail the server log. The pino startup banner, request handler errors, upstream API call traces, and rate-limit warnings all land in the per-server log (read via `mcp_log`) rather than coming back through `mcp_call`. Don't guess at runtime behavior from response text alone.
+When a call surprises you — slow, hangs, returns terse output, surfaces an unhelpful error — run `. /tmp/<project-name>-field-test-<ID>.sh && mcp_log <log>` to tail the server log. The pino startup banner, request handler errors, upstream API call traces, and rate-limit warnings all land in the per-server log (read via `mcp_log`) rather than coming back through `mcp_call`. Don't guess at runtime behavior from response text alone. To count upstream requests from the log, start the server with `MCP_LOG_RATE_LIMIT_THRESHOLD=0`: by default the logger drops a message repeated past its per-window threshold and reports it later as a `Suppressed N` line, so a count read mid-run comes up short.
 
 **Interpreting responses**
 
 - **`content[]` is an array of blocks — read all of them, never just `content[0]`.** A success result is assembled as `[...ctx.content media blocks, ...the format()/JSON domain render, ...the enrichment trailer]`. Everything the handler put on `ctx.enrich` — empty-result notices, totals, query echoes, truncation disclosure — renders in that trailer, a **separate trailing block**, not inside the `format()` block. Quoting `content[0].text` and reporting those fields as absent from `content[]` is a false parity gap; the suggested fix (render them in `format()` too) would double-render them. Dump `.result.content` in full before claiming drift.
 - Tool domain errors return `{result: {content: [...], isError: true}}` — they live in `result`, not `error`. Check `isError`, not the JSON-RPC error field.
-- **Tool error code/reason** rides on `result.structuredContent.error.{code, message, data?.reason}` — inspect that, not just the text. `data` is only spread when the handler threw an `McpError` (or `ZodError`); plain `throw new Error(...)` won't populate `data.reason`. Use `ctx.fail`-thrown errors when the contract reason matters. The text in `result.content[0].text` mirrors the message, adds `Recovery: <hint>` when `data.recovery.hint` says something the message does not already say, and closes with `(reason <reason> · not retryable)` for whichever of `data.reason` / `data.retryable` is present — the numeric code stays JSON-only.
+- **Tool error code/reason** rides on `result.structuredContent.error.{code, message, data?.reason}` — inspect that, not just the text. `data` carries what the handler threw as an `McpError` (or a `ZodError`'s issues) plus the framework's `data.requestId`; plain `throw new Error(...)` won't populate `data.reason`. Use `ctx.fail`-thrown errors when the contract reason matters — a declared reason arrives with its contract `recovery` as `data.recovery.hint` even when the throw site passed none. The text in `result.content[0].text` mirrors the message, adds `Recovery: <hint>` when `data.recovery.hint` says something the message does not already say, and closes with `(reason <reason> · not retryable · request <id>)` for whichever of `data.reason` / `data.retryable` / `data.requestId` is present — the numeric code stays JSON-only. The request id matches the `requestId` on that call's server log records.
 - **Resource errors** are JSON-RPC-level — they appear in the top-level `error.{code, data.reason}` field, not inside `result`. Resource handlers re-throw rather than producing an `isError` envelope.
 - JSON-RPC `error` only appears for protocol issues (bad session, malformed envelope, unknown method).
 - `mcp_call` already strips SSE framing. Pipe to `jq` for readability.
 
-### 6. Tear down
+### 6. Render app views
+
+Skip this step when no tool carries `_meta.ui.resourceUri`. List the app tools:
+
+```bash
+. /tmp/<project-name>-field-test-<ID>.sh
+mcp_call <url> <sid> tools/list '' <protocol> | jq -r '.result.tools[] | select(._meta.ui.resourceUri) | .name'
+```
+
+Render each one with `mcp-ts-core app-render` against the Step 1 server. It connects as an MCP Apps client, calls the tool, loads the `ui://` view into headless `chrome-headless-shell` inside the double-iframe sandbox and CSP the MCP Apps spec prescribes, plays the host half of the protocol, and writes `report.json` plus screenshots under `--out`. No window opens.
+
+```bash
+bunx @cyanheads/mcp-ts-core app-render --url <url> --tool <app_tool> --args '<happy-path JSON>' \
+  --click '<selector>' --out /tmp/<project-name>-field-test-<ID>-apps/<app_tool> > /dev/null; echo "exit=$?"
+jq '{initialized, failure, toolError, errors, cspViolations, size, steps, text}' \
+  /tmp/<project-name>-field-test-<ID>-apps/<app_tool>/report.json
+```
+
+The report also goes to stdout; read the file instead, since `messages` grows with every exchange. Pass one `--click` per control whose handler matters (a screenshot follows each), run a second pass with `--theme dark` when the view applies host theming, and add `--stream-input` when it renders partial input. Fill, wait-for, and evaluate steps need `renderAppTool` from `@cyanheads/mcp-ts-core/testing/apps` in a script; it returns the same report.
+
+**A setup failure exits 1** with `app-render: <reason>` on stderr and writes no report:
+
+| Reason names | Meaning |
+|:-------------|:--------|
+| A missing optional peer | `@modelcontextprotocol/client` or `@modelcontextprotocol/ext-apps` is not installed. With the user's go-ahead, `bun add -d` it; otherwise record app views as `skipped — requires <package>`. |
+| No browser, or a browser path | No usable `chrome-headless-shell`. With the user's go-ahead, `npx @puppeteer/browsers install chrome-headless-shell@stable --path ~/.cache/puppeteer` (without `--path` it installs into the working directory, where the host never looks), or pass an existing build with `--browser`; otherwise record `skipped — requires chrome-headless-shell`. Never point `--browser` at a desktop browser. |
+| The server is unreachable | Wrong URL, or the Step 1 server died — `mcp_log <log>`. |
+| No such tool, no UI resource, an unreadable UI resource, or a `_meta.ui.csp` entry | A server finding (`bug`): the tool is unregistered, its `resourceUri` is missing, `resources/read` on the `ui://` URI fails, or a CSP domain entry is not a plain origin. |
+
+**A view failure exits 0**: the run reached the browser, and the report says what the view did. Read every field:
+
+- **`initialized`** — the view completed `ui/initialize`. `false`, with `failure` naming the timeout, means the view never connected: a script threw before `app.connect()` (see `errors`), the CSP blocked its SDK import (see `cspViolations`), or the HTML does not use the ext-apps `App` class. `bug`.
+- **`toolError`** — the tool call failed at the protocol level, so the view received `tool-cancelled` instead of a result.
+- **`errors`** — uncaught exceptions and console errors, each tagged with its `frame`. A `view` entry is the server's own UI code: `bug`. `sandbox`, `host`, and `unknown` entries come from the host pages, not the server; report them apart from the server's findings.
+- **`cspViolations`** — loads the view's CSP blocked, as `directive` + `blockedURI`. An origin the view needs but its resource's `_meta.ui.csp` omits (`resourceDomains` for scripts, styles, images, fonts, and media; `connectDomains` for fetch and WebSocket; `frameDomains` for iframes) is a `bug`, because a spec-conformant host blocks the same load. `blockedURI: "eval"` means the view calls `eval` or `new Function`, which the policy never allows. An `eval` entry whose `sourceURL` points into the ext-apps bundle (`app-with-deps.js`) is Zod's guarded capability probe, which catches the refusal, not the view's own code, so it is no finding.
+- **`messages`** — every message between view and host, in order, with its `direction`. A healthy run opens `view-to-host` `ui/initialize` → `ui/notifications/initialized`, then `host-to-view` `ui/notifications/tool-input` → `ui/notifications/tool-result`. A click that should reach the server shows a `view-to-host` `tools/call` and its `host-to-view` response; an `error` there is the server's rejection, or the host refusing a tool whose `_meta.ui.visibility` excludes `app`. Requests that need a user or a model (`ui/message`, `ui/open-link`, `ui/update-model-context`, `ui/request-display-mode`) are recorded and acknowledged — check their params carry what the control meant to send.
+- **`steps`** — one entry per click and screenshot; `ok: false` with `No element matches <selector>` means the control is missing from the rendered view.
+- **`text` and the screenshots** — the rendered text after the steps, and the PNGs (`final.png`, one per click). Open them: a blank, unstyled, clipped, or unreadable-in-dark view is a `ux` finding even when every field above is clean, and so is data in the tool result's `structuredContent` that the view never shows.
+- **`size`** — the view's last `ui/notifications/size-changed`. Absent means the view never reports its size, so a host cannot fit its frame to it: `ux`.
+
+The harness stops the browser and deletes its profile itself; the `--out` directories are removed in Step 7.
+
+### 7. Tear down
 
 ```bash
 . /tmp/<project-name>-field-test-<ID>.sh
 mcp_stop <pid> <log> <port>
+rm -rf /tmp/<project-name>-field-test-<ID>-apps
 rm -f /tmp/<project-name>-field-test-<ID>.sh
 ```
 
-Kills the background server and its port-holding child, removes the server log, then removes the helper script itself. Do this *before* writing the report so nothing leaks into the next session. Pass the `port` — it's what turns "the wrapper PID is gone" into "the socket is actually free." If `mcp_stop` warns the port is still held or the PID survived SIGKILL, note it in the report and proceed — don't block on a zombie process, but do say which PID to kill.
+Kills the background server and its port-holding child, removes the server log and any app-render output, then removes the helper script itself. Do this *before* writing the report so nothing leaks into the next session. Pass the `port` — it's what turns "the wrapper PID is gone" into "the socket is actually free." If `mcp_stop` warns the port is still held or the PID survived SIGKILL, note it in the report and proceed — don't block on a zombie process, but do say which PID to kill.
 
-### 7. Report
+### 8. Report
 
 Four sections. Tight. The user should be able to skim the summary, scan the numbers, read details only for what matters, and act on numbered options.
 
@@ -514,5 +558,6 @@ End with:
 - [ ] **If a resource declared an `errors: [...]` contract:** ≥1 declared failure mode triggered; top-level JSON-RPC `error.code` and `error.data.reason` verified against the contract entry
 - [ ] **If any tool truncates, caps, or spills its output:** truncation forced; disclosure + a retrieval path (cursor, offset, selector, canvas handle) verified
 - [ ] External-state / auth-gated tools handled explicitly (run, skip, or confirm)
-- [ ] Server stopped (port confirmed free); server log and helper script removed
+- [ ] **If any tool carries `_meta.ui.resourceUri`:** each view rendered with `app-render` (Step 6); `initialized`, `errors`, `cspViolations`, the message log, and the screenshots checked; a missing peer or browser recorded as skipped, not as a server finding
+- [ ] Server stopped (port confirmed free); server log, app-render output, and helper script removed
 - [ ] Report: summary paragraph → size & latency table → grouped findings → numbered options

package/framework-skills/git-wrapup/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Land working-tree changes as logical commits — the work grouped by concern, topped by a release commit (version bump, changelog, regenerated artifacts). The work commits land first, then the version bump, verification, and the release commit on top. Stops at "committed locally on main" — or, when the project releases through a release PR, at "release branch pushed, PR open". No tag, no push to main, no publish: the release-and-publish skill merges, tags, and ships from here. Distilled from the git_wrapup_instructions protocol.
 metadata:
   author: cyanheads
-  version: "1.27"
+  version: "1.28"
   audience: external
   type: workflow
 ---
@@ -173,7 +173,7 @@ security: false    # true ONLY for a security fix in this server's own source
 ---
 ```
 
-**Write `summary:` LAST, derived from the body you just wrote — never independently.** It is the line most readers see: `changelog:build` copies it verbatim into the `CHANGELOG.md` rollup, which ships inside the npm tarball, and in release PR mode it opens the PR body. Written from recollection rather than from the body, it reliably names a mechanism that was never built or a target that was never fixed, while the body beside it stays correct. After writing it, re-read the body and confirm every claim in the summary appears there. Derived-from-the-body means the facts come from the body — not that every body item appears: it is one headline, and comma-stitching every change into an inventory near the 350-char cap is the failure mode.
+**Write `summary:` LAST, derived from the body you just wrote — never independently.** It is the line most readers see: `changelog:build` copies it verbatim into the `CHANGELOG.md` rollup, the entry file ships inside the npm tarball (`changelog/` is in `package.json` `files`; the rollup is not), and in release PR mode it opens the PR body. Written from recollection rather than from the body, it reliably names a mechanism that was never built or a target that was never fixed, while the body beside it stays correct. After writing it, re-read the body and confirm every claim in the summary appears there. Derived-from-the-body means the facts come from the body — not that every body item appears: it is one headline, and comma-stitching every change into an inventory near the 350-char cap is the failure mode.
 
 **`security:` is a source-code signal — not a dependency-CVE signal.** Set `security: true` only when this release fixes a vulnerability or adds hardening in code *this server ships*. A dependency or transitive CVE bump — even one that clears an advisory (`bun audit` going 1 → 0) — is routine maintenance: record it under `## Dependencies` with the advisory ID and leave the flag `false`. The `🛡️ Security` badge answers "does the server itself have a vuln"; a dep bump must not trip it.
 

package/framework-skills/orchestrations/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Pick and run a multi-phase workflow that chains foundational task skills (`git-wrapup`, `release-and-publish`, `maintenance`, `field-test`, `setup`, etc.) end-to-end. Routes user intent to a workflow file under `workflows/` — greenfield builds, maintenance + release, field-test + fix, or known-work + release. Single source for the universal rules (no commits without authorization, no destructive git, no marketing language), the orchestrator posture (own the goal, ground sub-agents in primary sources, verify against the goal), and the sub-agent strategy (orient block, parallel fanout, isolation, normalization) that apply across every workflow. Sub-agents are an optional capability — workflows run linearly when fanout isn't available.
 metadata:
   author: cyanheads
-  version: "1.12"
+  version: "1.13"
   audience: external
   type: workflow
 ---

package/framework-skills/orchestrations/workflows/greenfield-build.md

@@ -4,7 +4,7 @@ description: >
   Workflow: scaffold one or more new MCP server projects from `bunx @cyanheads/mcp-ts-core init` through design → build → polish → first public release. Each phase invokes a foundational skill end-to-end; this file is the sequencing and gates, not the procedural detail. Read `../SKILL.md` first for the universal rules and sub-agent strategy.
 metadata:
   author: cyanheads
-  version: "1.3"
+  version: "1.4"
   audience: external
   type: workflow
 ---
@@ -85,7 +85,7 @@ Sub-agent runs `bunx @cyanheads/mcp-ts-core init <name>`, follows the `setup` sk
 ### Phase 2: Initial commit
 Sub-agent verifies `gh repo view --json visibility` returns `PRIVATE` (or has explicit user authorization for public) before push. Tag is `v0.1.0`.
 
-A private repository without GitHub Advanced Security has no code scanning, so the scaffolded `.github/workflows/codeql.yml` fails on every push until the repo is public. Keep the file. GitHub registers the workflow on the first push, and that push already runs it. Right after this push, disable it with `gh workflow disable CodeQL` and delete that failed run with `gh run delete <id>`. It stays disabled through the private checkpoints. Phase 18 turns it back on.
+A private repository without GitHub Advanced Security has no code scanning, so the scaffolded `.github/workflows/codeql.yml` fails on every push until the repo is public. Keep the file. GitHub registers the workflow on the first push, and that push already runs it. Right after this push, disable it with `gh workflow disable CodeQL` and cancel that run with `gh run cancel <id>` before it fails. Keep the cancelled run: deleting a workflow's only run unregisters the workflow, and the next push registers it again as active and runs it. It stays disabled through the private checkpoints; after each checkpoint push, confirm that `gh api repos/<owner>/<repo>/actions/workflows` still shows it `disabled_manually`. Phase 18 turns it back on.
 
 ### Checkpoint commits (Phases 2, 5, 10, 16)
 Plain commits on `main`, pushed to the private repo. They follow `git-wrapup`'s step 3 conventions — grouped by concern, staged and committed by pathspec, one- or two-line bodies — and nothing else from that skill: no version bump, no changelog entry, no release branch or PR. Run end to end, `git-wrapup` bumps the version and, when the project declares a release PR mode, moves the work to `release/<version>` and opens a PR; that belongs to Phase 17 alone. Only Phase 2 tags (`v0.1.0`, annotated, `--cleanup=whitespace`).

package/framework-skills/polish-docs-meta/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Finalize documentation and project metadata for a ship-ready MCP server. Use after implementation is complete, tests pass, and devcheck is clean. Safe to run at any stage — each step checks current state and only acts on what still needs work.
 metadata:
   author: cyanheads
-  version: "2.20"
+  version: "2.22"
   audience: external
   type: workflow
 ---
@@ -95,6 +95,7 @@ Key sync points:
 - `description` matches `package.json` description
 - `environmentVariables` reflect the server config Zod schema — server-specific required vars in both entries, transport vars only in HTTP entry
 - Two package entries: one for stdio, one for HTTP (if both transports supported)
+- npm entries carry `runtimeHint: "npx"` and no `packageArguments` — a registry client runs the package's bin, which ignores `run start:*` arguments; the HTTP entry fixes `MCP_TRANSPORT_TYPE` as `"value": "http"`, never as a `default`. `lint:packaging` fails the arguments and a missing or wrong transport value
 
 ### 7. GitHub Repository Metadata
 
@@ -204,7 +205,7 @@ If the project ships as an `.mcpb` bundle for Claude Desktop (check for `manifes
 **`package.json` scripts:**
 
 - `bundle` — builds the `.mcpb` (`mcpb pack`, then `scripts/clean-mcpb.ts` prunes dev deps and strips dependency-shipped agent docs)
-- `lint:packaging` — validates `manifest.json` ↔ `server.json` env var consistency, version parity for `manifest.json`, the plugin manifests, and the README badge, and the Dockerfile build stage (run by `devcheck`, which gates the step on `manifest.json`, a plugin manifest, `.mcpbignore`, `README.md`, or `Dockerfile`)
+- `lint:packaging` — validates `manifest.json` ↔ `server.json` env var consistency, version parity for `manifest.json`, the plugin manifests, and the README badge, the launch shape of `server.json` npm entries (no `run start:*` arguments; a `streamable-http` entry sets `MCP_TRANSPORT_TYPE` to `"value": "http"`), and the Dockerfile's stages: a stage not pinned to `$BUILDPLATFORM` must not run JavaScript while building — no `bun run build`, `bun -e`, or script, and no `bun install` once `bunfig.toml` is in the stage (run by `devcheck`, which gates the step on `manifest.json`, a plugin manifest, `.mcpbignore`, `README.md`, `Dockerfile`, or `server.json`)
 
 **Cross-file consistency:**
 
@@ -270,7 +271,7 @@ Both must pass clean.
 - [ ] Agent protocol file accurate — no stale template content, real examples, structure matches reality
 - [ ] `.env.example` in sync with server config schema
 - [ ] `package.json` metadata complete (`description`, `mcpName`, `repository`, `author`, `keywords`, `engines`, `packageManager`)
-- [ ] `server.json` matches official MCP schema, versions synced, env vars current
+- [ ] `server.json` matches official MCP schema, versions synced, env vars current; npm entries launch through `npx` with no arguments, and the HTTP entry fixes `MCP_TRANSPORT_TYPE` as `"value": "http"`
 - [ ] GitHub repo description matches `package.json` description; topics ↔ keywords in sync
 - [ ] `bunfig.toml` present
 - [ ] Changelog current — either monolithic `CHANGELOG.md` (hand-edited, Keep a Changelog) or directory-based (`changelog/<minor>.x/<version>.md` + rollup regenerated and in sync)

package/framework-skills/polish-docs-meta/references/server-json.md

@@ -31,12 +31,8 @@ The manifest uses the official MCP schema. A typical server has two package entr
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@org-name/my-mcp-server",
-      "runtimeHint": "bun",
+      "runtimeHint": "npx",
       "version": "1.0.0",
-      "packageArguments": [
-        { "type": "positional", "value": "run" },
-        { "type": "positional", "value": "start:stdio" }
-      ],
       "environmentVariables": [
         {
           "name": "ACME_API_KEY",
@@ -60,12 +56,8 @@ The manifest uses the official MCP schema. A typical server has two package entr
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@org-name/my-mcp-server",
-      "runtimeHint": "bun",
+      "runtimeHint": "npx",
       "version": "1.0.0",
-      "packageArguments": [
-        { "type": "positional", "value": "run" },
-        { "type": "positional", "value": "start:http" }
-      ],
       "environmentVariables": [
         {
           "name": "ACME_API_KEY",
@@ -73,6 +65,12 @@ The manifest uses the official MCP schema. A typical server has two package entr
           "format": "string",
           "isRequired": true
         },
+        {
+          "name": "MCP_TRANSPORT_TYPE",
+          "description": "Selects the HTTP transport.",
+          "format": "string",
+          "value": "http"
+        },
         {
           "name": "MCP_HTTP_HOST",
           "description": "The hostname for the HTTP server.",
@@ -140,9 +138,9 @@ Each entry in `packages[]` describes one way to install and run the server:
 | `registryType` | Yes | `"npm"` for npm packages. |
 | `registryBaseUrl` | Yes | `"https://registry.npmjs.org"` for npm. |
 | `identifier` | Yes | The npm package name (e.g., `@org/my-server`). |
-| `runtimeHint` | No | `"bun"` or `"node"`. Tells clients which runtime to use. |
+| `runtimeHint` | No | `"npx"` for npm packages, the registry's runner for npm. A client that runs the hint as the command launches `<runtimeHint> <identifier>@<version>`, so `"node"` or `"bun"` there names a file path that does not exist. |
 | `version` | Yes | Package version. Must match top-level `version`. |
-| `packageArguments` | No | Array of `{ "type": "positional", "value": "..." }` args passed after the package command. |
+| `packageArguments` | No | Arguments appended to the launch command. Omit it: a framework server's bin reads none (see Package Arguments). |
 | `environmentVariables` | No | Array of env var descriptors (see below). |
 | `transport` | Yes | `{ "type": "stdio" }` or `{ "type": "streamable-http", "url": "..." }` |
 
@@ -154,28 +152,28 @@ Each entry in `packages[]` describes one way to install and run the server:
 | `description` | Yes | Human-readable purpose. |
 | `format` | No | `"string"` (default). |
 | `isRequired` | No | `true` if the server won't start without it. |
-| `default` | No | Default value if not set. |
+| `default` | No | Value used when the user sets none. The user can change it. |
+| `value` | No | Fixed value the client always sets; the user cannot change it. Use it for a setting the entry depends on, such as `MCP_TRANSPORT_TYPE` on the HTTP entry. |
 
 ### Package Arguments
 
-The `packageArguments` array tells clients what args to pass when running the package. For `bun run start:stdio`:
-
-```json
-"packageArguments": [
-  { "type": "positional", "value": "run" },
-  { "type": "positional", "value": "start:stdio" }
-]
-```
+A registry client launches an npm entry as `npx <identifier>@<version> <packageArguments>`, with the entry's `environmentVariables` set. That runs the package's bin (`dist/index.js`), not an npm script, and the bin reads no arguments: it takes its transport from `MCP_TRANSPORT_TYPE`. Leave `packageArguments` out. A `run` + `start:stdio` / `start:http` pair is npm-script syntax that reaches the bin as argv it ignores, and `lint:packaging` rejects it on any npm entry.
 
 ### Transport Patterns
 
-**stdio only** (one package entry):
+**stdio only** (one package entry). stdio is the framework's default transport, so the entry needs no transport variable:
 
 ```json
 "transport": { "type": "stdio" }
 ```
 
-**stdio + HTTP** (two package entries): One entry with `start:stdio` and `{ "type": "stdio" }`, another with `start:http` and `{ "type": "streamable-http", "url": "http://localhost:{port}/mcp" }`. The HTTP entry includes additional env vars for host, port, endpoint path, and auth mode.
+**stdio + HTTP** (two package entries): the stdio entry above, plus an entry with `{ "type": "streamable-http", "url": "http://localhost:{port}/mcp" }` that fixes the transport in its `environmentVariables`:
+
+```json
+{ "name": "MCP_TRANSPORT_TYPE", "description": "Selects the HTTP transport.", "format": "string", "value": "http" }
+```
+
+Use `value`, not `default`: a default is user-editable, and without the variable the server starts on stdio. `lint:packaging` fails a `streamable-http` npm entry that does not set it to `"http"`. The HTTP entry also carries env vars for host, port, endpoint path, and auth mode.
 
 ## Generating / Updating
 
@@ -187,9 +185,9 @@ If `server.json` doesn't exist, create it from the surface area audit. If it exi
 4. Set `repository` from `package.json` repository URL, with `"source": "github"`
 5. Create package entries — one for stdio, one for HTTP (if the server supports both transports)
 6. Set `identifier` to the npm package name from `package.json`
-7. Set `runtimeHint` to `"bun"`
-8. Set `packageArguments` for each transport (`start:stdio`, `start:http`)
-9. Populate `environmentVariables` — server-specific required vars in both entries, transport-specific vars (host, port, endpoint, auth) only in the HTTP entry, `MCP_LOG_LEVEL` in both
+7. Set `runtimeHint` to `"npx"`
+8. Leave out `packageArguments` — the bin takes its transport from `MCP_TRANSPORT_TYPE`, not from arguments
+9. Populate `environmentVariables` — server-specific required vars in both entries, `MCP_TRANSPORT_TYPE` with `"value": "http"` and the transport-specific vars (host, port, endpoint, auth) only in the HTTP entry, `MCP_LOG_LEVEL` in both
 10. All three `version` fields (top-level, and each package entry) must be identical and match `package.json`
 
 ## Keeping in Sync

package/framework-skills/release-and-publish/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Ship a release end-to-end across every registry the project targets (npm, MCP Registry, GitHub Releases for `.mcpb` bundles, GHCR). Runs the final verification gate, fast-forwards `main` when the release rode a release PR, creates the annotated tag on the commit `main` now points at, pushes commits and tags, then publishes to each applicable destination. Assumes git wrapup (version bumps, changelog, commit stack — and in release PR mode, the pushed branch and open PR) is already complete — this skill is the post-wrapup merge + tag + publish workflow. Retries transient network failures on publish steps; halts with a partial-state report when retries are exhausted or the failure is terminal.
 metadata:
   author: cyanheads
-  version: "2.22"
+  version: "2.24"
   audience: external
   type: workflow
 ---
@@ -68,7 +68,7 @@ The user fixes locally and re-invokes. On re-invocation, already-published desti
 Read `package.json` → capture `version`. Then use your git tools to verify:
 
 - **Working tree is clean** — no uncommitted changes
-- **The release commit is in the stack** — `git log -1 --format=%s` starts with `chore(release): <version>`, or, in gated release PR mode, `git log main..HEAD --format=%s` contains it with only the review pass's own commits above it (`release-pr-review` lands fixes as ordinary commits on top; the tag still goes on the tip). Any other commit above the release commit — new work, a second version — is a halt.
+- **The release commit is in the stack** — `git log -1 --format=%s` starts with `chore(release): <version>`, or, in gated release PR mode, `git log main..HEAD --format=%s` contains it with only the review pass's own commits above it (`release-pr-review` lands its fixes, and any work the caller handed it to include, as ordinary commits on top; the tag still goes on the tip). Any other commit above the release commit — one the review pass did not land, a second version — is a halt.
 - **Current branch** — `main`, or `release/<version>` in release PR mode. Anything else, halt.
 - **Release PR mode:** `gh pr view --json number,state,headRefOid` shows the PR `OPEN` with `headRefOid` equal to local HEAD. A mismatch means the branch has commits the PR doesn't (or the reverse) — halt and report both SHAs. Keep `number` and `headRefOid`: the merge check (step 3) and the tag body (step 4) need them after the checkout has moved to `main`.
 
@@ -280,7 +280,7 @@ docker buildx build --platform linux/amd64,linux/arm64 \
   --push .
 ```
 
-The build stage in `Dockerfile` must carry `FROM --platform=$BUILDPLATFORM` (the templates ship it). Without it the non-native leg of the multi-arch build runs under QEMU, where bun >= 1.4 aborts inside `bun run build` with a JavaScriptCore allocator assertion (`qemu: uncaught target signal 6`, exit 134) and no image publishes for either architecture. npm, the MCP Registry, and the GitHub Release have all published by this step, so the recovery is a follow-up patch release rather than a retry — check the flag before building, not after.
+No stage built for the target platform may run JavaScript: the non-native leg of the multi-arch build runs it under QEMU, where bun >= 1.4 aborts with a JavaScriptCore allocator assertion (`qemu: uncaught target signal 6`) and no image publishes for either architecture. That covers `bun run build`, and also a `bun install` that sees `bunfig.toml` — its security scanner runs as a Bun program and the install fails with `NoSecurityScanData`. The templates keep every such step in stages that start `FROM --platform=$BUILDPLATFORM` — the build stage, and a `deps` stage that cross-installs production dependencies with `--os`/`--cpu`, runs `scripts/install-otel.ts`, then runs `scripts/prune-musl-packages.ts` (Bun cannot filter optional dependencies by libc, so it deletes the musl variants the glibc runtime image never loads) — so the production stage's only Bun calls are `HEALTHCHECK` and `CMD`. `bun run lint:packaging` (check 15, part of `devcheck`) fails a Dockerfile that breaks this and names the line. npm, the MCP Registry, and the GitHub Release have all published by this step, so the recovery is a follow-up patch release rather than a retry — confirm the lint passes before building, not after.
 
 If the project uses a non-GHCR registry or a custom image name, respect the project's convention. If push fails with a 401/403, prompt the user to authenticate (`echo $GITHUB_TOKEN | docker login ghcr.io -u <OWNER> --password-stdin`) and retry. Halt on build failure or non-auth push failure.
 

package/framework-skills/release-pr-review/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Review pass on an open release PR (`release/<version>` → `main`) — the step between `git-wrapup` and `release-and-publish` when a project releases in gated release PR mode. Reads the PR's commit range through the `code-simplifier` lens plus a correctness review, verifies whatever an automated reviewer left on the PR, lands fixes as ordinary commits on top of the release branch and pushes it, keeps the PR body in sync with what ships, and leaves one summary comment. The only agent role that both edits and commits — and it never rewrites pushed history, tags, merges, touches `main`, or publishes.
 metadata:
   author: cyanheads
-  version: "1.6"
+  version: "1.8"
   audience: external
   type: workflow
 ---
@@ -21,7 +21,7 @@ Not for: PRs from outside contributors (those get a human reply, not a commit on
 - The PR is open, and its head SHA equals local HEAD
 - No tag `v<version>` exists yet — tagging is `release-and-publish`'s job, after this pass
 
-Verify all three in step 1; halt on any mismatch.
+Verify all three in step 1; halt on any mismatch. The one exception to a clean tree: uncommitted work the caller explicitly hands over to ship in this release. Verify it against its description, commit it first as ordinary commits on top of the stack (step 5's conventions), add it to the changelog entry, and review it with the rest of the range. Any other uncommitted change is a halt.
 
 ## Steps
 
@@ -84,14 +84,14 @@ A passing check is not an all-clear — it can pass while alerts stay open on th
 
 ```bash
 gh api "repos/<OWNER>/<REPO>/code-scanning/alerts?state=open&ref=refs/pull/<N>/merge" \
-  --jq '.[] | "\(.number) \(.rule.id) \(.most_recent_instance.ref) \(.most_recent_instance.analysis_key)"'
+  --jq '.[] | "\(.number) \(.rule.id) \(.most_recent_instance.ref) \(.most_recent_instance.category)"'
 ```
 
-Every alert ends the pass in a settled state: a real finding is fixed on the branch, a genuine false positive is dismissed with a stated reason. One trap sits between those two. **An alert that the branch has already fixed but that will not close is an analysis-key problem, not a dismissal decision.** An alert raised by the retired CodeQL default setup (`analysis_key` beginning `dynamic/`) can never close itself once the repository carries its own workflow, because an alert closes only when the *same* key re-scans the ref — the new key's scan reports zero results while the old alert stays open forever. None of the three dismissal reasons (`false positive`, `won't fix`, `used in tests`) is true of a real finding that has been fixed, and `won't fix` on a high-severity alert reads to anyone auditing the repository as a decision not to fix it. Delete the retired configuration's orphaned analyses instead, newest-first:
+Every alert ends the pass in a settled state: a real finding is fixed on the branch, a genuine false positive is dismissed with a stated reason. One trap sits between those two. **An alert that the branch has already fixed but that will not close is a category problem, not a dismissal decision.** GitHub re-evaluates an alert only through new analyses in the alert's own category (`most_recent_instance.category`), whichever workflow or setup uploads them. Once no current configuration uploads to that category, the fixed code is scanned only under other categories, where it reports zero results while the old alert stays open forever. The template CodeQL workflow uploads each language under `/language:<language>`, the category CodeQL default setup uses, so alerts default setup raised close normally, and default setup's earlier analyses share a set with the workflow's — neither orphaned nor deletable. The usual orphan is a retired category, such as the path-derived `.github/workflows/codeql.yml:analyze` an earlier workflow uploaded under. None of the three dismissal reasons (`false positive`, `won't fix`, `used in tests`) is true of a real finding that has been fixed, and `won't fix` on a high-severity alert reads to anyone auditing the repository as a decision not to fix it. Once the current workflow has analyzed the alert's ref under its own categories, delete the orphaned category's analyses on that ref instead, newest-first — only the most recent analysis of a set is deletable, and `confirm_delete` lets the last one go:
 
 ```bash
-gh api "repos/<OWNER>/<REPO>/code-scanning/analyses?per_page=100" \
-  --jq '.[] | select(.analysis_key | startswith("dynamic/")) | "\(.id) \(.created_at) \(.ref)"'
+gh api --paginate "repos/<OWNER>/<REPO>/code-scanning/analyses?ref=<REF>&per_page=100" \
+  --jq '.[] | select(.category == "<ORPHANED_CATEGORY>") | "\(.id) \(.created_at) \(.deletable)"'
 gh api -X DELETE "repos/<OWNER>/<REPO>/code-scanning/analyses/<ID>?confirm_delete=true"
 ```
 

package/framework-skills/security-pass/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Review an MCP server for common security gaps: LLM-facing surfaces as injection vector (tools, resources, prompts, descriptions), scope blast radius, destructive ops without consent, upstream auth shape, input sinks (URL / path / roots / shell / schema strictness / ReDoS), tenant isolation, leakage through errors and telemetry, unbounded resources, and HTTP-mode deployment surface. Use before a release, after a batch of handler changes, or when the user asks for a security review, audit, or hardening pass. Produces grouped findings and a numbered options list.
 metadata:
   author: cyanheads
-  version: "1.11"
+  version: "1.12"
   audience: external
   type: audit
 ---
@@ -110,7 +110,7 @@ grep -rn "auth: \[" src/mcp-server/tools/definitions/
 
 #### Axis 3 — Destructive ops without a consent round
 
-`ctx.requestInput` moves consent off the LLM and onto the user: the handler returns an `input_required` result and only runs the side effect once it is re-entered with an accepted response. Destructive tools without that round trust the LLM not to be tricked.
+`ctx.requestInput` moves consent off the LLM and onto the user: the handler returns an `input_required` result and only runs the side effect once it is re-entered and redeems the record it stored when it asked. An accepted response on `ctx.inputs` alone proves nothing — a client can send one on a call nothing prompted for. Destructive tools without that round trust the LLM not to be tricked.
 
 **Look in:** handlers with `destructiveHint: true` or side-effecting verbs in names (`delete_*`, `send_*`, `pay_*`, `publish_*`, `drop_*`).
 
@@ -125,11 +125,12 @@ grep -rnE "ctx\.requestInput|ctx\.inputs" src/mcp-server/tools/definitions/
 - The confirmation **response** is validated — `ctx.inputs.accepted(key, Schema)` with a schema, not the bare overload. The SDK never re-validates a response against the schema its request advertised, and the payload is LLM-mediated: "user confirmed" does not mean "user authored these exact fields."
 - A **declined or cancelled** response is terminal — checked via `ctx.inputs.view(key)` and thrown on, never re-asked (a re-ask loops until the round budget runs out) and never treated as consent.
 - Consent is scoped to the specific target (e.g., record ID rendered in the message), not a generic "proceed?"
-- Any `requestState` carried across rounds is integrity-protected if it influences authorization, resource access, or which target gets mutated. It round-trips through the client and comes back attacker-controlled; the SDK does not sign or verify it.
-- **A consent gate's state is server-issued and single-use.** A client can send `inputResponses` plus a `requestState` of its own on the very FIRST call — honored on 2025-era connections, even from a client that declared no `elicitation` — so a handler that only *compares* client-carried state against a fresh resolution deletes on a forged "accepted" answer without ever prompting. A signed state closes forgery but not replay within its TTL. Keep the confirmed target (plus a content hash, so a same-path swap is caught) in a server-side record keyed by a random id, send only the id, redeem it before anything else in the handler, and refuse an unknown, used, or expired id.
-- **The weak point is answerability, not availability.** `ctx.requestInput` is present on every transport and both protocol eras — the 2025-era shim issues the real `elicitation/create` round trip, the 2026-07-28 client fulfils the embedded request directly. A client that never retries simply leaves the destructive step un-run, which fails safe. Keep `destructiveHint: true` so client-side approval flows still surface the risk, and do not accept "proceed anyway when the round is unavailable" as a fallback. On a 2025-era connection whose client lacks the capability, `ctx.requestInput` throws `client_capability_missing` inside the handler; catching that to run the side effect is exactly this bypass — let it propagate.
+- Where `requestState` influences authorization, resource access, or which target gets mutated, `MCP_REQUEST_STATE_KEY` is set (≥ 32 bytes, the same on every instance a retry can reach). The framework then seals the string a handler returns and the SDK rejects any other state before the handler runs; unset, the state round-trips through the client and comes back attacker-controlled.
+- **A consent gate's state is server-issued and single-use.** The framework drops answers the client's declared capabilities do not cover, kind and mode, on both eras, so a client without `elicitation.form` — a URL-only client included — cannot pre-answer a form gate. A client that declared it still can: it may send `inputResponses` — and a `requestState` of its own, or one it was issued earlier — on the very first call, so a handler that only *compares* client-carried state against a fresh resolution deletes on an answer nobody was shown. A sealed state closes forgery but not replay within its 900 s lifetime. Keep what the prompt confirmed in a `ctx.state` record keyed by a random id — the operation (tool name, or the resource URI read), the caller (`ctx.auth` `clientId` and `sub`), the target, and a content hash so a same-path swap is caught — send only the id, redeem it before anything else in the handler, and ask again on an unknown, used, or expired id or on any field that differs from this call. Without the operation, an id minted by another gated tool or resource confirms this one; without the caller, another user in the same tenant redeems an id they were handed while `MCP_REQUEST_STATE_KEY` is unset. The record's storage is shared by every instance a 2026-07-28 retry can reach — `filesystem`, `supabase`, or `cloudflare-d1`, never `cloudflare-kv`, whose eventual consistency widens the race below.
+- **Redeeming is not atomic.** Read-then-delete stops a sequential replay, but concurrent retries carrying one id can each read the record before any delete lands and each run the action. Until `ctx.state` gains an atomic `take` ([#593](https://github.com/cyanheads/mcp-ts-core/issues/593)), an action that must not repeat — a payment, a send, a publish — is idempotent per record (the record id as the upstream idempotency key), or the risk is accepted knowingly and recorded in the findings.
+- **The weak point is answerability, not availability.** `ctx.requestInput` is present on every transport and both protocol eras — the 2025-era shim issues the real `elicitation/create` round trip, the 2026-07-28 client fulfils the embedded request directly. A client that never retries simply leaves the destructive step un-run, which fails safe. Keep `destructiveHint: true` so client-side approval flows still surface the risk, and do not accept "proceed anyway when the round is unavailable" as a fallback. On a 2025-era connection whose client lacks the capability, `ctx.requestInput` throws `client_capability_missing` inside the handler; catching that to run the side effect is exactly this bypass — let it propagate. So is skipping the prompt because `ctx.clientCapabilities` lacks `elicitation`: that property decides whether to ask for optional context, never whether consent is needed.
 
-**Smell:** `destructiveHint: true` file with no `ctx.requestInput` in it. Or `ctx.inputs.accepted('confirm')` with no schema argument — the content could be anything. Or a handler that re-issues the same request after a `decline`.
+**Smell:** `destructiveHint: true` file with no `ctx.requestInput` in it. Or `ctx.inputs.accepted('confirm')` with no schema argument — the content could be anything. Or a gate that proceeds on `ctx.inputs` without redeeming a `ctx.state` record, whose record omits the operation or the caller, or that compares a target carried in `requestState`. Or a non-repeatable action behind a gate with no idempotency key. Or a handler that re-issues the same request after a `decline`.
 
 #### Axis 4 — Upstream auth shape
 
@@ -343,7 +344,7 @@ End with:
 - [ ] `fuzzTool` started in parallel
 - [ ] Axis 1 — LLM-facing surfaces (tool / resource / prompt output + descriptions) framed and static
 - [ ] Axis 2 — scope granularity audited
-- [ ] Axis 3 — destructive ops verified to gate on a `ctx.requestInput` round, the response schema-validated, decline/cancel terminal
+- [ ] Axis 3 — destructive ops verified to gate on a `ctx.requestInput` round that redeems a `ctx.state` record bound to the operation, caller, and target, the response schema-validated, decline/cancel terminal, non-repeatable actions idempotent per record, `MCP_REQUEST_STATE_KEY` set where state drives a mutation
 - [ ] Axis 4 — upstream auth + token passthrough reviewed
 - [ ] Axis 5 — input sinks (URL / path / roots / shell / proto / schema strictness / ReDoS) checked
 - [ ] Axis 6 — tenant isolation: module-scope state swept