Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

fix(llm): close review regressions and pin critical cases

Alfredo Lopezb43a849a6929
diff --git a/.github/workflows/ci-public.yml b/.github/workflows/ci-public.yml
index 886372784..6e4a081d7 100644
--- a/.github/workflows/ci-public.yml
+++ b/.github/workflows/ci-public.yml
@@ -75,6 +75,21 @@ jobs:
- packages/codex-catalog-projection
- codex-llm-proxy
- grok-llm-proxy
+ include:
+ - service: gfs-controller
+ pinned_suites: serve.agentRateLimit.test.ts
+ - service: mcp-host
+ pinned_suites: gfsClient.retry429.test.ts logPayloadKeys.test.ts taskExecutor.test.ts
+ - service: control-api
+ pinned_suites:
+ helpers.realPostgresTeardown.test.ts routes.mcp-host.llmProviderAttempts.test.ts
+ pinned_cases: ../scripts/ci/pinned-vitest-cases/control-api.json
+ - service: codex-llm-proxy
+ pinned_suites: originPolicy.test.ts server.security.test.ts
+ pinned_cases: ../scripts/ci/pinned-vitest-cases/codex-llm-proxy.json
+ - service: grok-llm-proxy
+ pinned_suites: originPolicy.test.ts server.security.test.ts
+ pinned_cases: ../scripts/ci/pinned-vitest-cases/grok-llm-proxy.json
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
@@ -131,13 +146,15 @@ jobs:
if: matrix.service == 'gfs-controller'
run: node scripts/tests/run-node-test-files.mjs scripts/ci/assert-pinned-vitest-suites.test.mjs
- # PINNED_SUITES lists test files that must run and pass. The check reads
- # Vitest's JSON report, not the console output: a file whose tests are all
- # skipped is still printed by name, so a grep would accept it.
+ # PINNED_SUITES lists test files that must run and pass. PINNED_CASES
+ # optionally lists exact fullName witnesses that must survive merges. Both
+ # checks read Vitest's JSON report, not console output: a file whose tests
+ # are all skipped is still printed by name, so a grep would accept it.
- name: Test
working-directory: ${{ matrix.service }}
env:
- PINNED_SUITES: ${{ matrix.service == 'gfs-controller' && 'serve.agentRateLimit.test.ts' || matrix.service == 'mcp-host' && 'gfsClient.retry429.test.ts logPayloadKeys.test.ts taskExecutor.test.ts' || '' }}
+ PINNED_SUITES: ${{ matrix.pinned_suites || '' }}
+ PINNED_CASES: ${{ matrix.pinned_cases || '' }}
run: |
set -euo pipefail
if [ -z "$PINNED_SUITES" ]; then
@@ -149,6 +166,9 @@ jobs:
npm test -- --reporter=default --reporter=json --outputFile="$report"
# PINNED_SUITES is unquoted on purpose: one argument per file name.
node ../scripts/ci/assert-pinned-vitest-suites.mjs "$report" $PINNED_SUITES
+ if [ -n "$PINNED_CASES" ]; then
+ node ../scripts/ci/assert-pinned-vitest-suites.mjs --cases "$report" "$PINNED_CASES"
+ fi
- name: Test web-search image with isolated DNS TLS and MCP
if: matrix.service == 'mcp-servers/web-search'
diff --git a/codex-llm-proxy/src/codexTransport.ts b/codex-llm-proxy/src/codexTransport.ts
index 240d60847..daecd6b96 100644
--- a/codex-llm-proxy/src/codexTransport.ts
+++ b/codex-llm-proxy/src/codexTransport.ts
@@ -55,11 +55,11 @@ export class CodexTransportError extends Error {
}
/**
- * Review R3-L1: a fetch that failed on the network is undici's TypeError, whose
- * cause message names the upstream address. It becomes a mapped transport error
- * that keeps only the cause code, so the attempt line logs `causeCode` and never
- * the error itself. An error with no code-shaped cause is returned undefined and
- * stays unmapped, which logs it as a handler defect.
+ * Review R3-L1/R4-L1: a rejected undici fetch and a failed dns.lookup wrapped
+ * by origin policy both carry a code-shaped cause. It becomes a mapped
+ * transport error that keeps only the cause code, so the attempt line logs
+ * `causeCode` and never the error itself. An error with no code-shaped cause
+ * is returned undefined and stays unmapped, which logs it as a handler defect.
*/
function upstreamFetchFailure(err: unknown): CodexTransportError | undefined {
const code = fetchCauseCode(err)
diff --git a/codex-llm-proxy/src/controlApiClient.ts b/codex-llm-proxy/src/controlApiClient.ts
index 2f09bc522..bcd674bdd 100644
--- a/codex-llm-proxy/src/controlApiClient.ts
+++ b/codex-llm-proxy/src/controlApiClient.ts
@@ -65,8 +65,9 @@ const CONNECT_PHASE_CODES: ReadonlySet<string> = new Set([
'UND_ERR_CONNECT_TIMEOUT',
])
-// The code undici puts on a failed fetch's cause. Only a code-shaped string is
-// returned, so nothing else from the error can reach a log.
+// The code a rejected undici fetch puts on its cause, or origin policy puts on
+// a wrapped dns.lookup failure. Only a code-shaped string is returned, so
+// nothing else from the error can reach a log.
export function fetchCauseCode(err: unknown): string | undefined {
if (!(err instanceof Error)) return undefined
const cause: unknown = (err as { cause?: unknown }).cause
diff --git a/codex-llm-proxy/src/originPolicy.ts b/codex-llm-proxy/src/originPolicy.ts
index baeb0fde7..a3b18eb84 100644
--- a/codex-llm-proxy/src/originPolicy.ts
+++ b/codex-llm-proxy/src/originPolicy.ts
@@ -64,9 +64,10 @@ export async function assertResolvedUpstream(
} catch (err) {
// A failed lookup carries its system code (ENOTFOUND, EAI_AGAIN) on the
// error itself and names the host in its message. Only a code-shaped code
- // is kept, as the cause the transport maps to provider_unavailable.
+ // is kept, excluding Node programmer ERR_* codes, as the cause the
+ // transport maps to provider_unavailable.
const code: unknown = (err as { code?: unknown } | null)?.code
- if (typeof code === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/.test(code)) {
+ if (typeof code === 'string' && /^(?!ERR_)[A-Z][A-Z0-9_]{0,63}$/.test(code)) {
throw new Error('upstream address lookup failed', { cause: { code } })
}
throw err
diff --git a/codex-llm-proxy/test/originPolicy.test.ts b/codex-llm-proxy/test/originPolicy.test.ts
index 2e49eb635..0fbef4a7b 100644
--- a/codex-llm-proxy/test/originPolicy.test.ts
+++ b/codex-llm-proxy/test/originPolicy.test.ts
@@ -120,9 +120,58 @@ describe('originPolicy', () => {
).resolves.toBeUndefined()
})
- // Review R4-L1: a failed lookup carries its system code on the error itself
- // and names the host in its message. Only a code-shaped code is kept, as
- // the cause the transport maps by code.
+ it('wraps operational lookup codes without the host name', async () => {
+ const { assertResolvedUpstream } = await import('../src/originPolicy.js')
+ const codes = [
+ 'ENOTFOUND',
+ 'EAI_AGAIN',
+ 'EAI_NONAME',
+ 'ECONNREFUSED',
+ 'ENETUNREACH',
+ 'EHOSTUNREACH',
+ ] as const
+ let lookups = 0
+ for (const code of codes) {
+ const lookupError = Object.assign(new Error(`lookup failed for ${code}.invalid`), { code })
+ const err: unknown = await assertResolvedUpstream(
+ new URL(CODEX_COMPLETIONS_ORIGIN),
+ async () => {
+ lookups += 1
+ throw lookupError
+ }
+ ).then(
+ () => 'resolved',
+ (rejection: unknown) => rejection
+ )
+ expect(err).toBeInstanceOf(Error)
+ expect(err).not.toBeInstanceOf(OriginDeniedError)
+ expect((err as Error).message).toBe('upstream address lookup failed')
+ const cause = (err as { cause?: unknown }).cause as Record<string, unknown>
+ expect(cause).toEqual({ code })
+ expect(JSON.stringify({ message: (err as Error).message, cause })).not.toContain(
+ `${code}.invalid`
+ )
+ }
+ expect(lookups).toBe(codes.length)
+ })
+
+ it('rethrows a Node ERR_* lookup error as the same reference', async () => {
+ const { assertResolvedUpstream } = await import('../src/originPolicy.js')
+ const err = Object.assign(new Error('lookup argument is invalid'), {
+ code: 'ERR_INVALID_ARG_TYPE',
+ })
+ let lookups = 0
+ await expect(
+ assertResolvedUpstream(new URL(CODEX_COMPLETIONS_ORIGIN), async () => {
+ lookups += 1
+ throw err
+ })
+ ).rejects.toBe(err)
+ expect(lookups).toBe(1)
+ })
+
+ // Review R4-L1: the real lookup depends on the resolver honoring .invalid
+ // NXDOMAIN. The deterministic twins above own the code semantics.
it('maps a failed lookup to its code without the host name', async () => {
const { assertResolvedUpstream } = await import('../src/originPolicy.js')
const host = 'codex-origin-policy-r4-l1.invalid'
@@ -145,7 +194,7 @@ describe('originPolicy', () => {
expect(Object.keys(cause)).toEqual(['code'])
expect(String(cause.code)).toMatch(/^(ENOTFOUND|EAI_AGAIN)$/)
expect(JSON.stringify({ message: (err as Error).message, cause })).not.toContain(host)
- })
+ }, 15_000)
it('rethrows a lookup error without a code-shaped code unchanged', async () => {
const { assertResolvedUpstream } = await import('../src/originPolicy.js')
diff --git a/codex-llm-proxy/test/server.security.test.ts b/codex-llm-proxy/test/server.security.test.ts
index 12e3aba98..6356598ef 100644
--- a/codex-llm-proxy/test/server.security.test.ts
+++ b/codex-llm-proxy/test/server.security.test.ts
@@ -1584,6 +1584,7 @@ describe('codex-llm-proxy attempt telemetry', () => {
// Review R4-L1: a DNS failure carries its code on the lookup error itself,
// not in `cause`, and its message names the upstream host. The attempt line
// and both admin routes log it by cause code, with no err entry and no host.
+ // These real .invalid lookups depend on the resolver honoring NXDOMAIN.
const INVALID_UPSTREAM_HOST = 'codex-r4-l1.invalid'
function invalidHostLookup(calls: { count: number }) {
@@ -1628,7 +1629,7 @@ describe('codex-llm-proxy attempt telemetry', () => {
expect('err' in lines[0]!).toBe(false)
expect(serializeWithErrors(lines[0])).not.toContain(INVALID_UPSTREAM_HOST)
expectNoForbiddenKeys(lines[0]!)
- })
+ }, 15_000)
it('(r4-l1b) logs a catalog DNS lookup failure by cause code on both admin routes', async () => {
for (const [route, operation] of [
@@ -1674,7 +1675,7 @@ describe('codex-llm-proxy attempt telemetry', () => {
error.mockRestore()
}
}
- })
+ }, 15_000)
it('logs a mapped control-api failure without an err entry', async () => {
const { res, lines } = await run(
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index 8d910ac94..21ae3e5d6 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.694",
+ "version": "0.1.695",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.694",
+ "version": "0.1.695",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/grok-provider-attempt-contract": "file:../packages/grok-provider-attempt-contract",
diff --git a/control-api/package.json b/control-api/package.json
index 31d5b4cab..a73dad17e 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.694",
+ "version": "0.1.695",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/routes/mcp-host/llmProviderAttempts.routes.ts b/control-api/src/routes/mcp-host/llmProviderAttempts.routes.ts
index 4818d5839..9ff0ae9ff 100644
--- a/control-api/src/routes/mcp-host/llmProviderAttempts.routes.ts
+++ b/control-api/src/routes/mcp-host/llmProviderAttempts.routes.ts
@@ -27,7 +27,8 @@ import {
} from '../../services/subscriptionGrantIdentity.js'
import { llmProviderAttemptAuthorizeRateLimits } from '../workflows/shared/rateLimit.js'
-const log = rootLogger.child({ module: 'mcp-host-llm-provider-attempts' })
+const LOG_MODULE = 'mcp-host-llm-provider-attempts'
+const log = rootLogger.child({ module: LOG_MODULE })
// JSON.parse allocates one heap object per container, so a body under
// the byte limit can exhaust the heap before either authorizer runs. The
@@ -188,7 +189,7 @@ export function createMcpHostLlmProviderAttemptRoutes(gateway: K8sGateway): Rout
// that logger lacks this route's module binding, so it is added back.
router.use((err: unknown, req: Request, res: Response, next: NextFunction) => {
const typed = err as { type?: string; status?: number }
- const requestLog = req.log?.child({ module: 'mcp-host-llm-provider-attempts' }) ?? log
+ const requestLog = req.log?.child({ module: LOG_MODULE }) ?? log
const refuse = (status: number, error: string): void => {
requestLog.warn({ event: 'llm_provider_attempt_body_refused', type: typed.type, status })
res.status(status).json({ error })
diff --git a/control-api/test/helpers.realPostgresTeardown.test.ts b/control-api/test/helpers.realPostgresTeardown.test.ts
index 975c5ebd0..c10b53d0e 100644
--- a/control-api/test/helpers.realPostgresTeardown.test.ts
+++ b/control-api/test/helpers.realPostgresTeardown.test.ts
@@ -98,7 +98,6 @@ describe('endPoolAndWaitForClients', () => {
'endPoolAndWaitForClients: pg-pool no longer exposes _clients'
)
expect(pool.end).not.toHaveBeenCalled()
- // Witness that the helper ran: the refusal above names the missing list.
})
it('resolves after end() when the pool holds no client', async () => {
@@ -140,9 +139,13 @@ describe('endPoolAndWaitForClients', () => {
(err: NodeJS.ErrnoException) => err.code
)
expect(pool.totalCount).toBe(1)
+ const [client] = (pool as unknown as { _clients: Array<{ _ended: boolean }> })._clients
+ expect(client).toBeDefined()
+ expect(client._ended).toBe(false)
await endPoolAndWaitForClients(pool)
+ expect(client._ended).toBe(true)
expect(pool.ended).toBe(true)
expect(await queryOutcome).toBe('ECONNREFUSED')
})
diff --git a/control-api/test/routes.mcp-host.llmProviderAttempts.test.ts b/control-api/test/routes.mcp-host.llmProviderAttempts.test.ts
index 4e545f93d..1e07fdfa2 100644
--- a/control-api/test/routes.mcp-host.llmProviderAttempts.test.ts
+++ b/control-api/test/routes.mcp-host.llmProviderAttempts.test.ts
@@ -23,17 +23,28 @@ import { LlmProviderAttemptAuthorizeError } from '../src/services/llmProviderAtt
import * as authorizer from '../src/services/llmProviderAttemptAuthorizer.js'
import * as mcpHostJwt from '../src/utils/auth/mcpHostJwtToken.js'
-// Capture structured logs so the refusal event can be asserted without pino
+// Capture structured logs and their effective child bindings without pino
// transports. Every other logger method is a no-op.
-const { mockLogWarn } = vi.hoisted(() => ({ mockLogWarn: vi.fn() }))
+const { mockLogWarn, mockLogWarnBindings } = vi.hoisted(() => ({
+ mockLogWarn: vi.fn(),
+ mockLogWarnBindings: vi.fn(),
+}))
vi.mock('../src/observability/logger.js', () => {
- const makeLogger = (): unknown =>
+ const makeLogger = (bindings: Record<string, unknown> = {}): unknown =>
new Proxy(
{},
{
get(_t, prop) {
- if (prop === 'warn') return mockLogWarn
- if (prop === 'child') return () => makeLogger()
+ if (prop === 'warn') {
+ return (...args: unknown[]) => {
+ mockLogWarn(...args)
+ mockLogWarnBindings(bindings)
+ }
+ }
+ if (prop === 'child') {
+ return (childBindings: Record<string, unknown>) =>
+ makeLogger({ ...bindings, ...childBindings })
+ }
return () => {}
},
}
@@ -384,6 +395,7 @@ describe('authorize raw-body scan before JSON.parse', () => {
beforeEach(() => {
vi.mocked(authorizer.authorizeLlmProviderAttempt).mockReset()
mockLogWarn.mockReset()
+ mockLogWarnBindings.mockReset()
})
async function withRoute(run: (url: string) => Promise<void>): Promise<void> {
@@ -750,7 +762,19 @@ describe('authorize raw-body scan before JSON.parse', () => {
// which carries the correlationId, as the global error handler does.
// Review R4-L8: that logger is a child of the root logger without the
// route's module binding, so the route adds it back.
- it('logs a body refusal through req.log when the request has one', async () => {
+ it('preserves the module logger binding and request correlation on body refusals', async () => {
+ const moduleResponse = await request(buildApp())
+ .post('/api/v1/mcp-host/llm/provider-attempts/authorize')
+ .set(headers({ 'content-encoding': 'gzip' }))
+ .send(Buffer.from(gzipSync('{}')))
+ expect(moduleResponse.status).toBe(415)
+ expect(mockLogWarnBindings).toHaveBeenCalledTimes(1)
+ const moduleBinding = mockLogWarnBindings.mock.calls[0][0].module
+ expect(moduleBinding).toBeTypeOf('string')
+ expect(moduleBinding).not.toBe('')
+ mockLogWarn.mockClear()
+ mockLogWarnBindings.mockClear()
+
const lines: Array<Record<string, unknown>> = []
const requestLogger = pino(
{ level: 'info' },
@@ -780,7 +804,7 @@ describe('authorize raw-body scan before JSON.parse', () => {
type: 'encoding.unsupported',
status: 415,
correlationId: 'c-806',
- module: 'mcp-host-llm-provider-attempts',
+ module: moduleBinding,
})
const moduleRefusals = mockLogWarn.mock.calls.filter(
([fields]) => (fields as { event?: string })?.event === 'llm_provider_attempt_body_refused'
diff --git a/docs/architecture/codex-subscription-transport-contract.md b/docs/architecture/codex-subscription-transport-contract.md
index 3f5e6f8b0..9ebb10729 100644
--- a/docs/architecture/codex-subscription-transport-contract.md
+++ b/docs/architecture/codex-subscription-transport-contract.md
@@ -61,6 +61,12 @@ data and text parts that repeat `content` blanked in a temporary size
projection; the actual request and its hash are not modified. The two caps are not additive: a V2 request carrying a
hard-ceiling image (16 MiB decoded, about 21.3 MiB encoded) has about 2.7 MiB
left for non-image data before the 24 MiB envelope refuses it.
+Codex checks the complete V2 request against 24 MiB before measuring its
+non-image share. A real 1 KiB PNG with 12.5 MiB of repeated text is therefore
+refused locally as `maxVisualRequestBodyBytes`, which the Host maps to
+`attachment_too_large` and `InvalidAttachment`; Grok refuses the same shape as
+text with `request exceeds maxRequestBodyBytes outside image data`, because
+Grok checks the non-image share first.
The authorizer builds the exact V2 proxy envelope inside its transaction after
signing but before commit. Exceeding the bound rolls back the new attempt,
ticket and new reservation; it does not call the receipt finalizer before redeem.
@@ -510,9 +516,10 @@ behavior changes:
`deliveredAs: 'sse_done'` and `usage` when present. On a thrown failure,
`outcome` is `failed` and the event adds `code`, the transport `reason`,
`details` (for example `{limit, observed}` on
- `tool_call_limit_exceeded`), `causeCode` when the failure is a rejected
- `fetch` (the undici cause code, such as `ECONNREFUSED`, and nothing else
- from the error) and `deliveredAs`: `http_status` with
+ `tool_call_limit_exceeded`), `causeCode` when a rejected undici `fetch`
+ (for example `ECONNREFUSED`) or a failed `dns.lookup` wrapped by origin
+ policy (for example `ENOTFOUND` or `EAI_AGAIN`) carries a code-shaped cause
+ (only that code is logged), and `deliveredAs`: `http_status` with
`httpStatus` when no SSE byte had been sent, or `sse_error` when the
failure went out as an SSE error frame.
- Once the redeem succeeds, the proxy writes a `: keepalive` SSE comment
diff --git a/docs/architecture/grok-subscription-transport-contract.md b/docs/architecture/grok-subscription-transport-contract.md
index d4d0176f8..8aa3289dc 100644
--- a/docs/architecture/grok-subscription-transport-contract.md
+++ b/docs/architecture/grok-subscription-transport-contract.md
@@ -77,10 +77,24 @@ plus 7 MiB of text, or two 10 MiB images plus 4.5 MiB of text. It gets the
whole-body refusal, and the Host reports every whole-body refusal as an image
refusal (`attachment_too_large`, below), so the user is told to send fewer or
smaller images although shorter text would also fit. The Host refuses it
-before authorize, so no attempt is spent. Codex behaves the same way. For the
-same reason a V2 request accepted close to 35 MiB can leave less room than the
-authorize wrapper and the signed ticket need; the Host's authorize-body check
-refuses it, also before any attempt.
+before authorize, so no attempt is spent.
+
+Grok measures the non-image share before the whole request. A real 1 KiB PNG
+with 12.5 MiB of repeated text therefore reaches the whole-body band in Codex
+but not here: Grok refuses it as `request exceeds maxRequestBodyBytes outside
+image data`, which the Host maps to `request_limit_exceeded` and
+`ContextLengthExceeded`; Codex refuses the complete body first with
+`request exceeds maxVisualRequestBodyBytes`, which the Host maps to
+`attachment_too_large` and `InvalidAttachment`.
+
+| Grok/V2 check | Result | Host classification | Attempt effect |
+|---|---|---|---|
+| Local non-image share is over 8 MiB | Contract `limit`/`size`, `outside image data` | `request_limit_exceeded`, `ContextLengthExceeded` | No HTTP request, no authorize call, and no attempt |
+| Local non-image share passes, whole request is over 35 MiB | Contract `maxVisualRequestBodyBytes` | `attachment_too_large`, `InvalidAttachment` | No authorize call and no attempt |
+| Host authorize wrapper is over 35 MiB | Local `payload_too_large` | `ContextLengthExceeded` | The fetch is never emitted |
+| control-api raw or service-wrapper size is over 35 MiB | HTTP 413 `payload_too_large` | `ContextLengthExceeded` | Refused before the transaction |
+| Request plus wrapper fits, but exact proxy envelope with ticket and hash is over 35 MiB | HTTP 413 `payload_too_large` from `buildGrokProxyEnvelope` inside the transaction | `ContextLengthExceeded` | Signing happens first, then the new attempt, ticket, and new reservation roll back; none of those new records is persisted, while an existing Host-provided reservation remains |
+| Host post-authorize proxy-envelope defense refuses | Local `payload_too_large`, `dispatched: false` | `ContextLengthExceeded` | This is after authorize, so it must not be described as zero recorded attempts; the same-contract control-api check normally refuses first |
The value is a runtime limit, not a published fixture limit: the
`grok-llm-proxy/test/contractFreeze.test.ts` fixture describes the measured
@@ -892,9 +906,10 @@ that code. The retry is a new provider attempt with a new authorize, so a
redeemed ticket is never reused.
The client logs `grok_proxy_control_api_unreachable` with `path` only. The
-`grok_proxy_attempt_finished` line carries `causeCode` whenever the failure
-is a rejected `fetch`: the undici cause code, such as `ECONNREFUSED`, and
-nothing else from the error. When both finalize tries fail, the `err` of
+`grok_proxy_attempt_finished` line carries `causeCode` when a rejected undici
+`fetch` (for example `ECONNREFUSED`) or a failed `dns.lookup` wrapped by origin
+policy (for example `ENOTFOUND` or `EAI_AGAIN`) carries a code-shaped cause,
+and nothing else from the error. When both finalize tries fail, the `err` of
`grok_proxy_finalize_failed` carries it instead; the hop line never does.
## Feature flags
diff --git a/grok-llm-proxy/src/controlApiClient.ts b/grok-llm-proxy/src/controlApiClient.ts
index 4da035b72..0ae7252fb 100644
--- a/grok-llm-proxy/src/controlApiClient.ts
+++ b/grok-llm-proxy/src/controlApiClient.ts
@@ -65,8 +65,9 @@ const CONNECT_PHASE_CODES: ReadonlySet<string> = new Set([
'UND_ERR_CONNECT_TIMEOUT',
])
-// The code undici puts on a failed fetch's cause. Only a code-shaped string is
-// returned, so nothing else from the error can reach a log.
+// The code a rejected undici fetch puts on its cause, or origin policy puts on
+// a wrapped dns.lookup failure. Only a code-shaped string is returned, so
+// nothing else from the error can reach a log.
export function fetchCauseCode(err: unknown): string | undefined {
if (!(err instanceof Error)) return undefined
const cause: unknown = (err as { cause?: unknown }).cause
diff --git a/grok-llm-proxy/src/grokTransport.ts b/grok-llm-proxy/src/grokTransport.ts
index 3bd90882b..f4a81c540 100644
--- a/grok-llm-proxy/src/grokTransport.ts
+++ b/grok-llm-proxy/src/grokTransport.ts
@@ -83,11 +83,11 @@ export class GrokTransportError extends Error {
}
/**
- * Review R3-L1: a fetch that failed on the network is undici's TypeError, whose
- * cause message names the upstream address. It becomes a mapped transport error
- * that keeps only the cause code, so the attempt line logs `causeCode` and never
- * the error itself. An error with no code-shaped cause is returned undefined and
- * stays unmapped, which logs it as a handler defect.
+ * Review R3-L1/R4-L1: a rejected undici fetch and a failed dns.lookup wrapped
+ * by origin policy both carry a code-shaped cause. It becomes a mapped
+ * transport error that keeps only the cause code, so the attempt line logs
+ * `causeCode` and never the error itself. An error with no code-shaped cause
+ * is returned undefined and stays unmapped, which logs it as a handler defect.
*/
function upstreamFetchFailure(err: unknown): GrokTransportError | undefined {
const code = fetchCauseCode(err)
diff --git a/grok-llm-proxy/src/originPolicy.ts b/grok-llm-proxy/src/originPolicy.ts
index 9c6eb3cfc..24b3d5a9d 100644
--- a/grok-llm-proxy/src/originPolicy.ts
+++ b/grok-llm-proxy/src/originPolicy.ts
@@ -68,9 +68,10 @@ export async function assertResolvedUpstream(
} catch (err) {
// A failed lookup carries its system code (ENOTFOUND, EAI_AGAIN) on the
// error itself and names the host in its message. Only a code-shaped code
- // is kept, as the cause the transport maps to provider_unavailable.
+ // is kept, excluding Node programmer ERR_* codes, as the cause the
+ // transport maps to provider_unavailable.
const code: unknown = (err as { code?: unknown } | null)?.code
- if (typeof code === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/.test(code)) {
+ if (typeof code === 'string' && /^(?!ERR_)[A-Z][A-Z0-9_]{0,63}$/.test(code)) {
throw new Error('upstream address lookup failed', { cause: { code } })
}
throw err
diff --git a/grok-llm-proxy/test/originPolicy.test.ts b/grok-llm-proxy/test/originPolicy.test.ts
index f47e9b81e..a66f52096 100644
--- a/grok-llm-proxy/test/originPolicy.test.ts
+++ b/grok-llm-proxy/test/originPolicy.test.ts
@@ -143,9 +143,58 @@ describe('originPolicy', () => {
).resolves.toBeUndefined()
})
- // Review R4-L1: a failed lookup carries its system code on the error itself
- // and names the host in its message. Only a code-shaped code is kept, as
- // the cause the transport maps by code.
+ it('wraps operational lookup codes without the host name', async () => {
+ const { assertResolvedUpstream } = await import('../src/originPolicy.js')
+ const codes = [
+ 'ENOTFOUND',
+ 'EAI_AGAIN',
+ 'EAI_NONAME',
+ 'ECONNREFUSED',
+ 'ENETUNREACH',
+ 'EHOSTUNREACH',
+ ] as const
+ let lookups = 0
+ for (const code of codes) {
+ const lookupError = Object.assign(new Error(`lookup failed for ${code}.invalid`), { code })
+ const err: unknown = await assertResolvedUpstream(
+ new URL(GROK_COMPLETIONS_ORIGIN),
+ async () => {
+ lookups += 1
+ throw lookupError
+ }
+ ).then(
+ () => 'resolved',
+ (rejection: unknown) => rejection
+ )
+ expect(err).toBeInstanceOf(Error)
+ expect(err).not.toBeInstanceOf(OriginDeniedError)
+ expect((err as Error).message).toBe('upstream address lookup failed')
+ const cause = (err as { cause?: unknown }).cause as Record<string, unknown>
+ expect(cause).toEqual({ code })
+ expect(JSON.stringify({ message: (err as Error).message, cause })).not.toContain(
+ `${code}.invalid`
+ )
+ }
+ expect(lookups).toBe(codes.length)
+ })
+
+ it('rethrows a Node ERR_* lookup error as the same reference', async () => {
+ const { assertResolvedUpstream } = await import('../src/originPolicy.js')
+ const err = Object.assign(new Error('lookup argument is invalid'), {
+ code: 'ERR_INVALID_ARG_TYPE',
+ })
+ let lookups = 0
+ await expect(
+ assertResolvedUpstream(new URL(GROK_COMPLETIONS_ORIGIN), async () => {
+ lookups += 1
+ throw err
+ })
+ ).rejects.toBe(err)
+ expect(lookups).toBe(1)
+ })
+
+ // Review R4-L1: the real lookup depends on the resolver honoring .invalid
+ // NXDOMAIN. The deterministic twins above own the code semantics.
it('maps a failed lookup to its code without the host name', async () => {
const { assertResolvedUpstream } = await import('../src/originPolicy.js')
const host = 'grok-origin-policy-r4-l1.invalid'
@@ -168,7 +217,7 @@ describe('originPolicy', () => {
expect(Object.keys(cause)).toEqual(['code'])
expect(String(cause.code)).toMatch(/^(ENOTFOUND|EAI_AGAIN)$/)
expect(JSON.stringify({ message: (err as Error).message, cause })).not.toContain(host)
- })
+ }, 15_000)
it('rethrows a lookup error without a code-shaped code unchanged', async () => {
const { assertResolvedUpstream } = await import('../src/originPolicy.js')
diff --git a/grok-llm-proxy/test/server.security.test.ts b/grok-llm-proxy/test/server.security.test.ts
index 85873ace9..48ebb91a3 100644
--- a/grok-llm-proxy/test/server.security.test.ts
+++ b/grok-llm-proxy/test/server.security.test.ts
@@ -1551,6 +1551,7 @@ describe('grok-llm-proxy attempt telemetry', () => {
// Review R4-L1: a DNS failure carries its code on the lookup error itself,
// not in `cause`, and its message names the upstream host. The attempt line
// and both admin routes log it by cause code, with no err entry and no host.
+ // These real .invalid lookups depend on the resolver honoring NXDOMAIN.
const INVALID_UPSTREAM_HOST = 'grok-r4-l1.invalid'
function invalidHostLookup(calls: { count: number }) {
@@ -1596,7 +1597,7 @@ describe('grok-llm-proxy attempt telemetry', () => {
expect('err' in lines[0]!).toBe(false)
expect(serializeWithErrors(lines[0])).not.toContain(INVALID_UPSTREAM_HOST)
expectNoForbiddenKeys(lines[0]!)
- })
+ }, 15_000)
it('(r4-l1b) logs a catalog DNS lookup failure by cause code on both admin routes', async () => {
for (const [route, operation] of [
@@ -1642,7 +1643,7 @@ describe('grok-llm-proxy attempt telemetry', () => {
error.mockRestore()
}
}
- })
+ }, 15_000)
it('logs a mapped control-api failure without an err entry', async () => {
const { res, lines } = await run({
diff --git a/packages/grok-provider-attempt-contract/index.test.cjs b/packages/grok-provider-attempt-contract/index.test.cjs
index 11e70940a..84740238a 100644
--- a/packages/grok-provider-attempt-contract/index.test.cjs
+++ b/packages/grok-provider-attempt-contract/index.test.cjs
@@ -1084,9 +1084,10 @@ test('a V2 body over the visual ceiling because of repeated text gets the whole-
assert.equal(within.ok, true, within.message)
})
-// The non-image check runs before the whole-body check, so text past the
-// visual ceiling is reported as text, not as an attachment over budget. The
-// whole-body message stays reachable only through image data.
+// Grok checks the non-image share before the whole body. Text past the
+// non-image ceiling beside a small image is reported as text; repeated text
+// that stays within that shadow can still reach the whole-body message, as the
+// preceding test pins.
test('text past the visual ceiling beside one small image is refused outside image data', () => {
const text = 'x'.repeat(contract.LIMITS.maxVisualRequestBodyBytes)
const request = v2WithParts([imagePart(IMAGE_DATA.png), { type: 'text', text }], text)
@@ -1103,6 +1104,69 @@ test('text past the visual ceiling beside one small image is refused outside ima
)
})
+test('Grok reports sub-cap repeated text before the whole body while Codex reports the whole body', () => {
+ const png = realPngOfSize(1024, 16, 16, 3).toString('base64')
+ const text = 'x'.repeat(Math.floor(12.5 * MIB))
+ const request = v2WithParts([{ type: 'text', text }, imagePart(png)], text)
+
+ assert.deepEqual(contract.parseGrokCompletionRequest(request), {
+ ok: false,
+ code: 'limit',
+ kind: 'size',
+ message: 'request exceeds maxRequestBodyBytes outside image data',
+ })
+ assert.deepEqual(codexContract.parseCodexCompletionRequest(asCodex(request)), {
+ ok: false,
+ code: 'limit',
+ kind: 'size',
+ message: 'request exceeds maxVisualRequestBodyBytes',
+ })
+})
+
+test('the authorize wrapper can fit when the exact proxy envelope does not', () => {
+ const limit = contract.LIMITS.maxVisualRequestBodyBytes
+ const image = imagePart(declaredHeaderPngOfSize(16 * MIB).toString('base64'))
+ const requestFor = text => v2WithParts([{ type: 'text', text }, image], text)
+ const jsonBytes = value => Buffer.byteLength(JSON.stringify(value), 'utf8')
+ const authorizeWrapperFor = (request, requestHash = 'b'.repeat(64)) => ({
+ request,
+ invocationId: 'invocation-806-geometry',
+ attemptGeneration: 1,
+ providerAttemptIndex: 1,
+ policyRevision: 1,
+ policyHash: 'a'.repeat(64),
+ requestHash,
+ hostRef: 'research-host',
+ })
+ const wrapperOverhead = jsonBytes(authorizeWrapperFor(null)) - jsonBytes(null)
+ const emptyRequestBytes = jsonBytes(requestFor(''))
+ const textLength = Math.floor((limit - wrapperOverhead - 32 - emptyRequestBytes) / 2)
+ const request = requestFor('x'.repeat(textLength))
+ const parsed = contract.parseGrokCompletionRequest(request)
+ assert.equal(parsed.ok, true, parsed.message)
+ const requestHash = contract.hashGrokCompletionRequest(parsed.value)
+ const executionTicket = `header.${'a'.repeat(2048)}.sig`
+ const authorizeWrapper = authorizeWrapperFor(request, requestHash)
+ const exactEnvelope = {
+ executionTicket,
+ requestHash,
+ request: parsed.value,
+ }
+
+ assert.ok(jsonBytes(authorizeWrapper) <= limit - 32)
+ assert.ok(jsonBytes(exactEnvelope) > limit)
+ assert.deepEqual(contract.buildGrokProxyEnvelope(exactEnvelope), {
+ ok: false,
+ code: 'limit',
+ kind: 'size',
+ message: 'proxy envelope exceeds maxVisualRequestBodyBytes',
+ })
+ // This is contract geometry with the required AuthorizeAttemptBody fields and
+ // a deterministic representative ticket. The fixed 64-byte digest above only
+ // sizes the wrapper; the final wrapper uses the computed request hash. This
+ // does not claim real ticket issuance or prove PostgreSQL rollback itself.
+})
+
// Review R3-L3: a V2 user message carries its text twice, in `content` and in
// its text parts, and the parser requires their '\n' join to equal `content`.
// The non-image share counts that text once, as a V1 request would.
diff --git a/scripts/ci/assert-pinned-vitest-suites.mjs b/scripts/ci/assert-pinned-vitest-suites.mjs
index 5eb7de533..abd01cc99 100644
--- a/scripts/ci/assert-pinned-vitest-suites.mjs
+++ b/scripts/ci/assert-pinned-vitest-suites.mjs
@@ -7,7 +7,9 @@
// 4.1 even gives that file the status "passed", so the per-test statuses are
// the only signal.
//
-// Usage: node scripts/ci/assert-pinned-vitest-suites.mjs <report.json> <file name>...
+// Usage:
+// node scripts/ci/assert-pinned-vitest-suites.mjs <report.json> <file name>...
+// node scripts/ci/assert-pinned-vitest-suites.mjs --cases <report.json> <manifest.json>
import { readFileSync } from 'node:fs'
import { pathToFileURL } from 'node:url'
@@ -39,15 +41,91 @@ export function pinnedSuiteViolations(report, pinned) {
return violations
}
+function caseManifestPins(manifest) {
+ const violations = []
+ if (!Array.isArray(manifest) || manifest.length === 0) {
+ return { pins: [], violations: ['the case manifest is empty or not an array'] }
+ }
+
+ const pins = []
+ const seen = new Set()
+ for (const [index, entry] of manifest.entries()) {
+ if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+ violations.push(`case ${index}: entry must be an object`)
+ continue
+ }
+ const suite = entry.suite
+ const fullName = entry.fullName
+ if (typeof suite !== 'string' || suite.length === 0) {
+ violations.push(`case ${index}: suite must be a non-empty string`)
+ continue
+ }
+ if (typeof fullName !== 'string' || fullName.length === 0) {
+ violations.push(`case ${index}: fullName must be a non-empty string`)
+ continue
+ }
+ const identity = `${suite}\0${fullName}`
+ if (seen.has(identity)) {
+ violations.push(`case ${index}: duplicate pin ${suite} :: ${fullName}`)
+ continue
+ }
+ seen.add(identity)
+ pins.push({ suite, fullName })
+ }
+ return { pins, violations }
+}
+
+/** Returns one message per violation; an empty array means every pinned case ran. */
+export function pinnedCaseViolations(report, manifest) {
+ const { pins, violations } = caseManifestPins(manifest)
+ if (pins.length === 0) return violations
+ if (!Array.isArray(report?.testResults))
+ return [...violations, 'the report has no testResults array']
+
+ const suites = [...new Set(pins.map(pin => pin.suite))]
+ const suiteViolations = pinnedSuiteViolations(report, suites)
+ if (suiteViolations.length > 0) {
+ return [...violations, ...suiteViolations.map(violation => `${violation} [pinned cases]`)]
+ }
+
+ for (const pin of pins) {
+ const [file] = report.testResults.filter(
+ file => typeof file.name === 'string' && file.name.endsWith(`/${pin.suite}`)
+ )
+ const assertions = (file.assertionResults ?? []).filter(test => test.fullName === pin.fullName)
+ if (assertions.length !== 1) {
+ violations.push(
+ `${pin.suite} :: ${pin.fullName}: expected exactly 1 matching case, found ${assertions.length}`
+ )
+ }
+ }
+ return violations
+}
+
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
- const [reportPath, ...pinned] = process.argv.slice(2)
+ const arguments_ = process.argv.slice(2)
+ const caseMode = arguments_[0] === '--cases'
+ const [reportPath, ...pinned] = caseMode ? arguments_.slice(1) : arguments_
if (!reportPath) {
- console.error('usage: assert-pinned-vitest-suites.mjs <report.json> <file name>...')
+ console.error(
+ 'usage: assert-pinned-vitest-suites.mjs [--cases] <report.json> <file name... | manifest.json>'
+ )
process.exit(2)
}
const report = JSON.parse(readFileSync(reportPath, 'utf8'))
- const violations = pinnedSuiteViolations(report, pinned)
- for (const violation of violations) console.error(`pinned suite check: ${violation}`)
+ if (caseMode && pinned.length !== 1) {
+ console.error('case mode requires exactly one manifest path')
+ process.exit(2)
+ }
+ const violations = caseMode
+ ? pinnedCaseViolations(report, JSON.parse(readFileSync(pinned[0], 'utf8')))
+ : pinnedSuiteViolations(report, pinned)
+ const label = caseMode ? 'pinned case check' : 'pinned suite check'
+ for (const violation of violations) console.error(`${label}: ${violation}`)
if (violations.length > 0) process.exit(1)
- console.log(`pinned suite check: ${pinned.join(', ')} ran and passed`)
+ console.log(
+ caseMode
+ ? `pinned case check: ${pinned[0]} ran and passed`
+ : `pinned suite check: ${pinned.join(', ')} ran and passed`
+ )
}
diff --git a/scripts/ci/assert-pinned-vitest-suites.test.mjs b/scripts/ci/assert-pinned-vitest-suites.test.mjs
index b190d13a4..8ad0f99fc 100644
--- a/scripts/ci/assert-pinned-vitest-suites.test.mjs
+++ b/scripts/ci/assert-pinned-vitest-suites.test.mjs
@@ -5,10 +5,12 @@ import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { test } from 'node:test'
import { fileURLToPath } from 'node:url'
-import { pinnedSuiteViolations } from './assert-pinned-vitest-suites.mjs'
+import { pinnedCaseViolations, pinnedSuiteViolations } from './assert-pinned-vitest-suites.mjs'
const SCRIPT = fileURLToPath(new URL('./assert-pinned-vitest-suites.mjs', import.meta.url))
const PINNED = 'serve.agentRateLimit.test.ts'
+const CASE_SUITE = 'server.security.test.ts'
+const CASE_NAME = 'provider twin critical witness'
function file(name, statuses, status = 'passed') {
return {
@@ -21,6 +23,18 @@ function file(name, statuses, status = 'passed') {
}
}
+function caseFile(names, status = 'passed', fileStatus = 'passed') {
+ return {
+ name: `/work/provider/${CASE_SUITE}`,
+ status: fileStatus,
+ assertionResults: names.map((fullName, index) => ({
+ title: `case ${index}`,
+ fullName,
+ status,
+ })),
+ }
+}
+
test('accepts a pinned file whose every test passed', () => {
const report = { testResults: [file(PINNED, ['passed', 'passed']), file('other.test.ts', [])] }
assert.deepEqual(pinnedSuiteViolations(report, [PINNED]), [])
@@ -101,3 +115,135 @@ test('the CLI exits 0 on a clean report and 1 with a message on a skipped one',
rmSync(dir, { recursive: true, force: true })
}
})
+
+test('case pins reject a lost critical case that leaves the file checker green', () => {
+ const manifest = [
+ { suite: CASE_SUITE, fullName: CASE_NAME },
+ { suite: CASE_SUITE, fullName: 'other critical witness' },
+ ]
+ const report = { testResults: [caseFile(['other critical witness', 'unrelated test'])] }
+
+ assert.deepEqual(pinnedSuiteViolations(report, [CASE_SUITE]), [])
+ assert.deepEqual(pinnedCaseViolations(report, manifest), [
+ `${CASE_SUITE} :: ${CASE_NAME}: expected exactly 1 matching case, found 0`,
+ ])
+})
+
+test('case pins use the whole fullName and reject duplicates and non-passed cases', () => {
+ const manifest = [{ suite: CASE_SUITE, fullName: CASE_NAME }]
+ const renamed = {
+ testResults: [caseFile([`${CASE_NAME} with different behavior`])],
+ }
+ assert.deepEqual(pinnedCaseViolations(renamed, manifest), [
+ `${CASE_SUITE} :: ${CASE_NAME}: expected exactly 1 matching case, found 0`,
+ ])
+
+ const duplicate = { testResults: [caseFile([CASE_NAME, CASE_NAME])] }
+ assert.deepEqual(pinnedCaseViolations(duplicate, manifest), [
+ `${CASE_SUITE} :: ${CASE_NAME}: expected exactly 1 matching case, found 2`,
+ ])
+
+ const skipped = {
+ testResults: [
+ {
+ name: `/work/provider/${CASE_SUITE}`,
+ status: 'passed',
+ assertionResults: [
+ { fullName: CASE_NAME, status: 'skipped' },
+ { fullName: 'other', status: 'passed' },
+ ],
+ },
+ ],
+ }
+ assert.deepEqual(pinnedCaseViolations(skipped, manifest), [
+ `${CASE_SUITE}: 1 test(s) did not pass (skipped) [pinned cases]`,
+ ])
+
+ const failed = {
+ testResults: [
+ {
+ name: `/work/provider/${CASE_SUITE}`,
+ status: 'failed',
+ assertionResults: [
+ { fullName: CASE_NAME, status: 'failed' },
+ { fullName: 'other', status: 'passed' },
+ ],
+ },
+ ],
+ }
+ assert.deepEqual(pinnedCaseViolations(failed, manifest), [
+ `${CASE_SUITE}: file status is failed [pinned cases]`,
+ `${CASE_SUITE}: 1 test(s) did not pass (failed) [pinned cases]`,
+ ])
+})
+
+test('case pins reject malformed and duplicate manifests', () => {
+ assert.deepEqual(pinnedCaseViolations({ testResults: [] }, []), [
+ 'the case manifest is empty or not an array',
+ ])
+ assert.deepEqual(pinnedCaseViolations({ testResults: [] }, {}), [
+ 'the case manifest is empty or not an array',
+ ])
+
+ const invalidEntries = [null, { fullName: CASE_NAME }, { suite: CASE_SUITE }]
+ assert.deepEqual(pinnedCaseViolations({ testResults: [] }, invalidEntries), [
+ 'case 0: entry must be an object',
+ 'case 1: suite must be a non-empty string',
+ 'case 2: fullName must be a non-empty string',
+ ])
+
+ const duplicatePin = [
+ { suite: CASE_SUITE, fullName: CASE_NAME },
+ { suite: CASE_SUITE, fullName: CASE_NAME },
+ ]
+ const report = { testResults: [caseFile([CASE_NAME])] }
+ assert.deepEqual(pinnedCaseViolations(report, duplicatePin), [
+ `case 1: duplicate pin ${CASE_SUITE} :: ${CASE_NAME}`,
+ ])
+})
+
+test('case pins keep exact suite paths and reject reports without test results', () => {
+ const manifest = [{ suite: CASE_SUITE, fullName: CASE_NAME }]
+ const wrongPath = {
+ testResults: [
+ {
+ name: `/work/provider/x${CASE_SUITE}`,
+ status: 'passed',
+ assertionResults: [{ fullName: CASE_NAME, status: 'passed' }],
+ },
+ ],
+ }
+ assert.deepEqual(pinnedCaseViolations(wrongPath, manifest), [
+ `${CASE_SUITE}: expected exactly 1 file in the report, found 0 [pinned cases]`,
+ ])
+ assert.deepEqual(pinnedCaseViolations({}, manifest), ['the report has no testResults array'])
+})
+
+test('the case CLI exits 0 on a clean report and 1 when a critical case is missing', () => {
+ const dir = mkdtempSync(join(tmpdir(), 'pinned-cases-'))
+ try {
+ const reportPath = join(dir, 'report.json')
+ const manifestPath = join(dir, 'manifest.json')
+ const manifest = [{ suite: CASE_SUITE, fullName: CASE_NAME }]
+ writeFileSync(
+ reportPath,
+ JSON.stringify({ testResults: [caseFile([CASE_NAME, 'other test'])] })
+ )
+ writeFileSync(manifestPath, JSON.stringify(manifest))
+
+ const ok = spawnSync(process.execPath, [SCRIPT, '--cases', reportPath, manifestPath], {
+ encoding: 'utf8',
+ })
+ assert.equal(ok.status, 0, ok.stderr)
+ assert.match(ok.stdout, /pinned case check: .* ran and passed/)
+
+ writeFileSync(reportPath, JSON.stringify({ testResults: [caseFile(['other test'])] }))
+ const missing = spawnSync(process.execPath, [SCRIPT, '--cases', reportPath, manifestPath], {
+ encoding: 'utf8',
+ })
+ assert.equal(missing.status, 1)
+ assert.match(missing.stderr, /expected exactly 1 matching case, found 0/)
+ } finally {
+ rmSync(dir, { recursive: true, force: true })
+ }
+})
diff --git a/scripts/ci/pinned-vitest-cases/README.md b/scripts/ci/pinned-vitest-cases/README.md
new file mode 100644
index 000000000..f14147d48
--- /dev/null
+++ b/scripts/ci/pinned-vitest-cases/README.md
@@ -0,0 +1,13 @@
+# Pinned Vitest cases
+
+These manifests are used by `assert-pinned-vitest-suites.mjs --cases`. A pin names one Vitest suite
+by its exact file suffix and one assertion by its exact `fullName`. CI first applies the existing
+whole-file check, then requires every pinned case to appear exactly once and pass.
+
+The pins guard against merge resolutions that delete, rename, skip, or fail a critical case while
+leaving its suite green. An intentional test rename must update the reviewed pin in the same change.
+
+These are Vitest-only witnesses. Contract `node:test` suites, real-PostgreSQL lanes, and runtime
+validation have their own gates. A passing pinned case proves execution and status, not that the
+test's assertions or documentation remain meaningful; producer review and mutation evidence still
+own that claim.
diff --git a/scripts/ci/pinned-vitest-cases/codex-llm-proxy.json b/scripts/ci/pinned-vitest-cases/codex-llm-proxy.json
new file mode 100644
index 000000000..537ffcdf4
--- /dev/null
+++ b/scripts/ci/pinned-vitest-cases/codex-llm-proxy.json
@@ -0,0 +1,50 @@
+[
+ {
+ "suite": "originPolicy.test.ts",
+ "fullName": "originPolicy wraps operational lookup codes without the host name"
+ },
+ {
+ "suite": "originPolicy.test.ts",
+ "fullName": "originPolicy rethrows a Node ERR_* lookup error as the same reference"
+ },
+ {
+ "suite": "originPolicy.test.ts",
+ "fullName": "originPolicy maps a failed lookup to its code without the host name"
+ },
+ {
+ "suite": "server.security.test.ts",
+ "fullName": "codex-llm-proxy attempt telemetry (g1-1a) answers 429 rate_limited and forwards a valid upstream Retry-After"
+ },
+ {
+ "suite": "server.security.test.ts",
+ "fullName": "codex-llm-proxy attempt telemetry (g1-1b) answers 429 with no Retry-After header when the upstream value is invalid"
+ },
+ {
+ "suite": "server.security.test.ts",
+ "fullName": "codex-llm-proxy attempt telemetry (g1-3a) answers 422 upstream_rejected with the upstream status"
+ },
+ {
+ "suite": "server.security.test.ts",
+ "fullName": "codex-llm-proxy attempt telemetry (g1-3c) carries the upstream status on the SSE error frame after a keepalive"
+ },
+ {
+ "suite": "server.security.test.ts",
+ "fullName": "codex-llm-proxy attempt telemetry (g1-1d) delivers an upstream 429 after a keepalive as an SSE rate_limited frame"
+ },
+ {
+ "suite": "server.security.test.ts",
+ "fullName": "codex-llm-proxy attempt telemetry (g1-4a) answers 503 control_plane_unavailable when redeem cannot connect"
+ },
+ {
+ "suite": "server.security.test.ts",
+ "fullName": "codex-llm-proxy attempt telemetry (g1-5) passes a control_plane_unavailable redeem denial through as 503 with its own label"
+ },
+ {
+ "suite": "server.security.test.ts",
+ "fullName": "codex-llm-proxy attempt telemetry (r4-l1a) logs a DNS lookup failure by cause code, without err or host"
+ },
+ {
+ "suite": "server.security.test.ts",
+ "fullName": "codex-llm-proxy attempt telemetry (r4-l1b) logs a catalog DNS lookup failure by cause code on both admin routes"
+ }
+]
diff --git a/scripts/ci/pinned-vitest-cases/control-api.json b/scripts/ci/pinned-vitest-cases/control-api.json
new file mode 100644
index 000000000..bb6fc35c7
--- /dev/null
+++ b/scripts/ci/pinned-vitest-cases/control-api.json
@@ -0,0 +1,10 @@
+[
+ {
+ "suite": "helpers.realPostgresTeardown.test.ts",
+ "fullName": "endPoolAndWaitForClients ends a real pg Pool whose in-flight connect is refused"
+ },
+ {
+ "suite": "routes.mcp-host.llmProviderAttempts.test.ts",
+ "fullName": "authorize raw-body scan before JSON.parse preserves the module logger binding and request correlation on body refusals"
+ }
+]
diff --git a/scripts/ci/pinned-vitest-cases/grok-llm-proxy.json b/scripts/ci/pinned-vitest-cases/grok-llm-proxy.json
new file mode 100644
index 000000000..2ae82d744
--- /dev/null
+++ b/scripts/ci/pinned-vitest-cases/grok-llm-proxy.json
@@ -0,0 +1,54 @@
+[
+ {
+ "suite": "originPolicy.test.ts",
+ "fullName": "originPolicy wraps operational lookup codes without the host name"
+ },
+ {
+ "suite": "originPolicy.test.ts",
+ "fullName": "originPolicy rethrows a Node ERR_* lookup error as the same reference"
+ },
+ {
+ "suite": "originPolicy.test.ts",
+ "fullName": "originPolicy maps a failed lookup to its code without the host name"
+ },
+ {
+ "suite": "server.security.test.ts",
+ "fullName": "grok-llm-proxy security surface (g1-2) rate limits the completion endpoint with a JSON rate_limited body"
+ },
+ {
+ "suite": "server.security.test.ts",
+ "fullName": "grok-llm-proxy attempt telemetry (g1-1a) answers 429 rate_limited and forwards a valid upstream Retry-After"
+ },
+ {
+ "suite": "server.security.test.ts",
+ "fullName": "grok-llm-proxy attempt telemetry (g1-1b) answers 429 with no Retry-After header when the upstream value is invalid"
+ },
+ {
+ "suite": "server.security.test.ts",
+ "fullName": "grok-llm-proxy attempt telemetry (g1-3a) answers 422 upstream_rejected with the upstream status"
+ },
+ {
+ "suite": "server.security.test.ts",
+ "fullName": "grok-llm-proxy attempt telemetry (g1-3c) carries the upstream status on the SSE error frame after a keepalive"
+ },
+ {
+ "suite": "server.security.test.ts",
+ "fullName": "grok-llm-proxy attempt telemetry (g1-1d) delivers an upstream 429 after a keepalive as an SSE rate_limited frame"
+ },
+ {
+ "suite": "server.security.test.ts",
+ "fullName": "grok-llm-proxy attempt telemetry (g1-4a) answers 503 control_plane_unavailable when redeem cannot connect"
+ },
+ {
+ "suite": "server.security.test.ts",
+ "fullName": "grok-llm-proxy attempt telemetry (g1-5) passes a control_plane_unavailable redeem denial through as 503 with its own label"
+ },
+ {
+ "suite": "server.security.test.ts",
+ "fullName": "grok-llm-proxy attempt telemetry (r4-l1a) logs a DNS lookup failure by cause code, without err or host"
+ },
+ {
+ "suite": "server.security.test.ts",
+ "fullName": "grok-llm-proxy attempt telemetry (r4-l1b) logs a catalog DNS lookup failure by cause code on both admin routes"
+ }
+]