From 350aadd3d40afa6ce9f098f5b7a2e87199e44d6f Mon Sep 17 00:00:00 2001
From: sebi <gore.sebyx@yahoo.com>
Date: Tue, 18 Aug 2026 21:42:11 -0500
Subject: [PATCH 1/3] fix(cli,ai,mcp): an apostrophe in JSX text turned the
 errors gate off for a whole file
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Second half of the tier-4/5 sweep, split from #152 at ~60 files each.

The gate hole was LIVE, not latent. `maskLiterals` treated `'` as a string
opener, so an apostrophe in JSX text blanked everything up to the next quote and
`scanFixes` returned nothing for the rest of the file — while `scanCodes` kept
passing, masking it. `packages/http/src/errors.ts` contains
`…already route "${input.otherRoute}"'s`, so EIGHT real `fix:` lines in that file
had never been checked by `x verify`. All eight pass now. One test asserted
"nothing in the installed framework raises X_DRAINING" — disproved by `draining()`
in the very file the gate had stopped reading.

The chosen fix is the cheap one — a quote with no partner on its own line is text,
copying `endOfRegex`'s existing rule — and its gap is stated rather than hidden:
two apostrophes on one line still blank the span between them. Blast radius drops
from rest-of-file to one line. Full coverage needs a JSX tokenizer, which the
file's own header rules out.

`agent()` sent Anthropic a transcript it rejects, in TWO places. A turn emitting a
tool call and `respond` together replayed the `respond` tool_use with no matching
tool_result. The repair path had the same hole and is far more reachable: ANY
output-schema mismatch in an agent() run was a 400. The loop now answers the
superseded `respond` with an is_error result telling the model to read the tool
results and answer again — rather than discarding a block the model emitted, or
using an answer composed before the tools it called had run.

MCP's `additionalProperties: false` accepted and dropped every argument named
after an Object.prototype member. Third instance of the class this release, and
`Object.hasOwn` alone was NOT sufficient — it turns the `__proto__` drop into a
`__proto__` re-prototype of the record the handler reads, so every write goes
through Object.defineProperty.

A page with zero executable JavaScript could fail its JS budget, with a fix line
naming an import that does not exist. `x verify --workers 5000` was accepted
although both summaries say max 8 — 842 concurrent Bun processes, each with the
module graph and a cloned database.

Plus seven more instances of the caught-value totality class in ai and mcp, and
the smaller CLI set: dev-traces dropping every request that arrived with an
inbound traceparent, a bare Error on a taken metrics port, METRICS_PORT ignored
in dev, a missing binary whose fix line checks nothing about missing binaries,
JSONC in a root tsconfig silently disabling X_PACKAGE_UNREFERENCED.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                 |  39 ++++
 packages/ai/CLAUDE.md                        |  34 +++
 packages/ai/src/agent-transcript.test.ts     | 218 +++++++++++++++++++
 packages/ai/src/agent-transcript.ts          |  94 ++++++++
 packages/ai/src/agent.ts                     |  59 ++---
 packages/ai/src/gateway.test.ts              |  48 ++++
 packages/ai/src/gateway.ts                   |  26 ++-
 packages/ai/src/hive-pool.test.ts            | 105 +++++++++
 packages/ai/src/hive-pool.ts                 |  17 +-
 packages/ai/src/hive-result.ts               |   7 +
 packages/ai/src/tools.test.ts                | 100 +++++++++
 packages/ai/src/tools.ts                     |  45 +++-
 packages/cli/CLAUDE.md                       |  18 +-
 packages/cli/src/budgets.test.ts             |  21 ++
 packages/cli/src/budgets.ts                  |  20 +-
 packages/cli/src/cmd-db-branch.test.ts       |  30 ++-
 packages/cli/src/cmd-db-branch.ts            |   8 +-
 packages/cli/src/cmd-dev.test.ts             |  19 +-
 packages/cli/src/cmd-dev.ts                  |  11 +-
 packages/cli/src/cmd-doctor.test.ts          |  43 +++-
 packages/cli/src/cmd-doctor.ts               |  29 ++-
 packages/cli/src/cmd-help.test.ts            |  19 ++
 packages/cli/src/cmd-new.ts                  |   2 +-
 packages/cli/src/cmd-test.test.ts            |  40 ++++
 packages/cli/src/cmd-test.ts                 |  14 +-
 packages/cli/src/cmd-verify.test.ts          |  50 ++++-
 packages/cli/src/cmd-verify.ts               |  26 ++-
 packages/cli/src/db-branch.test.ts           |  18 ++
 packages/cli/src/db-branch.ts                |  18 ++
 packages/cli/src/dev-assets.test.ts          |  27 +++
 packages/cli/src/dev-assets.ts               |  25 ++-
 packages/cli/src/dev-roles.ts                |   8 +-
 packages/cli/src/dev-storage.test.ts         |  20 +-
 packages/cli/src/dev-storage.ts              |  10 +-
 packages/cli/src/dev-traces.test.ts          |  33 ++-
 packages/cli/src/dev-traces.ts               |  30 ++-
 packages/cli/src/error-fixes.test.ts         |  60 +++--
 packages/cli/src/exec.test.ts                |  44 ++++
 packages/cli/src/exec.ts                     |  43 +++-
 packages/cli/src/metrics-endpoint.test.ts    |  25 ++-
 packages/cli/src/metrics-endpoint.ts         |  61 ++++--
 packages/cli/src/serve.test.ts               |  16 ++
 packages/cli/src/serve.ts                    |  18 +-
 packages/cli/src/storage-surfaces.test.ts    |  20 +-
 packages/cli/src/test-workers.ts             |   5 +-
 packages/cli/src/ts-scan.test.ts             |  25 +++
 packages/cli/src/ts-scan.ts                  |  15 +-
 packages/cli/src/tsconfig-references.test.ts |  28 +++
 packages/cli/src/tsconfig-references.ts      |  29 ++-
 packages/manifest/CLAUDE.md                  |   5 +
 packages/manifest/src/emit.test.ts           |  16 ++
 packages/manifest/src/emit.ts                |  11 +-
 packages/mcp/CLAUDE.md                       |  22 ++
 packages/mcp/src/query-limits.test.ts        |  23 ++
 packages/mcp/src/query-limits.ts             |  16 +-
 packages/mcp/src/registry.test.ts            |  30 +++
 packages/mcp/src/registry.ts                 |  22 +-
 packages/mcp/src/server.test.ts              |  73 ++++++-
 packages/mcp/src/server.ts                   |  21 +-
 packages/mcp/src/validate-args.test.ts       |  66 ++++++
 packages/mcp/src/validate-args.ts            |  22 +-
 61 files changed, 1846 insertions(+), 201 deletions(-)
 create mode 100644 packages/ai/src/agent-transcript.test.ts
 create mode 100644 packages/ai/src/agent-transcript.ts
 create mode 100644 packages/ai/src/hive-pool.test.ts
 create mode 100644 packages/cli/src/exec.test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index aeb6b97b..d8800c62 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -302,6 +302,45 @@ Semver applies from 1.0.0. A breaking change to a documented API needs a major 
   the throws that caused it reached the job retry classifier as bare `Error`s with no code; and
   restored `localStorage` was written on `about:blank` where it can never reach the site's origin.
 
+- **An apostrophe in JSX text silently disabled the `errors` gate for a whole file, and it was not
+  hypothetical.** `maskLiterals` treated `'` as a literal opener and blanked everything up to the
+  next one, so `scanFixes` returned nothing for the rest of the file — while `scanCodes` kept
+  passing, masking the hole. `packages/http/src/errors.ts` contains
+  `…already route "${input.otherRoute}"'s`, so **eight real `fix:` lines in that file had never been
+  checked**. All eight pass now. One test asserted "nothing in the installed framework raises
+  `X_DRAINING`" — disproved by `draining()` in the very file the gate had stopped reading.
+
+- **A page with zero executable JavaScript could fail its JS budget**, with a `fix:` line naming an
+  import that does not exist. Every inline `<script>` body was counted, including
+  `application/ld+json` (which the SEO helpers emit) and island props. `@ultimat3/render`'s `head.ts`
+  already owned the rule: *"the body is data, not code."*
+
+- **`x verify --workers 5000` was accepted** although both flag summaries say "max 8", and
+  `planShards` clamps only to the file count — 842 concurrent Bun processes, each with the framework
+  module graph and a cloned database. Both summaries also named `CPUs - 1` as the default, a value
+  the code measured and rejected as *"slower than not sharding at all"*.
+
+- **`agent()` sent the Anthropic API a transcript it rejects, in two places.** A turn emitting a tool
+  call **and** `respond` replayed the `respond` `tool_use` with no matching `tool_result` → 400. The
+  repair path had the same hole and is more reachable: **any** output-schema mismatch in an `agent()`
+  run was a 400. The loop now answers the superseded `respond` with an `is_error` result telling the
+  model to read the tool results and answer again — rather than discarding a block the model emitted,
+  or using an answer composed before the tools it called had run.
+
+- **MCP `additionalProperties: false` accepted and dropped every argument named after an
+  `Object.prototype` member** (`constructor`, `__proto__`, `toString`), because the check walked the
+  prototype chain. Third instance of this class in one release, after `@ultimat3/i18n`'s catalog and
+  `@ultimat3/schema`'s coercion. `Object.hasOwn` alone was **not** sufficient: it turns the
+  `__proto__` *drop* into a `__proto__` *re-prototype* of the record the handler reads, so every
+  write now goes through `Object.defineProperty`.
+
+- Also: a request arriving with an inbound `traceparent` never appeared in `/_x/timeline`; a second
+  `x dev` died with a bare `Error` on a port collision and `METRICS_PORT` was honoured in the
+  container but ignored in dev; a missing binary produced `fix: x doctor --json`, which checks
+  nothing about missing binaries; a root `tsconfig.json` written as JSONC silently disabled
+  `X_PACKAGE_UNREFERENCED`; and `x doctor --port 65535` suggested `--port 65536`, which `x dev`
+  refuses.
+
 - **The outbox relay's claim locked nothing, so two relays could publish one batch and a job could
   run twice.** `SQL_OUTBOX_CLAIM` ends in `for update skip locked`, but the relay issues it on a
   **pooled** connection with no transaction — a bare statement runs in an implicit transaction that
diff --git a/packages/ai/CLAUDE.md b/packages/ai/CLAUDE.md
index 725a3738..ba42bc02 100644
--- a/packages/ai/CLAUDE.md
+++ b/packages/ai/CLAUDE.md
@@ -53,6 +53,7 @@ until 2026-08, naming a tool no catalog contained (`llm.test.ts`, `agent.test.ts
 | `llm.ts` | `llm()` — the model call, declared as an `action`; and what a streamed answer must satisfy |
 | `llm-stream.ts` | `.stream()`'s plumbing: the sink, the ambient mark, the one-turn drive |
 | `agent.ts` | `agent()` — the tool loop, declared as an `action` |
+| `agent-transcript.ts` | what one turn leaves in the transcript: the assistant replay, the tool results, the correction |
 | `agent-facts.ts` | `describeAgents()` — the agent registry and the row a manifest publishes |
 | `agent-job.ts` | `agentJob()` — an agent as a real `JobHandle`, composed from `job()` |
 | `hive.ts` | `hive()` — one action fanned out over many inputs, declared as an `action` |
@@ -102,6 +103,12 @@ until 2026-08, naming a tool no catalog contained (`llm.test.ts`, `agent.test.ts
   zero leaks the ceiling upward on every release.
 - Cost is `Money` (integer minor units), rounded **up**. Never a float, never a division
   that loses a fraction.
+- **The gateway's two reads of a provider's throw are total.** A `Provider` is the APP's object, so
+  the value it rejects with is one the framework did not build: `isRetryable` indexes it (a getter,
+  or a `Proxy` trap) and fails closed if the read raises, and the failure line goes through core's
+  `renderThrowable` rather than `error.message` / `String(error)` — a renderer that throws replaces
+  `X_AI_PROVIDER_UNAVAILABLE` with a bare `TypeError` nothing catches by code, and it bounds a
+  provider's 1MB body out of the `cause`.
 - Every non-2xx and every in-band `error` frame becomes `AiTransportError`, which carries a real
   `status` field — that field IS the gateway's retry rule. A body parsed as a message would read
   as an empty, successful answer, which is the one outcome nothing downstream can detect.
@@ -317,6 +324,26 @@ until 2026-08, naming a tool no catalog contained (`llm.test.ts`, `agent.test.ts
     contract from turns in a loop, and half-shipping it would be the second path axiom 1 refuses.
   - **No semantic cache on `agent()`.** Similar prompts do not have similar answers once the answer
     depends on what `lookupOrder` returned this second.
+  - **Every `tool_use` block the transcript replays is answered by a `tool_result` in the very next
+    message** — the Messages API's own rule, and `agent-transcript.ts` owns both halves of it for
+    that reason. Two paths broke it, both through `respond`, which is filtered out of the calls
+    that RUN and replayed like any other block: a turn emitting a tool call AND `respond` together
+    (ordinary parallel tool use), and a `respond` whose input failed the output schema, followed by
+    a plain user message. Both were a 400 (`tool_use ids were found without tool_result blocks`),
+    i.e. `X_AI_PROVIDER_UNAVAILABLE` in place of a completed run, and `agent.test.ts` never mixed
+    the two so neither shipped visible. An unaccepted `respond` now comes back as its own
+    `tool_result`, `is_error`, saying why — the answer is SUPERSEDED, not wrong: it was written
+    before the results of the tools the same turn asked for existed, so the loop continues and the
+    model answers again with them in hand. Discarding the block instead would have been the other
+    legal fix and loses the record; USING the speculative answer would skip the tool results the
+    model itself asked for, after those tools already ran.
+  - **A tool result is rendered totally.** `runLlmToolCall` returns `content: string` and the loop
+    TRUNCATES it, so `JSON.stringify`'s other two answers both have to be handled: `undefined` for
+    an action that returns nothing (`'null'`), and a throw on a bigint, a cycle or a `toJSON` of
+    the value's own — reported as "the tool ran and its result is not JSON", never as a failure,
+    because a model told the tool failed calls it again and buys its side effects twice. The throw
+    it catches is read with `stringField`, never `typeof error.code === 'string'`: the value is an
+    app's, so the probe is a getter call or a `Proxy` trap inside the catch block.
   - `AiMessage.content` widened to `string | readonly AiContentBlock[]` for this: a `tool_result`
     has to name the `tool_use` it answers and a string has nowhere to put the id. The block field
     names are the Messages API's, so `body()` passes them through untouched.
@@ -347,6 +374,13 @@ until 2026-08, naming a tool no catalog contained (`llm.test.ts`, `agent.test.ts
     parallelism because `reserve` DEBITS on the root's turnstile before the call. Three members
     against a ceiling only one fits leave exactly one `ok`; that is asserted through the hive
     rather than asserted about the ledger, because the ledger already promised it.
+  - **A member's throw is RECORDED, whatever it is.** `failureOf` reads it with `isThrownError` and
+    `stringField` from core, never `error instanceof Error` and `.message`: a member is an app's
+    action, so a `Proxy` makes `instanceof` run a `getPrototypeOf` trap, and a throw there takes
+    down the whole hive — the one outcome the three arms exist to prevent. `skipped` has two
+    reasons, because they are two facts: `SKIPPED_ABORTED` (a sibling failed under `'abort'`) and
+    `SKIPPED_NO_INPUT` (the split produced nothing at that index). One string for both sent a
+    caller to retry a tail that was never cut.
   - **`onMemberError` is required.** `'abort'` stops and leaves the rest `skipped`; `'collect'`
     harvests. Both are right for somebody, so neither may be inherited silently.
   - `concurrency` defaults to 4 and `minMembers` to 2, and neither number is measured off any run —
diff --git a/packages/ai/src/agent-transcript.test.ts b/packages/ai/src/agent-transcript.test.ts
new file mode 100644
index 00000000..7f7635d6
--- /dev/null
+++ b/packages/ai/src/agent-transcript.test.ts
@@ -0,0 +1,218 @@
+/**
+ * The transcript the next turn replays, and the one rule the Messages API enforces about it:
+ * every `tool_use` block an assistant turn carries must be answered by a `tool_result` in the very
+ * next message. A transcript that breaks it is a 400 — an `X_AI_PROVIDER_UNAVAILABLE` in place of
+ * a completed run — so it is asserted structurally here rather than trusted per case.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { createContext, userActor } from '@ultimat3/core';
+import { allow } from '@ultimat3/policy';
+import { t } from '@ultimat3/schema';
+import { agent } from './agent';
+import { createGateway } from './gateway';
+import { definePrompt, type Prompt } from './prompt';
+import type { AiMessage, GenerateRequest, GenerateResult, Provider, TokenUsage } from './provider';
+import { costOf, EchoProvider } from './provider';
+import { configureAi } from './runtime';
+import type { ProjectableAction } from './tools';
+
+const Input = t.object({ orderId: t.string });
+const Output = t.object({ answer: t.string });
+const USAGE: TokenUsage = {
+  inputTokens: 12,
+  outputTokens: 8,
+  cacheReadTokens: 0,
+  cacheWriteTokens: 0,
+};
+
+type Turn = { readonly calls: readonly { name: string; input: Record<string, unknown> }[] };
+
+function scripted(...turns: readonly Turn[]): { provider: Provider; seen: GenerateRequest[] } {
+  const seen: GenerateRequest[] = [];
+  const provider: Provider = {
+    name: 'scripted',
+    models: ['claude-opus-5'],
+    generate(request) {
+      const turn = turns[Math.min(seen.length, turns.length - 1)];
+      seen.push(request);
+      return Promise.resolve({
+        model: 'claude-opus-5',
+        text: '',
+        toolCalls: (turn?.calls ?? []).map((call, index) => ({
+          id: `call-${seen.length}-${index}`,
+          name: call.name,
+          input: call.input,
+        })),
+        stopReason: 'tool_use',
+        stopDetails: undefined,
+        usage: USAGE,
+        cost: costOf('claude-opus-5', USAGE),
+      } satisfies GenerateResult);
+    },
+    stream: (request) => new EchoProvider().stream(request),
+  };
+  return { provider, seen };
+}
+
+function lookupTool(): ProjectableAction {
+  return {
+    name: 'lookupOrder',
+    description: 'Look an order up',
+    mcp: { expose: true },
+    run: () => Promise.resolve({ status: 'shipped' }),
+  };
+}
+
+let seq = 0;
+function promptFor(): Prompt<{ orderId: string }> {
+  seq += 1;
+  return definePrompt<{ orderId: string }>({
+    id: `transcript-${seq}`,
+    version: '1.0.0',
+    template: 'Resolve order {{orderId}}.',
+  });
+}
+
+function ctxAs(id: string) {
+  return createContext({ actor: userActor({ id }) });
+}
+
+const blocksOf = (message: AiMessage | undefined) =>
+  Array.isArray(message?.content) ? message.content : [];
+
+/**
+ * The API's rule, executable: the ids a transcript asks about and never answers. Each `tool_use`
+ * is looked up in the message that FOLLOWS its own, because that is the only place the Messages
+ * API accepts the answer.
+ */
+function unansweredToolUses(messages: readonly AiMessage[]): readonly string[] {
+  const open: string[] = [];
+  for (const [index, message] of messages.entries()) {
+    const asked = blocksOf(message)
+      .filter((block) => block.type === 'tool_use')
+      .map((block) => (block.type === 'tool_use' ? block.id : ''));
+    if (asked.length === 0) continue;
+    const answered = new Set(
+      blocksOf(messages[index + 1])
+        .filter((block) => block.type === 'tool_result')
+        .map((block) => (block.type === 'tool_result' ? block.tool_use_id : '')),
+    );
+    open.push(...asked.filter((id) => !answered.has(id)));
+  }
+  return open;
+}
+
+describe('every tool_use the transcript replays is answered', () => {
+  // Parallel tool use: one turn asks for a tool AND answers. The answer was written before the
+  // tool result existed, so the loop keeps going — and the `respond` block it replays needs a
+  // `tool_result` of its own or the next request is a 400.
+  test('a turn that calls a tool AND respond leaves no tool_use unanswered', async () => {
+    const { provider, seen } = scripted(
+      {
+        calls: [
+          { name: 'lookupOrder', input: { id: 'o-1' } },
+          { name: 'respond', input: { answer: 'guessed' } },
+        ],
+      },
+      { calls: [{ name: 'respond', input: { answer: 'shipped' } }] },
+    );
+    configureAi({ gateway: createGateway({ providers: [provider] }) });
+
+    const support = agent({
+      input: Input,
+      output: Output,
+      prompt: promptFor(),
+      vars: ({ input }) => ({ orderId: input.orderId }),
+      tools: [lookupTool()],
+      policy: allow(),
+    }).named('parallelAgent');
+
+    // The run completes on the SECOND turn's answer: the speculative one was written without the
+    // tool result the same turn asked for.
+    expect(await support({ orderId: 'o-1' }, { ctx: ctxAs('user-7') })).toEqual({
+      answer: 'shipped',
+    });
+    const replayed = seen[1]?.messages ?? [];
+    expect(unansweredToolUses(replayed)).toEqual([]);
+    // The real tool's result is still first, and the rejected answer is flagged so the model does
+    // not read it as data.
+    const results = blocksOf(replayed[2]);
+    expect(results[0]).toMatchObject({ type: 'tool_result', tool_use_id: 'call-1-0' });
+    expect(results[1]).toMatchObject({
+      type: 'tool_result',
+      tool_use_id: 'call-1-1',
+      is_error: true,
+    });
+  });
+
+  // The same hole on the repair path: a `respond` whose input fails the output schema is replayed
+  // as a `tool_use`, and the correction that follows it has to be that call's `tool_result`.
+  test('a repair turn answers the respond call it is correcting', async () => {
+    const { provider, seen } = scripted(
+      { calls: [{ name: 'respond', input: { answer: 42 } }] },
+      { calls: [{ name: 'respond', input: { answer: 'shipped' } }] },
+    );
+    configureAi({ gateway: createGateway({ providers: [provider] }) });
+
+    const support = agent({
+      input: Input,
+      output: Output,
+      prompt: promptFor(),
+      vars: ({ input }) => ({ orderId: input.orderId }),
+      tools: [lookupTool()],
+      policy: allow(),
+    }).named('repairAgent');
+
+    expect(await support({ orderId: 'o-1' }, { ctx: ctxAs('user-7') })).toEqual({
+      answer: 'shipped',
+    });
+    const replayed = seen[1]?.messages ?? [];
+    expect(unansweredToolUses(replayed)).toEqual([]);
+    const correction = blocksOf(replayed[2])[0];
+    expect(correction).toMatchObject({ type: 'tool_result', tool_use_id: 'call-1-0' });
+    expect(correction && 'content' in correction ? correction.content : '').toContain(
+      'failed its schema',
+    );
+  });
+
+  // A model that answers in prose emits no `tool_use` at all, so the correction stays an ordinary
+  // user message — a `tool_result` naming nothing would be the 400 in the other direction.
+  test('a prose answer is corrected with a plain user message', async () => {
+    const seen: GenerateRequest[] = [];
+    const provider: Provider = {
+      name: 'prose',
+      models: ['claude-opus-5'],
+      generate(request) {
+        seen.push(request);
+        return Promise.resolve({
+          model: 'claude-opus-5',
+          text: seen.length === 1 ? '{"answer":42}' : '{"answer":"shipped"}',
+          toolCalls: [],
+          stopReason: 'end_turn',
+          stopDetails: undefined,
+          usage: USAGE,
+          cost: costOf('claude-opus-5', USAGE),
+        } satisfies GenerateResult);
+      },
+      stream: (request) => new EchoProvider().stream(request),
+    };
+    configureAi({ gateway: createGateway({ providers: [provider] }) });
+
+    const support = agent({
+      input: Input,
+      output: Output,
+      prompt: promptFor(),
+      vars: ({ input }) => ({ orderId: input.orderId }),
+      tools: [lookupTool()],
+      policy: allow(),
+    }).named('proseAgent');
+
+    expect(await support({ orderId: 'o-1' }, { ctx: ctxAs('user-7') })).toEqual({
+      answer: 'shipped',
+    });
+    const replayed = seen[1]?.messages ?? [];
+    expect(unansweredToolUses(replayed)).toEqual([]);
+    expect(replayed[2]?.content).toContain('failed its schema');
+  });
+});
diff --git a/packages/ai/src/agent-transcript.ts b/packages/ai/src/agent-transcript.ts
new file mode 100644
index 00000000..24819019
--- /dev/null
+++ b/packages/ai/src/agent-transcript.ts
@@ -0,0 +1,94 @@
+/**
+ * The transcript one agent turn leaves behind: the assistant message replaying what the model
+ * emitted, and the user message answering it. One file because the Messages API's rule spans both
+ * halves — every `tool_use` block replayed here must be answered by a `tool_result` in the very
+ * next message — and a rule split across two call sites is a rule one of them will miss.
+ */
+
+import { RESPOND } from './llm';
+import type { AiContentBlock, AiMessage, GenerateResult } from './provider';
+import type { LlmToolCall, LlmToolResult } from './tools';
+
+/**
+ * The model's turn, replayed as the transcript the next request needs. `tool_use` blocks survive
+ * as themselves here — unlike `llm()`'s repair turn, which flattens them to text precisely
+ * because it has no `tool_result` to follow them with, and the API demands one.
+ */
+export function assistantTurn(result: GenerateResult): AiMessage {
+  const blocks: AiContentBlock[] = [];
+  if (result.text !== '') blocks.push({ type: 'text', text: result.text });
+  for (const call of result.toolCalls) {
+    blocks.push({ type: 'tool_use', id: call.id, name: call.name, input: call.input });
+  }
+  // A turn with neither text nor a tool call would be an empty content array, which is a 400.
+  return blocks.length === 0
+    ? { role: 'assistant', content: '(no answer)' }
+    : { role: 'assistant', content: blocks };
+}
+
+/**
+ * What the model is told when it answered in the same turn it asked for a tool. Parallel tool use
+ * is normal, and the answer that comes with it was written before the tool result existed — so it
+ * is superseded, not wrong, and saying which is what stops the next turn repeating it verbatim.
+ */
+const SUPERSEDED = `This answer arrived in the same turn as the tool calls above, so it was written before their results existed. Read the results in this message, then call the "${RESPOND}" tool again.`;
+
+/**
+ * The tool results of one turn, plus a `tool_result` for every `respond` call the loop did not
+ * accept. The second half is not optional: `respond` is filtered out of the calls that get RUN,
+ * but it is replayed as a `tool_use` like any other, and a `tool_use` the next message does not
+ * answer is a 400 (`tool_use ids were found without tool_result blocks`) — the whole run lost to
+ * an `X_AI_PROVIDER_UNAVAILABLE` because the model did the ordinary thing.
+ *
+ * Real results stay first: they are what the model asked for, and the rejection reads as the
+ * instruction that follows them.
+ */
+export function toolResultTurn(
+  results: readonly LlmToolResult[],
+  chars: number,
+  unaccepted: readonly LlmToolCall[],
+): AiMessage {
+  return {
+    role: 'user',
+    content: [
+      ...results.map((result) => ({
+        type: 'tool_result' as const,
+        tool_use_id: result.toolUseId,
+        content: truncate(result.content, chars),
+        // A denial or a failure is an outcome the model should read and react to, flagged so it
+        // does not read as data.
+        ...(result.isError === true ? { is_error: true } : {}),
+      })),
+      ...rejections(unaccepted, SUPERSEDED),
+    ],
+  };
+}
+
+/**
+ * The correction after an answer that failed its schema, in whichever shape the turn it corrects
+ * demands: a `tool_result` when the answer came through `respond` (the dominant path, and a
+ * `tool_use` the API insists on seeing answered), a plain user message when the model answered in
+ * prose and there is no id to name. Framework text, so never truncated by `maxToolResultChars`.
+ */
+export function repairTurn(unaccepted: readonly LlmToolCall[], issues: string): AiMessage {
+  const text = `That answer failed its schema: ${issues}. Call the "${RESPOND}" tool with a value that satisfies it. Answer only through the tool.`;
+  return unaccepted.length === 0
+    ? { role: 'user', content: text }
+    : { role: 'user', content: rejections(unaccepted, text) };
+}
+
+/** A `tool_result` saying an answer was not taken, flagged so the model does not read it as data. */
+function rejections(calls: readonly LlmToolCall[], text: string): readonly AiContentBlock[] {
+  return calls.map((call) => ({
+    type: 'tool_result' as const,
+    tool_use_id: call.id,
+    content: text,
+    is_error: true,
+  }));
+}
+
+/** Truncation says so. A silently shortened tool result is a model reasoning over half a table. */
+function truncate(text: string, chars: number): string {
+  if (text.length <= chars) return text;
+  return `${text.slice(0, chars)}\n[truncated: ${text.length - chars} more characters]`;
+}
diff --git a/packages/ai/src/agent.ts b/packages/ai/src/agent.ts
index 8253cdf2..0b5e6aff 100644
--- a/packages/ai/src/agent.ts
+++ b/packages/ai/src/agent.ts
@@ -27,6 +27,7 @@ import type { InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import { formatIssues, validateAsync } from '@ultimat3/schema';
 import type { AgentFact } from './agent-facts';
 import { registerAgentFact } from './agent-facts';
+import { assistantTurn, repairTurn, toolResultTurn } from './agent-transcript';
 import type { BudgetLimits } from './budget';
 import { BudgetLedger, currentBudget, withBudget } from './budget';
 import {
@@ -42,7 +43,6 @@ import type { ModelId } from './models';
 import { DEFAULT_MODEL, moreCapableThan } from './models';
 import type { Prompt, PromptVars } from './prompt';
 import type {
-  AiContentBlock,
   AiMessage,
   GenerateRequest,
   GenerateResult,
@@ -277,6 +277,9 @@ async function run<
         throwIfAborted(args.ctx);
         const result = await gateway.generate({ ...base, messages });
         const requested = result.toolCalls.filter((call) => call.name !== RESPOND);
+        // The same turn's `respond` calls, kept rather than forgotten: they are never RUN, but
+        // `assistantTurn` replays them, and every replayed `tool_use` has to be answered.
+        const answers = result.toolCalls.filter((call) => call.name === RESPOND);
         span.setAttributes({
           'agent.turns': turn,
           'agent.tool_calls': calls,
@@ -309,7 +312,16 @@ async function run<
             requested.map((call) => runLlmToolCall(adapted.tools, call, actor)),
           );
           calls += requested.length;
-          messages = [...messages, assistantTurn(result), toolResults(results, chars)];
+          messages = [
+            ...messages,
+            assistantTurn(result),
+            // Parallel tool use — one turn asking for a tool AND answering — is normal, and the
+            // answer is speculative: it was written before the result it asked for existed. So
+            // the loop continues, and the answer is REJECTED on the wire rather than dropped,
+            // because a replayed `respond` block with no `tool_result` is a 400 and the whole run
+            // becomes an `X_AI_PROVIDER_UNAVAILABLE`.
+            toolResultTurn(results, chars, answers),
+          ];
           continue;
         }
 
@@ -321,7 +333,7 @@ async function run<
         if (result.stopReason === 'max_tokens') {
           throw new LlmTruncatedError({ prompt: name, maxTokens: base.maxTokens });
         }
-        messages = [...messages, assistantTurn(result), { role: 'user', content: repair(issues) }];
+        messages = [...messages, assistantTurn(result), repairTurn(answers, issues)];
       }
 
       // Two different exhaustions, so two different causes: a loop that kept calling tools and
@@ -368,47 +380,6 @@ function assertAnswerable(result: GenerateResult, name: string): void {
   });
 }
 
-/**
- * The model's turn, replayed as the transcript the next request needs. `tool_use` blocks survive
- * as themselves here — unlike `llm()`'s repair turn, which flattens them to text precisely
- * because it has no `tool_result` to follow them with, and the API demands one.
- */
-function assistantTurn(result: GenerateResult): AiMessage {
-  const blocks: AiContentBlock[] = [];
-  if (result.text !== '') blocks.push({ type: 'text', text: result.text });
-  for (const call of result.toolCalls) {
-    blocks.push({ type: 'tool_use', id: call.id, name: call.name, input: call.input });
-  }
-  // A turn with neither text nor a tool call would be an empty content array, which is a 400.
-  return blocks.length === 0
-    ? { role: 'assistant', content: '(no answer)' }
-    : { role: 'assistant', content: blocks };
-}
-
-function toolResults(results: readonly LlmToolResult[], chars: number): AiMessage {
-  return {
-    role: 'user',
-    content: results.map((result) => ({
-      type: 'tool_result' as const,
-      tool_use_id: result.toolUseId,
-      content: truncate(result.content, chars),
-      // A denial or a failure is an outcome the model should read and react to, flagged so it
-      // does not read as data.
-      ...(result.isError === true ? { is_error: true } : {}),
-    })),
-  };
-}
-
-/** Truncation says so. A silently shortened tool result is a model reasoning over half a table. */
-function truncate(text: string, chars: number): string {
-  if (text.length <= chars) return text;
-  return `${text.slice(0, chars)}\n[truncated: ${text.length - chars} more characters]`;
-}
-
-function repair(issues: string): string {
-  return `That answer failed its schema: ${issues}. Call the "${RESPOND}" tool with a value that satisfies it. Answer only through the tool.`;
-}
-
 function limitsOf<
   TInput extends StandardSchemaV1,
   TOutput extends StandardSchemaV1,
diff --git a/packages/ai/src/gateway.test.ts b/packages/ai/src/gateway.test.ts
index c4d5a288..5967a7f8 100644
--- a/packages/ai/src/gateway.test.ts
+++ b/packages/ai/src/gateway.test.ts
@@ -150,6 +150,54 @@ describe('routing and retries', () => {
     expect(attempts).toBe(1);
   });
 
+  // A `Provider` is an APP's object — `createGateway({ providers })` takes whatever it is handed —
+  // so the value it rejects with is one the framework did not build. Both reads in the retry loop
+  // run on it: `isRetryable` indexes it, and the failure line renders it. A throw from either
+  // replaces `X_AI_PROVIDER_UNAVAILABLE` with a bare TypeError raised inside the catch block.
+  test('a provider that rejects with a value fighting to be read still ends in a coded error', async () => {
+    const hostile: readonly unknown[] = [
+      new Proxy(
+        {},
+        {
+          get() {
+            throw new Error('trapped get');
+          },
+          getPrototypeOf() {
+            throw new Error('trapped getPrototypeOf');
+          },
+        },
+      ),
+      Object.create(null),
+      Symbol('rejected'),
+    ];
+    for (const value of hostile) {
+      const rude: Provider = {
+        name: 'rude',
+        models: ANTHROPIC_MODEL_IDS,
+        generate: () => Promise.reject(value),
+        // biome-ignore lint/correctness/useYield: interface requires a generator shape
+        async *stream(): AsyncIterable<StreamChunk> {
+          throw new Error('unused');
+        },
+      };
+      const gateway = createGateway({
+        providers: [rude],
+        retry: { attempts: 2, baseDelayMs: 0, maxDelayMs: 0 },
+        sleep: async () => undefined,
+      });
+      // `toThrow(Class)` passes in Bun 1.3.14 when a call merely RETURNS an error, so the code is
+      // asserted off the caught value instead.
+      let thrown: unknown;
+      try {
+        await gateway.generate({ messages: [{ role: 'user', content: 'x' }], maxTokens: 8 });
+      } catch (error) {
+        thrown = error;
+      }
+      expect((thrown as { code?: string } | undefined)?.code).toBe('X_AI_PROVIDER_UNAVAILABLE');
+      expect(typeof (thrown as { cause?: unknown } | undefined)?.cause).toBe('string');
+    }
+  });
+
   test('a cache hit skips the provider entirely', async () => {
     let calls = 0;
     const counting: Provider = {
diff --git a/packages/ai/src/gateway.ts b/packages/ai/src/gateway.ts
index 15de96d8..13f5d0ab 100644
--- a/packages/ai/src/gateway.ts
+++ b/packages/ai/src/gateway.ts
@@ -4,6 +4,7 @@
 // budgeted, and cost-accounted in integer minor units. Everything an app does with a model
 // goes through here, so budgets and accounting cannot be bypassed by a stray fetch.
 
+import { renderThrowable } from '@ultimat3/core';
 import type { Money } from '@ultimat3/money';
 import type { BudgetLimits, BudgetStore } from './budget';
 import { BudgetLedger, currentBudget, estimateSpend, withBudget } from './budget';
@@ -183,7 +184,11 @@ class GatewayImpl implements Gateway {
         try {
           return { ...(await call(provider)), provider: provider.name };
         } catch (error) {
-          failures.push(`${provider.name}#${attempt}: ${messageOf(error)}`);
+          // `renderThrowable`, never `error.message` or `String(error)`: this line becomes the
+          // `cause` of `X_AI_PROVIDER_UNAVAILABLE`, and a renderer that throws replaces the coded
+          // refusal with a `TypeError` nothing downstream can catch by code. It bounds the text
+          // too — a provider's 1MB body is not a cause.
+          failures.push(`${provider.name}#${attempt}: ${renderThrowable(error)}`);
           if (!isRetryable(error) || attempt === this.retry.attempts) break;
           await this.sleep(backoffMs(this.retry, attempt));
         }
@@ -205,14 +210,17 @@ export function backoffMs(policy: RetryPolicy, attempt: number): number {
  */
 export function isRetryable(error: unknown): boolean {
   if (typeof error !== 'object' || error === null) return false;
-  const e = error as { status?: unknown; code?: unknown };
-  if (typeof e.status === 'number') return e.status === 429 || e.status >= 500;
-  return e.code === 'ETIMEDOUT' || e.code === 'ECONNRESET';
-}
-
-function messageOf(error: unknown): string {
-  if (error instanceof Error) return error.message;
-  return String(error);
+  // A `Provider` is the APP's object, so the value it rejected with is one the framework did not
+  // build: `e.status` is a getter call and, on a `Proxy`, a trap. A value that fights being read
+  // cannot be SHOWN to be retryable, and this runs inside the catch block that has nothing left
+  // to answer with — so it fails closed rather than raising.
+  try {
+    const e = error as { status?: unknown; code?: unknown };
+    if (typeof e.status === 'number') return e.status === 429 || e.status >= 500;
+    return e.code === 'ETIMEDOUT' || e.code === 'ECONNRESET';
+  } catch {
+    return false;
+  }
 }
 
 /**
diff --git a/packages/ai/src/hive-pool.test.ts b/packages/ai/src/hive-pool.test.ts
new file mode 100644
index 00000000..ac5bfcc9
--- /dev/null
+++ b/packages/ai/src/hive-pool.test.ts
@@ -0,0 +1,105 @@
+/**
+ * The pool's own contract, tested without a model in the way: three arms, split order, and the
+ * rule both of them depend on — a member's throw is RECORDED, whatever it is. A member is an
+ * app's action, so the thrown value is one the framework did not build, and a probe that raises
+ * while reading it takes down the whole run the three arms exist to keep.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import type { Ctx } from '@ultimat3/core';
+import { createContext, runWithContext, userActor } from '@ultimat3/core';
+import { runPool } from './hive-pool';
+import type { HiveMember } from './hive-result';
+import { SKIPPED_ABORTED, SKIPPED_NO_INPUT } from './hive-result';
+
+/** `withChildContext` needs an ambient one, so every pool here runs inside a real context. */
+function pooled<I, O>(
+  inputs: readonly I[],
+  onMemberError: 'abort' | 'collect',
+  member: (payload: I, ctx: Ctx) => Promise<O>,
+): Promise<readonly HiveMember<O>[]> {
+  const ctx = createContext({ actor: userActor({ id: 'user-7' }) });
+  return runWithContext(ctx, () =>
+    runPool<I, O>({
+      inputs,
+      width: 1,
+      ctx,
+      onMemberError,
+      member: (payload) => member(payload, ctx),
+    }),
+  );
+}
+
+/** A value that fights every probe a `catch` block would make of it. */
+const trapped = (): unknown =>
+  new Proxy(
+    {},
+    {
+      get() {
+        throw new Error('trapped get');
+      },
+      getPrototypeOf() {
+        throw new Error('trapped getPrototypeOf');
+      },
+    },
+  );
+
+describe('a member throw is recorded, never re-raised', () => {
+  test.each([
+    ['a Proxy that traps getPrototypeOf', trapped],
+    ['a null-prototype object', () => Object.create(null) as unknown],
+    ['a symbol', () => Symbol('thrown')],
+    [
+      'an object whose message getter throws',
+      () =>
+        Object.defineProperty({}, 'message', {
+          get() {
+            throw new Error('trapped message');
+          },
+          enumerable: true,
+        }) as unknown,
+    ],
+  ])('%s becomes a failed member, and the siblings still run', async (_label, make) => {
+    const members = await pooled<number, string>([1, 2, 3], 'collect', (payload) =>
+      payload === 2 ? Promise.reject(make()) : Promise.resolve(`v${payload}`),
+    );
+
+    expect(members.map((one) => one.status)).toEqual(['ok', 'failed', 'ok']);
+    const failed = members[1];
+    expect(failed?.status === 'failed' ? failed.code : '').toBe('unknown');
+    expect(failed?.status === 'failed' ? typeof failed.reason : '').toBe('string');
+  });
+
+  test('an ordinary Error keeps its own message', async () => {
+    const members = await pooled<number, string>([1], 'collect', () =>
+      Promise.reject(new Error('kaboom')),
+    );
+    expect(members[0]).toEqual({ status: 'failed', index: 0, code: 'unknown', reason: 'kaboom' });
+  });
+});
+
+describe('a skipped member says WHICH skip it was', () => {
+  test('an aborted sibling and an empty split are two different reasons', async () => {
+    const stopped = await pooled<number, string>([1, 2, 3], 'abort', (payload) =>
+      payload === 1 ? Promise.reject(new Error('no')) : Promise.resolve('v'),
+    );
+    expect(stopped.map((one) => (one.status === 'skipped' ? one.reason : one.status))).toEqual([
+      'failed',
+      SKIPPED_ABORTED,
+      SKIPPED_ABORTED,
+    ]);
+
+    // Nothing was aborted here: index 1 simply has no input, and saying a sibling failed would
+    // send a caller to retry a tail that was never cut.
+    const sparse = await pooled<number | undefined, string>(
+      [1, undefined, 3],
+      'collect',
+      (payload) => Promise.resolve(`v${payload}`),
+    );
+    expect(sparse.map((one) => (one.status === 'skipped' ? one.reason : one.status))).toEqual([
+      'ok',
+      SKIPPED_NO_INPUT,
+      'ok',
+    ]);
+  });
+});
diff --git a/packages/ai/src/hive-pool.ts b/packages/ai/src/hive-pool.ts
index d19bcfc5..3925e0ed 100644
--- a/packages/ai/src/hive-pool.ts
+++ b/packages/ai/src/hive-pool.ts
@@ -5,9 +5,9 @@
 // happens to the siblings when one throws". Nothing here knows what a model is.
 
 import type { Ctx } from '@ultimat3/core';
-import { isUltimateError, withChildContext } from '@ultimat3/core';
+import { isThrownError, isUltimateError, stringField, withChildContext } from '@ultimat3/core';
 import type { HiveMember, HiveMemberError } from './hive-result';
-import { SKIPPED_ABORTED } from './hive-result';
+import { SKIPPED_ABORTED, SKIPPED_NO_INPUT } from './hive-result';
 
 export interface PoolInput<I, O> {
   readonly inputs: readonly I[];
@@ -45,8 +45,10 @@ export async function runPool<I, O>(input: PoolInput<I, O>): Promise<readonly Hi
       const payload = inputs[index];
       // Every index is claimed by exactly one worker and assigned exactly once, so the array has
       // no holes for a caller to trip over — `skipped` is a recorded outcome, never an absence.
+      // Two reasons, because they are two facts: the run stopped, or the split had nothing here.
       if (controller.signal.aborted || payload === undefined) {
-        members[index] = { status: 'skipped', index, reason: SKIPPED_ABORTED };
+        const reason = controller.signal.aborted ? SKIPPED_ABORTED : SKIPPED_NO_INPUT;
+        members[index] = { status: 'skipped', index, reason };
         continue;
       }
       try {
@@ -76,8 +78,13 @@ export async function runPool<I, O>(input: PoolInput<I, O>): Promise<readonly Hi
  */
 function failureOf(error: unknown): { readonly code: string; readonly reason: string } {
   if (isUltimateError(error)) return { code: error.code, reason: error.cause };
-  if (error instanceof Error && error.message !== '') {
-    return { code: 'unknown', reason: error.message };
+  // `isThrownError` and `stringField`, never `error instanceof Error` and `.message`: a member
+  // is an app's action, so the value is one the framework did not build — `instanceof` runs a
+  // `Proxy`'s `getPrototypeOf` trap and `.message` is a getter call. A throw HERE would take the
+  // whole hive down with it, which is the one outcome the three arms exist to prevent.
+  const message = stringField(error, 'message');
+  if (isThrownError(error) && message !== undefined && message !== '') {
+    return { code: 'unknown', reason: message };
   }
   return { code: 'unknown', reason: 'the member threw a value that is not an Error' };
 }
diff --git a/packages/ai/src/hive-result.ts b/packages/ai/src/hive-result.ts
index 8508b05d..2dc4caa7 100644
--- a/packages/ai/src/hive-result.ts
+++ b/packages/ai/src/hive-result.ts
@@ -59,6 +59,13 @@ export type HiveMemberError =
 
 export const SKIPPED_ABORTED = 'a sibling failed and onMemberError is abort';
 
+/**
+ * The OTHER way a member never runs, and a different fact: `split` produced nothing at this
+ * index. Its own string because `SKIPPED_ABORTED` named a cause that did not happen — a caller
+ * reading it retries the tail against a hive that stopped early, when the split is what to fix.
+ */
+export const SKIPPED_NO_INPUT = 'split produced no input at this index';
+
 /**
  * The member's `output` embedded verbatim in the `ok` arm, so a hive over `summarisePost` publishes
  * a summary in its OpenAPI response and its MCP `outputSchema` — not an opaque object.
diff --git a/packages/ai/src/tools.test.ts b/packages/ai/src/tools.test.ts
index b3bdcdfd..02932839 100644
--- a/packages/ai/src/tools.test.ts
+++ b/packages/ai/src/tools.test.ts
@@ -136,6 +136,106 @@ describe('runLlmToolCall renders a failure the model can act on', () => {
   });
 });
 
+// The values here are the ones the framework did not build: a tool's OUTPUT and a tool's THROW
+// both come from an app's own code, and `LlmToolResult.content` is typed `string` — the agent
+// loop truncates it, so anything else ends the whole run in a `TypeError` two frames away.
+describe('runLlmToolCall survives a result the framework did not build', () => {
+  test('a tool that returns nothing answers null, never a content that is not a string', async () => {
+    const silent = projectable('publishPost', { expose: true }, async () => undefined);
+    const result = await runLlmToolCall(
+      [silent],
+      { id: 'call-5', name: 'publishPost', input: { id: 'p1' } },
+      actor,
+    );
+    expect(result).toEqual({ toolUseId: 'call-5', content: 'null' });
+    expect(typeof result.content).toBe('string');
+  });
+
+  // `JSON.stringify` throws on a bigint and on a cycle, and RUNS any `toJSON` the value carries.
+  // The tool already ran, so telling the model it failed would buy a second run of its side
+  // effects — the result says the call succeeded and the value cannot be read.
+  test('an unserialisable result is reported as one, and never as a failed call', async () => {
+    for (const output of [
+      { total: 10n },
+      (() => {
+        const cycle: Record<string, unknown> = {};
+        cycle['self'] = cycle;
+        return cycle;
+      })(),
+      {
+        toJSON() {
+          throw new Error('no');
+        },
+      },
+    ]) {
+      const odd = projectable('publishPost', { expose: true }, async () => output);
+      const result = await runLlmToolCall(
+        [odd],
+        { id: 'call-6', name: 'publishPost', input: { id: 'p1' } },
+        actor,
+      );
+      expect(result.isError).toBe(true);
+      expect(result.content).toContain('not JSON');
+      expect(result.content).toContain('ran');
+    }
+  });
+
+  // The throw a `catch` block cannot read: `typeof error.code` is a getter call, and on a `Proxy`
+  // it is a trap. The branch that renders a denial must not be the branch that raises one.
+  test('a throw that fights being read is still a tool_result, not a raised TypeError', async () => {
+    const hostile: unknown[] = [
+      new Proxy(
+        {},
+        {
+          get() {
+            throw new Error('trapped get');
+          },
+          getPrototypeOf() {
+            throw new Error('trapped getPrototypeOf');
+          },
+        },
+      ),
+      Object.defineProperty(Object.create(null), 'code', {
+        get() {
+          throw new Error('trapped getter');
+        },
+        enumerable: true,
+      }),
+      Symbol('thrown'),
+    ];
+    for (const value of hostile) {
+      const boom = projectable('publishPost', { expose: true }, () => Promise.reject(value));
+      const result = await runLlmToolCall(
+        [boom],
+        { id: 'call-7', name: 'publishPost', input: { id: 'p1' } },
+        actor,
+      );
+      expect(result).toEqual({ toolUseId: 'call-7', content: 'tool failed', isError: true });
+    }
+  });
+
+  // A null-prototype error object is what a worker, a subprocess or a JSON round trip produces,
+  // and it still carries the three fields — reading them must not depend on a prototype.
+  test('a null-prototype error object still renders its code, cause and fix', async () => {
+    const flattened = Object.assign(Object.create(null), {
+      code: 'X_ORDER_LOCKED',
+      cause: 'order o-1 is closed',
+      fix: 'x db query "select * from orders"',
+    });
+    const boom = projectable('publishPost', { expose: true }, () => Promise.reject(flattened));
+    const result = await runLlmToolCall(
+      [boom],
+      { id: 'call-8', name: 'publishPost', input: { id: 'p1' } },
+      actor,
+    );
+    expect(result).toEqual({
+      toolUseId: 'call-8',
+      content: 'X_ORDER_LOCKED: order o-1 is closed (fix: x db query "select * from orders")',
+      isError: true,
+    });
+  });
+});
+
 describe('asProjectableAction', () => {
   const publishPost = () =>
     action({
diff --git a/packages/ai/src/tools.ts b/packages/ai/src/tools.ts
index d43b4b9c..c2cc98a1 100644
--- a/packages/ai/src/tools.ts
+++ b/packages/ai/src/tools.ts
@@ -20,7 +20,7 @@
 import type { AnyAction } from '@ultimat3/action';
 import { actionName, invoke, isAction } from '@ultimat3/action';
 import type { Actor } from '@ultimat3/core';
-import { isMcpExposed } from '@ultimat3/core';
+import { isMcpExposed, stringField } from '@ultimat3/core';
 import { toMcpInputSchema } from '@ultimat3/schema';
 
 /** The JSON Schema subset the framework emits for tool arguments. */
@@ -166,18 +166,47 @@ export async function runLlmToolCall(
   }
   try {
     const output = await action.run({ input: call.input, actor });
-    return { toolUseId: call.id, content: JSON.stringify(output) };
+    return resultOf(call.id, output);
   } catch (error) {
     // A policy denial is an outcome the model should read and react to, not a crash.
     return { toolUseId: call.id, content: describeFailure(error), isError: true };
   }
 }
 
+/**
+ * One tool's return value as the `tool_result` text. `content` is typed `string` and the agent
+ * loop TRUNCATES it, so anything else ends the run in a `TypeError` two frames away — and the
+ * value is an app's, so neither of `JSON.stringify`'s two other answers can be assumed away:
+ * `undefined` for a handler that returns nothing, and a throw on a bigint, a cycle or a `toJSON`
+ * of its own. A throw is reported as what it is — the call SUCCEEDED and its value cannot be
+ * read — never as a failure, because a model told the tool failed calls it again and buys its
+ * side effects twice.
+ */
+function resultOf(toolUseId: string, output: unknown): LlmToolResult {
+  let text: string | undefined;
+  try {
+    text = JSON.stringify(output);
+  } catch {
+    return {
+      toolUseId,
+      content:
+        'the tool ran, but its result is not JSON (a bigint, a cycle, or a toJSON that threw) — do not call it again',
+      isError: true,
+    };
+  }
+  return { toolUseId, content: text ?? 'null' };
+}
+
+/**
+ * The thrown value, read STRUCTURALLY and totally. `stringField` from `@ultimat3/core`, never
+ * `typeof e.code === 'string'`: the value is whatever an app's handler, its driver or its SDK
+ * threw, so each read is a getter call or a `Proxy` trap — and it runs inside the catch block
+ * that has nothing left to answer the model with if the probe itself raises.
+ */
 function describeFailure(error: unknown): string {
-  if (typeof error !== 'object' || error === null) return 'tool failed';
-  const e = error as { code?: unknown; cause?: unknown; fix?: unknown };
-  if (typeof e.code !== 'string') return 'tool failed';
-  const cause = typeof e.cause === 'string' ? e.cause : 'unknown';
-  const fix = typeof e.fix === 'string' ? e.fix : '';
-  return fix === '' ? `${e.code}: ${cause}` : `${e.code}: ${cause} (fix: ${fix})`;
+  const code = stringField(error, 'code');
+  if (code === undefined) return 'tool failed';
+  const cause = stringField(error, 'cause') ?? 'unknown';
+  const fix = stringField(error, 'fix') ?? '';
+  return fix === '' ? `${code}: ${cause}` : `${code}: ${cause} (fix: ${fix})`;
 }
diff --git a/packages/cli/CLAUDE.md b/packages/cli/CLAUDE.md
index 044ad2a6..cdf68b29 100644
--- a/packages/cli/CLAUDE.md
+++ b/packages/cli/CLAUDE.md
@@ -12,7 +12,7 @@ Tier 5. May import tiers 0–4. Nothing imports this except `create-ultimate`.
 | I/O | only `dispatch.ts` renders or exits; commands return `CommandResult` |
 | Staying up | a command still listening when `run` resolves returns `hold` (`hold.ts`), or `bin.ts` exits out from under it |
 | `--json` | every command, no exceptions — same data as the human render |
-| Errors | codes + titles in `src/error-codes.ts`, classes in `src/errors.ts`, subclass `UltimateError`, never a bare `Error` |
+| Errors | codes + titles in `src/error-codes.ts`, classes in `src/errors.ts`, subclass `UltimateError`, never a bare `Error`. A class may sit beside its one thrower when `errors.ts` has no room under the 500-line ceiling — `db-seed.ts` and `metrics-endpoint.ts` do |
 | Subprocesses | only through `exec.ts`, so a test can inject a fake `Runner` |
 | Templates | `templates/*.ts` return strings; no fixture files on disk |
 | Strings | rendered output through `messages.ts`, missing key renders `⟦key⟧` — see below for what is *not* rendered output |
@@ -512,8 +512,10 @@ session-scoped and the grant dies when the connection returns to the pool, so ev
 itself as leader and a rolling update double-fires every task.
 
 The relay runs on `worker` and only `worker` — the role that exists wherever jobs run at all.
-Duplicating it is safe (publish-then-mark is at-least-once and the idempotency key collapses the
-repeat) but pointless.
+Duplicating it is safe — the claim is a **lease** taken in the statement that locks the row
+(`@ultimat3/jobs`' `outbox-pg.ts`, fenced on `claimed_by`), so two relays never hold one batch —
+but pointless. The idempotency key is not the reason and never was: its conflict target is a
+partial index over live states, so it collapses a repeat only while the first job is still live.
 
 `SQL_IDEMPOTENCY_TABLE` is applied beside `SQL_JOBS_TABLE`, and the store is installed by the boot
 rather than by the app, even though `@ultimat3/action` documents
@@ -605,6 +607,16 @@ route: a tenant-scoped key takes `AUTHORIZED_OBJECT_CACHE` (`private, max-age=0`
 `authorization`/`cookie`), and only a key no tenant owns keeps `immutable`. A genuinely public image
 belongs under `apps/web/site/`, which is a static asset and never touches that disk.
 
+**A variant is CACHED only at a width the framework can mint.** The cache key is built entirely
+from caller-supplied query values, so `?w=1`, `?w=2`, … each wrote a new object to the app's only
+disk, on a route every signed-in tenant may reach for their own keys. `@ultimat3/seo`'s
+`MAX_IMAGE_WIDTH` (8192) bounds that and does not close it. `isMintableWidth` is the bound:
+`DEFAULT_WIDTHS` **plus the source's own intrinsic width**, which is exactly the set `usableWidths`
+puts in a `srcset` — the constant alone would refuse the widest entry of any image whose intrinsic
+width is not one of the eight. Anything outside it is still served; only the `put` is refused, so
+no caller gains a new 4xx. `?q=` is deliberately still unbounded here — the closed set for quality
+is `@ultimat3/seo`'s to declare, not this file's.
+
 `ICON_SOURCE` lives here, not in `cmd-doctor.ts`, because this is the module that reads it: the
 diagnostic checks what `x dev` serves, so one constant cannot pass the check and serve nothing.
 It is a **PNG** — core decodes PNG and JPEG only, and the SVG this used to name could never
diff --git a/packages/cli/src/budgets.test.ts b/packages/cli/src/budgets.test.ts
index 07a2c499..eab5cd57 100644
--- a/packages/cli/src/budgets.test.ts
+++ b/packages/cli/src/budgets.test.ts
@@ -120,6 +120,27 @@ describe('unit · measureJsBytes weighs the document, not the graph', () => {
     await Bun.write(join(dir, 'chunk.js'), 'console.log(1)');
     expect(await measureJsBytes('<script src="/chunk.js"></script>', dir)).toBe(14);
   });
+
+  // The bug this guards: a document that makes the browser execute NOTHING failed its JS budget,
+  // with a `fix:` telling the author to move an import that does not exist. `@ultimat3/seo` emits
+  // `application/ld+json` for structured data and `@ultimat3/render` emits `application/json` for
+  // island props — both are data the parser never runs.
+  test('a JSON-typed script is data, so a page of only data ships zero JS', async () => {
+    const document =
+      '<script type="application/ld+json">{"@type":"Article","headline":"a long headline"}</script>' +
+      '<script type="application/json" data-x-props="i1">{"title":"another long string"}</script>';
+    expect(await measureJsBytes(document, out)).toBe(0);
+  });
+
+  test('the rule is the type ending in json, not the one literal type', async () => {
+    expect(await measureJsBytes('<script type="importmap+json">{"a":1}</script>', out)).toBe(0);
+    expect(await measureJsBytes('<script type="APPLICATION/LD+JSON"> {"a":1} </script>', out)).toBe(
+      0,
+    );
+    // A module is code, and so is a type nobody declared.
+    expect(await measureJsBytes('<script type="module">let a=1</script>', out)).toBe(7);
+    expect(await measureJsBytes('<script>let a=1</script>', out)).toBe(7);
+  });
 });
 
 describe('unit · writeBuildStats is what makes X_BUDGET_UNMEASURED reachable', () => {
diff --git a/packages/cli/src/budgets.ts b/packages/cli/src/budgets.ts
index 6a571c93..46207df0 100644
--- a/packages/cli/src/budgets.ts
+++ b/packages/cli/src/budgets.ts
@@ -123,6 +123,17 @@ export async function readBuildStats(root: string): Promise<BuildStats | undefin
 
 const SCRIPT_TAG = /<script(?<attrs>[^>]*)>(?<body>[\s\S]*?)<\/script>/g;
 const SRC_ATTR = /\ssrc="(?<src>[^"]*)"/;
+const TYPE_ATTR = /\stype="(?<type>[^"]*)"/;
+
+/**
+ * `application/ld+json`, `application/json`, any `…+json`: the body is data, not code — the rule
+ * `@ultimat3/render`'s `head.ts` already states, restated because its `carriesJson` reads a
+ * `HeadTag` and is not exported, and this side has an attribute string off the emitted document.
+ * Without it a page shipping only `meta.ld` structured data and island props measured 8kb of JS
+ * and failed a 2kb budget with a `fix:` naming an import chain that does not exist.
+ */
+const carriesJson = (attrs: string): boolean =>
+  (TYPE_ATTR.exec(attrs)?.groups?.['type'] ?? '').trim().toLowerCase().endsWith('json');
 /**
  * An island's chunk is reached by `import()` from inside the hydration runtime, so it never appears
  * as a `<script src>` — and a document weighed by script tags alone was charged for the runtime and
@@ -144,8 +155,9 @@ export interface MeasuredJs {
 }
 
 /**
- * What a rendered document actually makes the browser execute: the bytes of every inline script,
- * the size of every file a `src` points at, and the size of every island chunk it boots. Measured
+ * What a rendered document actually makes the browser execute: the bytes of every inline script
+ * the parser will run, the size of every file a `src` points at, and the size of every island
+ * chunk it boots. A JSON-typed script is skipped — it is data the parser never runs. Measured
  * from the emitted HTML rather than from the declared graph, because the graph is what a route
  * *says* it ships and this gate exists to catch the case where those two disagree.
  */
@@ -162,7 +174,9 @@ export async function measureDocumentJs(html: string, out: string): Promise<Meas
   };
 
   for (const match of html.matchAll(SCRIPT_TAG)) {
-    const src = SRC_ATTR.exec(match.groups?.['attrs'] ?? '')?.groups?.['src'];
+    const attrs = match.groups?.['attrs'] ?? '';
+    if (carriesJson(attrs)) continue;
+    const src = SRC_ATTR.exec(attrs)?.groups?.['src'];
     if (src === undefined) {
       jsBytes += Buffer.byteLength(match.groups?.['body'] ?? '', 'utf8');
       continue;
diff --git a/packages/cli/src/cmd-db-branch.test.ts b/packages/cli/src/cmd-db-branch.test.ts
index 8d9b40fb..64891e98 100644
--- a/packages/cli/src/cmd-db-branch.test.ts
+++ b/packages/cli/src/cmd-db-branch.test.ts
@@ -15,11 +15,15 @@ import { exec } from './exec';
 import { parseArgs } from './parse';
 import { SPECS } from './registry';
 
-const ctxFor = (argv: readonly string[], cwd: string): CommandContext => ({
+const ctxFor = (
+  argv: readonly string[],
+  cwd: string,
+  env: Readonly<Record<string, string>> = {},
+): CommandContext => ({
   args: parseArgs(argv, SPECS),
   cwd,
   runner: exec,
-  env: {},
+  env,
   bunVersion: '1.3.0',
 });
 
@@ -68,6 +72,28 @@ describe('unit · x db branch', () => {
     }
   });
 
+  // The bug this guards: `Number.parseInt(ctx.env['PORT'] ?? '3000', 10)` — the bare form
+  // `flag-number.ts` exists to eliminate — put `http://feat.localhost:NaN` in `data.preview`, a
+  // machine-readable field naming no port at all.
+  test('PORT decides the preview url, and a PORT that is not one fails before the clone', async () => {
+    const root = await appRoot();
+    try {
+      const created = await dbCommand.run(
+        ctxFor(['db', 'branch', 'create', 'feat-p'], root, { PORT: '4000' }),
+      );
+      expect(created.data).toMatchObject({ preview: 'http://feat-p.localhost:4000' });
+
+      const refused = await thrownBy(
+        dbCommand.run(ctxFor(['db', 'branch', 'create', 'feat-bad'], root, { PORT: 'abc' })),
+      );
+      expect(refused).toMatchObject({ code: 'X_PORT_INVALID' });
+      // Nothing was cloned: the refusal happens before the branch is made.
+      expect(existsSync(join(root, '.x', 'pgdata-feat-bad'))).toBe(false);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
   test('the OLD bare-name form refuses, and hands back the invocation that means it', async () => {
     const root = await appRoot();
     try {
diff --git a/packages/cli/src/cmd-db-branch.ts b/packages/cli/src/cmd-db-branch.ts
index 4c688ea6..4a9a133c 100644
--- a/packages/cli/src/cmd-db-branch.ts
+++ b/packages/cli/src/cmd-db-branch.ts
@@ -11,6 +11,7 @@ import {
   branchDatabaseName,
   createExternalBranch,
   createPgliteBranch,
+  databaseNameOf,
   dropExternalBranch,
   dropPgliteBranch,
   isBranchName,
@@ -27,6 +28,7 @@ import { MissingPositionalError, UnknownCommandError } from './errors';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { flagString, nearest } from './parse';
+import { portFromEnv } from './serve';
 import { renderTable } from './table';
 
 /**
@@ -145,7 +147,9 @@ async function runCreate(
   services: DevServices,
   name: string,
 ): Promise<CommandResult> {
-  const port = Number.parseInt(ctx.env['PORT'] ?? '3000', 10);
+  // `portFromEnv`, never a bare `Number.parseInt`: the latter reads `PORT=abc` as `NaN` and put
+  // `http://feat.localhost:NaN` in `data.preview` — a machine-readable field naming no port.
+  const port = portFromEnv(ctx.env);
   let branch: BranchRow;
   try {
     branch =
@@ -205,7 +209,7 @@ function notABranch(services: DevServices, name: string): CommandResult {
   const target =
     services.db.mode === 'embedded'
       ? pgliteBranchLocation(services.db.url, name)
-      : branchDatabaseName(services.db.url.split('/').at(-1) ?? 'postgres', name);
+      : branchDatabaseName(databaseNameOf(services.db.url), name);
   return failure(msg('cli.db.branch.failed'), {
     code: 'X_DB_BRANCH_FAILED',
     cause: `"${name}" is not a branch of this database, so nothing was dropped (it would be ${target})`,
diff --git a/packages/cli/src/cmd-dev.test.ts b/packages/cli/src/cmd-dev.test.ts
index c7714a59..782cdbe5 100644
--- a/packages/cli/src/cmd-dev.test.ts
+++ b/packages/cli/src/cmd-dev.test.ts
@@ -104,6 +104,14 @@ let server: DevServer;
  */
 const BOOT_TIMEOUT_MS = 60_000;
 
+/** Bound and released: `METRICS_PORT` is read as a NAMED port, so it can be neither 0 nor 9090. */
+const METRICS_PORT = ((): number => {
+  const probe = Bun.serve({ port: 0, hostname: 'localhost', fetch: () => new Response('') });
+  const port = Number(new URL(probe.url).port);
+  probe.stop(true);
+  return port;
+})();
+
 beforeAll(async () => {
   await rm(ROOT, { recursive: true, force: true });
   for (const [path, contents] of Object.entries(FILES)) {
@@ -111,7 +119,9 @@ beforeAll(async () => {
   }
   resetRegistries();
   // Port 0 asks the OS for a free one, so this suite never collides with a running `x dev`.
-  server = await startDev({ root: ROOT, port: 0, env: {}, roles: ['web', 'worker', 'scheduler'] });
+  // `METRICS_PORT` is named, because `x dev` ignoring it is the thing under test.
+  const env = { METRICS_PORT: String(METRICS_PORT) };
+  server = await startDev({ root: ROOT, port: 0, env, roles: ['web', 'worker', 'scheduler'] });
 }, BOOT_TIMEOUT_MS);
 
 /**
@@ -155,6 +165,13 @@ describe('unit · x dev boots the app', () => {
     expect(server.findings).toEqual([]);
   });
 
+  // `cmd-dev.ts` passed no `metricsPort`, so `METRICS_PORT` moved the scrape port in the container
+  // and did nothing here — where it bound 9090 and the second `x dev` on the box died on it.
+  test('x dev honours METRICS_PORT, the same variable the container reads', async () => {
+    expect(new URL(server.running.metricsUrl).port).toBe(String(METRICS_PORT));
+    expect((await fetch(`${server.running.metricsUrl}/metrics`)).status).toBe(200);
+  });
+
   test('the app loaded cleanly and its actions are mounted as HTTP routes', async () => {
     const response = await fetchDev('/api/posts/echo', {
       method: 'POST',
diff --git a/packages/cli/src/cmd-dev.ts b/packages/cli/src/cmd-dev.ts
index 1d8b4ddf..d0b97f85 100644
--- a/packages/cli/src/cmd-dev.ts
+++ b/packages/cli/src/cmd-dev.ts
@@ -42,6 +42,7 @@ import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { findingFrom } from './output';
 import { flagString } from './parse';
+import { metricsPortFor } from './serve';
 import { loopFacts, loopFinding, loopNotice } from './statement-loop';
 
 const DEFAULT_PORT = 3000;
@@ -185,6 +186,10 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
   const running = await startRoles({
     roles: options.roles ?? DEV_ROLES,
     port: options.port,
+    // `serve.ts`'s expression, called rather than restated: `METRICS_PORT` was read in the
+    // container and ignored here, so the scrape port an operator moved was the one port `x dev`
+    // could not move — and the second `x dev` on a box died binding the hardcoded 9090.
+    metricsPort: metricsPortFor(options.env, options.port),
     buildId,
     runtime,
     routes,
@@ -266,14 +271,16 @@ export const devCommand: CliCommand = {
   spec: {
     name: 'dev',
     summary: 'all roles in one process: embedded services, sub-second reload, /_x mounted',
-    usage: 'x dev [--port 3000] [--role web,worker] [--json]',
+    usage: 'x dev [--port 3000] [--role web,worker] [--once] [--json]',
     requiresApp: true,
     flags: [
       { name: 'port', type: 'string', summary: 'HTTP port', default: String(DEFAULT_PORT) },
       {
         name: 'role',
         type: 'string',
-        summary: `roles to run (default: all of ${DEV_ROLES.join(',')})`,
+        // `replicator` is named because it is selectable and NOT default — it takes a replication
+        // slot on a shared database, which is not something every `x dev` should do by starting.
+        summary: `roles to run (default: all of ${DEV_ROLES.join(',')}; replicator is opt-in)`,
       },
       { name: 'once', type: 'boolean', summary: 'boot, report, exit — for smoke tests and CI' },
     ],
diff --git a/packages/cli/src/cmd-doctor.test.ts b/packages/cli/src/cmd-doctor.test.ts
index 2baff6b8..2418d7a1 100644
--- a/packages/cli/src/cmd-doctor.test.ts
+++ b/packages/cli/src/cmd-doctor.test.ts
@@ -1,7 +1,10 @@
 import { afterEach, describe, expect, test } from 'bun:test';
 import type { DoctorProbe } from './cmd-doctor';
-import { OFFLINE_FALLBACK, probeFor, runDoctor } from './cmd-doctor';
+import { doctorCommand, doctorPort, OFFLINE_FALLBACK, probeFor, runDoctor } from './cmd-doctor';
 import { ICON_SOURCE } from './dev-assets';
+import { PORT_RANGE, parseIntFlag } from './flag-number';
+import type { ParsedArgs } from './parse';
+import { parseArgs } from './parse';
 
 const probe = (over: Partial<DoctorProbe> = {}): DoctorProbe => ({
   bunVersion: '1.3.14',
@@ -50,6 +53,44 @@ describe('unit · x doctor', () => {
     expect(findings[0]?.fix).toBe('x dev --port 3001');
   });
 
+  // The bug this guards: `port + 1` at the top of the range emitted `x dev --port 65536`, which
+  // `x dev` refuses with X_CLI_BAD_FLAG — a fix line that reproduces a failure instead of ending
+  // one. The neighbour below is a port; the one above does not exist.
+  test('the suggested port is one x dev accepts, at the top of the range too', async () => {
+    const top = await runDoctor(probe({ port: PORT_RANGE.max, portFree: async () => false }));
+    expect(top[0]?.fix).toBe(`x dev --port ${PORT_RANGE.max - 1}`);
+    // And the suggestion is still parseable by the reader it is handed to.
+    for (const port of [3000, PORT_RANGE.max]) {
+      const findings = await runDoctor(probe({ port, portFree: async () => false }));
+      const suggested = Number((findings[0]?.fix ?? '').split(' ').at(-1));
+      // `x dev`'s own flag config, so the assertion is that the READER of this line accepts it.
+      expect(
+        parseIntFlag(String(suggested), {
+          name: 'port',
+          command: 'dev',
+          ...PORT_RANGE,
+          example: 'x dev --port 3000',
+        }),
+      ).toBe(suggested);
+    }
+  });
+
+  // `Bun.serve({ port: 0 })` always succeeds, so `x doctor --port 0` ran a check that could not
+  // fail. 0 means "let the kernel pick" to `x dev` and means nothing at all to a probe.
+  test('--port 0 is refused: a port to TEST is never the kernel picking one', () => {
+    const args = (value: string): ParsedArgs =>
+      parseArgs(['doctor', '--port', value], [doctorCommand.spec]);
+    let caught: unknown;
+    try {
+      doctorPort(args('0'));
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toMatchObject({ code: 'X_CLI_BAD_FLAG' });
+    expect(doctorPort(args('1'))).toBe(1);
+    expect(doctorPort(args(String(PORT_RANGE.max)))).toBe(PORT_RANGE.max);
+  });
+
   test('running outside an app stops after the one finding that explains everything', async () => {
     const findings = await runDoctor(probe({ root: undefined, exists: () => false }));
     expect(findings.map((finding) => finding.code)).toEqual(['X_NOT_IN_APP']);
diff --git a/packages/cli/src/cmd-doctor.ts b/packages/cli/src/cmd-doctor.ts
index 498f2778..958a87e3 100644
--- a/packages/cli/src/cmd-doctor.ts
+++ b/packages/cli/src/cmd-doctor.ts
@@ -14,6 +14,7 @@ import { checkSourceDrift } from './drift';
 import { intFlagOr, PORT_RANGE } from './flag-number';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
+import type { ParsedArgs } from './parse';
 
 /**
  * The injection seam `runDoctor` reads instead of the environment. Not a semver surface —
@@ -126,7 +127,7 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
       finding(
         'X_PORT_IN_USE',
         `port ${probe.port} is already listening`,
-        `x dev --port ${probe.port + 1}`,
+        `x dev --port ${neighbouringPort(probe.port)}`,
       ),
     );
   }
@@ -165,6 +166,26 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
   return findings;
 }
 
+/**
+ * A free-port suggestion `x dev` will actually accept. `port + 1` at the top of the range emitted
+ * `x dev --port 65536`, which `x dev` refuses with `X_CLI_BAD_FLAG` — a fix line that reproduces a
+ * failure rather than ending one. The neighbour below is a port; the one above does not exist.
+ */
+const neighbouringPort = (port: number): number =>
+  port < PORT_RANGE.max ? port + 1 : PORT_RANGE.max - 1;
+
+/**
+ * The port to TEST, and the one place `x doctor` reads it. `PORT_RANGE.min` is 0 because `x dev
+ * --port 0` means "let the kernel pick"; here 0 means nothing, and `Bun.serve({ port: 0 })` always
+ * succeeds — so the port check could not fail, which is worse than not running it.
+ */
+export const doctorPort = (args: ParsedArgs): number =>
+  intFlagOr(
+    args,
+    { name: 'port', command: 'doctor', ...PORT_RANGE, min: 1, example: 'x doctor --port 3000' },
+    DEFAULT_DOCTOR_PORT,
+  );
+
 const portFree = async (port: number): Promise<boolean> => {
   try {
     const server = Bun.serve({ port, fetch: () => new Response('') });
@@ -213,11 +234,7 @@ export const doctorCommand: CliCommand = {
     ],
   },
   async run(ctx: CommandContext): Promise<CommandResult> {
-    const port = intFlagOr(
-      ctx.args,
-      { name: 'port', command: 'doctor', ...PORT_RANGE, example: 'x doctor --port 3000' },
-      DEFAULT_DOCTOR_PORT,
-    );
+    const port = doctorPort(ctx.args);
     const findings = await runDoctor(probeFor(ctx.cwd, ctx.bunVersion, port));
     return {
       ok: findings.length === 0,
diff --git a/packages/cli/src/cmd-help.test.ts b/packages/cli/src/cmd-help.test.ts
index 8d881cef..771970a8 100644
--- a/packages/cli/src/cmd-help.test.ts
+++ b/packages/cli/src/cmd-help.test.ts
@@ -46,6 +46,25 @@ describe('unit · x help', () => {
     }
   });
 
+  // `x help <cmd>` renders `spec.flags` directly, so a flag missing from `usage` is NOT invisible
+  // there — but the usage line and `wiki/CLI-Reference.md` still disagreed about `x new --force`
+  // and `x dev --once`, and the wiki is the surface an agent reads first. Two commands, named,
+  // because five others (`g`, `db`, `deploy`, `manifest`, `jobs`) still omit flags from a usage
+  // line this rule would have to be widened across in one commit.
+  test('x new and x dev name every flag they declare in their own usage line', () => {
+    for (const name of ['new', 'dev']) {
+      const spec = SPECS.find((candidate) => candidate.name === name);
+      expect(spec).toBeDefined();
+      for (const flag of spec?.flags ?? []) {
+        // A boolean declared `example` is written `--no-example`: the negation IS the mention.
+        const named =
+          spec?.usage.includes(`--${flag.name}`) === true ||
+          spec?.usage.includes(`--no-${flag.name}`) === true;
+        expect([name, flag.name, named]).toEqual([name, flag.name, true]);
+      }
+    }
+  });
+
   // One command's page is a different shape: the hint is the summary there too, but it is not in
   // the body at all, so nothing about this change may add it back.
   test('one command page carries its usage and no catalogue hint', () => {
diff --git a/packages/cli/src/cmd-new.ts b/packages/cli/src/cmd-new.ts
index 158d520e..4005a8e8 100644
--- a/packages/cli/src/cmd-new.ts
+++ b/packages/cli/src/cmd-new.ts
@@ -67,7 +67,7 @@ export const newCommand: CliCommand = {
   spec: {
     name: 'new',
     summary: 'scaffold a new Ultimate monorepo that already runs',
-    usage: 'x new <name> [--dir path] [--no-example] [--dry-run] [--json]',
+    usage: 'x new <name> [--dir path] [--no-example] [--dry-run] [--force] [--json]',
     flags: [
       { name: 'dir', type: 'string', summary: 'parent directory (default: cwd)' },
       {
diff --git a/packages/cli/src/cmd-test.test.ts b/packages/cli/src/cmd-test.test.ts
index cf563850..074f4835 100644
--- a/packages/cli/src/cmd-test.test.ts
+++ b/packages/cli/src/cmd-test.test.ts
@@ -14,6 +14,7 @@ import type { Runner } from './exec';
 import { parseArgs } from './parse';
 import { discoverTests } from './test-select';
 import { SHARD_COMMAND_PREFIX } from './test-shards';
+import { defaultWorkers, WORKER_CEILING, WORKER_FLOOR } from './test-workers';
 import type { TestType } from './verify-tests';
 import { TEST_TYPES } from './verify-tests';
 
@@ -146,6 +147,45 @@ describe('unit · x test type selection', () => {
   });
 });
 
+describe('unit · x test --workers is bounded by the ceiling it documents', () => {
+  // The bug this guards: the summary said "max 8" and the reader passed no `max` at all, so
+  // `--workers 5000` was accepted and `planShards` clamped only to the file count — 842 concurrent
+  // Bun processes over this repo, each with the framework module graph and its own database.
+  test('a width above WORKER_CEILING is refused before a single process starts', async () => {
+    const { runner, calls } = recorder();
+    await expect(
+      testCommand.run(
+        context(['test', '--workers', String(WORKER_CEILING + 1)], import.meta.dir, runner),
+      ),
+    ).rejects.toMatchObject({ code: 'X_CLI_BAD_FLAG', fix: 'x test --workers 1' });
+    expect(calls.length).toBe(0);
+  });
+
+  test('the ceiling itself is accepted — the bound is inclusive', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'ultimate-x-test-ceiling-'));
+    try {
+      await Bun.write(join(root, 'a.test.ts'), 'export {};\n');
+      const { runner, calls } = recorder();
+      await testCommand.run(context(['test', '--workers', String(WORKER_CEILING)], root, runner));
+      expect(calls.length).toBe(1);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  // `x help test` derives from the spec, so a summary naming a default the code measured and
+  // REJECTED (`test-workers.ts`: `cpus - 1` is slower than not sharding at all) sends an agent to
+  // a number no run ever uses.
+  test('the summary names the default the code actually computes', () => {
+    const summary = (testCommand.spec.flags ?? []).find((flag) => flag.name === 'workers')?.summary;
+    expect(summary).not.toContain('CPUs - 1');
+    expect(summary).toContain(`max ${WORKER_CEILING}`);
+    expect(defaultWorkers(4)).toBe(6);
+    expect(defaultWorkers(1)).toBe(WORKER_FLOOR);
+    expect(defaultWorkers(64)).toBe(WORKER_CEILING);
+  });
+});
+
 describe('unit · x test extra positionals', () => {
   // `x test contract live` used to run contract and drop `live` in silence: a caller reading
   // "contract passed" believed both suites had run. Nothing may spawn before this is refused.
diff --git a/packages/cli/src/cmd-test.ts b/packages/cli/src/cmd-test.ts
index 9911fde5..142805b4 100644
--- a/packages/cli/src/cmd-test.ts
+++ b/packages/cli/src/cmd-test.ts
@@ -11,7 +11,7 @@ import type { ParsedArgs } from './parse';
 import { flagString } from './parse';
 import { discoverTests, missingSelection, readSample, readType, sampleFiles } from './test-select';
 import { quoteArg, runShards } from './test-shards';
-import { defaultWorkers } from './test-workers';
+import { defaultWorkers, WORKER_CEILING, WORKER_FLOOR, WORKER_OVERSUBSCRIBE } from './test-workers';
 import type { TestType } from './verify-tests';
 import { TEST_TYPES } from './verify-tests';
 
@@ -25,6 +25,12 @@ const readIndex = (args: ParsedArgs, name: string, min: number): number | undefi
     name,
     command: 'test',
     min,
+    // The ceiling the summary already claimed and the reader never enforced: `--workers 5000` was
+    // accepted, `planShards` clamps only to the file count, and `runParallel` `Promise.all`s them —
+    // one Bun process per test FILE, each with the framework module graph and a cloned database.
+    // `--worker` is an index into that split, so the same bound holds it (the exact upper index is
+    // `workers - 1`, refused a line below by the check that knows the real width).
+    max: WORKER_CEILING,
     example: `x test --${name} ${Math.max(min, 1)}`,
   });
 
@@ -54,7 +60,11 @@ export const testCommand: CliCommand = {
     usage: `x test [${TEST_TYPES.join('|')}] [--filter text] [--sample N] [--workers N] [--worker I] [--json]`,
     positionalChoices: TEST_TYPES,
     flags: [
-      { name: 'workers', type: 'string', summary: 'process count (default: CPUs - 1, max 8)' },
+      {
+        name: 'workers',
+        type: 'string',
+        summary: `process count (default: ${WORKER_OVERSUBSCRIBE}x CPUs, min ${WORKER_FLOOR}, max ${WORKER_CEILING})`,
+      },
       {
         name: 'worker',
         type: 'string',
diff --git a/packages/cli/src/cmd-verify.test.ts b/packages/cli/src/cmd-verify.test.ts
index c6708784..37791b55 100644
--- a/packages/cli/src/cmd-verify.test.ts
+++ b/packages/cli/src/cmd-verify.test.ts
@@ -6,8 +6,11 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { MANIFEST_FILENAME } from '@ultimat3/manifest';
 import { OPENAPI_FILE } from './app-openapi';
-import { runVerify, VERIFY_STEPS, verifyCommand, verifyStepNames } from './cmd-verify';
+import { readWorkers, runVerify, VERIFY_STEPS, verifyCommand, verifyStepNames } from './cmd-verify';
 import { exitCodeFor } from './output';
+import type { ParsedArgs } from './parse';
+import { parseArgs } from './parse';
+import { WORKER_CEILING } from './test-workers';
 import { VERIFY_FLOOR_FILE } from './verify-floor';
 import type { VerifyContext, VerifyStep } from './verify-step';
 import { VERIFY_STEP_NAMES } from './verify-step';
@@ -303,6 +306,32 @@ describe('unit · x verify', () => {
     expect(verifyCommand.spec.usage).toBe('x verify [--workers N] [--json]');
   });
 
+  // The bug this guards: the summary said "max 8" and `readWorkers` passed no `max`, so
+  // `--workers 5000` was accepted and every parallel step spawned one Bun process per test file.
+  test('--workers is bounded by the ceiling the summary names', () => {
+    const args = (value: string): ParsedArgs =>
+      parseArgs(['verify', '--workers', value], [verifyCommand.spec]);
+    expect(readWorkers(args(String(WORKER_CEILING)))).toBe(WORKER_CEILING);
+    expect(readWorkers(parseArgs(['verify'], [verifyCommand.spec]))).toBeUndefined();
+    // `toThrow(Class)` passes in Bun 1.3.14 when the callee merely RETURNS an error, so the code
+    // is asserted off a caught value instead.
+    let caught: unknown;
+    try {
+      readWorkers(args(String(WORKER_CEILING + 1)));
+    } catch (error) {
+      caught = error;
+    }
+    expect(caught).toMatchObject({ code: 'X_CLI_BAD_FLAG', fix: 'x verify --workers 4' });
+  });
+
+  // `x help verify` derives from the spec, and `cpus - 1` is the default `test-workers.ts`
+  // measured and rejected — slower than not sharding at all.
+  test('the flag summary names the default the code actually computes', () => {
+    const summary = verifyCommand.spec.flags?.[0]?.summary ?? '';
+    expect(summary).not.toContain('CPUs - 1');
+    expect(summary).toContain(`max ${WORKER_CEILING}`);
+  });
+
   test('a host check adds findings to the step it was registered for', async () => {
     const withHost: readonly VerifyStep[] = [
       {
@@ -408,13 +437,27 @@ describe('unit · x verify', () => {
     });
   });
 
-  describe('roadmap only runs when a host registers it', () => {
+  describe('roadmap applies to a repo that HAS a roadmap', () => {
     const step = VERIFY_STEPS.find((candidate) => candidate.name === 'roadmap');
 
-    test('skipped with no host check registered', async () => {
+    test('skipped in a repo with no docs/idea/14-roadmap.md', async () => {
       expect(await step?.applies?.(ctx)).toBe(false);
     });
 
+    // The bug this guards: `applies` keyed on a CALLER-supplied option, so a caller of the exported
+    // `runVerify(VERIFY_STEPS, ctx)` that passes no `hostChecks` — in a repo whose committed
+    // `x.verify.json` names `roadmap` — got `X_VERIFY_SUITE_VANISHED`, whose `fix:` is the command
+    // that just failed. Whether the step applies is a fact about the repo, never about the call.
+    test('applies on the file, not on the option', async () => {
+      const root = await mkdtemp(join(tmpdir(), 'x-verify-roadmap-'));
+      try {
+        await Bun.write(join(root, 'docs', 'idea', '14-roadmap.md'), '# roadmap\n');
+        expect(await step?.applies?.({ ...ctx, root })).toBe(true);
+      } finally {
+        await rm(root, { recursive: true, force: true });
+      }
+    });
+
     test('applies and surfaces the host findings once one is registered', async () => {
       // `cmd-verify` carries `fix` through to both renderers verbatim, so the fixture holds a real
       // one: an exact edit naming the file, the row and the marker, not advice.
@@ -424,7 +467,6 @@ describe('unit · x verify', () => {
         fix: 'edit docs/idea/14-roadmap.md: put "✅" or "🚧" in the second cell of the row starting "| 3 |", then: bun run scripts/roadmap.ts --json',
       };
       const withHost: VerifyContext = { ...ctx, hostChecks: { roadmap: async () => [finding] } };
-      expect(await step?.applies?.(withHost)).toBe(true);
       const outcome = await step?.run(withHost);
       expect(outcome?.ok).toBe(false);
       expect(outcome?.findings).toEqual([finding]);
diff --git a/packages/cli/src/cmd-verify.ts b/packages/cli/src/cmd-verify.ts
index d9b0e858..0c47401e 100644
--- a/packages/cli/src/cmd-verify.ts
+++ b/packages/cli/src/cmd-verify.ts
@@ -31,6 +31,7 @@ import { msg } from './messages';
 import type { CommandResult, Finding, StepResult } from './output';
 import { findingFrom } from './output';
 import type { ParsedArgs } from './parse';
+import { WORKER_CEILING, WORKER_FLOOR, WORKER_OVERSUBSCRIBE } from './test-workers';
 import {
   floorProblemFindings,
   floorRequires,
@@ -44,6 +45,9 @@ import { TEST_STEPS } from './verify-tests';
 import { checkFileSizes, checkPackageShape, hasWorkspacePackages } from './workspace-checks';
 
 /** The whole contract, in cost order. Every check the framework knows how to make lives here. */
+/** The one file that makes the `roadmap` step answerable, and therefore what `applies` reads. */
+const ROADMAP_FILE = join('docs', 'idea', '14-roadmap.md');
+
 export const VERIFY_STEPS: readonly VerifyStep[] = [
   {
     name: 'typecheck',
@@ -224,8 +228,11 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
     name: 'roadmap',
     summary: "every roadmap milestone's status marker matches what is actually on disk",
     // A generated app ships no `docs/idea/14-roadmap.md` — only the framework monorepo does, so
-    // only a host that registers this check has anything for the step to verify.
-    applies: async (ctx) => ctx.hostChecks?.roadmap !== undefined,
+    // the FILE is what decides. It keyed on `ctx.hostChecks?.roadmap` until `As of 2026-08`, which
+    // is a fact about the CALL: a caller of the exported `runVerify(VERIFY_STEPS, ctx)` passing no
+    // `hostChecks`, in a repo whose committed `x.verify.json` names `roadmap`, got
+    // `X_VERIFY_SUITE_VANISHED` — whose `fix:` is the command that had just failed.
+    applies: async (ctx) => existsSync(join(ctx.root, ROADMAP_FILE)),
     run: async (ctx) => fromFindings(await hostFindings(ctx, 'roadmap')),
   },
 ];
@@ -390,7 +397,7 @@ export const verifyCommand: CliCommand = {
       {
         name: 'workers',
         type: 'string',
-        summary: 'test processes per parallel step (default: CPUs - 1, max 8)',
+        summary: `test processes per parallel step (default: ${WORKER_OVERSUBSCRIBE}x CPUs, min ${WORKER_FLOOR}, max ${WORKER_CEILING})`,
       },
     ],
   },
@@ -405,13 +412,20 @@ export const verifyCommand: CliCommand = {
   },
 };
 
-/** `x test --workers` refuses the same values for the same reason — and now through the same
- * reader, so the claim is enforced rather than asserted in a comment. */
-const readWorkers = (args: ParsedArgs): number | undefined =>
+/**
+ * `x test --workers` refuses the same values for the same reason — and now through the same
+ * reader, so the claim is enforced rather than asserted in a comment. Exported for the test that
+ * pins the bound: the command's `run` reaches it only after the whole gate would have started.
+ *
+ * `max` is the ceiling the summary already claimed. Without it `--workers 5000` parsed, `planShards`
+ * clamped only to the file count, and `runParallel` `Promise.all`ed one Bun process per test file.
+ */
+export const readWorkers = (args: ParsedArgs): number | undefined =>
   readIntFlag(args, {
     name: 'workers',
     command: 'verify',
     min: 1,
+    max: WORKER_CEILING,
     example: 'x verify --workers 4',
   });
 
diff --git a/packages/cli/src/db-branch.test.ts b/packages/cli/src/db-branch.test.ts
index e7485858..1ae7400f 100644
--- a/packages/cli/src/db-branch.test.ts
+++ b/packages/cli/src/db-branch.test.ts
@@ -16,6 +16,7 @@ import {
   branchNameOf,
   createExternalBranch,
   createPgliteBranch,
+  databaseNameOf,
   dropExternalBranch,
   dropPgliteBranch,
   isBranchName,
@@ -131,6 +132,23 @@ describe('unit · the embedded database', () => {
   });
 });
 
+describe('unit · the database a connection URL names', () => {
+  // The bug this guards: `url.split('/').at(-1)` took the query string with it, so the refusal on
+  // `x db branch drop` named `postly?sslmode=require_branch_x` — a database that does not exist,
+  // in a message whose whole job is to be checkable.
+  test('the name is the path, never the path plus the query string', () => {
+    expect(databaseNameOf('postgres://u:p@host:5432/postly?sslmode=require')).toBe('postly');
+    expect(databaseNameOf('postgres://u:p@host:5432/postly')).toBe('postly');
+    // A percent-encoded name is decoded, because that is the name `pg_database` holds.
+    expect(databaseNameOf('postgres://host/my%20db')).toBe('my db');
+  });
+
+  test('a URL with no database, and a string that is not a URL, fall back rather than throw', () => {
+    expect(databaseNameOf('postgres://u:p@host:5432/')).toBe('postgres');
+    expect(databaseNameOf('not a url at all')).toBe('postgres');
+  });
+});
+
 describe('unit · the external database', () => {
   test('only databases carrying the branch marker are branches', async () => {
     const client = createRecordingClient();
diff --git a/packages/cli/src/db-branch.ts b/packages/cli/src/db-branch.ts
index 9a6bd6e3..6f9cf833 100644
--- a/packages/cli/src/db-branch.ts
+++ b/packages/cli/src/db-branch.ts
@@ -48,6 +48,24 @@ export function isBranchName(value: string): boolean {
   }
 }
 
+/**
+ * The database a connection URL names. `url.split('/').at(-1)` took the query string with it, so
+ * a refusal built from it named `postly?sslmode=require_branch_x` — a database that does not exist
+ * — in a message whose whole point is that a reader can check it. `pathname` is the one part that
+ * IS the database, and it arrives percent-encoded, which `pg_database` does not.
+ *
+ * Falls back rather than throwing: the caller is already reporting a failure, and a second throw
+ * from the reporter replaces a checkable refusal with a stack trace.
+ */
+export function databaseNameOf(url: string, fallback = 'postgres'): string {
+  try {
+    const name = decodeURIComponent(new URL(url).pathname.replace(/^\//, ''));
+    return name === '' ? fallback : name;
+  } catch {
+    return fallback;
+  }
+}
+
 /** Where a branch's app answers once something serves it — the preview half of the design. */
 export const previewUrl = (branch: string, port: number): string =>
   `http://${branch}.localhost:${port}`;
diff --git a/packages/cli/src/dev-assets.test.ts b/packages/cli/src/dev-assets.test.ts
index 11177bed..f05ab908 100644
--- a/packages/cli/src/dev-assets.test.ts
+++ b/packages/cli/src/dev-assets.test.ts
@@ -172,6 +172,33 @@ describe('unit · dev assets · responsive variants', () => {
     ).rejects.toBeUltimateError('X_IMAGE_UNSUPPORTED');
   });
 
+  // The bug this guards: the variant cache was keyed ENTIRELY on caller-supplied query values with
+  // no cap of its own, so an authenticated reader holding `storage:read` could mint one stored
+  // object per `?w=` on the app's only disk — `?w=1`, `?w=2`, … up to seo's `MAX_IMAGE_WIDTH`.
+  // The route is intentionally reachable by every signed-in tenant, so the write has to be bounded
+  // by what the framework can MINT, not by what a URL can ask for.
+  test('a width no srcset can mint is served but never written to the disk', async () => {
+    const routes = assetRoutes({ root, storage });
+    const cached = variantKey(SOURCE_KEY, { width: 7, format: 'png' });
+
+    const response = await call(routes, `${MEDIA_BASE_PATH}/${SOURCE_KEY}?w=7&f=png`);
+    // Still answered — refusing would break nothing an attacker cares about and would turn a
+    // cache decision into a new 4xx an app has to learn about.
+    expect(probeImage(new Uint8Array(await response.arrayBuffer())).width).toBe(7);
+    expect(await storage.disk().exists(cached)).toBe(false);
+  });
+
+  // `usableWidths` appends the SOURCE's own width when it is not one of `DEFAULT_WIDTHS`, so the
+  // widest entry of a real `srcset` is a width outside the closed set — clamping to that set alone
+  // would refuse a URL the framework itself mints.
+  test("the source's own intrinsic width is cacheable, because a srcset names it", async () => {
+    const routes = assetRoutes({ root, storage });
+    const cached = variantKey(SOURCE_KEY, { width: 1200, format: 'png' });
+
+    await call(routes, `${MEDIA_BASE_PATH}/${SOURCE_KEY}?w=1200&f=png`);
+    expect(await storage.disk().exists(cached)).toBe(true);
+  });
+
   test('an unusable width is refused before any byte is decoded', async () => {
     const routes = assetRoutes({ root, storage });
     await expect(call(routes, `${MEDIA_BASE_PATH}/${SOURCE_KEY}?w=0`)).rejects.toBeUltimateError(
diff --git a/packages/cli/src/dev-assets.ts b/packages/cli/src/dev-assets.ts
index 0e5bad04..418444f6 100644
--- a/packages/cli/src/dev-assets.ts
+++ b/packages/cli/src/dev-assets.ts
@@ -14,7 +14,7 @@ import { applyCacheHeaders } from '@ultimat3/http';
 import type { IconPlan } from '@ultimat3/pwa';
 import { BuiltinImagePipeline, PwaIconMissingError, planIcons } from '@ultimat3/pwa';
 import type { ImageQuery, ImageTransformDriver } from '@ultimat3/seo';
-import { builtinImageDriver, parseImageQuery } from '@ultimat3/seo';
+import { builtinImageDriver, DEFAULT_WIDTHS, parseImageQuery } from '@ultimat3/seo';
 import type { ImageFormat, ImageTransform, Storage } from '@ultimat3/storage';
 import { IMAGE_FORMATS, isTenantScoped, variantKey } from '@ultimat3/storage';
 import {
@@ -49,6 +49,24 @@ export const MEDIA_BASE_PATH = '/media';
  */
 const IMMUTABLE_IMAGE: CacheHint = { mode: 'immutable' };
 
+/**
+ * Whether a variant is one the framework itself can MINT, and therefore one worth storing.
+ *
+ * The cache key is built entirely from caller-supplied query values, and a signed-in reader
+ * holding `storage:read` may ask for any of them on their own objects — so `?w=1`, `?w=2`, … each
+ * wrote a new object to the app's only disk. `@ultimat3/seo`'s `MAX_IMAGE_WIDTH` (8192) bounds the
+ * blast radius and does not close it: 8192 stored objects per source, per format, is amplification
+ * a tenant drives with a `for` loop.
+ *
+ * The set is `DEFAULT_WIDTHS` **plus the source's intrinsic width**, which is exactly what
+ * `usableWidths` puts in a `srcset` — clamping to the constant alone would refuse the widest entry
+ * of every image whose intrinsic width is not one of the eight, a URL the framework mints itself.
+ * Anything outside it is still SERVED: this decides what is written, not what is answered, so no
+ * caller gains a new 4xx and the disk stops growing on a stranger's key.
+ */
+const isMintableWidth = (width: number | undefined, intrinsic: number): boolean =>
+  width === undefined || width === intrinsic || DEFAULT_WIDTHS.includes(width);
+
 const imageResponse = (bytes: Uint8Array, contentType: string, cache: CacheHint): Response =>
   applyCacheHeaders(
     // Copied, not passed through: a `Uint8Array<ArrayBufferLike>` may be backed by a
@@ -112,6 +130,7 @@ async function transformedVariant(
   }
 
   const source = await disk.get(key);
+  const intrinsic = probeImage(source.bytes).width;
   // The seam is WHICH driver transforms, not who resolves the bytes: `TransformRequest.width` is
   // required, and a request with no `?w=` gets its width from the source's own header — so the
   // read happens either way and a supplied driver is handed the same resolved request the builtin
@@ -122,11 +141,11 @@ async function transformedVariant(
     src: key,
     // A header read, not a decode: `?f=webp` alone still needs a width, and the source's own is
     // the only one that does not resize an image the caller never asked to resize.
-    width: query.width ?? probeImage(source.bytes).width,
+    width: query.width ?? intrinsic,
     ...(query.format === undefined ? {} : { format: query.format }),
     ...(query.quality === undefined ? {} : { quality: query.quality }),
   });
-  if (cached !== undefined) {
+  if (cached !== undefined && isMintableWidth(query.width, intrinsic)) {
     await disk.put(cached, variant.bytes, { contentType: variant.contentType });
   }
   return imageResponse(variant.bytes, variant.contentType, cache);
diff --git a/packages/cli/src/dev-roles.ts b/packages/cli/src/dev-roles.ts
index d45c7152..d4503b60 100644
--- a/packages/cli/src/dev-roles.ts
+++ b/packages/cli/src/dev-roles.ts
@@ -294,9 +294,11 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
     // — every enqueue in a request handler silently becomes a job that never runs.
     //
     // On `worker`, and on `worker` alone: it is the role that exists wherever jobs run at all, and
-    // a relay is safe to duplicate (publish-then-mark is at-least-once and the idempotency key
-    // collapses the repeat) but pointless to spread. A deployment with no `worker` has no one to
-    // run the jobs either way.
+    // a relay is safe to duplicate — the claim is a LEASE taken in the statement that locks the
+    // row, so two relays never hold one batch — but pointless to spread. The idempotency key is
+    // not the reason and never was: its conflict target is a partial index over live states, so it
+    // collapses a repeat only while the first job is still live. A deployment with no `worker` has
+    // no one to run the jobs either way.
     const relay: OutboxRelay | null = selected.includes('worker')
       ? createOutboxRelay({ store: options.runtime.outbox, driver: options.runtime.jobs })
       : null;
diff --git a/packages/cli/src/dev-storage.test.ts b/packages/cli/src/dev-storage.test.ts
index 49be12cf..8e539c88 100644
--- a/packages/cli/src/dev-storage.test.ts
+++ b/packages/cli/src/dev-storage.test.ts
@@ -14,14 +14,14 @@ import type { RequestContext, Route } from '@ultimat3/http';
 import { createRequestContext, defineHttpConfig, UltimateRequest } from '@ultimat3/http';
 import { clearPermissions, clearRoles, definePermissions, defineRoles } from '@ultimat3/policy';
 import type { Storage } from '@ultimat3/storage';
-import { defineStorage, localDriver, resetStorage, scopedKey } from '@ultimat3/storage';
 import {
-  etagMatches,
-  parseByteRange,
-  STORAGE_BASE_PATH,
-  STORAGE_READ_PERMISSION,
-  storageRoutes,
-} from './dev-storage';
+  DEFAULT_SIGNED_URL_BASE,
+  defineStorage,
+  localDriver,
+  resetStorage,
+  scopedKey,
+} from '@ultimat3/storage';
+import { etagMatches, parseByteRange, STORAGE_READ_PERMISSION, storageRoutes } from './dev-storage';
 
 const BYTES = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
 const KEY = scopedKey('org-1', 'avatars', 'a.png');
@@ -46,10 +46,10 @@ interface CallInit {
  */
 async function call(routes: readonly Route[], init: CallInit = {}): Promise<Response> {
   const route = routes[0];
-  expect(route?.path).toBe(`${STORAGE_BASE_PATH}/:disk/*key`);
+  expect(route?.path).toBe(`${DEFAULT_SIGNED_URL_BASE}/:disk/*key`);
   if (route === undefined) throw new Error('no route');
   const key = init.key ?? KEY;
-  const url = new URL(`http://dev.test${STORAGE_BASE_PATH}/${init.disk ?? 'local'}/${key}`);
+  const url = new URL(`http://dev.test${DEFAULT_SIGNED_URL_BASE}/${init.disk ?? 'local'}/${key}`);
   const ctx: RequestContext = createRequestContext({
     url,
     method: 'GET',
@@ -158,7 +158,7 @@ describe('unit · dev storage · authorization', () => {
     // holding the same line on its own, with the code the decision carried rather than a
     // flattened 403 — so the guarantee does not depend on which surface called it.
     const route = storageRoutes({ storage })[0];
-    const url = new URL(`http://dev.test${STORAGE_BASE_PATH}/local/${KEY}`);
+    const url = new URL(`http://dev.test${DEFAULT_SIGNED_URL_BASE}/local/${KEY}`);
     const ctx = createRequestContext({
       url,
       method: 'GET',
diff --git a/packages/cli/src/dev-storage.ts b/packages/cli/src/dev-storage.ts
index e3a49599..1883fd6a 100644
--- a/packages/cli/src/dev-storage.ts
+++ b/packages/cli/src/dev-storage.ts
@@ -2,6 +2,10 @@
 // owns keys, bytes and the tenant boundary and owns no `Response`; `@ultimat3/policy` owns the
 // one authz decision; this file is where those two meet a `Route` — the same shape `dev-assets.ts`
 // uses for `/icons` and `/media`, so `x dev` and `apps/web/server.ts` mount one read path, not two.
+//
+// The base path is `@ultimat3/storage`'s `DEFAULT_SIGNED_URL_BASE`, imported and never restated:
+// `localDriver` SIGNS `/_storage/<disk>/<key>`, so a local `'/_storage'` here is a second statement
+// of one constant — and a signer and a reader that disagree serve 404 for every signed URL.
 
 import { actorOf } from '@ultimat3/action';
 import type { Actor } from '@ultimat3/core';
@@ -12,15 +16,13 @@ import { can, codeOf, evaluate, forbidden, reasonOf } from '@ultimat3/policy';
 import type { Storage, StorageRead } from '@ultimat3/storage';
 import {
   assertSafeKey,
+  DEFAULT_SIGNED_URL_BASE,
   isTenantScoped,
   isWithinOrg,
   objectNotFound,
   orgMismatch,
 } from '@ultimat3/storage';
 
-/** `localDriver` signs `/_storage/<disk>/<key>`, so the read half hangs off the same base. */
-export const STORAGE_BASE_PATH = '/_storage';
-
 /**
  * The one capability that gates reading a stored object, on every disk. A permission and not a
  * per-disk family: `disk` is in the policy's `input`, so an app that wants a per-disk rule writes
@@ -223,7 +225,7 @@ export function storageRoutes(options: StorageRoutesOptions): readonly Route[] {
   return [
     {
       method: 'GET',
-      path: `${STORAGE_BASE_PATH}/:disk/*key`,
+      path: `${DEFAULT_SIGNED_URL_BASE}/:disk/*key`,
       meta: {
         name: 'storage.read',
         auth: 'required',
diff --git a/packages/cli/src/dev-traces.test.ts b/packages/cli/src/dev-traces.test.ts
index 95006567..3cec58ec 100644
--- a/packages/cli/src/dev-traces.test.ts
+++ b/packages/cli/src/dev-traces.test.ts
@@ -3,7 +3,7 @@
 // Every span below arrives through `withSpan`, exactly as `x dev` receives them.
 
 import { afterEach, describe, expect, test } from 'bun:test';
-import type { FrozenClock } from '@ultimat3/core';
+import type { FrozenClock, SpanContext } from '@ultimat3/core';
 import { configureTelemetry, frozenClock, resetTelemetry, withSpan } from '@ultimat3/core';
 import { STATEMENT_ATTRIBUTE } from '@ultimat3/db';
 import { createTraceRecorder } from './dev-traces';
@@ -20,7 +20,7 @@ const install = (
 /** One request, exactly as the HTTP pipeline opens it: root span, `http.*` attributes, children. */
 function request(
   clock: FrozenClock,
-  facts: { id: string; method?: string; path: string; status?: number },
+  facts: { id: string; method?: string; path: string; status?: number; parent?: SpanContext },
   children: readonly string[] = [],
   statements: readonly string[] = [],
 ): void {
@@ -53,10 +53,19 @@ function request(
         'http.status_code': facts.status ?? 200,
       });
     },
-    { kind: 'server' },
+    // Exactly `pipeline.ts`'s own call: `parent: correlation.parent`, which is defined whenever the
+    // caller sent a `traceparent` and `undefined` when it did not.
+    { kind: 'server', ...(facts.parent === undefined ? {} : { parent: facts.parent }) },
   );
 }
 
+/** A caller's span, as `parseTraceparent` hands one back off an inbound `traceparent` header. */
+const inbound: SpanContext = {
+  traceId: '4bf92f3577b34da6a3ce929d0e0e4736',
+  spanId: '00f067aa0ba902b7',
+  traceFlags: 1,
+};
+
 afterEach(() => {
   resetTelemetry();
 });
@@ -121,6 +130,24 @@ describe('unit · the /_x timeline source', () => {
     expect(spans.every((span) => span.startMs >= 0)).toBe(true);
   });
 
+  // The bug this guards: `isHttpRoot` also required `parentSpanId === undefined`, and
+  // `packages/http/src/pipeline.ts` passes `parent: correlation.parent` — so a request from an
+  // instrumented client, an ingress or a service mesh had a defined parent, `spans.find` answered
+  // `undefined`, and the whole trace vanished from `/_x/timeline`.
+  test('a request that arrived with an inbound traceparent is still a request', () => {
+    const { recorder, clock } = install();
+    request(clock, { id: 'req_1', path: '/feed', parent: inbound }, ['query.feed']);
+
+    const [trace] = recorder.traces();
+    expect(recorder.traces()).toHaveLength(1);
+    expect(trace?.requestId).toBe('req_1');
+    expect(trace?.path).toBe('/feed');
+    // The root still anchors the flame at depth 0, whatever it arrived with.
+    const root = trace?.spans.find((span) => span.parentId === null);
+    expect(root?.kind).toBe('http');
+    expect(trace?.spans.filter((span) => span.parentId === null)).toHaveLength(1);
+  });
+
   test('spans that never got an http root are not reported as requests', () => {
     const { recorder, clock } = install();
     // A worker's job trace: same tracer, no request. The timeline panel would otherwise show a
diff --git a/packages/cli/src/dev-traces.ts b/packages/cli/src/dev-traces.ts
index 9ab93905..c9be4cb4 100644
--- a/packages/cli/src/dev-traces.ts
+++ b/packages/cli/src/dev-traces.ts
@@ -71,9 +71,27 @@ function requestFacts(root: ReadableSpan): { method: string; path: string } {
   };
 }
 
+/** `http.request_id` is stamped by the pipeline's root and by nothing else; the name is a fallback. */
 const isHttpRoot = (span: ReadableSpan): boolean =>
-  span.parentSpanId === undefined &&
-  (span.attributes['http.request_id'] !== undefined || /^[A-Z]+ \//.test(span.name));
+  span.attributes['http.request_id'] !== undefined || /^[A-Z]+ \//.test(span.name);
+
+/**
+ * The request's own span among a trace's. `parentSpanId === undefined` was a third CONDITION
+ * until `As of 2026-08`, and it dropped every request that arrived with an inbound
+ * `traceparent`: `pipeline.ts` passes `parent: correlation.parent`, so the root has a defined
+ * `parentSpanId`, `spans.find(isHttpRoot)` answered `undefined`, and the whole trace vanished
+ * from `/_x/timeline` for any caller behind an instrumented client, an ingress or a service
+ * mesh. It survives as the TIE-BREAK: the outermost candidate is the one whose parent is not
+ * itself in this recording, so a nested candidate can never outrank the request's own span.
+ */
+function httpRootOf(spans: readonly ReadableSpan[]): ReadableSpan | undefined {
+  const candidates = spans.filter(isHttpRoot);
+  const recorded = new Set(spans.map((span) => span.context.spanId));
+  const outermost = candidates.find(
+    (span) => span.parentSpanId === undefined || !recorded.has(span.parentSpanId),
+  );
+  return outermost ?? candidates[0];
+}
 
 function toTrace(root: ReadableSpan, spans: readonly ReadableSpan[]): RequestTrace {
   const { method, path } = requestFacts(root);
@@ -121,7 +139,11 @@ export function createTraceRecorder(options: { limit?: number } = {}): TraceReco
     const spans = byTrace.get(traceId);
     if (spans === undefined) {
       byTrace.set(traceId, [span]);
-      // Bounded by trace, not by span: dropping half a request would leave a flame with holes.
+      // Bounded by TRACE, not by span: dropping half a request would leave a flame with holes.
+      // The cost is stated rather than capped — one trace's span array has no bound of its own, so
+      // a request issuing 50k statements holds 50k `ReadableSpan`s until it is evicted. That is a
+      // dev-only recorder (`serve.ts` installs none), and a per-trace cap would silently produce
+      // the holed flame this bound exists to prevent.
       while (byTrace.size > limit) {
         const oldest = byTrace.keys().next();
         if (oldest.done === true) break;
@@ -137,7 +159,7 @@ export function createTraceRecorder(options: { limit?: number } = {}): TraceReco
     traces(): readonly RequestTrace[] {
       const traces: RequestTrace[] = [];
       for (const spans of byTrace.values()) {
-        const root = spans.find(isHttpRoot);
+        const root = httpRootOf(spans);
         if (root !== undefined) traces.push(toTrace(root, spans));
       }
       return traces.sort((a, b) => b.startedAt.localeCompare(a.startedAt));
diff --git a/packages/cli/src/error-fixes.test.ts b/packages/cli/src/error-fixes.test.ts
index 68978a47..f88e1486 100644
--- a/packages/cli/src/error-fixes.test.ts
+++ b/packages/cli/src/error-fixes.test.ts
@@ -7,7 +7,8 @@ import { afterAll, describe, expect, test } from 'bun:test';
 import { mkdtemp, rm, symlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { loadErrorCatalog } from './error-catalog';
+import { loadErrorCatalog, registeredErrorCodes } from './error-catalog';
+import { CLI_ERROR_CODES } from './error-codes';
 import { fixProblem } from './error-contract';
 import {
   codeFixes,
@@ -196,6 +197,28 @@ describe('unit · errors.explain projects the throw site', () => {
   );
 });
 
+/**
+ * A registered, non-CLI code the throw-site index holds no entry for — DERIVED, never named.
+ *
+ * `X_DRAINING` was the literal here until `endOfLiteral` stopped reading a lone apostrophe as a
+ * string opener: the desync blanked the rest of `packages/http/src/errors.ts`, so `draining()` at
+ * its line 426 was invisible and this suite asserted a premise the source disproves. Any code with
+ * no readable site exercises the same branch, and no single code gaining one falsifies it again.
+ * A CLI code is excluded because `CLI_FIXES` answers those and the fallback never runs.
+ */
+async function unindexedCode(): Promise<string> {
+  const [registered] = await Promise.all([registeredErrorCodes(), loadCodeFixes()]);
+  const found = [...registered]
+    .sort()
+    .find(
+      (code) => !codeFixes().has(code) && !(CLI_ERROR_CODES as readonly string[]).includes(code),
+    );
+  // Not a silent skip: every code having a readable site is a real change to what this branch
+  // means, and it should be read here rather than pass as a test that stopped testing anything.
+  expect(found).toBeDefined();
+  return found ?? '';
+}
+
 describe('unit · the three honest fallbacks', () => {
   test(
     'a code whose throw site computes its fix leads with the file, and with no verb',
@@ -215,16 +238,16 @@ describe('unit · the three honest fallbacks', () => {
   );
 
   // Loaded, NOT reset. `resetCodeFixes()` empties the index for every code alike, so the assertion
-  // would have held for a reason that has nothing to do with X_DRAINING — it would still pass if
-  // core grew a readable throw site for it tomorrow.
+  // would have held for a reason that has nothing to do with the branch under test — it would
+  // still pass if the framework grew a readable throw site for the code tomorrow.
   test(
-    'a code nothing in the installed framework raises says exactly that',
+    'a code the throw-site index holds nothing for says so instead of naming a command',
     async () => {
-      await Promise.all([loadErrorCatalog(), loadCodeFixes()]);
-      expect(codeFixes().get('X_DRAINING')).toBeUndefined();
+      const code = await unindexedCode();
+      expect(codeFixes().get(code)).toBeUndefined();
       expect(codeFixScan()).toBe('read');
-      const fix = explainErrorCode('X_DRAINING')?.fix ?? '';
-      expect(fix).toContain('nothing in the installed framework raises X_DRAINING');
+      const fix = explainErrorCode(code)?.fix ?? '';
+      expect(fix).toContain(`nothing in the installed framework raises ${code}`);
       expect(fixProblem(fix)).toBeUndefined();
     },
     REPO_SCAN_MS,
@@ -233,12 +256,17 @@ describe('unit · the three honest fallbacks', () => {
   // The third case is the one an empty index used to be indistinguishable from: nothing LOOKED.
   // Asserting the same code both ways is what proves the two lines are chosen by `codeFixScan()`
   // and not by the code. Last in the file, because it leaves the index reset.
-  test('an unread index says the packages could not be read, never that nothing raises the code', () => {
-    resetCodeFixes();
-    expect(codeFixScan()).toBe('unread');
-    const fix = explainErrorCode('X_DRAINING')?.fix ?? '';
-    expect(fix).toContain('could not be read');
-    expect(fix).not.toContain('nothing in the installed framework raises');
-    expect(fixProblem(fix)).toBeUndefined();
-  });
+  test(
+    'an unread index says the packages could not be read, never that nothing raises the code',
+    async () => {
+      const code = await unindexedCode();
+      resetCodeFixes();
+      expect(codeFixScan()).toBe('unread');
+      const fix = explainErrorCode(code)?.fix ?? '';
+      expect(fix).toContain('could not be read');
+      expect(fix).not.toContain('nothing in the installed framework raises');
+      expect(fixProblem(fix)).toBeUndefined();
+    },
+    REPO_SCAN_MS,
+  );
 });
diff --git a/packages/cli/src/exec.test.ts b/packages/cli/src/exec.test.ts
new file mode 100644
index 00000000..c95884f3
--- /dev/null
+++ b/packages/cli/src/exec.test.ts
@@ -0,0 +1,44 @@
+// The one subprocess boundary, from both ends: a program that runs, and a program that is not
+// there. The second is the case `x deploy` hits on a machine without `docker`, and it reached the
+// user as `Error: Executable not found in $PATH` — no code, no fix, from the boundary whose own
+// header says the "command not found" failure mode is identical everywhere.
+
+import { describe, expect, test } from 'bun:test';
+import { exec } from './exec';
+
+/** Thrown values are read as data: `expect(fn).toThrow(Class)` passes in Bun 1.3.14 on a RETURN. */
+const thrownBy = async (run: () => Promise<unknown>): Promise<Record<string, unknown>> => {
+  try {
+    await run();
+  } catch (error) {
+    return error as unknown as Record<string, unknown>;
+  }
+  return {};
+};
+
+describe('unit · the CLI subprocess boundary', () => {
+  test('a program that exists runs, and its output comes back', async () => {
+    const result = await exec(['bun', '--version'], { cwd: import.meta.dir });
+    expect(result.ok).toBe(true);
+    expect(result.code).toBe(0);
+    expect(result.stdout.trim().length).toBeGreaterThan(0);
+  });
+
+  test('a program that is not on PATH is a coded refusal naming the program', async () => {
+    const thrown = await thrownBy(() =>
+      exec(['definitely-not-a-real-binary-xyz', '--help'], { cwd: import.meta.dir }),
+    );
+    expect(thrown['code']).toBe('X_CLI_UNEXPECTED');
+    expect(String(thrown['cause'])).toContain('definitely-not-a-real-binary-xyz');
+    // The dead end this replaces: `dispatch.ts` rendered the bare Error as X_CLI_UNEXPECTED with
+    // `fix: x doctor --json`, and `runDoctor` checks nothing about an absent binary.
+    expect(String(thrown['fix'])).toContain('definitely-not-a-real-binary-xyz');
+    expect(String(thrown['fix'])).not.toBe('x doctor --json');
+  });
+
+  test('an empty command is a caller bug, coded like every other CLI failure', async () => {
+    const thrown = await thrownBy(() => exec([], { cwd: import.meta.dir }));
+    expect(thrown['code']).toBe('X_CLI_UNEXPECTED');
+    expect(String(thrown['cause'])).toContain('empty command');
+  });
+});
diff --git a/packages/cli/src/exec.ts b/packages/cli/src/exec.ts
index 7db5efef..8d8714da 100644
--- a/packages/cli/src/exec.ts
+++ b/packages/cli/src/exec.ts
@@ -5,7 +5,7 @@
 // `UltimateError` straight from core rather than a class in `./errors`: this module is imported by
 // every command, and `./errors` runs `registerErrorCodes` on import — a subprocess boundary must
 // not decide when the CLI's registry is populated. `X_CLI_UNEXPECTED` is owned there all the same.
-import { UltimateError } from '@ultimat3/core';
+import { renderThrowable, UltimateError } from '@ultimat3/core';
 
 export interface ExecResult {
   readonly command: readonly string[];
@@ -27,6 +27,39 @@ export type Runner = (command: readonly string[], options: ExecOptions) => Promi
 /** performance.now(), not Date.now(): the test preload freezes the wall clock on purpose. */
 const now = (): number => performance.now();
 
+/**
+ * The failure mode this file's header already promised was identical everywhere, and the one it
+ * never coded. `x deploy` on a machine without `docker` threw Bun's own `Error: Executable not
+ * found in $PATH`; `dispatch.ts` rendered it as `X_CLI_UNEXPECTED` with `fix: x doctor --json`,
+ * and `runDoctor` checks nothing about an absent binary — an instruction that cannot close the
+ * error is axiom 4 inverted. The code stays `X_CLI_UNEXPECTED` (the CLI already owns it for a
+ * failure of its own machinery); what changes is that the fix names the program to install.
+ *
+ * The thrown value goes through core's render helper and is never interpolated: an `unknown`
+ * reaching a `cause:` through `${…}` is what `bun run error-render` refuses, and this one is
+ * genuinely unknown — Bun raises `ENOENT` for a missing program, `EACCES` for an unrunnable one.
+ *
+ * The return type is inferred so this stays one statement of `Bun.spawn`'s own shape.
+ */
+function spawnOrRefuse(command: readonly string[], options: ExecOptions) {
+  const [head = '', ...rest] = command;
+  try {
+    return Bun.spawn([head, ...rest], {
+      cwd: options.cwd,
+      env: options.env === undefined ? Bun.env : { ...Bun.env, ...options.env },
+      stdin: options.stdin === undefined ? 'ignore' : new TextEncoder().encode(options.stdin),
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+  } catch (error) {
+    throw new UltimateError({
+      code: 'X_CLI_UNEXPECTED',
+      cause: `the CLI could not run "${head}" from ${options.cwd}: ${renderThrowable(error)}`,
+      fix: `install "${head}" and put it on PATH, then re-run — confirm with: command -v ${head}`,
+    });
+  }
+}
+
 export const exec: Runner = async (command, options) => {
   const started = now();
   const [head, ...rest] = command;
@@ -40,13 +73,7 @@ export const exec: Runner = async (command, options) => {
       fix: 'pass the program as the first element: exec(["bun", "test"], { cwd })',
     });
   }
-  const proc = Bun.spawn([head, ...rest], {
-    cwd: options.cwd,
-    env: options.env === undefined ? Bun.env : { ...Bun.env, ...options.env },
-    stdin: options.stdin === undefined ? 'ignore' : new TextEncoder().encode(options.stdin),
-    stdout: 'pipe',
-    stderr: 'pipe',
-  });
+  const proc = spawnOrRefuse([head, ...rest], options);
   const [stdout, stderr, code] = await Promise.all([
     new Response(proc.stdout).text(),
     new Response(proc.stderr).text(),
diff --git a/packages/cli/src/metrics-endpoint.test.ts b/packages/cli/src/metrics-endpoint.test.ts
index 0b7fcb12..dc1e11e1 100644
--- a/packages/cli/src/metrics-endpoint.test.ts
+++ b/packages/cli/src/metrics-endpoint.test.ts
@@ -12,7 +12,11 @@ import {
   resetListeners,
   resetMetrics,
 } from '@ultimat3/core';
-import { type MetricsEndpoint, startMetricsEndpoint } from './metrics-endpoint';
+import {
+  type MetricsEndpoint,
+  MetricsPortInUseError,
+  startMetricsEndpoint,
+} from './metrics-endpoint';
 
 let endpoint: MetricsEndpoint | undefined;
 
@@ -59,6 +63,25 @@ describe('the scrape endpoint', () => {
     expect((await scrape('/healthz')).status).toBe(404);
   });
 
+  // The bug this guards: a second `x dev` died on `Bun.serve`'s own bare `Error` — no `X_*` code,
+  // no `fix:` — at the FIRST thing `startRoles` opens, so the boot path this package owns handed
+  // back a stack trace instead of an instruction.
+  test('a port already bound is a coded refusal naming the port, never a bare Error', () => {
+    const taken = Number(new URL(endpoint?.url ?? 'http://localhost:0').port);
+    let caught: unknown;
+    try {
+      startMetricsEndpoint({ port: taken }).stop();
+    } catch (error) {
+      caught = error;
+    }
+    // `expect(fn).toThrow(Class)` passes in Bun 1.3.14 when the callee merely RETURNS an error, so
+    // the identity is asserted off the caught value.
+    expect(caught).toBeInstanceOf(MetricsPortInUseError);
+    expect(caught).toMatchObject({ code: 'X_PORT_IN_USE' });
+    expect((caught as { cause: string }).cause).toContain(String(taken));
+    expect((caught as { fix: string }).fix).toContain('METRICS_PORT=');
+  });
+
   test('a scrape does not reset the counters it read', async () => {
     recordRequest({ method: 'GET', route: '/public', status: 200, durationMs: 1 });
     await scrape();
diff --git a/packages/cli/src/metrics-endpoint.ts b/packages/cli/src/metrics-endpoint.ts
index 2a8064b8..eb3a2a41 100644
--- a/packages/cli/src/metrics-endpoint.ts
+++ b/packages/cli/src/metrics-endpoint.ts
@@ -8,7 +8,9 @@ import {
   METRICS_PATH,
   markListening,
   metricsText,
+  UltimateError,
 } from '@ultimat3/core';
+import { docsFor } from './error-codes';
 
 /**
  * A port of its own, and NOT the role's HTTP port, for one reason the chart makes concrete:
@@ -25,6 +27,27 @@ import {
  */
 export const DEFAULT_METRICS_PORT = 9090;
 
+/**
+ * `X_PORT_IN_USE` is the code the CLI already registers for "this dev port is taken", and the
+ * scrape port is one — a synonym here would be a second code for one condition. The fix moves the
+ * port rather than naming a process to kill, because `METRICS_PORT` is the one knob both `x dev`
+ * and the container read (`serve.ts`'s `metricsPortFromEnv`).
+ */
+export class MetricsPortInUseError extends UltimateError {
+  constructor(input: { port: number }) {
+    super({
+      code: 'X_PORT_IN_USE',
+      cause: `the metrics port ${input.port} is already bound, so no role could open its scrape listener`,
+      fix: `METRICS_PORT=${input.port + 1} x dev --json`,
+      docs: docsFor('X_PORT_IN_USE'),
+    });
+  }
+}
+
+/** Bun surfaces the bind failure as an `Error` carrying the libc code; nothing else is ours. */
+const isAddressInUse = (error: unknown): boolean =>
+  error instanceof Error && (error as { code?: unknown }).code === 'EADDRINUSE';
+
 export interface MetricsEndpointOptions {
   /** 0 asks the kernel for an ephemeral port, which is what a test wants. */
   readonly port?: number;
@@ -45,20 +68,32 @@ export interface MetricsEndpoint {
  * signal at the moment of load is worse than no autoscaler.
  */
 export function startMetricsEndpoint(options: MetricsEndpointOptions = {}): MetricsEndpoint {
-  const server = Bun.serve({
-    port: options.port ?? DEFAULT_METRICS_PORT,
-    hostname: options.hostname ?? 'localhost',
-    fetch(request: Request): Response {
-      if (new URL(request.url).pathname !== METRICS_PATH) {
-        return new Response('not found', { status: 404 });
-      }
-      // `collectMetrics()` is cumulative and never reset by a read, so two scrapers cannot steal
-      // each other's samples — but a cache would hand the second one a stale window.
-      return new Response(metricsText(), {
-        headers: { 'content-type': METRICS_CONTENT_TYPE, 'cache-control': 'no-store' },
+  const port = options.port ?? DEFAULT_METRICS_PORT;
+  // `startRoles` opens this FIRST, before any role, so `Bun.serve`'s own bare `Error` was what a
+  // second `x dev` on one machine reported: no code, no fix, at the boot path this package owns.
+  // The return type is inferred, keeping `Bun.serve`'s own shape stated once.
+  function listen() {
+    try {
+      return Bun.serve({
+        port,
+        hostname: options.hostname ?? 'localhost',
+        fetch(request: Request): Response {
+          if (new URL(request.url).pathname !== METRICS_PATH) {
+            return new Response('not found', { status: 404 });
+          }
+          // `collectMetrics()` is cumulative and never reset by a read, so two scrapers cannot
+          // steal each other's samples — but a cache would hand the second one a stale window.
+          return new Response(metricsText(), {
+            headers: { 'content-type': METRICS_CONTENT_TYPE, 'cache-control': 'no-store' },
+          });
+        },
       });
-    },
-  });
+    } catch (error) {
+      if (!isAddressInUse(error)) throw error;
+      throw new MetricsPortInUseError({ port });
+    }
+  }
+  const server = listen();
   // Same rule as every other socket the framework opens: announce it, so a request back to it is
   // recognisably this process calling itself rather than egress the test seal must refuse.
   const stopListening = markListening(server.url.origin);
diff --git a/packages/cli/src/serve.test.ts b/packages/cli/src/serve.test.ts
index ec580c30..377ae57d 100644
--- a/packages/cli/src/serve.test.ts
+++ b/packages/cli/src/serve.test.ts
@@ -13,6 +13,7 @@ import {
   configureReporting,
   DEFAULT_PORT,
   ERROR_DSN_KEY,
+  metricsPortFor,
   metricsPortFromEnv,
   portFromEnv,
   releaseBoot,
@@ -68,6 +69,21 @@ test('a METRICS_PORT that is not a port names ITSELF, or the fix line edits the
   expect(thrown.fix).toContain('METRICS_PORT=9090');
 });
 
+// The bug this guards: `serve.ts` computed this inline and `cmd-dev.ts` passed nothing, so
+// `METRICS_PORT` was honoured in the container and ignored by `x dev` — the dev/prod parity break
+// `dev-roles.ts`'s own header forbids. One expression, both callers.
+test('metricsPortFor is the one answer both the container and x dev read', () => {
+  expect(metricsPortFor({}, 3000)).toBe(DEFAULT_METRICS_PORT);
+  expect(metricsPortFor({ METRICS_PORT: '9464' }, 3000)).toBe(9464);
+  // An in-process caller asking for an ephemeral app port is a test, and a test that grabbed the
+  // fixed 9090 would fail the next suite booting beside it.
+  expect(metricsPortFor({}, 0)).toBe(0);
+  // An environment that names the port still wins at port 0 — that is the deploy talking.
+  expect(metricsPortFor({ METRICS_PORT: '9464' }, 0)).toBe(9464);
+  // An explicit override outranks both.
+  expect(metricsPortFor({ METRICS_PORT: '9464' }, 0, 9999)).toBe(9999);
+});
+
 test('a container binds every interface, and dev does not', () => {
   expect(CONTAINER_BINDING).toEqual({ dev: false, hostname: '0.0.0.0' });
 });
diff --git a/packages/cli/src/serve.ts b/packages/cli/src/serve.ts
index 6d44dcb5..35aa096c 100644
--- a/packages/cli/src/serve.ts
+++ b/packages/cli/src/serve.ts
@@ -86,6 +86,20 @@ export function metricsPortFromEnv(env: Env): number {
   return portValue(env, 'METRICS_PORT', DEFAULT_METRICS_PORT);
 }
 
+/**
+ * The scrape port a boot uses, given the app port it already resolved. One expression, and it is
+ * exported because `x dev` is the second caller: `cmd-dev.ts` passed no `metricsPort` at all, so
+ * `METRICS_PORT` was honoured in the container and ignored on a laptop — the dev/prod parity break
+ * `dev-roles.ts`'s own header forbids, and a second copy of this rule would be the same break
+ * one edit later.
+ *
+ * An in-process caller asking for an ephemeral app port is a test, and a test that grabbed the
+ * fixed 9090 would fail the next suite to boot beside it. An environment that names the port still
+ * wins — that is the deploy talking.
+ */
+export const metricsPortFor = (env: Env, port: number, override?: number): number =>
+  override ?? (port === 0 && env['METRICS_PORT'] === undefined ? 0 : metricsPortFromEnv(env));
+
 /**
  * The one env var that turns error monitoring on, and the only vendor-shaped name in the boot
  * path. Not a platform primitive (axiom 7): the value is a URL to whatever the operator runs, the
@@ -302,9 +316,7 @@ async function bootRoles(boot: {
   // An in-process caller asking for an ephemeral app port is a test, and a test that grabbed the
   // fixed 9090 would fail the next suite to boot beside it. An environment that names the port
   // still wins — that is the deploy talking.
-  const metricsPort =
-    options.metricsPort ??
-    (port === 0 && options.env['METRICS_PORT'] === undefined ? 0 : metricsPortFromEnv(options.env));
+  const metricsPort = metricsPortFor(options.env, port, options.metricsPort);
   const running = await startRoles({
     roles: [role],
     port,
diff --git a/packages/cli/src/storage-surfaces.test.ts b/packages/cli/src/storage-surfaces.test.ts
index de5298c8..093a69b0 100644
--- a/packages/cli/src/storage-surfaces.test.ts
+++ b/packages/cli/src/storage-surfaces.test.ts
@@ -27,14 +27,16 @@ import {
 } from '@ultimat3/http';
 import { clearPermissions, clearRoles, definePermissions, defineRoles } from '@ultimat3/policy';
 import type { Storage } from '@ultimat3/storage';
-import { defineStorage, localDriver, resetStorage, scopedKey, variantKey } from '@ultimat3/storage';
-import { assetRoutes, MEDIA_BASE_PATH } from './dev-assets';
 import {
-  AUTHORIZED_OBJECT_CACHE,
-  STORAGE_BASE_PATH,
-  STORAGE_READ_PERMISSION,
-  storageRoutes,
-} from './dev-storage';
+  DEFAULT_SIGNED_URL_BASE,
+  defineStorage,
+  localDriver,
+  resetStorage,
+  scopedKey,
+  variantKey,
+} from '@ultimat3/storage';
+import { assetRoutes, MEDIA_BASE_PATH } from './dev-assets';
+import { AUTHORIZED_OBJECT_CACHE, STORAGE_READ_PERMISSION, storageRoutes } from './dev-storage';
 
 /** A real PNG, because the `?w=` cases below decode it rather than refusing it as a bad image. */
 const BYTES = encodeImage(createRaster(64, 64, 'tenant-a-private'), 'png');
@@ -104,9 +106,9 @@ function mediaVerdict(key: string, actor: Actor, query = ''): Promise<Verdict> {
 /** The `/_storage` surface, same object, same actor. */
 function storageVerdict(key: string, actor: Actor): Promise<Verdict> {
   const route = storageRoutes({ storage })[0];
-  expect(route?.path).toBe(`${STORAGE_BASE_PATH}/:disk/*key`);
+  expect(route?.path).toBe(`${DEFAULT_SIGNED_URL_BASE}/:disk/*key`);
   const disk = storage.defaultDisk;
-  const url = new URL(`http://dev.test${STORAGE_BASE_PATH}/${disk}/${key}`);
+  const url = new URL(`http://dev.test${DEFAULT_SIGNED_URL_BASE}/${disk}/${key}`);
   const ctx = contextFor(url, { disk, key }, actor);
   return verdictOf(
     async () =>
diff --git a/packages/cli/src/test-workers.ts b/packages/cli/src/test-workers.ts
index 1f875ce1..3121f149 100644
--- a/packages/cli/src/test-workers.ts
+++ b/packages/cli/src/test-workers.ts
@@ -43,5 +43,8 @@ export const WORKER_CEILING = 8;
 /** Oversubscription factor. See the table above — it is measured, not chosen for roundness. */
 export const WORKER_OVERSUBSCRIBE = 1.5;
 
+/** The floor the paragraph above names: a 1-core box shards rather than reverting to serial. */
+export const WORKER_FLOOR = 2;
+
 export const defaultWorkers = (available: number = availableCpus()): number =>
-  Math.max(2, Math.min(WORKER_CEILING, Math.round(available * WORKER_OVERSUBSCRIBE)));
+  Math.max(WORKER_FLOOR, Math.min(WORKER_CEILING, Math.round(available * WORKER_OVERSUBSCRIBE)));
diff --git a/packages/cli/src/ts-scan.test.ts b/packages/cli/src/ts-scan.test.ts
index 27876761..9b6f4694 100644
--- a/packages/cli/src/ts-scan.test.ts
+++ b/packages/cli/src/ts-scan.test.ts
@@ -54,6 +54,19 @@ describe('maskLiterals', () => {
     const source = '<p>{a}</p><b name="x" />;';
     expect(maskLiterals(source)).toBe('<p>{a}</p><b name=" " />;');
   });
+
+  // The bug this guards: an apostrophe in JSX text read as a string opener, so masking ran to the
+  // next `'` in the FILE — in practice the next `fix:` literal — and blanked every declaration in
+  // between. A `'`/`"` that does not close on its own line is text: a JS string may not span one.
+  test('an apostrophe in JSX text is text, not a literal opener', () => {
+    const source = "<p>Don't panic</p>;\nconst a = 'x';";
+    expect(maskLiterals(source)).toBe("<p>Don't panic</p>;\nconst a = ' ';");
+  });
+
+  test('a template literal still spans lines', () => {
+    const source = 'const a = `one\ntwo`;\nconst b = 1;';
+    expect(maskLiterals(source)).toBe('const a = `   \n   `;\nconst b = 1;');
+  });
 });
 
 describe('scanFixes', () => {
@@ -91,6 +104,18 @@ throw new E({ fix: 'x doctor --json' });`;
     expect(fixes(source)).toEqual(['x doctor --json']);
   });
 
+  // Same masking desync, reached from JSX rather than from a regex: the file's `fix:` lines
+  // vanished wholesale, `x verify`'s `errors` step checked none of them, and `scanCodes` still
+  // found the code — so `X_ERROR_CODE_UNDOCUMENTED` passed and hid the hole.
+  test('an apostrophe in JSX text does not hide the declaration below it', () => {
+    const source =
+      'export function Panel() {\n' +
+      "  return <p>Don't panic</p>;\n" +
+      '}\n' +
+      "throw new E({ code: 'X_A', fix: 'x doctor --json' });";
+    expect(scanFixes(source, 'a.tsx')).toEqual([{ at: 'a.tsx', line: 4, fix: 'x doctor --json' }]);
+  });
+
   test('an escape and a character class do not close the regex early', () => {
     expect(fixes("const re = /[/']|a\\/b/;\nthrow new E({ fix: 'x help' });")).toEqual(['x help']);
   });
diff --git a/packages/cli/src/ts-scan.ts b/packages/cli/src/ts-scan.ts
index 0fbfa6ac..98dafe91 100644
--- a/packages/cli/src/ts-scan.ts
+++ b/packages/cli/src/ts-scan.ts
@@ -28,14 +28,23 @@ const REGEX_AFTER_WORDS = new Set(
   'await case delete do else in instanceof new of return throw typeof void yield'.split(' '),
 );
 
-/** Index just past the closing quote of the literal opening at `from`, or the end of the text. */
+/**
+ * Index just past the closing quote of the literal opening at `from`, or `from + 1` when a `'`/`"`
+ * does not close on its own line — which makes it text, not a literal. Only a template literal may
+ * span a newline, so the apostrophe in `<p>Don't panic</p>` is JSX text; read as an opener it ran
+ * forward to the next `'` in the FILE (the next `fix:` line) and blanked every declaration between,
+ * silently emptying the `errors` gate for the whole file. Same rule `endOfRegex` applies to a `/`.
+ * An escaped newline is still a continuation: the escape is consumed before the line test.
+ */
 function endOfLiteral(text: string, from: number): number {
   const quote = text[from] as string;
+  const spansLines = quote === '`';
   for (let i = from + 1; i < text.length; i += 1) {
     if (text[i] === '\\') i += 1;
     else if (text[i] === quote) return i + 1;
+    else if (!spansLines && text[i] === '\n') return from + 1;
   }
-  return text.length;
+  return spansLines ? text.length : from + 1;
 }
 
 /**
@@ -156,6 +165,8 @@ function valueLiterals(
     const ch = masked[i] as string;
     if (QUOTES.has(ch)) {
       const end = endOfLiteral(masked, i);
+      // A quote that never closes is one character of code, not an empty literal to report.
+      if (end === i + 1) continue;
       if (depth === 0) found.push({ value: source.slice(i + 1, end - 1), index: i });
       i = end - 1;
     } else if (OPENERS.has(ch)) depth += 1;
diff --git a/packages/cli/src/tsconfig-references.test.ts b/packages/cli/src/tsconfig-references.test.ts
index 25c3fdd2..8aa11037 100644
--- a/packages/cli/src/tsconfig-references.test.ts
+++ b/packages/cli/src/tsconfig-references.test.ts
@@ -63,6 +63,34 @@ describe('unit · every published workspace is in the root build graph', () => {
     });
   });
 
+  // The false green this closes: `tsc` accepts JSONC and `Bun.file().json()` rejects it, so a root
+  // written the way `tsc --init` writes one was read as "this repo does not use project
+  // references" — the check went dark and `typecheck` stayed green over the packages it skipped.
+  test('a root written as JSONC is read, not silently treated as having no references', async () => {
+    const jsonc = [
+      '{',
+      '  // The build graph. https://www.typescriptlang.org/tsconfig#references',
+      '  "files": [], /* nothing is compiled from the root itself */',
+      '  "references": [',
+      '    { "path": "./packages/core" },',
+      '  ],',
+      '}',
+    ].join('\n');
+    await withRoot(jsonc, async (root) => {
+      const findings = await checkRootReferences(root, ['core', 'cli']);
+      expect(findings).toHaveLength(1);
+      expect(findings[0]?.cause).toContain('packages/cli');
+    });
+  });
+
+  // A `//` inside a string is a URL, never a comment — and a `,` inside one is not trailing.
+  test('a comment marker inside a string value survives the strip', async () => {
+    const jsonc = '{"references":[{"path":"./packages/core"}],"x":"https://a.dev/b,]"}';
+    await withRoot(jsonc, async (root) => {
+      expect(await checkRootReferences(root, ['core'])).toEqual([]);
+    });
+  });
+
   // Axiom 4: the fix is the edit, naming the file and the exact entry to add.
   test('the fix names the file, the entry and the command that proves it', () => {
     const { fix } = unreferencedFinding('cli');
diff --git a/packages/cli/src/tsconfig-references.ts b/packages/cli/src/tsconfig-references.ts
index 6c329dfb..dda8b018 100644
--- a/packages/cli/src/tsconfig-references.ts
+++ b/packages/cli/src/tsconfig-references.ts
@@ -9,6 +9,7 @@
 import { join } from 'node:path';
 import { docsFor } from './error-codes';
 import type { Finding } from './output';
+import { maskLiterals, stripComments } from './ts-scan';
 
 const ROOT_TSCONFIG = 'tsconfig.json';
 
@@ -22,15 +23,39 @@ const ROOT_TSCONFIG = 'tsconfig.json';
 export const normalizeReferencePath = (path: string): string =>
   path.replace(/^\.\//, '').replace(/\/+$/, '');
 
+/**
+ * A tsconfig is JSONC and `JSON.parse` is not, so the comments and trailing commas `tsc` accepts —
+ * and `tsc --init` writes — are removed before the parse. `Bun.file().json()` rejects both, and
+ * the rejection was mapped to "this root does not use project references": the check went dark on
+ * exactly the roots most likely to have been written by hand, while `typecheck` stayed green over
+ * every package it then skipped. `stripComments` is `ts-scan.ts`'s, so a `//` inside a string is a
+ * URL and not a comment; the trailing-comma pass reads MASKED text for the same reason.
+ */
+function parseJsonc(text: string): unknown {
+  const uncommented = stripComments(text);
+  const masked = maskLiterals(uncommented);
+  const chars = [...uncommented];
+  for (let i = 0; i < masked.length; i += 1) {
+    if (masked[i] !== ',') continue;
+    let next = i + 1;
+    while (next < masked.length && /\s/.test(masked[next] as string)) next += 1;
+    if (masked[next] === '}' || masked[next] === ']') chars[i] = ' ';
+  }
+  return JSON.parse(chars.join('')) as unknown;
+}
+
 /**
  * `undefined` means "this root does not use project references" — a different repo shape, not an
  * empty graph. A scaffolded app is that shape (`extends` + `include`, no references at all), and
  * telling its author to add an entry to a list that does not exist is a fix that makes the build
- * worse. A tsconfig that will not parse is `typecheck`'s to report, with tsc's own message.
+ * worse. A tsconfig that will not parse EVEN AS JSONC is `typecheck`'s to report, with tsc's own
+ * message — this check has no code that would mean "the file is broken" and must not borrow one
+ * that means something else.
  */
 async function referencedPaths(root: string): Promise<ReadonlySet<string> | undefined> {
   const payload: unknown = await Bun.file(join(root, ROOT_TSCONFIG))
-    .json()
+    .text()
+    .then(parseJsonc)
     .catch(() => undefined);
   const references =
     typeof payload === 'object' && payload !== null
diff --git a/packages/manifest/CLAUDE.md b/packages/manifest/CLAUDE.md
index 8855a3f6..8a9c145f 100644
--- a/packages/manifest/CLAUDE.md
+++ b/packages/manifest/CLAUDE.md
@@ -47,6 +47,11 @@ by the CLI, not imported.
   section a truncated or hand-trimmed file happens not to carry was a bare `TypeError` two calls
   from the gate that exists to explain. The FACTS inside a section stay unwalked — a manifest
   written before a field existed is still readable, which is `MANIFEST_VERSION`'s rule.
+- **A byte count is `Buffer.byteLength`, never `String.length`.** `EmitResult.bytes` measures the
+  file on disk and a manifest carries the APP's strings — a locale name, an entity description, a
+  title in the app's own language — so UTF-16 code units under-report every non-ASCII one.
+  `agents-md.ts` measures the same quantity the same way. Nothing committed carries the number:
+  `writeAppManifest` is the only caller and it reads `path` alone, so correcting it is not drift.
 - **`--json` is awaited.** `emitManifest({ stdout: true })` writes through `await Bun.write(
   Bun.stdout, …)`: a write to a pipe is asynchronous and `process.exit()` discards the queue, and
   this is the largest payload the CLI prints. Same bug `scripts/stdout-truncation.test.ts` pins.
diff --git a/packages/manifest/src/emit.test.ts b/packages/manifest/src/emit.test.ts
index 3cf27c9b..682346ca 100644
--- a/packages/manifest/src/emit.test.ts
+++ b/packages/manifest/src/emit.test.ts
@@ -183,6 +183,22 @@ describe('emitManifest', () => {
     });
   });
 
+  // `bytes` is a byte count, and a manifest carries app strings — a locale name, an entity
+  // description, a title in the app's own language. `String.length` counts UTF-16 code units, so
+  // it under-reports every one of them, and `agents-md.ts` measures the same thing with
+  // `Buffer.byteLength` one file away.
+  test('bytes counts the bytes on disk, not the code units in the string', async () => {
+    const accented = buildManifest({
+      ...sources,
+      app: { name: 'caf\u00e9-\u65e5\u672c-\ud83d\ude80', version: '1.4.2' },
+    });
+    await withTempDir(async (path) => {
+      const result = await emitManifest({ manifest: accented, path });
+      expect(result.bytes).toBe(Bun.file(path).size);
+      expect(result.bytes).toBeGreaterThan(manifestJson(accented).length);
+    });
+  });
+
   test('a changed manifest over the same path reports changed again', async () => {
     await withTempDir(async (path) => {
       await emitManifest({ manifest: fresh, path });
diff --git a/packages/manifest/src/emit.ts b/packages/manifest/src/emit.ts
index 44974a73..f4113716 100644
--- a/packages/manifest/src/emit.ts
+++ b/packages/manifest/src/emit.ts
@@ -54,6 +54,11 @@ export interface EmitResult {
 export async function emitManifest(input: EmitInput): Promise<EmitResult> {
   const path = input.path ?? `./${MANIFEST_FILENAME}`;
   const text = manifestJson(input.manifest);
+  // The bytes on disk, never `text.length`: a manifest carries the APP's strings — a locale name,
+  // an entity description, a title in the app's own language — and `String.length` counts UTF-16
+  // code units, so it under-reports every one of them and over-reports nothing. `agents-md.ts`
+  // measures the same quantity the same way.
+  const bytes = Buffer.byteLength(text, 'utf8');
 
   if (input.stdout === true) {
     // stdout is the wire in `--json` mode; nothing else may be written to it — and the write is
@@ -61,16 +66,16 @@ export async function emitManifest(input: EmitInput): Promise<EmitResult> {
     // is still queued. Unawaited, the largest payload the CLI prints was the one that lost bytes,
     // exactly as `scripts/stdout-truncation.test.ts` documents for the same bug elsewhere.
     await Bun.write(Bun.stdout, text);
-    return { path, bytes: text.length, buildId: input.manifest.buildId, changed: false };
+    return { path, bytes, buildId: input.manifest.buildId, changed: false };
   }
 
   const existing = await readIfExists(path);
   // Skip the write when nothing moved: an unchanged mtime keeps file watchers quiet.
   if (existing === text) {
-    return { path, bytes: text.length, buildId: input.manifest.buildId, changed: false };
+    return { path, bytes, buildId: input.manifest.buildId, changed: false };
   }
   await Bun.write(path, text);
-  return { path, bytes: text.length, buildId: input.manifest.buildId, changed: true };
+  return { path, bytes, buildId: input.manifest.buildId, changed: true };
 }
 
 /** Read and structurally validate a manifest. `undefined` when absent or unparseable. */
diff --git a/packages/mcp/CLAUDE.md b/packages/mcp/CLAUDE.md
index fb40ca69..fddc5152 100644
--- a/packages/mcp/CLAUDE.md
+++ b/packages/mcp/CLAUDE.md
@@ -49,6 +49,28 @@ import. The CLI wires it.
   fails, every caller simply sees every tool.
 - Resolve order is visibility → scope → args → policy. Validating first leaks a schema;
   running the policy first decides a refusal from attacker-supplied input.
+- **A key's membership of a declared schema is `Object.hasOwn(properties, key)`, never
+  `properties[key] === undefined`.** The arguments of a `tools/call` are NAMED by the caller, and
+  `Object.prototype` supplies a value for `constructor`, `toString`, `hasOwnProperty` and
+  `__proto__` on every plain object — so the index read answered "declared" for four names no
+  schema declares, and `validate-args.ts` accepted them past an `additionalProperties: false` that
+  forbids them and then dropped them. Third instance of the class in the framework, after
+  `@ultimat3/i18n`'s catalog lookup and `@ultimat3/schema`'s `coerce`. Its twin: a validated key
+  lands on the result through `Object.defineProperty`, because `out[key] = v` for `__proto__` runs
+  the setter on `Object.prototype` and re-prototypes the record instead of adding a key.
+- **Anything a tool RETURNS is rendered totally.** `jsonResult` is handed an action's own return
+  value, and `JSON.stringify` answers `undefined` for a handler that returned nothing (a
+  `ContentBlock.text` that is not a string is an invalid frame) and THROWS on a bigint, a cycle or
+  a `toJSON` the value carries. Unreadable is an ordinary `isError` result, never an escape past
+  `server.ts`'s catch, which would report a bug in the tool for a fault in the rendering.
+  `query-limits.ts`' `rowBytes` holds the same line one layer earlier: a row the driver decoded
+  into a bigint costs `Infinity` and is cut by the byte ceiling, rather than raising inside the cap
+  that exists to protect the answer.
+- **A thrown value is read with `stringField` from `@ultimat3/core`, never `typeof e.code ===
+  'string'`.** `asFrameworkError` reads four fields off whatever an app's handler threw; each read
+  is a getter call, or a `Proxy` trap, inside the catch block that owes the caller a response — and
+  a probe that raises there leaves the JSON-RPC request with no answer at all, not even the
+  `-32603` the transport promises for a genuine bug.
 - A framework error rendered into a tool result is **byte-identical to
   `UltimateError.format()`** — one denial must not read one way over MCP and another in the
   terminal. `server.ts` renders it; the test pins it against `format()`, never a literal.
diff --git a/packages/mcp/src/query-limits.test.ts b/packages/mcp/src/query-limits.test.ts
index 2d05d8c9..27f4ee9a 100644
--- a/packages/mcp/src/query-limits.test.ts
+++ b/packages/mcp/src/query-limits.test.ts
@@ -90,3 +90,26 @@ describe('capQueryRows reports every cut it makes', () => {
     expect(result.truncated).toBe(false);
   });
 });
+
+// The rows are a DRIVER's: `db.query` runs an agent-authored statement and the host hands back
+// whatever the driver decoded. `JSON.stringify` throws on a bigint — an `int8` column on a driver
+// that maps it faithfully — and on a cycle, so the cap that exists to protect the model's context
+// was the thing that raised, two frames from the tool that owes the agent an answer.
+describe('a row the driver decoded into something JSON cannot hold', () => {
+  const limits = resolveQueryLimits(10);
+
+  test('is dropped and reported as the byte ceiling, never raised', () => {
+    const source: QueryRows = {
+      columns: ['n'],
+      rows: [[1], [10n], [2]],
+      guards: [],
+    };
+    const result = capQueryRows(source, limits);
+    // The rows before it survive; the unserialisable one and everything after it do not, which is
+    // exactly what the byte ceiling already promises — and the answer still serialises.
+    expect(result.rowCount).toBe(1);
+    expect(result.truncated).toBe(true);
+    expect(result.truncatedBy).toBe('bytes');
+    expect(() => JSON.stringify(result)).not.toThrow();
+  });
+});
diff --git a/packages/mcp/src/query-limits.ts b/packages/mcp/src/query-limits.ts
index 471a5d05..57ec0032 100644
--- a/packages/mcp/src/query-limits.ts
+++ b/packages/mcp/src/query-limits.ts
@@ -56,9 +56,21 @@ export function resolveQueryLimits(requested: unknown): QueryLimits {
 
 const encoder = new TextEncoder();
 
-/** Serialised size of one row, plus the separator it costs inside the JSON array. */
+/**
+ * Serialised size of one row, plus the separator it costs inside the JSON array.
+ *
+ * A row the driver decoded into something JSON cannot hold — a bigint from an `int8` column, a
+ * cycle — costs `Infinity`, which is not a fudge: the row cannot be returned to the agent at all,
+ * and the ceiling it blows is already the one whose answer ("select fewer columns") is the right
+ * one. Raising instead would take down the tool that owes the agent a reply, from inside the cap
+ * that exists to protect it.
+ */
 function rowBytes(row: readonly unknown[]): number {
-  return encoder.encode(JSON.stringify(row)).length + 1;
+  try {
+    return encoder.encode(JSON.stringify(row)).length + 1;
+  } catch {
+    return Number.POSITIVE_INFINITY;
+  }
 }
 
 /**
diff --git a/packages/mcp/src/registry.test.ts b/packages/mcp/src/registry.test.ts
index a452daa8..e731cb69 100644
--- a/packages/mcp/src/registry.test.ts
+++ b/packages/mcp/src/registry.test.ts
@@ -252,4 +252,34 @@ describe('textResult / jsonResult', () => {
       { type: 'text', text: JSON.stringify({ b: 1, a: 2 }, null, 2) },
     ]);
   });
+
+  // The value is an ACTION's return value — `toolFromAction` hands `primitive.run`'s output
+  // straight here — so `JSON.stringify`'s two non-string answers are both reachable from an app:
+  // `undefined` for a handler that returns nothing, and a throw on a bigint, a cycle or a
+  // `toJSON` of its own. A `ContentBlock.text` that is not a string is an invalid MCP frame, and
+  // a throw here escapes the server's own catch as a bug it did not cause.
+  test('a tool result that is not JSON becomes an isError block, never a throw', () => {
+    const cycle: Record<string, unknown> = {};
+    cycle['self'] = cycle;
+    for (const value of [
+      { total: 10n },
+      cycle,
+      {
+        toJSON: () => {
+          throw new Error('no');
+        },
+      },
+    ]) {
+      const result = jsonResult(value);
+      expect(result.isError).toBe(true);
+      expect(typeof result.content[0]?.text).toBe('string');
+      expect(result.content[0]?.text).toContain('not JSON');
+    }
+  });
+
+  test('a tool that returns nothing renders null, not a block with no text', () => {
+    const result = jsonResult(undefined);
+    expect(result.content).toEqual([{ type: 'text', text: 'null' }]);
+    expect('isError' in result).toBe(false);
+  });
 });
diff --git a/packages/mcp/src/registry.ts b/packages/mcp/src/registry.ts
index b669fbe9..8e60a258 100644
--- a/packages/mcp/src/registry.ts
+++ b/packages/mcp/src/registry.ts
@@ -223,7 +223,25 @@ export function textResult(text: string, isError = false): McpToolResult {
   return isError ? { content, isError: true } : { content };
 }
 
-/** JSON payload as a text block — stable 2-space form so an agent can diff two calls. */
+/**
+ * JSON payload as a text block — stable 2-space form so an agent can diff two calls.
+ *
+ * TOTAL, because the value is an app's: `toolFromAction` hands an action's own return value
+ * straight here, and `JSON.stringify` answers `undefined` for a handler that returned nothing —
+ * a `text` that is not a string is an invalid MCP frame — and THROWS on a bigint, a cycle or a
+ * `toJSON` the value carries. A throw would leave the server's catch reporting a bug in the tool
+ * for a fault in the rendering, so the unreadable case is an ordinary `isError` result: the same
+ * three-line shape every other expected failure comes back as, and one an agent can act on.
+ */
 export function jsonResult(value: unknown): McpToolResult {
-  return textResult(JSON.stringify(value, null, 2));
+  let text: string | undefined;
+  try {
+    text = JSON.stringify(value, null, 2);
+  } catch {
+    return textResult(
+      'the tool ran, but its result is not JSON (a bigint, a cycle, or a toJSON that threw) — the tool has to return a JSON-serialisable value',
+      true,
+    );
+  }
+  return textResult(text ?? 'null');
 }
diff --git a/packages/mcp/src/server.test.ts b/packages/mcp/src/server.test.ts
index 263124bf..a7a0e010 100644
--- a/packages/mcp/src/server.test.ts
+++ b/packages/mcp/src/server.test.ts
@@ -5,7 +5,7 @@ import type { AnyMcpTool, McpCaller, McpToolResult } from './registry';
 import { textResult } from './registry';
 import { frameworkResources } from './resources';
 import { createMcpServer } from './server';
-import { INVALID_PARAMS, INVALID_REQUEST, METHOD_NOT_FOUND } from './wire';
+import { INTERNAL_ERROR, INVALID_PARAMS, INVALID_REQUEST, METHOD_NOT_FOUND } from './wire';
 
 const agent = { kind: 'agent', id: 'agent-1' } as unknown as Actor;
 
@@ -237,3 +237,74 @@ describe('a framework error reaches the model in the shape the terminal prints',
     expect(text).not.toContain('see docs');
   });
 });
+
+// The transport's promise for anything that is NOT a framework error: `-32603`, no internals
+// leaked. It is reached past four property reads of a value an app's handler threw — a getter
+// call, or a `Proxy` trap — so the probe can raise where the catch block has nothing left to
+// answer with, and the JSON-RPC request then dies with no response at all.
+describe('a throw that fights being read is still an answer, never an escape', () => {
+  const hostile = (value: unknown): AnyMcpTool => ({
+    name: 'orders.hostile',
+    description: 'throws a value that traps every read',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    handle: () => Promise.reject(value),
+  });
+
+  test.each([
+    [
+      'a Proxy trapping get and getPrototypeOf',
+      new Proxy(
+        {},
+        {
+          get() {
+            throw new Error('trapped get');
+          },
+          getPrototypeOf() {
+            throw new Error('trapped getPrototypeOf');
+          },
+        },
+      ) as unknown,
+    ],
+    [
+      'an object whose code getter throws',
+      Object.defineProperty({}, 'code', {
+        get() {
+          throw new Error('trapped code');
+        },
+        enumerable: true,
+      }) as unknown,
+    ],
+    ['a symbol', Symbol('thrown') as unknown],
+  ])('%s becomes -32603, with the tool named and nothing leaked', async (_label, value) => {
+    const server = createMcpServer({ tools: [hostile(value)] });
+    const response = await server.handle(
+      call('tools/call', { name: 'orders.hostile', arguments: {} }),
+      caller(undefined, []),
+    );
+    const error = response?.error;
+    expect(error?.code).toBe(INTERNAL_ERROR);
+    expect(error?.message).toBe('tool "orders.hostile" failed unexpectedly');
+  });
+
+  // A null-prototype coded object is what a worker or a JSON round trip produces, and it still
+  // renders — the discriminator is the FIELD, never the prototype.
+  test('a null-prototype coded object still renders its three lines', async () => {
+    const flattened = Object.assign(Object.create(null), {
+      code: 'X_FOREIGN',
+      cause: 'a worker sent this back',
+      fix: 'x doctor',
+    });
+    const server = createMcpServer({ tools: [hostile(flattened)] });
+    const response = await server.handle(
+      call('tools/call', { name: 'orders.hostile', arguments: {} }),
+      caller(undefined, []),
+    );
+    const result = response?.result as
+      | { content: { text: string }[]; isError?: boolean }
+      | undefined;
+    expect(result?.isError).toBe(true);
+    expect(result?.content[0]?.text).toBe(
+      'X_FOREIGN\n  cause: a worker sent this back\n  fix:   x doctor',
+    );
+  });
+});
diff --git a/packages/mcp/src/server.ts b/packages/mcp/src/server.ts
index 4e614799..10130c65 100644
--- a/packages/mcp/src/server.ts
+++ b/packages/mcp/src/server.ts
@@ -3,6 +3,7 @@
 // and an already-resolved caller, and returns a response or `null` for a notification.
 // Both transports (http, stdio) and every test drive this one function.
 
+import { stringField } from '@ultimat3/core';
 import { formatIssues } from '@ultimat3/schema';
 import { auditToolCall, outcomeForCode } from './audit';
 import { McpScopeDeniedError } from './errors';
@@ -242,17 +243,21 @@ interface FrameworkError {
  * transport must stay independent of which package threw.
  */
 function asFrameworkError(error: unknown): FrameworkError | undefined {
-  if (typeof error !== 'object' || error === null) return undefined;
-  const e = error as { code?: unknown; title?: unknown; cause?: unknown; fix?: unknown };
-  if (typeof e.code !== 'string' || !e.code.startsWith('X_')) return undefined;
+  // `stringField` from `@ultimat3/core`, never `typeof e.code === 'string'`: the value is whatever
+  // an app's handler, its driver or its SDK threw, so each read is a getter call or a `Proxy`
+  // trap. This runs inside the catch block that owes the caller an answer, and a probe that
+  // raises here leaves the JSON-RPC request with no response at all — not even the `-32603` the
+  // header promises for a genuine bug.
+  const code = stringField(error, 'code');
+  if (code === undefined || !code.startsWith('X_')) return undefined;
   return {
-    code: e.code,
-    title: typeof e.title === 'string' ? e.title : '',
-    cause: typeof e.cause === 'string' ? e.cause : 'unknown',
+    code,
+    title: stringField(error, 'title') ?? '',
+    cause: stringField(error, 'cause') ?? 'unknown',
     // A substituted fix is still a fix an agent will act on, so it has to be runnable. `see docs`
-    // named no docs and no command; `e.code` is already narrowed to an `X_` string by the guard
+    // named no docs and no command; `code` is already narrowed to an `X_` string by the guard
     // above, so the substitute is the one command that explains exactly this code.
-    fix: typeof e.fix === 'string' ? e.fix : `x errors explain ${e.code}`,
+    fix: stringField(error, 'fix') ?? `x errors explain ${code}`,
   };
 }
 
diff --git a/packages/mcp/src/validate-args.test.ts b/packages/mcp/src/validate-args.test.ts
index 4be4a172..5262e566 100644
--- a/packages/mcp/src/validate-args.test.ts
+++ b/packages/mcp/src/validate-args.test.ts
@@ -272,3 +272,69 @@ describe('validateArgs: default schema type', () => {
     });
   });
 });
+
+// A `tools/call` names its arguments, and an agent — or whatever is driving one — chooses those
+// names. `Object.prototype` supplies a value for `constructor`, `toString` and `__proto__` on
+// every plain object, so a membership test that reads the prototype chain answers "declared" for
+// three names no schema declared: the arguments were accepted and then dropped, which is the one
+// outcome nothing downstream can detect. Third instance of the class in this sweep, after
+// `@ultimat3/i18n`'s catalog lookup and `@ultimat3/schema`'s `coerce`.
+describe('validateArgs: a property named after one of Object.prototype', () => {
+  const strict: JsonSchema = {
+    type: 'object',
+    properties: { id: { type: 'string' } },
+    required: ['id'],
+    additionalProperties: false,
+  };
+
+  test('additionalProperties false refuses it, exactly as it refuses any other unknown key', () => {
+    for (const key of ['constructor', '__proto__', 'toString', 'hasOwnProperty', 'valueOf']) {
+      expect(validateArgs(strict, { id: 'a', [key]: 1 })).toEqual({
+        ok: false,
+        issues: [{ path: key, message: 'unknown property' }],
+      });
+    }
+  });
+
+  test('an open schema carries it through as an OWN key, never dropped', () => {
+    const open: JsonSchema = { type: 'object', properties: { id: { type: 'string' } } };
+    const result = validateArgs(open, { id: 'a', constructor: 1, toString: 2 });
+    expect(result.ok).toBe(true);
+    const value = result.ok ? result.value : {};
+    expect(Object.hasOwn(value, 'constructor')).toBe(true);
+    expect(value['constructor']).toBe(1);
+    expect(value['toString']).toBe(2);
+  });
+
+  // The half the `hasOwn` fix would otherwise turn from a drop into a pollution: `out[key] = v`
+  // for `__proto__` runs the setter on `Object.prototype` and REPLACES the result's prototype
+  // instead of adding a key, so the arguments a handler reads carry properties nobody sent.
+  test('an open schema cannot have the result object re-prototyped by a __proto__ argument', () => {
+    const open: JsonSchema = { type: 'object', properties: { id: { type: 'string' } } };
+    const result = validateArgs(open, JSON.parse('{"id":"a","__proto__":{"isAdmin":true}}'));
+    expect(result.ok).toBe(true);
+    const value = result.ok ? result.value : {};
+    expect(Object.getPrototypeOf(value)).toBe(Object.prototype);
+    expect(value['isAdmin']).toBeUndefined();
+    expect(Object.hasOwn(value, '__proto__')).toBe(true);
+  });
+
+  // A schema that really does declare one of those names is the reason the discriminator is
+  // `Object.hasOwn` rather than a deny-list: declared is declared, and it still validates.
+  test('a schema that declares such a property validates it like any other', () => {
+    const declared: JsonSchema = {
+      type: 'object',
+      properties: { constructor: { type: 'string' } },
+      required: ['constructor'],
+      additionalProperties: false,
+    };
+    expect(validateArgs(declared, { constructor: 'ctor' })).toEqual({
+      ok: true,
+      value: { constructor: 'ctor' },
+    });
+    expect(validateArgs(declared, { constructor: 7 })).toEqual({
+      ok: false,
+      issues: [{ path: 'constructor', message: 'must be a string' }],
+    });
+  });
+});
diff --git a/packages/mcp/src/validate-args.ts b/packages/mcp/src/validate-args.ts
index f5d98218..b0b3b4e1 100644
--- a/packages/mcp/src/validate-args.ts
+++ b/packages/mcp/src/validate-args.ts
@@ -78,29 +78,43 @@ function object(
   const out: Record<string, unknown> = {};
 
   for (const key of Object.keys(source)) {
-    if (properties[key] === undefined) {
+    // `Object.hasOwn`, never `properties[key] === undefined`: the second walks the prototype
+    // chain, so `constructor`, `toString` and `__proto__` read as DECLARED on every schema and an
+    // argument named after one was accepted past an `additionalProperties: false` that forbids it,
+    // then silently dropped. Same discriminator as the loop below, which always had it right.
+    if (!Object.hasOwn(properties, key)) {
       if (schema.additionalProperties === false) {
         issues.push({ path: join(path, key), message: 'unknown property' });
         continue;
       }
-      out[key] = source[key];
+      put(out, key, source[key]);
     }
   }
   for (const [key, child] of Object.entries(properties)) {
     const at = join(path, key);
     const present = Object.hasOwn(source, key) && source[key] !== undefined;
     if (!present) {
-      if (child.default !== undefined) out[key] = child.default;
+      if (child.default !== undefined) put(out, key, child.default);
       else if (schema.required?.includes(key) === true) {
         issues.push({ path: at, message: 'is required' });
       }
       continue;
     }
-    out[key] = walk(child, source[key], at, issues);
+    put(out, key, walk(child, source[key], at, issues));
   }
   return out;
 }
 
+/**
+ * One validated key onto the result. `out[key] = value` is not an assignment for exactly one
+ * name: `__proto__` runs `Object.prototype`'s setter and REPLACES the object's prototype instead
+ * of adding a key, so a caller-chosen argument name decides what the handler's `args.isAdmin`
+ * reads. `defineProperty` writes a plain own data property whatever the name is.
+ */
+function put(out: Record<string, unknown>, key: string, value: unknown): void {
+  Object.defineProperty(out, key, { value, writable: true, enumerable: true, configurable: true });
+}
+
 function array(schema: JsonSchema, input: unknown, path: string, issues: ArgIssue[]): unknown {
   if (!Array.isArray(input)) {
     issues.push({ path, message: 'must be an array' });

From f3c02155bbf3b0fd289f293395ef63789301620c Mon Sep 17 00:00:00 2001
From: sebi <gore.sebyx@yahoo.com>
Date: Tue, 18 Aug 2026 21:57:05 -0500
Subject: [PATCH 2/3] fix(cli): the port-collision test asserted the kernel's
 behaviour, not this package's
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CI caught a test I added in this PR. `metrics-endpoint.test.ts` bound a live port a
second time and expected `Bun.serve` to throw EADDRINUSE. It does locally. GitHub's
runner allowed the second bind, so the test failed for a reason that was never this
package's contract — a flaky test in the gate is worse than no test.

Rewritten to assert the MAPPING, which is what is actually ours: an EADDRINUSE-shaped
throw becomes a coded refusal naming the port and the knob that moves it. Whether the
OS refuses a rebind is decided elsewhere and does not answer the same way everywhere.

`isAddressInUse` was also an instance of the class this whole sweep has been fixing:
`error instanceof Error && error.code === 'EADDRINUSE'` runs `getPrototypeOf` and then
a getter on a value this process did not build. It reads through core's `stringField`
now, which also makes it answer correctly for a bind failure that crossed a worker or
a subprocess — a plain object carrying the libc code, for which `instanceof Error` is
false. That case is the one the mutation check bites on.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 packages/cli/src/metrics-endpoint.test.ts | 58 ++++++++++++++++++-----
 packages/cli/src/metrics-endpoint.ts      | 14 ++++--
 2 files changed, 56 insertions(+), 16 deletions(-)

diff --git a/packages/cli/src/metrics-endpoint.test.ts b/packages/cli/src/metrics-endpoint.test.ts
index dc1e11e1..b44336c7 100644
--- a/packages/cli/src/metrics-endpoint.test.ts
+++ b/packages/cli/src/metrics-endpoint.test.ts
@@ -13,6 +13,7 @@ import {
   resetMetrics,
 } from '@ultimat3/core';
 import {
+  isAddressInUse,
   type MetricsEndpoint,
   MetricsPortInUseError,
   startMetricsEndpoint,
@@ -66,20 +67,51 @@ describe('the scrape endpoint', () => {
   // The bug this guards: a second `x dev` died on `Bun.serve`'s own bare `Error` — no `X_*` code,
   // no `fix:` — at the FIRST thing `startRoles` opens, so the boot path this package owns handed
   // back a stack trace instead of an instruction.
-  test('a port already bound is a coded refusal naming the port, never a bare Error', () => {
+  //
+  // Asserted on the MAPPING, not on a second `Bun.serve`: whether the kernel refuses a rebind of a
+  // live port is the OS's business and it does not answer the same way everywhere — this test bound
+  // the port twice and passed locally while GitHub's runner allowed the second bind, so it failed
+  // for a reason that was never this package's contract. What is ours is that an EADDRINUSE-shaped
+  // throw becomes a coded refusal naming the port, and that is decidable without racing a socket.
+  test('an EADDRINUSE-shaped throw is recognised, and nothing else is', () => {
+    const bind = Object.assign(new Error('Failed to start server'), { code: 'EADDRINUSE' });
+    expect(isAddressInUse(bind)).toBe(true);
+
+    expect(isAddressInUse(Object.assign(new Error('nope'), { code: 'EACCES' }))).toBe(false);
+    expect(isAddressInUse(new Error('no code at all'))).toBe(false);
+    expect(isAddressInUse(undefined)).toBe(false);
+
+    // A bind failure that crossed a worker or a subprocess arrives as a plain object carrying the
+    // libc code — structurally the same fault, and `error instanceof Error` answers false for it.
+    expect(isAddressInUse({ message: 'Failed to start server', code: 'EADDRINUSE' })).toBe(true);
+
+    // And a value that fights being read answers false rather than throwing out of the guard:
+    // `getPrototypeOf` is what `instanceof` runs, so a trap there took the old check with it.
+    const hostile = new Proxy(
+      {},
+      {
+        getPrototypeOf() {
+          throw new TypeError('trapped getPrototypeOf');
+        },
+        get() {
+          throw new TypeError('trapped get');
+        },
+      },
+    );
+    expect(isAddressInUse(hostile)).toBe(false);
+  });
+
+  test('the refusal names the port and the knob that moves it', () => {
     const taken = Number(new URL(endpoint?.url ?? 'http://localhost:0').port);
-    let caught: unknown;
-    try {
-      startMetricsEndpoint({ port: taken }).stop();
-    } catch (error) {
-      caught = error;
-    }
-    // `expect(fn).toThrow(Class)` passes in Bun 1.3.14 when the callee merely RETURNS an error, so
-    // the identity is asserted off the caught value.
-    expect(caught).toBeInstanceOf(MetricsPortInUseError);
-    expect(caught).toMatchObject({ code: 'X_PORT_IN_USE' });
-    expect((caught as { cause: string }).cause).toContain(String(taken));
-    expect((caught as { fix: string }).fix).toContain('METRICS_PORT=');
+    expect(taken).toBeGreaterThan(0);
+
+    const refusal = new MetricsPortInUseError({ port: taken });
+    expect(refusal).toBeInstanceOf(MetricsPortInUseError);
+    expect(refusal).toMatchObject({ code: 'X_PORT_IN_USE' });
+    expect(refusal.cause).toContain(String(taken));
+    // `METRICS_PORT` is the one knob both `x dev` and the container read, so the fix has to name it.
+    expect(refusal.fix).toContain('METRICS_PORT=');
+    expect(refusal.fix).toContain(String(taken + 1));
   });
 
   test('a scrape does not reset the counters it read', async () => {
diff --git a/packages/cli/src/metrics-endpoint.ts b/packages/cli/src/metrics-endpoint.ts
index eb3a2a41..40816311 100644
--- a/packages/cli/src/metrics-endpoint.ts
+++ b/packages/cli/src/metrics-endpoint.ts
@@ -8,6 +8,7 @@ import {
   METRICS_PATH,
   markListening,
   metricsText,
+  stringField,
   UltimateError,
 } from '@ultimat3/core';
 import { docsFor } from './error-codes';
@@ -44,9 +45,16 @@ export class MetricsPortInUseError extends UltimateError {
   }
 }
 
-/** Bun surfaces the bind failure as an `Error` carrying the libc code; nothing else is ours. */
-const isAddressInUse = (error: unknown): boolean =>
-  error instanceof Error && (error as { code?: unknown }).code === 'EADDRINUSE';
+/**
+ * Bun surfaces the bind failure as an `Error` carrying the libc code; nothing else is ours. Read
+ * through `stringField`, never `error instanceof Error` plus a property access: both run on a value
+ * this process did not build, and either can throw one line before the guard that was meant to make
+ * the path safe. Exported because whether the kernel refuses a second bind is the OS's business,
+ * not this package's — the contract worth pinning is that an EADDRINUSE-shaped throw becomes a
+ * coded refusal, and that is testable without racing a socket.
+ */
+export const isAddressInUse = (error: unknown): boolean =>
+  stringField(error, 'code') === 'EADDRINUSE';
 
 export interface MetricsEndpointOptions {
   /** 0 asks the kernel for an ephemeral port, which is what a test wants. */

From 7d93491cf128a36a5d2f904c2517bb20f7983ee5 Mon Sep 17 00:00:00 2001
From: sebi <gore.sebyx@yahoo.com>
Date: Tue, 18 Aug 2026 22:26:46 -0500
Subject: [PATCH 3/3] fix(cli,render): a charset parameter downgraded the JSON
 escaper, and a fix line named port 65536
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review round on #158. Four of CodeRabbit's seven applied, three declined, plus one
finding the review surfaced in a package it did not name.

The best catch is a bug I wrote in this very PR. `cmd-doctor` emitted
`fix: x dev --port 65536` for `--port 65535`, and this PR added `neighbouringPort`
to close it — then `metrics-endpoint.ts` shipped `METRICS_PORT=${port + 1}`, the
identical off-by-one, in new code. `neighbouringPort` moved to `flag-number.ts`
beside `PORT_RANGE`, the constant that bounds it, and both call it now.

`carriesJson` tested whether the type attribute ends in `json`, so a real document's
`application/ld+json; charset=utf-8` did not match. In `budgets.ts` that counted an
SEO structured-data block as executable JavaScript again — the bug this PR exists to
fix, still reachable through the spelling every real document uses.

The same predicate exists in `@ultimat3/render`, where it chooses the ESCAPER, and
the review did not name that copy. There a charset parameter sent the JSON-LD block
— built from route data, which is the path attacker text takes — to
`escapeRawTextContent` instead of `escapeJsonContent`. Not a break-out: `</` is
escaped either way. But the JSON rule is total on purpose (`<`, `>`, `&`, U+2028,
U+2029) so nothing survives that could spell `</script` after any transformation, and
a charset is not a reason to leave it. Both copies now cut the MIME parameter first.

Also: `exec.ts`'s missing-binary fix interpolated the program name into a shell line
unquoted, so a name with a space produced a `fix:` that does not run — it uses the
`quoteArg` the repo already ships, moved to a leaf module because `exec.ts` importing
`test-shards.ts` would have closed a cycle onto the CLI's one subprocess boundary.
And `x verify`'s flag summary promised `min 2` while its reader accepted 1.

Declined: moving `MetricsPortInUseError` into `errors.ts` (489 lines; the class puts
it at ~504, over the ceiling `filesize` enforces — `db-seed.ts` is the precedent and
CLAUDE.md records the exception), replacing hostile-value test fixtures with coded
errors (their purpose is to be values the framework did not build), and rendering an
MCP result string through `t()` (`packages/mcp` has no `t()` in source, and
`from-action.ts:45` states why: it would make a published artifact locale-dependent).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 packages/cli/CLAUDE.md                    |  1 +
 packages/cli/README.md                    |  1 +
 packages/cli/src/budgets.test.ts          | 15 +++++++
 packages/cli/src/budgets.ts               | 10 ++++-
 packages/cli/src/cmd-doctor.ts            | 10 +----
 packages/cli/src/cmd-test.ts              |  3 +-
 packages/cli/src/cmd-verify.test.ts       | 31 +------------
 packages/cli/src/cmd-verify.ts            | 16 ++++---
 packages/cli/src/exec.test.ts             | 11 +++++
 packages/cli/src/exec.ts                  |  9 +++-
 packages/cli/src/flag-number.ts           | 11 +++++
 packages/cli/src/index.ts                 |  3 +-
 packages/cli/src/metrics-endpoint.test.ts | 11 +++++
 packages/cli/src/metrics-endpoint.ts      |  6 ++-
 packages/cli/src/shell-quote.test.ts      | 23 ++++++++++
 packages/cli/src/shell-quote.ts           | 15 +++++++
 packages/cli/src/test-shards.test.ts      |  7 ---
 packages/cli/src/test-shards.ts           | 11 +----
 packages/cli/src/verify-workers.test.ts   | 55 +++++++++++++++++++++++
 packages/render/src/head.test.ts          | 19 ++++++++
 packages/render/src/head.ts               | 16 +++++--
 21 files changed, 213 insertions(+), 71 deletions(-)
 create mode 100644 packages/cli/src/shell-quote.test.ts
 create mode 100644 packages/cli/src/shell-quote.ts
 create mode 100644 packages/cli/src/verify-workers.test.ts

diff --git a/packages/cli/CLAUDE.md b/packages/cli/CLAUDE.md
index cdf68b29..ba33b8ed 100644
--- a/packages/cli/CLAUDE.md
+++ b/packages/cli/CLAUDE.md
@@ -7,6 +7,7 @@ Tier 5. May import tiers 0–4. Nothing imports this except `create-ultimate`.
 | Entry | `src/bin.ts` (`#!/usr/bin/env bun`) — argv, stdout, exit code only |
 | stdout | `write-line.ts`'s `writeLine` — synchronous fd 1, never `process.stdout.write`, which truncates at the 64KB pipe buffer when `process.exit` follows. Exported, because `create-ultimate`'s entry point needs the same one |
 | Numeric flags | `flag-number.ts` — one reader for `--port` / `--workers` / `--shard`. A bare `Number.parseInt` accepts `4abc` and answers `NaN`, which turned three checks into ones that cannot fail |
+| Shell quoting | `shell-quote.ts`'s `quoteArg` — every value the CLI pastes into a `fix:` or a reproduce line, `exec.ts`'s missing-program refusal and `test-shards.ts`'s reproduce command both. A name holding a space or a `;` interpolated bare is an instruction that runs something else |
 | Missing positionals | `MissingPositionalError`, never `BadFlagError` (names a flag that does not exist) and never `UnknownCommandError` (says a known command form is not one). Its `example` is a REAL invocation — `x g route <name>` in a shell is a redirect |
 | Bare subcommands | `CommandSpec.defaultSubcommand`, **declared**. The parser answered `subcommands[0]` until 1.2.0, so `x db` ran `gen` — the migration GENERATOR — because it sorted first, and `x mcp` started a server. A command with no defensible default declares none and `MissingSubcommandError` refuses the bare form; `parse.test.ts` pins the set at exactly `db` and `mcp`. Its fix is `x help <command>`, never `x <command> --help`: the subcommand is resolved *after* the flag loop, so the latter throws the same error again — a fix line that reproduced its own failure |
 | I/O | only `dispatch.ts` renders or exits; commands return `CommandResult` |
diff --git a/packages/cli/README.md b/packages/cli/README.md
index 4bb61acf..3dfab8f4 100644
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -82,6 +82,7 @@ is held to the same error contract shipped source is (`X_GUARD_INVALID`, `X_GUAR
 | `dispatch.ts` | parse → run → render → exit; the only I/O boundary |
 | `parse.ts` | flags, subcommands, `--json`, `--help`, suggestions |
 | `flag-number.ts` | the one integer-flag reader — `--port`, `--workers`, `--shard` |
+| `shell-quote.ts` | the one POSIX quoter for a value pasted into a `fix:` or a reproduce line |
 | `output.ts` | one data shape, two renderers, the 3-line error format |
 | `registry.ts` | the one command list |
 | `generate-kinds.ts` | which generators exist, and how a command line names one |
diff --git a/packages/cli/src/budgets.test.ts b/packages/cli/src/budgets.test.ts
index eab5cd57..24d72589 100644
--- a/packages/cli/src/budgets.test.ts
+++ b/packages/cli/src/budgets.test.ts
@@ -132,6 +132,21 @@ describe('unit · measureJsBytes weighs the document, not the graph', () => {
     expect(await measureJsBytes(document, out)).toBe(0);
   });
 
+  // A real document writes the charset: `<script type="application/ld+json; charset=utf-8">` is
+  // what a CMS and half the structured-data guides emit, and it does not END with `json` — so the
+  // budget charged an SEO block as executable JS again, which is the bug the case above closes.
+  test('a MIME parameter does not turn structured data back into code', async () => {
+    const withCharset = '<script type="application/ld+json; charset=utf-8">{"a":1}</script>';
+    expect(await measureJsBytes(withCharset, out)).toBe(0);
+    expect(
+      await measureJsBytes('<script type="application/json;charset=utf-8">1</script>', out),
+    ).toBe(0);
+    // And the parameter cannot make code data: the suffix test still decides, on the type alone.
+    expect(
+      await measureJsBytes('<script type="text/javascript; charset=utf-8">let a=1</script>', out),
+    ).toBe(7);
+  });
+
   test('the rule is the type ending in json, not the one literal type', async () => {
     expect(await measureJsBytes('<script type="importmap+json">{"a":1}</script>', out)).toBe(0);
     expect(await measureJsBytes('<script type="APPLICATION/LD+JSON"> {"a":1} </script>', out)).toBe(
diff --git a/packages/cli/src/budgets.ts b/packages/cli/src/budgets.ts
index 46207df0..f0abbac2 100644
--- a/packages/cli/src/budgets.ts
+++ b/packages/cli/src/budgets.ts
@@ -132,8 +132,14 @@ const TYPE_ATTR = /\stype="(?<type>[^"]*)"/;
  * Without it a page shipping only `meta.ld` structured data and island props measured 8kb of JS
  * and failed a 2kb budget with a `fix:` naming an import chain that does not exist.
  */
-const carriesJson = (attrs: string): boolean =>
-  (TYPE_ATTR.exec(attrs)?.groups?.['type'] ?? '').trim().toLowerCase().endsWith('json');
+const carriesJson = (attrs: string): boolean => {
+  // Everything from the first `;` is a MIME PARAMETER and not the type: a real document writes
+  // `type="application/ld+json; charset=utf-8"`, which does not END with `json`, so the suffix
+  // test alone charged an SEO structured-data block as executable JavaScript all over again.
+  const [type = ''] = (TYPE_ATTR.exec(attrs)?.groups?.['type'] ?? '').split(';');
+  return type.trim().toLowerCase().endsWith('json');
+};
+
 /**
  * An island's chunk is reached by `import()` from inside the hydration runtime, so it never appears
  * as a `<script src>` — and a document weighed by script tags alone was charged for the runtime and
diff --git a/packages/cli/src/cmd-doctor.ts b/packages/cli/src/cmd-doctor.ts
index 958a87e3..618a3530 100644
--- a/packages/cli/src/cmd-doctor.ts
+++ b/packages/cli/src/cmd-doctor.ts
@@ -11,7 +11,7 @@ import type { CliCommand, CommandContext } from './command';
 import { checkMigrationSnapshots } from './db-snapshot';
 import { ICON_SOURCE } from './dev-assets';
 import { checkSourceDrift } from './drift';
-import { intFlagOr, PORT_RANGE } from './flag-number';
+import { intFlagOr, neighbouringPort, PORT_RANGE } from './flag-number';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import type { ParsedArgs } from './parse';
@@ -166,14 +166,6 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
   return findings;
 }
 
-/**
- * A free-port suggestion `x dev` will actually accept. `port + 1` at the top of the range emitted
- * `x dev --port 65536`, which `x dev` refuses with `X_CLI_BAD_FLAG` — a fix line that reproduces a
- * failure rather than ending one. The neighbour below is a port; the one above does not exist.
- */
-const neighbouringPort = (port: number): number =>
-  port < PORT_RANGE.max ? port + 1 : PORT_RANGE.max - 1;
-
 /**
  * The port to TEST, and the one place `x doctor` reads it. `PORT_RANGE.min` is 0 because `x dev
  * --port 0` means "let the kernel pick"; here 0 means nothing, and `Bun.serve({ port: 0 })` always
diff --git a/packages/cli/src/cmd-test.ts b/packages/cli/src/cmd-test.ts
index 142805b4..9cf4153a 100644
--- a/packages/cli/src/cmd-test.ts
+++ b/packages/cli/src/cmd-test.ts
@@ -9,8 +9,9 @@ import { readIntFlag } from './flag-number';
 import type { CommandResult } from './output';
 import type { ParsedArgs } from './parse';
 import { flagString } from './parse';
+import { quoteArg } from './shell-quote';
 import { discoverTests, missingSelection, readSample, readType, sampleFiles } from './test-select';
-import { quoteArg, runShards } from './test-shards';
+import { runShards } from './test-shards';
 import { defaultWorkers, WORKER_CEILING, WORKER_FLOOR, WORKER_OVERSUBSCRIBE } from './test-workers';
 import type { TestType } from './verify-tests';
 import { TEST_TYPES } from './verify-tests';
diff --git a/packages/cli/src/cmd-verify.test.ts b/packages/cli/src/cmd-verify.test.ts
index 37791b55..69a7ea94 100644
--- a/packages/cli/src/cmd-verify.test.ts
+++ b/packages/cli/src/cmd-verify.test.ts
@@ -6,11 +6,8 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { MANIFEST_FILENAME } from '@ultimat3/manifest';
 import { OPENAPI_FILE } from './app-openapi';
-import { readWorkers, runVerify, VERIFY_STEPS, verifyCommand, verifyStepNames } from './cmd-verify';
+import { runVerify, VERIFY_STEPS, verifyCommand, verifyStepNames } from './cmd-verify';
 import { exitCodeFor } from './output';
-import type { ParsedArgs } from './parse';
-import { parseArgs } from './parse';
-import { WORKER_CEILING } from './test-workers';
 import { VERIFY_FLOOR_FILE } from './verify-floor';
 import type { VerifyContext, VerifyStep } from './verify-step';
 import { VERIFY_STEP_NAMES } from './verify-step';
@@ -306,32 +303,6 @@ describe('unit · x verify', () => {
     expect(verifyCommand.spec.usage).toBe('x verify [--workers N] [--json]');
   });
 
-  // The bug this guards: the summary said "max 8" and `readWorkers` passed no `max`, so
-  // `--workers 5000` was accepted and every parallel step spawned one Bun process per test file.
-  test('--workers is bounded by the ceiling the summary names', () => {
-    const args = (value: string): ParsedArgs =>
-      parseArgs(['verify', '--workers', value], [verifyCommand.spec]);
-    expect(readWorkers(args(String(WORKER_CEILING)))).toBe(WORKER_CEILING);
-    expect(readWorkers(parseArgs(['verify'], [verifyCommand.spec]))).toBeUndefined();
-    // `toThrow(Class)` passes in Bun 1.3.14 when the callee merely RETURNS an error, so the code
-    // is asserted off a caught value instead.
-    let caught: unknown;
-    try {
-      readWorkers(args(String(WORKER_CEILING + 1)));
-    } catch (error) {
-      caught = error;
-    }
-    expect(caught).toMatchObject({ code: 'X_CLI_BAD_FLAG', fix: 'x verify --workers 4' });
-  });
-
-  // `x help verify` derives from the spec, and `cpus - 1` is the default `test-workers.ts`
-  // measured and rejected — slower than not sharding at all.
-  test('the flag summary names the default the code actually computes', () => {
-    const summary = verifyCommand.spec.flags?.[0]?.summary ?? '';
-    expect(summary).not.toContain('CPUs - 1');
-    expect(summary).toContain(`max ${WORKER_CEILING}`);
-  });
-
   test('a host check adds findings to the step it was registered for', async () => {
     const withHost: readonly VerifyStep[] = [
       {
diff --git a/packages/cli/src/cmd-verify.ts b/packages/cli/src/cmd-verify.ts
index 0c47401e..08356078 100644
--- a/packages/cli/src/cmd-verify.ts
+++ b/packages/cli/src/cmd-verify.ts
@@ -413,18 +413,22 @@ export const verifyCommand: CliCommand = {
 };
 
 /**
- * `x test --workers` refuses the same values for the same reason — and now through the same
- * reader, so the claim is enforced rather than asserted in a comment. Exported for the test that
- * pins the bound: the command's `run` reaches it only after the whole gate would have started.
+ * Both bounds are the constants the flag summary already names, so `x help verify` and the reader
+ * cannot disagree. Exported for the test that pins them: the command's `run` reaches this only
+ * after the whole gate would have started.
  *
- * `max` is the ceiling the summary already claimed. Without it `--workers 5000` parsed, `planShards`
- * clamped only to the file count, and `runParallel` `Promise.all`ed one Bun process per test file.
+ * `max` is the ceiling. Without it `--workers 5000` parsed, `planShards` clamped only to the file
+ * count, and `runParallel` `Promise.all`ed one Bun process per test file. `min` is `WORKER_FLOOR`,
+ * the same number `defaultWorkers` will not go below — the gate spreads or it does not shard, and
+ * `--workers 1` was a serial run the summary said was impossible. `x test --workers 1` stays legal
+ * and is deliberately NOT this reader: `runShards` clamps the width to the file count, so a
+ * one-file corpus makes `X_TEST_SHARD_FAILED`'s own `fix:` say `--workers 1`.
  */
 export const readWorkers = (args: ParsedArgs): number | undefined =>
   readIntFlag(args, {
     name: 'workers',
     command: 'verify',
-    min: 1,
+    min: WORKER_FLOOR,
     max: WORKER_CEILING,
     example: 'x verify --workers 4',
   });
diff --git a/packages/cli/src/exec.test.ts b/packages/cli/src/exec.test.ts
index c95884f3..44d8ffc6 100644
--- a/packages/cli/src/exec.test.ts
+++ b/packages/cli/src/exec.test.ts
@@ -36,6 +36,17 @@ describe('unit · the CLI subprocess boundary', () => {
     expect(String(thrown['fix'])).not.toBe('x doctor --json');
   });
 
+  // Axiom 4 inverted a second way: the program name was interpolated into the fix line twice,
+  // unquoted, so a name holding a space pasted back as two arguments and `command -v` answered
+  // about the first word. `quoteArg` is the CLI's one POSIX quoter and both references take it.
+  test('a program name with a space still produces a runnable fix', async () => {
+    const name = 'definitely not a real binary xyz';
+    const thrown = await thrownBy(() => exec([name, '--help'], { cwd: import.meta.dir }));
+    expect(thrown['code']).toBe('X_CLI_UNEXPECTED');
+    expect(String(thrown['fix'])).toContain(`command -v '${name}'`);
+    expect(String(thrown['fix'])).toContain(`install '${name}'`);
+  });
+
   test('an empty command is a caller bug, coded like every other CLI failure', async () => {
     const thrown = await thrownBy(() => exec([], { cwd: import.meta.dir }));
     expect(thrown['code']).toBe('X_CLI_UNEXPECTED');
diff --git a/packages/cli/src/exec.ts b/packages/cli/src/exec.ts
index 8d8714da..b75f3835 100644
--- a/packages/cli/src/exec.ts
+++ b/packages/cli/src/exec.ts
@@ -6,6 +6,9 @@
 // every command, and `./errors` runs `registerErrorCodes` on import — a subprocess boundary must
 // not decide when the CLI's registry is populated. `X_CLI_UNEXPECTED` is owned there all the same.
 import { renderThrowable, UltimateError } from '@ultimat3/core';
+// `shell-quote.ts` is a leaf — it imports nothing, so the subprocess boundary stays importable
+// from anywhere, this file's header rule about a single boundary included.
+import { quoteArg } from './shell-quote';
 
 export interface ExecResult {
   readonly command: readonly string[];
@@ -35,6 +38,10 @@ const now = (): number => performance.now();
  * error is axiom 4 inverted. The code stays `X_CLI_UNEXPECTED` (the CLI already owns it for a
  * failure of its own machinery); what changes is that the fix names the program to install.
  *
+ * The program name goes through `quoteArg` at BOTH references: `docker compose` or any name a
+ * shell would resplit produced a `fix:` that runs something else, which is axiom 4 inverted twice
+ * in one line.
+ *
  * The thrown value goes through core's render helper and is never interpolated: an `unknown`
  * reaching a `cause:` through `${…}` is what `bun run error-render` refuses, and this one is
  * genuinely unknown — Bun raises `ENOENT` for a missing program, `EACCES` for an unrunnable one.
@@ -55,7 +62,7 @@ function spawnOrRefuse(command: readonly string[], options: ExecOptions) {
     throw new UltimateError({
       code: 'X_CLI_UNEXPECTED',
       cause: `the CLI could not run "${head}" from ${options.cwd}: ${renderThrowable(error)}`,
-      fix: `install "${head}" and put it on PATH, then re-run — confirm with: command -v ${head}`,
+      fix: `install ${quoteArg(head)} and put it on PATH, then re-run — confirm with: command -v ${quoteArg(head)}`,
     });
   }
 }
diff --git a/packages/cli/src/flag-number.ts b/packages/cli/src/flag-number.ts
index 559cebc7..27a6b569 100644
--- a/packages/cli/src/flag-number.ts
+++ b/packages/cli/src/flag-number.ts
@@ -54,3 +54,14 @@ export const intFlagOr = (args: ParsedArgs, flag: IntFlag, fallback: number): nu
  * free port. Two ranges for one concept is the drift this constant exists to prevent.
  */
 export const PORT_RANGE = { min: 0, max: 65_535 } as const;
+
+/**
+ * A free-port suggestion the thing being fixed will actually accept. `port + 1` at the top of the
+ * range names 65536, which is not a port — so a `fix:` built that way reproduces a failure instead
+ * of ending one: `x doctor` emitted `x dev --port 65536`, which `x dev` refuses with
+ * `X_CLI_BAD_FLAG`. The neighbour below is a port; the one above does not exist. Here rather than
+ * beside either caller, because two ports-are-bounded rules is the drift `PORT_RANGE` above
+ * already exists to prevent.
+ */
+export const neighbouringPort = (port: number): number =>
+  port < PORT_RANGE.max ? port + 1 : PORT_RANGE.max - 1;
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index c4c601af..dee2c4a7 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -219,6 +219,7 @@ export {
   runRole,
   serveApp,
 } from './serve';
+export { quoteArg } from './shell-quote';
 export {
   eachSourceFile,
   isGenerated,
@@ -231,7 +232,7 @@ export { countsOf } from './test-counts';
 export type { TestFile } from './test-select';
 export { belongsToType, discoverTests, sampleFiles } from './test-select';
 export type { ReproduceOptions, RunShardsOptions, Shard } from './test-shards';
-export { planShards, quoteArg, reproduceFor, runShards, shardArgs } from './test-shards';
+export { planShards, reproduceFor, runShards, shardArgs } from './test-shards';
 export { availableCpus, defaultWorkers, WORKER_CEILING } from './test-workers';
 export type { CodeFixSite, CodeSite, FixSite, SourceSite } from './ts-scan';
 export {
diff --git a/packages/cli/src/metrics-endpoint.test.ts b/packages/cli/src/metrics-endpoint.test.ts
index b44336c7..dff4334f 100644
--- a/packages/cli/src/metrics-endpoint.test.ts
+++ b/packages/cli/src/metrics-endpoint.test.ts
@@ -12,6 +12,7 @@ import {
   resetListeners,
   resetMetrics,
 } from '@ultimat3/core';
+import { PORT_RANGE } from './flag-number';
 import {
   isAddressInUse,
   type MetricsEndpoint,
@@ -114,6 +115,16 @@ describe('the scrape endpoint', () => {
     expect(refusal.fix).toContain(String(taken + 1));
   });
 
+  // The same defect `x doctor` shipped and this release closed one file over: `port + 1` at the
+  // top of the range names 65536, which is not a port — so the one instruction the reader is
+  // given fails. The neighbour below is a port; the one above does not exist.
+  test('the port the fix names is one that exists, at the top of the range too', () => {
+    expect(new MetricsPortInUseError({ port: 3000 }).fix).toContain('METRICS_PORT=3001 ');
+    const top = new MetricsPortInUseError({ port: PORT_RANGE.max });
+    expect(top.fix).toContain(`METRICS_PORT=${PORT_RANGE.max - 1} `);
+    expect(top.fix).not.toContain(String(PORT_RANGE.max + 1));
+  });
+
   test('a scrape does not reset the counters it read', async () => {
     recordRequest({ method: 'GET', route: '/public', status: 200, durationMs: 1 });
     await scrape();
diff --git a/packages/cli/src/metrics-endpoint.ts b/packages/cli/src/metrics-endpoint.ts
index 40816311..8d294a7a 100644
--- a/packages/cli/src/metrics-endpoint.ts
+++ b/packages/cli/src/metrics-endpoint.ts
@@ -12,6 +12,7 @@ import {
   UltimateError,
 } from '@ultimat3/core';
 import { docsFor } from './error-codes';
+import { neighbouringPort } from './flag-number';
 
 /**
  * A port of its own, and NOT the role's HTTP port, for one reason the chart makes concrete:
@@ -33,13 +34,16 @@ export const DEFAULT_METRICS_PORT = 9090;
  * scrape port is one — a synonym here would be a second code for one condition. The fix moves the
  * port rather than naming a process to kill, because `METRICS_PORT` is the one knob both `x dev`
  * and the container read (`serve.ts`'s `metricsPortFromEnv`).
+ *
+ * The port it names comes from `neighbouringPort`, never `port + 1`: at the top of the range
+ * that is 65536, and an instruction that cannot run is the failure this code exists to end.
  */
 export class MetricsPortInUseError extends UltimateError {
   constructor(input: { port: number }) {
     super({
       code: 'X_PORT_IN_USE',
       cause: `the metrics port ${input.port} is already bound, so no role could open its scrape listener`,
-      fix: `METRICS_PORT=${input.port + 1} x dev --json`,
+      fix: `METRICS_PORT=${neighbouringPort(input.port)} x dev --json`,
       docs: docsFor('X_PORT_IN_USE'),
     });
   }
diff --git a/packages/cli/src/shell-quote.test.ts b/packages/cli/src/shell-quote.test.ts
new file mode 100644
index 00000000..49a5e44f
--- /dev/null
+++ b/packages/cli/src/shell-quote.test.ts
@@ -0,0 +1,23 @@
+// The one quoter, from both ends: a value that needs nothing is left readable, and a value that
+// would change the meaning of the line is closed off.
+
+import { describe, expect, test } from 'bun:test';
+import { quoteArg } from './shell-quote';
+
+describe('unit · quoteArg', () => {
+  test('an ordinary path is left alone, so the common line stays readable', () => {
+    expect(quoteArg('packages/cli/src/cmd-test.test.ts')).toBe('packages/cli/src/cmd-test.test.ts');
+    expect(quoteArg('')).toBe("''");
+    expect(quoteArg('a b')).toBe("'a b'");
+  });
+
+  test('a metacharacter cannot start a second command', () => {
+    expect(quoteArg('a; rm -rf b')).toBe("'a; rm -rf b'");
+    expect(quoteArg('$(id)')).toBe("'$(id)'");
+  });
+
+  // `'it'\''s slow'` — close, an escaped quote, reopen. Anything else truncates the argument.
+  test('a single quote is escaped the one way a single-quoted string allows', () => {
+    expect(quoteArg("it's slow")).toBe("'it'\\''s slow'");
+  });
+});
diff --git a/packages/cli/src/shell-quote.ts b/packages/cli/src/shell-quote.ts
new file mode 100644
index 00000000..7740ce60
--- /dev/null
+++ b/packages/cli/src/shell-quote.ts
@@ -0,0 +1,15 @@
+// POSIX single-quoting for a value the CLI pastes into a line a reader runs — a `fix:`, a
+// reproduce command. Its own module, and not `test-shards.ts` where it started, because the
+// subprocess boundary needs it too and `test-shards.ts` imports `exec.ts`: one leaf both can
+// reach is the alternative to an import cycle or a second quoter.
+
+const SHELL_SAFE = /^[\w@%+=:,./-]+$/;
+
+/**
+ * A program name, a `--filter` or a path holding a space, a `$` or a `;` pastes back as two
+ * arguments or as a second command, so an unquoted line runs something other than what it claims.
+ * `'\''` is the only escape a single-quoted string has. A shell-safe value is left alone, so the
+ * common case stays readable.
+ */
+export const quoteArg = (value: string): string =>
+  SHELL_SAFE.test(value) ? value : `'${value.split("'").join("'\\''")}'`;
diff --git a/packages/cli/src/test-shards.test.ts b/packages/cli/src/test-shards.test.ts
index 59565796..f35f7196 100644
--- a/packages/cli/src/test-shards.test.ts
+++ b/packages/cli/src/test-shards.test.ts
@@ -11,7 +11,6 @@ import type { TestFile } from './test-select';
 import type { Shard } from './test-shards';
 import {
   planShards,
-  quoteArg,
   reproduceFor,
   runShards,
   SHARD_COMMAND_PREFIX,
@@ -322,10 +321,4 @@ describe('unit · reproduceFor', () => {
       "x test --filter 'it'\\''s slow' --workers 1 --worker 0",
     );
   });
-
-  test('quoteArg leaves an ordinary path alone, so the common line stays readable', () => {
-    expect(quoteArg('packages/cli/src/cmd-test.test.ts')).toBe('packages/cli/src/cmd-test.test.ts');
-    expect(quoteArg('')).toBe("''");
-    expect(quoteArg('a b')).toBe("'a b'");
-  });
 });
diff --git a/packages/cli/src/test-shards.ts b/packages/cli/src/test-shards.ts
index 1b2eae22..e74d26f4 100644
--- a/packages/cli/src/test-shards.ts
+++ b/packages/cli/src/test-shards.ts
@@ -8,6 +8,7 @@ import type { Runner } from './exec';
 import { execOutput } from './exec';
 import { msg } from './messages';
 import type { CommandResult, Finding, JsonValue, StepResult } from './output';
+import { quoteArg } from './shell-quote';
 import type { TestFile } from './test-select';
 import { bySizeThenPath } from './test-select';
 import type { TestType } from './verify-tests';
@@ -64,16 +65,6 @@ export const shardArgs = (shard: Shard): readonly string[] => [
   ...shard.files,
 ];
 
-const SHELL_SAFE = /^[\w@%+=:,./-]+$/;
-
-/**
- * POSIX single-quoting for the values a caller supplies. A `--filter` holding a space, a `$` or a
- * `;` pastes back as two arguments or as a second command, so an unquoted line would run something
- * other than the run it claims to reproduce. `'\''` is the only escape a single-quoted string has.
- */
-export const quoteArg = (value: string): string =>
-  SHELL_SAFE.test(value) ? value : `'${value.split("'").join("'\\''")}'`;
-
 export interface ReproduceOptions {
   /** The *effective* worker count: `planShards` clamps to the file count, and the split follows. */
   readonly workers: number;
diff --git a/packages/cli/src/verify-workers.test.ts b/packages/cli/src/verify-workers.test.ts
new file mode 100644
index 00000000..9b167a25
--- /dev/null
+++ b/packages/cli/src/verify-workers.test.ts
@@ -0,0 +1,55 @@
+// `x verify --workers N`, from both ends of the bound. Its own file because `cmd-verify.test.ts`
+// drives the step engine and this drives one flag reader — and the engine's file is at the line
+// ceiling, so a third bound assertion could not have landed beside it.
+
+import { describe, expect, test } from 'bun:test';
+import { readWorkers, verifyCommand } from './cmd-verify';
+import type { ParsedArgs } from './parse';
+import { parseArgs } from './parse';
+import { WORKER_CEILING, WORKER_FLOOR } from './test-workers';
+
+const args = (value: string): ParsedArgs =>
+  parseArgs(['verify', '--workers', value], [verifyCommand.spec]);
+
+/** `toThrow(Class)` passes in Bun 1.3.14 when the callee merely RETURNS an error. */
+const thrownBy = (run: () => unknown): unknown => {
+  try {
+    run();
+  } catch (error) {
+    return error;
+  }
+  return undefined;
+};
+
+describe('unit · x verify --workers', () => {
+  // The bug this guards: the summary said "max 8" and `readWorkers` passed no `max`, so
+  // `--workers 5000` was accepted and every parallel step spawned one Bun process per test file.
+  test('--workers is bounded by the ceiling the summary names', () => {
+    expect(readWorkers(args(String(WORKER_CEILING)))).toBe(WORKER_CEILING);
+    expect(readWorkers(parseArgs(['verify'], [verifyCommand.spec]))).toBeUndefined();
+    expect(thrownBy(() => readWorkers(args(String(WORKER_CEILING + 1))))).toMatchObject({
+      code: 'X_CLI_BAD_FLAG',
+      fix: 'x verify --workers 4',
+    });
+  });
+
+  // The same defect at the other end, and the one that makes `WORKER_FLOOR` load-bearing rather
+  // than decorative: the flag summary named the constant while the reader passed a literal 1, so
+  // `x verify --workers 1` ran the gate serially against help text that said the minimum was 2.
+  test('--workers is bounded by the floor the summary names', () => {
+    expect(readWorkers(args(String(WORKER_FLOOR)))).toBe(WORKER_FLOOR);
+    expect(thrownBy(() => readWorkers(args(String(WORKER_FLOOR - 1))))).toMatchObject({
+      code: 'X_CLI_BAD_FLAG',
+      fix: 'x verify --workers 4',
+    });
+  });
+
+  // `x help verify` derives from the spec, and `cpus - 1` is the default `test-workers.ts`
+  // measured and rejected — slower than not sharding at all.
+  test('the flag summary names the bounds the reader actually enforces', () => {
+    const summary = verifyCommand.spec.flags?.[0]?.summary ?? '';
+    expect(summary).not.toContain('CPUs - 1');
+    expect(summary).toContain(`min ${WORKER_FLOOR}`);
+    expect(summary).toContain(`max ${WORKER_CEILING}`);
+  });
+});
diff --git a/packages/render/src/head.test.ts b/packages/render/src/head.test.ts
index 4bbacefb..5da32a63 100644
--- a/packages/render/src/head.test.ts
+++ b/packages/render/src/head.test.ts
@@ -236,6 +236,25 @@ describe('JSON-LD content', () => {
     expect(parsed).toEqual({ '@type': 'WebSite', name });
   });
 
+  test('a charset parameter does not downgrade the JSON escaper to the raw-text one', () => {
+    // A real document writes `application/ld+json; charset=utf-8`. That does not end in `json`, so
+    // the suffix test alone sent the block built from route data — the path attacker text takes —
+    // to `escapeRawTextContent`, which escapes `</` and nothing else. `<`, `>` and `&` survived.
+    const html = renderHead([
+      {
+        kind: 'script',
+        key: 'script:ld+json',
+        attrs: { type: 'application/ld+json; charset=utf-8' },
+        content: JSON.stringify({ '@type': 'WebSite', name: '<a> & </b>' }),
+      },
+    ]);
+
+    expect(html).toContain('\\u003c');
+    expect(html).toContain('\\u0026');
+    expect(html).not.toContain('<a>');
+    expect(html).not.toContain(' & ');
+  });
+
   test('the JSON escape is \\u-form, never an HTML entity — an entity is not decoded here', () => {
     const html = ldHead({ '@type': 'WebSite', name: '<a> & </b>' });
     expect(html).not.toContain('&lt;');
diff --git a/packages/render/src/head.ts b/packages/render/src/head.ts
index df426c4c..355e031e 100644
--- a/packages/render/src/head.ts
+++ b/packages/render/src/head.ts
@@ -134,10 +134,20 @@ function contentOf(tag: HeadTag, raw: string): string {
   return carriesJson(tag) ? escapeJsonContent(raw) : escapeRawTextContent(raw);
 }
 
-/** `application/ld+json`, `application/json`, any `…+json`: the body is data, not code. */
+/**
+ * `application/ld+json`, `application/json`, any `…+json`: the body is data, not code.
+ *
+ * The MIME parameter is cut before the suffix test, because a real document writes
+ * `type="application/ld+json; charset=utf-8"` and that does not end in `json` — so the block built
+ * from route data, which is the path attacker text takes, silently took the raw-text escaper
+ * instead of the total one. `</` is escaped either way, so this was a weakened boundary rather than
+ * a break-out; the JSON rule is total on purpose, and a `charset` is not a reason to leave it.
+ */
 function carriesJson(tag: HeadTag): boolean {
-  const type = tag.attrs?.['type'];
-  return typeof type === 'string' && type.trim().toLowerCase().endsWith('json');
+  const declared = tag.attrs?.['type'];
+  if (typeof declared !== 'string') return false;
+  const [type = ''] = declared.split(';');
+  return type.trim().toLowerCase().endsWith('json');
 }
 
 export interface ThemeScriptOptions {