@cartanova/qgrid-cli 2.7.0 → 2.7.2

package/bundle/web-dist/server/entry-server.generated.js

@@ -1,6 +1,6 @@
-import { A as matchMutation, B as __require, C as infiniteQueryBehavior, D as functionalUpdate, E as notifyManager, F as skipToken, I as focusManager, L as Subscribable, M as noop$1, N as partialMatchKey, O as hashKey, P as resolveStaleTime, R as __commonJSMin, S as Mutation, T as onlineManager, V as __toESM, _ as useQuery, b as require_jsx_runtime, c as SD, d as _enum, f as number$1, j as matchQuery, k as hashQueryKeyByOptions, l as SUPPORTED_LOCALES, m as string$2, n as QgridService, p as object, u as setLocale, v as QueryClientProvider, w as Query, x as require_react, z as __exportAll } from "./assets/services.generated-D3Q3FYot.js";
-import { A as decodePath, C as findRouteMatch, D as createLRUCache, E as processRouteTree, F as last, I as replaceEqualDeep, M as findLast, N as functionalUpdate$1, O as invariant, P as isPromise, S as findFlatMatch, T as processRouteMasks, _ as interpolatePath, a as Link$1, b as trimPath, c as usePrevious$1, d as useRouter, f as getRouterContext, g as cleanPath, h as isNotFound, i as createRootRouteWithContext, j as deepEqual$2, k as createControlledPromise, l as matchContext, m as rootRouteId, n as createFileRoute, p as warning, r as createLazyFileRoute, s as useLayoutEffect$3, t as lazyRouteComponent, u as useRouterState, v as joinPaths, w as findSingleMatch, x as trimPathRight, y as resolvePath } from "./assets/lazyRouteComponent-DOc8TV-P.js";
-import { n as require_shim, t as require_react_dom } from "./assets/react-dom-BotjLnTK.js";
+import { A as hashQueryKeyByOptions, B as __exportAll, C as Mutation, D as notifyManager, E as onlineManager, F as resolveStaleTime, H as __toESM, I as skipToken, L as focusManager, M as matchQuery, N as noop$1, O as functionalUpdate, P as partialMatchKey, R as Subscribable, S as require_react, T as Query, V as __require, c as SD, d as _enum, f as boolean$1, h as string$2, j as matchMutation, k as hashKey, l as SUPPORTED_LOCALES, m as object, n as QgridService, p as number$1, u as setLocale, v as useQuery, w as infiniteQueryBehavior, x as require_jsx_runtime, y as QueryClientProvider, z as __commonJSMin } from "./assets/services.generated-DyPeBI00.js";
+import { A as decodePath, C as findRouteMatch, D as createLRUCache, E as processRouteTree, F as last, I as replaceEqualDeep, M as findLast, N as functionalUpdate$1, O as invariant, P as isPromise, S as findFlatMatch, T as processRouteMasks, _ as interpolatePath, a as Link$1, b as trimPath, c as usePrevious$1, d as useRouter, f as getRouterContext, g as cleanPath, h as isNotFound, i as createRootRouteWithContext, j as deepEqual$2, k as createControlledPromise, l as matchContext, m as rootRouteId, n as createFileRoute, p as warning, r as createLazyFileRoute, s as useLayoutEffect$3, t as lazyRouteComponent, u as useRouterState, v as joinPaths, w as findSingleMatch, x as trimPathRight, y as resolvePath } from "./assets/lazyRouteComponent-0y-znAfz.js";
+import { n as require_shim, t as require_react_dom } from "./assets/react-dom-zmEq8BVp.js";
 import minpath from "node:path";
 import minproc from "node:process";
 import { fileURLToPath as urlToPath } from "node:url";
@@ -46580,7 +46580,7 @@ function ChatWidget() {
 }
 //#endregion
 //#region src/components/Sidebar.tsx
-var qgridVersion = "2.7.0";
+var qgridVersion = "2.7.2";
 function Sidebar({ className }) {
 	const pathname = useRouterState({ select: (s) => s.location.pathname });
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("aside", {
@@ -68465,33 +68465,33 @@ function RootComponent() {
 }
 //#endregion
 //#region src/routes/tokens.tsx
-var $$splitComponentImporter$5 = () => import("./assets/tokens-c0EN3iCx.js");
+var $$splitComponentImporter$5 = () => import("./assets/tokens-BumM0gnH.js");
 var Route$5 = createFileRoute("/tokens")({ component: lazyRouteComponent($$splitComponentImporter$5, "component") });
 //#endregion
 //#region src/routes/settings.tsx
-var $$splitComponentImporter$4 = () => import("./assets/settings-DOQjV28c.js");
+var $$splitComponentImporter$4 = () => import("./assets/settings-D1u5WdpP.js");
 var Route$4 = createFileRoute("/settings")({ component: lazyRouteComponent($$splitComponentImporter$4, "component") });
 //#endregion
 //#region src/routes/monit.tsx
-var $$splitComponentImporter$3 = () => import("./assets/monit-BSaKhh5D.js");
+var $$splitComponentImporter$3 = () => import("./assets/monit-8WAsPETB.js");
 var monitSearchSchema = object({ level: _enum([
 	"all",
-	"scaling",
 	"warn",
 	"error"
-]).optional().default("all") });
+]).optional().default("all").catch(() => "all") });
 var Route$3 = createFileRoute("/monit")({
 	validateSearch: monitSearchSchema,
 	component: lazyRouteComponent($$splitComponentImporter$3, "component")
 });
 //#endregion
 //#region src/routes/logs.tsx
-var $$splitComponentImporter$2 = () => import("./assets/logs-CfF3nmLM.js");
+var $$splitComponentImporter$2 = () => import("./assets/logs-CJBbHM3_.js");
 var logsSearchSchema = object({
 	token: string$2().optional(),
 	project: string$2().optional(),
 	model: string$2().optional(),
 	sort: string$2().optional(),
+	broken: boolean$1().optional(),
 	page: number$1().optional().default(1)
 });
 var Route$2 = createFileRoute("/logs")({
@@ -68500,11 +68500,11 @@ var Route$2 = createFileRoute("/logs")({
 });
 //#endregion
 //#region src/routes/index.tsx
-var $$splitComponentImporter$1 = () => import("./assets/routes-CHMxrTT0.js");
+var $$splitComponentImporter$1 = () => import("./assets/routes-B6bX3o41.js");
 var Route$1 = createFileRoute("/")({ component: lazyRouteComponent($$splitComponentImporter$1, "component") });
 //#endregion
 //#region src/routes/requests/show.tsx
-var $$splitComponentImporter = () => import("./assets/show-Cn_C6Qvl.js");
+var $$splitComponentImporter = () => import("./assets/show-Cr7vwR0l.js");
 var showSearchSchema = object({ id: number$1() });
 var Route = createFileRoute("/requests/show")({
 	validateSearch: showSearchSchema,

package/dist/cli.d.ts

@@ -1 +1,10 @@
-export {}
+//#region src/cli.d.ts
+declare const RUNTIME_CLI_DEPENDENCIES: readonly [{
+  readonly command: "claude";
+  readonly packageName: "@anthropic-ai/claude-code";
+  readonly label: "Claude Code";
+  readonly missingReason: "Anthropic tokens require Claude Code.";
+}];
+declare function ensureLatestRuntimeCliDependencies(): void;
+//#endregion
+export { RUNTIME_CLI_DEPENDENCIES, ensureLatestRuntimeCliDependencies };

package/dist/cli.js

@@ -144,11 +144,6 @@ function resolveQgridRestartCommand(packageManager, globalBinDir) {
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
 const RUNTIME_CLI_DEPENDENCIES = [{
-	command: "codex",
-	packageName: "@openai/codex",
-	label: "Codex CLI",
-	missingReason: "OpenAI tokens require codex app-server."
-}, {
 	command: "claude",
 	packageName: "@anthropic-ai/claude-code",
 	label: "Claude Code",
@@ -326,4 +321,4 @@ program.name("qgrid").version(pkg.version).description("Qgrid — LLM subscripti
 });
 program.parse();
 //#endregion
-export {};
+export { RUNTIME_CLI_DEPENDENCIES, ensureLatestRuntimeCliDependencies };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartanova/qgrid-cli",
-  "version": "2.7.0",
+  "version": "2.7.2",
   "repository": {
     "type": "git",
     "url": "https://github.com/cartanova-ai/qgrid"
@@ -18,7 +18,6 @@
   "type": "module",
   "dependencies": {
     "@ai-sdk/anthropic": "^3.0.0",
-    "@ai-sdk/openai": "^3.0.0",
     "@ai-sdk/provider": "^3.0.0",
     "@ai-sdk/provider-utils": "^4.0.0",
     "@anthropic-ai/sdk": "^0.81.0",
@@ -42,11 +41,13 @@
     "radashi": "^12.2.0",
     "sonamu": "0.10.3",
     "typescript": "6.0.3",
+    "ws": "8.20.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/node": "25.0.7",
     "@types/pg": "^8.20.0",
+    "@types/ws": "8.18.1",
     "tsdown": "^0.22.3"
   },
   "engines": {

package/skills/qgrid/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qgrid
-description: Work on the qgrid repository, an LLM subscription-token proxy with OpenAI Codex app-server workers, Anthropic Claude Code fresh-spawn runtime, AI SDK provider compatibility, Sonamu API/web generation, token routing, prompt-cache behavior, request logging, quota thresholds, and dashboard flows. Use when implementing, debugging, reviewing, or planning qgrid code, docs, migrations, provider integrations, CLI/runtime behavior, request logs, or SDK behavior.
+description: Work on the qgrid repository, an LLM subscription-token proxy with direct OpenAI private-backend HTTPS/SSE transport, Anthropic Claude Code fresh-spawn runtime, AI SDK provider compatibility, Sonamu API/web generation, weighted token routing, prompt-cache behavior, request logging, quota thresholds, and dashboard flows. Use when implementing, debugging, reviewing, or planning qgrid code, docs, migrations, provider integrations, CLI/runtime behavior, request logs, or SDK behavior.
 ---
 
 # Qgrid
@@ -13,12 +13,12 @@ Before changing code, identify the affected path:
 
 - Public AI SDK provider: read `references/ai-sdk-provider-contract.md`.
 - CLI startup, env vars, server boot, OAuth callback URL: read `references/cli-env-and-server-boot.md`.
-- OpenAI models or Codex worker/thread/cache behavior: read `references/openai-codex-runtime.md`.
+- OpenAI direct transport, permits, routing, cache affinity, OAuth, or quota behavior: read `references/openai-codex-runtime.md`.
 - Anthropic models or Claude Code spawn/stream-json behavior: read `references/anthropic-claude-code-runtime.md`.
 - Token registration, OAuth, token sync, active/inactive behavior, quota thresholds, or weighted token routing: read `references/token-auth-quota-lifecycle.md`.
 - Provider comparisons, routing, or cross-provider bugs: read `references/provider-runtime-differences.md`.
 - Tool calling, AI SDK multi-step loops, or tool-call request logs: read `references/tool-calling-and-multiturn.md`.
-- `sessionKey`, `threadCoord`, prompt cache metrics, usage accounting, or cost: read `references/prompt-cache-and-usage.md`.
+- `sessionKey`, opaque affinity coordinates, prompt cache metrics, usage accounting, or cost: read `references/prompt-cache-and-usage.md`.
 - Design rationale, prior decisions, or "why is this feature shaped this way?": read `references/decision-rationale.md`.
 - Dashboard changes: read `references/sonamu-api-web-flow.md`.
 - Request log lifecycle, tool-call steps, telemetry/logger behavior: read `references/request-log-run-lifecycle.md`.
@@ -34,7 +34,7 @@ Prefer `QGRID_PROJECT_NAME` as the project-wide default. Use config `projectName
 
 When writing AI SDK examples or setup code, import the public `QgridProviderOptions` type and apply `satisfies QgridProviderOptions` to the value under `providerOptions.qgrid`. AI SDK types the outer `providerOptions` as a generic JSON record, so it cannot infer qgrid's option names and values by itself. `QgridProviderOptions` is the inner qgrid namespace type, not the outer record type.
 
-Request logging is enabled by default. Use `providerOptions.qgrid.logger: false` only for a call that must create zero qgrid request-log rows. The same option suppresses both qgrid's server-native logging and `createQgridLogger` telemetry logging for that generation; it does not disable generation, AI SDK tool execution, multi-step continuation, or provider thread coordination. The old `logMode` input has been removed and must not appear in setup code or raw qgrid payloads.
+Request logging is enabled by default. Use `providerOptions.qgrid.logger: false` only for a call that must create zero qgrid request-log rows. The same option suppresses both qgrid's server-native logging and `createQgridLogger` telemetry logging for that generation; it does not disable generation, AI SDK tool execution, multi-step continuation, or OpenAI cache affinity. The old `logMode` input has been removed and must not appear in setup code or raw qgrid payloads.
 
 ## Non-Negotiable Boundaries
 
@@ -59,4 +59,4 @@ Choose verification by blast radius:
 - AI SDK changes: run `packages/ai-sdk` tests and inspect generated request payload behavior.
 - Sonamu API/model changes: check generated files and both API and web consumers.
 
-Do not rely on one provider's behavior to infer the other provider's behavior. OpenAI/Codex and Anthropic/Claude Code have different process lifetimes, cache behavior, usage accounting, and structured-output paths.
+Do not rely on one provider's behavior to infer the other provider's behavior. OpenAI direct transport and Anthropic/Claude Code have different execution lifecycles, cache behavior, usage accounting, and structured-output paths.

package/skills/qgrid/references/ai-sdk-provider-contract.md

@@ -58,12 +58,12 @@ Do not write `providerOptions: { ... } satisfies QgridProviderOptions`: the expo
 `providerOptions.qgrid` supports:
 
 - `logger`: request-log switch. Omitted or `true` is the default and enables qgrid logging; `false` guarantees that generation creates zero qgrid request-log rows.
-- `sessionKey`: OpenAI thread reuse key. Disabled for Anthropic models.
+- `sessionKey`: source for model-scoped opaque OpenAI prompt-cache affinity. Disabled for Anthropic models.
 - `effort`
 - `verbosity`: OpenAI/Codex route only.
 - `reasoningSummary`: OpenAI/Codex route only.
 - `serviceTier`: OpenAI/Codex route only.
-- `timeoutMs`: Anthropic server-side Claude Code process timeout in milliseconds. It must be a positive integer no greater than 30 minutes and defaults to 240 seconds.
+- `timeoutMs`: Anthropic server-side Claude Code process timeout in milliseconds. It must be a positive integer no greater than 30 minutes and defaults to 240 seconds. For non-stream `generateText`, the SDK derives request-scoped Undici `headersTimeout` and `bodyTimeout` values as `timeoutMs + 60_000` without changing the process-global dispatcher.
 - `fallbackModels`: reserved for future qgrid server-side fallback routing. It is not the Fable 5 safety-refusal fallback, which is owned by Claude Code upstream.
 - `imageGeneration`: OpenAI/Codex non-stream only. Enables Codex's built-in `image_generation` tool for that request.
 - `imageGenerationOptions`: optional image quality/size hints and cost-estimation basis. Current supported values are `quality: "low" | "medium" | "high"` and `size: "1024x1024" | "1024x1536" | "1536x1024"`.
@@ -73,9 +73,15 @@ Do not write `providerOptions: { ... } satisfies QgridProviderOptions`: the expo
 AI SDK's standard top-level `timeout` is still the overall client-side budget. AI SDK converts it
 to the `abortSignal` in `LanguageModelV3CallOptions`, so a custom provider cannot recover the
 original numeric duration. Do not infer or duplicate that timeout. Use
-`providerOptions.qgrid.timeoutMs` only for the server-side Claude Code limit, and recommend setting
-the AI SDK timeout high enough to include network and server overhead. Client cancellation and
-non-streaming HTTP disconnects propagate separately through `AbortSignal`.
+`providerOptions.qgrid.timeoutMs` for the server-side Claude Code limit. The SDK also uses that
+explicit value to keep its own non-stream HTTP transport budget 60 seconds above the server
+limit; this prevents Undici's 300-second default from cutting off long Anthropic requests first.
+Recommend setting the AI SDK timeout high enough to include network and server overhead. Client
+cancellation and non-streaming HTTP disconnects propagate separately through `AbortSignal`.
+
+Transport failures preserve their root category in the public error message. In particular,
+`UND_ERR_HEADERS_TIMEOUT` reports the effective transport budget and `ECONNREFUSED` reports a
+connection refusal instead of leaving both as an undifferentiated `fetch failed`.
 
 ## Request logging
 
@@ -93,7 +99,7 @@ const result = await generateText({
 });
 ```
 
-`logger: false` affects observability only. Generation, streaming, AI SDK client tool execution, multi-step continuation, and OpenAI thread coordination continue normally. When `createQgridLogger` is also installed, it reads the same option and suppresses its external-provider telemetry lifecycle for that generation; qgrid provider calls are always skipped by the telemetry integration to prevent double logging.
+`logger: false` affects observability only. Generation, streaming, AI SDK client tool execution, multi-step continuation, and OpenAI cache affinity continue normally. When `createQgridLogger` is also installed, it reads the same option and suppresses its external-provider telemetry lifecycle for that generation; qgrid provider calls are always skipped by the telemetry integration to prevent double logging.
 
 For raw qgrid query/stream payloads, the corresponding input is top-level `logger?: boolean`, also defaulting to `true`. The old `logMode` input has been removed. Because the wire schema accepts unknown keys, a legacy payload containing `logMode` is accepted but the field is ignored. It must not appear in new code. Migrate callers as follows:
 
@@ -103,7 +109,7 @@ For raw qgrid query/stream payloads, the corresponding input is top-level `logge
 
 ## OpenAI/Codex Fast mode
 
-qgrid supports Codex Fast mode per request through `providerOptions.qgrid.serviceTier`. Pass `"fast"`; qgrid forwards it through the OpenAI route to Codex `turn/start`, and Codex normalizes the legacy `fast` value to the upstream `priority` service tier.
+qgrid supports Codex Fast mode per request through `providerOptions.qgrid.serviceTier`. Pass `"fast"`; qgrid forwards it as `service_tier: "priority"` in the direct OpenAI Responses request.
 
 ```ts
 const result = await generateText({
@@ -123,7 +129,7 @@ Fast mode contract:
 - It works on both `generateText` and `streamText`; image generation remains non-stream for unrelated reasons.
 - Omit `serviceTier` for normal/default routing. qgrid's current API accepts `"fast"` and `"flex"`; callers should not send Codex's normalized `"priority"` value directly.
 - qgrid is a pass-through for this selection. Codex applies the tier only when its Fast mode feature is enabled and the selected model advertises support; otherwise Codex can omit the unsupported tier.
-- Fast mode changes upstream service-tier routing, not qgrid worker capacity. It does not change WPT, client concurrency, queue behavior, or worker autoscaling.
+- Fast mode changes upstream service-tier routing only. It does not change token weights or client concurrency.
 - Do not promise a fixed latency improvement. Verify TTFT, duration, throughput, and quota consumption with a workload-specific A/B test.
 
 ## Request construction
@@ -140,14 +146,17 @@ Payload responsibilities:
 - Send `logger: false` when the per-call option disables request logging; otherwise rely on the server default.
 - Preserve and resend `runContext` for tool-call follow-ups.
 - Let the server infer single-turn completion versus an open tool-call run. Logging-disabled tool calls still use the SDK's local pending-call correlation and continue without a request-log id.
-- Store/resend OpenAI `threadCoord` by `sessionKey`.
+- Derive/store/resend opaque OpenAI affinity coordinates by `sessionKey`.
 - Send `imageGeneration` and `imageGenerationOptions` when configured.
 - Send AI SDK multimodal image/file message parts as qgrid `input` only when `imageGeneration` is enabled. Normal non-image-generation calls keep `user_prompt` text-only and do not forward image input.
 - Reject oversized reference-image data URLs before the request leaves the SDK. Reference images travel as JSON data URLs; callers should compress/resize large photos, preferably to WebP/JPEG.
 
-Tools and `jsonSchema` can be used together as of qgrid 2.5.4. The server composes
-them into one strict action envelope for every provider turn. `toolChoice` is not
-part of the current qgrid wire contract and must not be described as supported.
+Tools and `jsonSchema` can be used together as of qgrid 2.5.4. On OpenAI the
+server composes them into one strict action envelope enforced by constrained
+decoding; on Anthropic (SON-532) the same envelope contract is rendered as text
+at the end of the system prompt and the reply is validated by `parseEnvelope`.
+`toolChoice` is not part of the current qgrid wire contract and must not be
+described as supported.
 
 Before provider dispatch, qgrid validates caller output schemas and every tool
 input schema with an iterative preflight. Output/tool schema serialization, tool
@@ -155,24 +164,26 @@ names, descriptions, JSON escaping, and composition framing share an aggregate
 512 KiB UTF-8 budget. Schema JSON values are limited to 20,000 in aggregate, and
 each schema is limited to depth 128. Malformed, unsupported top-level output, or
 over-budget schemas fail with HTTP 400 before request-log creation or stream ID
-allocation. The fully composed and strictified schema is checked again against
-the 512 KiB budget. Anthropic routes additionally enforce a 64 KiB UTF-8 ceiling
-because Claude Code receives that schema as one `--json-schema` argv value.
+allocation. On OpenAI the fully composed and strictified schema is checked again
+against the 512 KiB budget. Anthropic performs only this syntax/complexity
+preflight — no strictify, no argv ceiling (the old 64 KiB `--json-schema` limit
+is gone; large schema contracts ride the system-prompt file branch).
 
 OpenAI normalizes positional tuple schemas in supported positive schema
 positions and enforces their positional constraints. Tuples in negative,
 conditional, or otherwise non-normalizable schema positions fail with HTTP 400
 instead of being rewritten with changed semantics. References from those
 positions fail for the same reason because definitions are normalized globally.
-Anthropic positional tuple schemas fail with HTTP 400 because Claude Code cannot
-preserve positional semantics. Tuple nodes must explicitly declare
-`type: "array"`; express nullable tuples with an `anyOf` array/null branch.
-
-Structured schemas accept only local root-relative JSON Pointer `$ref` values
-targeting the document root or a chain of `$defs`/`definitions` entry roots.
-References into properties, tuple internals, conditionals, or literal values
-fail with HTTP 400 because normalization can move or rewrite those targets.
-Resource IDs, anchors, external refs, dynamic refs, and recursive refs are also
+Tuple nodes must explicitly declare `type: "array"`; express nullable tuples
+with an `anyOf` array/null branch. These normalization restrictions are
+OpenAI-only: the Anthropic route injects the schema verbatim as prompt text, so
+positional tuples and arbitrary `$ref` forms pass through unchanged.
+
+On OpenAI, structured schemas accept only local root-relative JSON Pointer
+`$ref` values targeting the document root or a chain of `$defs`/`definitions`
+entry roots. References into properties, tuple internals, conditionals, or
+literal values fail with HTTP 400 because normalization can move or rewrite
+those targets. Resource IDs, anchors, external refs, dynamic refs, and recursive refs are also
 rejected.
 
 When tools are present, qgrid sends tool definitions to the server as `tools`; it does not send them to OpenAI or Anthropic as native provider tools. The server converts them into a strict structured-output schema and maps the model's structured result back into AI SDK `tool-call` content.
@@ -216,7 +227,7 @@ Usage maps qgrid standard usage into AI SDK V3 usage:
 
 ## Anthropic sessionKey guard
 
-Do not store or replay `sessionKey` thread coordinates for `anthropic/*` models. Tests cover this because Anthropic fresh-spawn runtime cannot safely use Codex-style thread reuse.
+Do not store or replay `sessionKey` affinity coordinates for `anthropic/*` models. Anthropic fresh-spawn runtime uses its own prefix-cache behavior.
 
 ## Logger integration
 

package/skills/qgrid/references/anthropic-claude-code-runtime.md

@@ -61,7 +61,7 @@ Refresh is attempted through `QgridFrame.refreshToken` with provider set to `ant
 ```text
 claude -p
   --tools ""
-  --allowed-tools StructuredOutput        # only when jsonSchema exists
+  --allowed-tools StructuredOutput        # legacy structured path only — unused since SON-532
   --disallowedTools Monitor PushNotification RemoteTrigger
   --input-format stream-json
   --output-format stream-json
@@ -76,18 +76,22 @@ claude -p
   --effort <effort-or-low>
   --disable-slash-commands
   --session-id <uuid>
-  --json-schema <schema>                  # only when jsonSchema exists
+  --json-schema <schema>                  # legacy structured path only — unused since SON-532
 ```
 
 Important details:
 
-- `--tools ""` blocks normal tools. With structured output, only `StructuredOutput` is allowed.
+- `--tools ""` blocks normal tools on every call.
+- **qgrid no longer passes `--json-schema` (SON-532).** Schema and tool-envelope contracts are
+  rendered as text (`schema-prompt.ts`) and appended to the system prompt; CC runs in plain text
+  mode, qgrid strips code fences (`fence-strip.ts`), and validation belongs to the consumer's zod
+  and qgrid's `parseEnvelope`. The `buildClaudeArgs` structured branch remains in code but is
+  unreachable from qgrid dispatch.
 - `--setting-sources project` plus seeded settings isolates user configuration.
 - `--system-prompt` or `--system-prompt-file` is always supplied. Omitting it would allow Claude Code default system prompt injection.
-- Large system prompts over 64 KiB are written to a temporary file to avoid argv `E2BIG`.
-- Final structured-output schemas are limited to 64 KiB UTF-8 because Claude Code receives each
-  schema as one `--json-schema` argv value. qgrid applies this check before request-log or stream
-  allocation and repeats it at dispatcher/session boundaries.
+- Large system prompts over 64 KiB are written to a temporary file to avoid argv `E2BIG` — this
+  same branch absorbs large injected schema contracts, so the old 64 KiB schema argv limit no
+  longer applies (only the global 512 KiB caller-schema complexity limit remains).
 - `--thinking disabled`, `MAX_THINKING_TOKENS=0`, and adaptive thinking env suppression keep thinking off for existing models. Fable 5 requires always-on adaptive thinking. Opus 5 defaults to adaptive thinking and rejects disabled thinking at `xhigh`/`max` effort. qgrid omits all three suppressors for both models and uses `effort` to control depth.
 
 ## Spawn env
@@ -209,13 +213,26 @@ Upstream references:
 
 ## Structured output
 
-qgrid strictifies schemas before provider dispatch. Claude Code `--json-schema` is not grammar-constrained decoding; it is a `StructuredOutput` tool plus post-validation behavior. Keep schemas strict and preserve error signaling for failed structured-output attempts.
-
-`MAX_STRUCTURED_OUTPUT_RETRIES` defaults to `1` and is clamped to at least 1. Avoid setting it to 0; Claude Code can fail before emitting a useful attempt.
-
-qgrid pins this env var only when the call is **structured and streaming**. The pin exists because a retry inside a stream doubles wall-clock time (SON-495); that reasoning does not apply to non-streaming `generate`, which already waits for completion. Streaming is detected via `includePartialMessages`, which only `generateStream` sets.
-
-Non-streaming structured calls therefore keep Claude Code's default retry budget. This matters because Claude models comply with structured output less reliably than OpenAI models: pinning retries to 1 turns a single rejected attempt into an immediate `error_max_structured_output_retries`. Measured on dev0 before the fix, `deti_production` on Opus 4.8 failed 39.6% of non-streaming structured calls for this reason.
+**Since SON-532 the anthropic route delivers schemas by prompt, not by `--json-schema`.** The
+consumer's original schema (no strictify — nullish/optional intent preserved) is rendered as text
+and appended to the system prompt; anthropic is cold-only, so every multi-turn step re-sends the
+contract. Responses are plain text: qgrid strips fences and trims, and validation is the
+consumer's zod (user schema) or qgrid's `parseEnvelope` (tool envelope). Prose or degenerate
+output fails honestly — retry is the caller's decision.
+
+Why: CC's `--json-schema` is not grammar-constrained decoding — it is a `StructuredOutput` tool
+plus post-hoc AJV scoring with an internal retry loop that cannot be disabled. The strictified
+scoring schema contradicted consumer intent (nullish frozen into required), so the model's
+correct-per-instructions output was rejected and retried invisibly: deti transcripts showed 2–4
+round trips per call, 216–512 s latency, and 4.7–9.1× billed output tokens, all collapsed into
+one request-log row. OpenAI keeps the strictified schema because constrained decoding actually
+enforces it there.
+
+Legacy notes (structured path, unreachable from qgrid dispatch but still in `claude-session.ts`):
+`MAX_STRUCTURED_OUTPUT_RETRIES` was pinned to 1 only for structured **streaming** calls (SON-495 —
+a retry inside a stream doubles wall-clock); non-streaming kept CC's default budget because
+pinning it caused 39.6% failures on `deti_production` Opus 4.8. Compliance measurement for the
+prompt path lives in `scripts/schema-delivery-bench.ts`.
 
 When a non-streaming retry succeeds, the result event's `structured_output` is the canonical
 schema-validated value. Do not let a previously captured assistant tool input override it. Preserve

package/skills/qgrid/references/cli-env-and-server-boot.md

@@ -64,14 +64,8 @@ When helping a user set up qgrid locally, check for `QGRID_PROJECT_NAME` or conf
 
 | Env | Default | Meaning |
 |---|---:|---|
-| `QGRID_OPENAI_AUTOSCALE` | enabled | Set to `"false"` or `"0"` to disable demand expansion and scale-down, keeping capacity fixed at the minimum. Fixed-mode health maintenance still replaces missing or terminal workers. |
-| `QGRID_OPENAI_MIN_WORKERS_PER_TOKEN` | `1` | Steady-state minimum worker slots maintained for each active OpenAI token. Transient restarts keep their slot; terminal or missing slots are replaced. Clamped to 1..20. |
-| `QGRID_OPENAI_MAX_WORKERS_PER_TOKEN` | `3` when autoscaling | Maximum workers per active OpenAI token. It cannot be lower than the resolved minimum and is hard-capped at 20. When autoscaling is disabled, the maximum equals the minimum. |
-| `QGRID_OPENAI_SCALE_INTERVAL_MS` | `5000` | OpenAI pool health, idle-thread cleanup, and demand autoscaling evaluation interval. Clamped to 250..300000 ms. |
-| `QGRID_OPENAI_SCALE_DOWN_IDLE_MS` | `600000` | Idle time before an excess worker becomes eligible for scale-down. Clamped to 1000 ms..24 hours. |
-| `QGRID_OPENAI_MAX_ESTIMATED_RSS_GIB` | `16` | Refuse scale-up when estimated qgrid worker RSS would exceed this value. Estimate: `0.71 + 0.157 * totalWorkerCount` GiB. Clamped to 1..32 GiB; the upper bound is an operator-typo guard, not an OOM-safety guarantee. |
-| `QGRID_OPENAI_MIN_HOST_AVAILABLE_GIB` | `20` | Refuse scale-up when current host available memory is below this value. Clamped to 0..64 GiB. |
-| `QGRID_OPENAI_THREAD_REUSE` | enabled | Set to `"false"` to disable OpenAI thread reuse and force cold thread behavior. |
+| `QGRID_OPENAI_TRANSPORT` | `websocket` | OpenAI transport selector (`https` or `websocket`). Invalid values fail at dispatcher configuration time. This is the only OpenAI runtime knob; there is no concurrency cap. |
+| `QGRID_OPENAI_AUTOSCALE` / `QGRID_OPENAI_MIN_WORKERS_PER_TOKEN` / `QGRID_OPENAI_MAX_WORKERS_PER_TOKEN` / `QGRID_OPENAI_PERMITS_PER_TOKEN` | ignored | Removed. OpenAI requests run uncapped like Anthropic (stateless per-request execution); setting these has no effect. |
 | `MAX_STRUCTURED_OUTPUT_RETRIES` | `1` for structured Anthropic streaming calls | Claude Code structured-output retry count for streaming only, clamped to at least 1 by qgrid. Non-streaming `generate` leaves the variable unset and uses Claude Code's default retry budget. |
 
 ## Server boot lifecycle
@@ -90,11 +84,10 @@ On shutdown, it stops provider dispatchers and the token subscriber.
 
 ### Runtime settings
 
-Some env values are editable at runtime through the dashboard's Settings page, backed by the `settings` table (key-value). Resolution order is DB → env → code default: env stays as a fallback so a deploy that has not written any setting yet keeps working exactly as before. `loadSettings()` runs in `onStart` before the dispatchers are constructed, since the OpenAI pool reads its worker counts in its constructor.
+Some env values are editable at runtime through the dashboard's Settings page, backed by the `settings` table (key-value). Resolution order is DB → env → code default: env stays as a fallback so a deploy that has not written any setting yet keeps working exactly as before.
 
-- Editable: OpenAI autoscale and min/max workers per token, the worker memory guards, Slack delivery control (master switch, reminder on/off, reminder interval, quiet-hours window, weekend behaviour), and the Slack channel/user-map/bot-token. `SETTING_DEFS` in `setting.constant.ts` is the single definition — key, env name, type, bounds, and whether the change applies immediately or needs a restart. The `settings` table itself (`setting.entity.json`) only stores `(key, value)` strings; everything the UI needs to render and validate a key lives in that constant, not in the schema.
+- Editable: Slack delivery control (master switch, reminder on/off, reminder interval, quiet-hours window, weekend behaviour), and the Slack channel/user-map/bot-token. `SETTING_DEFS` in `setting.constant.ts` is the single definition — key, env name, type, bounds, and whether the change applies immediately or needs a restart. The `settings` table itself (`setting.entity.json`) only stores `(key, value)` strings; everything the UI needs to render and validate a key lives in that constant, not in the schema.
 - Not editable: anything needed before the server can read its own database (`QGRID_DB_*`, `HOST`, `PORT`, `NODE_ENV`). These are exposed read-only on the same page so an operator can confirm which environment they are looking at; the DB password is masked.
-- Worker settings are marked `restart` because `resolveOpenAIWorkerPoolConfig` is called once in the dispatcher constructor. Changing them writes to the DB but does not resize a running pool. `POST /api/setting/restartServer` is how those land without an SSH session.
 
 ### Restart from the dashboard
 
@@ -136,7 +129,7 @@ This allowlist preserves anonymous inference and logger database writes for SDK
 
 ### Readiness during startup
 
-HTTP listening opens before the dispatchers finish starting, so requests can arrive while a provider is still unavailable. On dev0 that window is 1–2 minutes: 25 OpenAI workers spawn at `SPAWN_INTERVAL_MS` apart, plus codex process init.
+HTTP listening opens before the dispatchers finish starting, so requests can arrive while a provider is still unavailable. OpenAI startup loads token metadata and creates no Codex child processes.
 
 - `QgridDispatcher.startupState` tracks each provider as `starting` → `ready` or `failed`. A request for an unready provider throws `ServiceUnavailableException` (503, with a `Retry-After` header) while starting, and `InternalServerErrorException` (500) once initialization has failed — retrying helps in the first case and never in the second. Both used to be `QuotaError`, which told callers their tokens were exhausted and gave them nothing to act on.
 - `GET /api/qgrid/health` reports `ready` plus per-provider state. A 200 alone does not mean requests will succeed; read `providers` for that.
@@ -145,4 +138,4 @@ HTTP listening opens before the dispatchers finish starting, so requests can arr
 ## OAuth callbacks
 
 - Anthropic OAuth: loopback dashboards use `/callback` on the qgrid server (base derived per request from `Origin`, falling back to `X-Forwarded-Host`/`Host`). Remote dashboards cannot use a public callback (client redirect-URI allowlist), so `oauthStart` returns `mode: "code"` with the console callback and the user pastes the shown `code#state` into the dashboard (`oauthComplete`). No env configuration either way; direct non-HTTP calls fall back to localhost and `PORT`.
-- OpenAI OAuth is handled by Codex app-server's own callback flow and completed through qgrid's OpenAI OAuth APIs.
+- OpenAI OAuth uses qgrid's direct PKCE authorize/callback flow and direct token exchange.

package/skills/qgrid/references/decision-rationale.md

@@ -30,7 +30,7 @@ Key decisions:
 - qgrid's AI SDK provider follows the AI SDK `LanguageModelV3` contract. Generic usage belongs to AI SDK docs; qgrid-specific docs should focus on qgrid routing, logging, cache/session behavior, and `providerOptions.qgrid`.
 - qgrid-specific options live under `providerOptions.qgrid`, not under provider-specific namespaces such as `providerOptions.openai`. Consumers should not need to branch on Codex versus Claude internals.
 - AI SDK exposes the outer `providerOptions` as a generic JSON record. `QgridProviderOptions` intentionally types the nested `providerOptions.qgrid` value, and examples should apply `satisfies` there to restore qgrid-specific inference without replacing AI SDK's outer contract.
-- AI SDK's standard `timeout` owns the client-side total budget and reaches custom providers only as an `AbortSignal`. `providerOptions.qgrid.timeoutMs` separately owns the Anthropic server-side Claude process timer; keeping the two explicit avoids pretending the original AI SDK timeout number is available inside qgrid.
+- AI SDK's standard `timeout` owns the client-side total budget and reaches custom providers only as an `AbortSignal`. `providerOptions.qgrid.timeoutMs` separately owns the Anthropic server-side Claude process timer. For non-stream calls, the qgrid SDK may derive its own request-scoped Undici header/body budget from that explicit qgrid value (`timeoutMs + 60s`), but must not mutate the global dispatcher or pretend the original AI SDK timeout number is available.
 - `projectName` is provider config/payload camelCase. `project_name` is the Sonamu/database request-log column. Prefer `QGRID_PROJECT_NAME` as the project-wide default so request logs and metrics remain filterable at volume.
 - `fallbackModels` may exist as a typed future option, but it is not a server wire contract until the server implements fallback routing. Do not forward it as behavior just because the type exists.
 - Fable 5 refusal fallback is an upstream Claude Code safety path to Opus 4.8, not qgrid's reserved `fallbackModels` feature or Claude Code's overload-only `--fallback-model` flag. qgrid observes and reports the actual route and provider cost; it must not retry again.
@@ -74,26 +74,18 @@ Key decisions:
   behavior, never to leaked envelope text. See
   `references/tool-calling-and-multiturn.md` (Streaming With Tools).
 
-## OpenAI/Codex Runtime
-
-Sources:
-
-- `docs/plans/2026-05-18-feat-codex-app-server-backend-pivot-plan.md`
-- `docs/plans/2026-05-30-feat-codex-builtin-tool-suppression-plan.md`
-- `docs/plans/2026-06-06-feat-codex-thread-reuse-prompt-cache-plan.md`
-- `docs/solutions/logic-errors/qgrid-prompt-cache-hit-rate-metric-miscalculation.md`
+## OpenAI Direct Codex Runtime
 
 Key decisions:
 
-- OpenAI uses Codex `app-server` directly over stdio, not `codex exec`. The app-server path gives qgrid OAuth login, persistent workers, and thread handles.
-- Workers are persistent and token-scoped. qgrid can spawn multiple workers per token, but each worker is single-flight for turns. This differs from Anthropic, which fresh-spawns per request.
-- qgrid unsets normal OpenAI API-key paths and logs in with ChatGPT/OAuth credentials. This keeps the runtime aligned with subscription-token pooling rather than API billing.
-- Built-in Codex tools, apps, skills, web search, shell, and large instruction blocks are suppressed. The primary reason is tool-call correctness: Codex built-ins can steal calls that qgrid expects to represent as emulated AI SDK tool calls. Token savings are secondary.
-- Thread reuse exists because Codex/OpenAI prompt cache keys are tied to the Codex conversation/thread. New `thread/start` calls miss cache even with identical prefixes.
-- Reuse must be explicit through a server-issued coordinate such as `threadCoord`. Do not use content hashes or hidden closures; same-looking prompts from different sessions can cross-contaminate.
-- Reuse fallback should be cold and correct. Invalid worker id, epoch mismatch, missing thread, busy worker timeout, or over-threshold token should not corrupt a conversation.
-- Cache and usage metrics use per-turn usage. For Codex, `tokenUsage.total` is conversation cumulative; request logs must use `tokenUsage.last`.
-- OpenAI/Codex cached tokens are included in `input_tokens`. Cache-hit denominator is `input_tokens`, not `input + cache_read + cache_creation`.
+- OpenAI uses direct HTTPS `POST` to the private ChatGPT Codex Responses backend and decodes SSE. It does not spawn Codex child processes.
+- Direct PKCE OAuth, refresh, and `wham/usage` quota lookup replace delegated runtime calls. Generation and quota requests send Codex CLI identity headers.
+- Requests run uncapped, matching the Anthropic runtime: transport is a single HTTPS/WS request, so no local resource justifies a cap, and upstream limits are the backend's responses. The worker-era permit/queue layer was removed once this became clear.
+- Every turn sends full Responses-format history. A model-scoped opaque value derived from `sessionKey` is forwarded as `prompt_cache_key`; it is not a provider thread address.
+- `AbortSignal` cancellation covers queue wait, retry delay, and active HTTPS transport.
+- The transport interface is independent of HTTPS so a future WebSocket implementation can preserve dispatcher behavior.
+- The backend is private and unstable. Mocked protocol tests do not establish live provider compatibility.
+- OpenAI cached tokens are included in `input_tokens`. Cache-hit denominator is `input_tokens`, not `input + cache_read + cache_creation`.
 
 ## Anthropic/Claude Code Runtime
 
@@ -111,12 +103,22 @@ Sources:
 Key decisions:
 
 - Anthropic is an internal Claude subscription OAuth path. The API-key provider was not pursued because it does not serve qgrid's subscription-pooling value.
-- Anthropic is cold-only. It does not use Codex-style thread reuse because Claude Code prompt cache is prefix-based and AI SDK consumers already send full message history for each step.
+- Anthropic is cold-only. It does not use OpenAI `sessionKey` affinity because Claude Code prompt cache is prefix-based and AI SDK consumers already send full message history for each step.
 - The shared `threadCoord` response shape may still appear for provider symmetry, but AI SDK storage/replay is disabled for `anthropic/*` models.
 - Claude Code `stream-json` drops structural assistant role replay in the outbound API payload. qgrid flattens prior history into text because structural role replay through the CLI is not reliable.
-- Claude Code `--json-schema` is not constrained native tool calling. It creates a `StructuredOutput` tool and validates after model generation. Keep schemas strict and fail on non-success subtypes or retry exhaustion.
-- `MAX_STRUCTURED_OUTPUT_RETRIES=1` means one attempt. Do not set it to 0 expecting "no retry but one attempt"; that can mean no useful attempt.
-- The retry pin is scoped to **streaming** structured calls only. SON-495 fixed retries to 1 because a retry inside a stream doubles wall-clock time — a latency argument that does not hold for non-streaming `generate`. Applying the pin to both paths made every non-streaming structured call fail on its first rejected attempt, and since Claude complies with structured output less reliably than OpenAI, that produced a 39.6% `error_max_structured_output_retries` rate for `deti_production` on Opus 4.8 (dev0, 2026-07). Non-streaming now uses Claude Code's default retry budget; `includePartialMessages` is the streaming discriminator.
+- **qgrid does not pass `--json-schema` to Claude Code (SON-532, 2026-08).** CC's mode is not
+  constrained decoding — it creates a `StructuredOutput` tool, scores the free-form output with
+  AJV afterwards, and retries internally on mismatch with no off switch. The strictified scoring
+  schema contradicted consumer intent (nullish frozen into required), so correct-per-instructions
+  outputs were rejected and retried invisibly: deti transcripts showed 2–4 round trips, 216–512 s,
+  and 4.7–9.1× billed output per call, collapsed into one request-log row. Schemas and the tool
+  envelope now travel as text at the end of the system prompt (`schema-prompt.ts`, consumer's
+  original schema, no strictify), the server strips fences only (`fence-strip.ts`), and validation
+  is consumer zod / `parseEnvelope`. Honest failure on violations is unchanged.
+- Legacy (structured path, unreachable from qgrid dispatch): `MAX_STRUCTURED_OUTPUT_RETRIES=1`
+  means one attempt (never set 0), and the retry pin was scoped to **streaming** structured calls
+  only — SON-495's latency argument does not hold for non-streaming `generate`, where pinning
+  produced a 39.6% failure rate for `deti_production` on Opus 4.8 (dev0, 2026-07).
 - 1M context support is measured per model and is a mitigation, not a guarantee. It reduces compaction/hang frequency for huge prompts, but does not make every structured prompt reliable.
 - Spawn env must be whitelisted. Never pass inherited `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, or `ANTHROPIC_BASE_URL` unless intentionally building an API-key/proxy path.
 - `--setting-sources project` is required for shared-service isolation. User/local Claude settings can load hooks or memory and leak context across requests.
@@ -141,7 +143,7 @@ Key decisions:
 - Provider criteria differ by primary window: Anthropic uses `five_hour.utilization`; OpenAI uses `primary.usedPercent`.
 - Threshold gates are by token id, not token name. Names are display/logging labels and can change.
 - Lookup failure is fail-open with logs/metrics. Hard failure happens only when usage was read successfully and the token is over threshold.
-- OpenAI needs the gate in reuse, idle selection, and queue drain paths. A reusable but over-threshold worker must fall back cold to another eligible token when possible.
+- OpenAI applies the gate during token selection. An affinity-preferred token over threshold must fall back to another eligible token when possible.
 
 ## Weighted Token Routing
 
@@ -155,8 +157,8 @@ Key decisions:
 - `tokens.weight` is a per-token integer from 1 to 100 defaulting to 1. It is a relative routing share for new requests, not an enable/disable switch. Weight 0 is invalid; disabling a token stays on `active`.
 - Both providers share one smooth weighted round-robin selector in the provider common layer. The selector knows only token ids, weights, and current scores. Dispatchers own quota, lifecycle, and worker availability, and pass in only the eligible token id set per selection. Do not teach the selector about credentials, workers, or queues.
 - The quota threshold gate runs before weighted selection. An over-threshold token receives no weighted assignment regardless of weight, and the schedule is computed from the remaining eligible tokens.
-- OpenAI thread reuse stays pinned to its original worker and neither reads nor mutates weighted-selector state. Cache affinity intentionally beats weight distribution; only cold requests are weighted.
-- OpenAI routing is work-conserving. A token whose workers are all busy is omitted from the current selection round instead of making requests wait for the heavy-weight token. Queue drain re-runs weighted selection for the head item; the previous released-worker shortcut was removed because it bypassed weighting.
+- OpenAI cache affinity prefers its prior token whenever that token remains eligible; otherwise routing uses weighted selection.
+- Busyness never excludes a token: with no concurrency cap there is no queue and no drain.
 - Candidate collection, selector mutation, and worker acquisition must run without an intervening `await`. A weighted score is consumed only when the dispatcher can commit the assignment synchronously; this is what keeps concurrent Anthropic selections spread correctly.
 - Selector scores reset when token topology or configured weights change. Temporary ineligibility from quota or busy workers only excludes the token from that selection's candidate set and does not reset schedule state.
 - Weight-change notification is owned by the versioned migration trigger (`tokens_weight_changed_upd`); the boot-time trigger setup SQL intentionally excludes `weight` from its WHEN clause, and a test pins this so exactly one trigger fires per weight-only change.
@@ -218,7 +220,7 @@ Key decisions:
 
 - Image generation is OpenAI/Codex-only and request-level opt-in. It is essentially a Codex-hosted `image_generation` tool call, not qgrid directly calling the OpenAI Images API. Always-on image tools would change every turn's tool configuration and threaten prompt-cache stability.
 - It is non-stream only. Codex returns completed base64 image payloads, not useful image deltas.
-- Image turns are cold one-shot threads and are excluded from thread reuse. This prevents base64 payloads from entering reusable conversation state and cache prefixes.
+- Image turns send full input directly and retain no provider conversation state. This prevents base64 payloads from entering reusable state.
 - qgrid performs preflight capability/model gates and postflight "image count must be greater than zero" checks. Codex can otherwise silently return text when image generation is unavailable or unused.
 - Returned images are inline base64 content parts for consumers and AI SDK `file` parts. Reference images are accepted through AI SDK multimodal message parts only on the `imageGeneration` path, and are transported as JSON data URLs with SDK-side size guarding.
 - `imageGenerationOptions` currently supports quality and size. The worker instruction and request-log pricing assumption use `gpt-image-2`, with defaults `medium` and `1536x1024`.

package/skills/qgrid/references/docs-workflow.md

@@ -19,7 +19,7 @@ The project workflow is documented in `docs/WORKFLOW.md`.
 
 Before changing runtime-sensitive areas, search `docs/diagnosis`, `docs/solutions`, and recent `docs/plans` for prior decisions. qgrid has important historical decisions around:
 
-- Codex thread reuse and prompt cache.
+- OpenAI full-history replay and opaque prompt-cache affinity.
 - Claude Code fresh spawn.
 - structured output strictness.
 - Anthropic usage categories.