@cartanova/qgrid-cli 2.4.7 → 2.4.9

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

@@ -36,19 +36,63 @@ Setup agents should treat a missing project label as an actionable configuration
 
 qgrid-specific behavior is controlled through `providerOptions.qgrid`. Explain these options precisely because they are qgrid's extension point beyond normal AI SDK usage.
 
+AI SDK declares the outer `providerOptions` as a generic JSON record, so it does not infer qgrid-specific keys or literal values. qgrid exports `QgridProviderOptions` for the inner `providerOptions.qgrid` value. Import it and put the `satisfies` check at that inner boundary:
+
+```ts
+import { generateText } from "ai";
+import { qgrid, type QgridProviderOptions } from "@cartanova/qgrid-ai-sdk";
+
+const result = await generateText({
+  model: qgrid("anthropic/claude-fable-5"),
+  prompt,
+  providerOptions: {
+    qgrid: {
+      effort: "high",
+    } satisfies QgridProviderOptions,
+  },
+});
+```
+
+Do not write `providerOptions: { ... } satisfies QgridProviderOptions`: the exported type describes the nested qgrid options object, not AI SDK's outer provider-name map. Use this typed pattern in qgrid setup guidance and examples so misspelled keys and invalid option values fail at compile time.
+
 `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.
 - `effort`
 - `verbosity`: OpenAI/Codex route only.
 - `reasoningSummary`: OpenAI/Codex route only.
 - `serviceTier`: OpenAI/Codex route only.
-- `fallbackModels`: reserved for future fallback routing.
+- `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"`.
 
 `providerOptions.qgrid` does not currently support `projectName` or `project_name`. Prefer `QGRID_PROJECT_NAME` for the default project label; use config `projectName` only when a caller needs to override that default.
 
+## Request logging
+
+Request logging is enabled by default. Opt out per generation with the typed qgrid option:
+
+```ts
+const result = await generateText({
+  model: qgrid("openai/gpt-5.6-terra"),
+  prompt,
+  providerOptions: {
+    qgrid: {
+      logger: false,
+    } satisfies QgridProviderOptions,
+  },
+});
+```
+
+`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.
+
+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 and legacy payloads containing it are rejected. Migrate callers as follows:
+
+- Omitted logging mode or `"auto"`: remove it; omit `logger` or send `logger: true`.
+- `"run"`: remove it; the server now infers a continued tool run from `runContext`, tool results, and the provider finish reason.
+- `"none"`: replace it with `logger: false`.
+
 ## 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.
@@ -60,7 +104,7 @@ const result = await generateText({
   providerOptions: {
     qgrid: {
       serviceTier: "fast",
-    },
+    } satisfies QgridProviderOptions,
   },
 });
 ```
@@ -85,8 +129,9 @@ Payload responsibilities:
 - Send `jsonSchema` only when no tools are present and response format top-level schema is `object`.
 - Send `history` as JSON string when prior messages exist.
 - Send `projectName` when configured.
-- Use `logMode: "run"` for tool-call loops.
+- 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`.
 - 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.
@@ -112,6 +157,15 @@ qgrid response content maps to AI SDK content:
 
 When `imageGeneration` was requested and the server returns no image part, the AI SDK provider throws a version-skew/error guard instead of silently accepting text-only output.
 
+For a successful Fable 5 refusal fallback:
+
+- `response.modelId` and `providerMetadata.qgrid.model` are the actual serving model, normally `claude-opus-4-8`.
+- `providerMetadata.qgrid.requestedModel` remains `claude-fable-5`.
+- `providerMetadata.qgrid.modelFallbacks` preserves the refusal route and optional category/explanation.
+- `providerMetadata.qgrid.costSource` reports whether cost came from Claude Code or qgrid's pricing table. Prefer the provider-reported combined cost for this path.
+
+Do not expose the requested Fable model as `response.modelId` after Opus served the answer, and do not map this upstream safety behavior onto the reserved `providerOptions.qgrid.fallbackModels` option.
+
 Usage maps qgrid standard usage into AI SDK V3 usage:
 
 - `inputTokens.total = input_tokens`
@@ -126,4 +180,4 @@ Do not store or replay `sessionKey` thread coordinates for `anthropic/*` models.
 
 ## Logger integration
 
-`createQgridLogger` records external provider calls into qgrid request logs. It skips qgrid provider calls to avoid double-logging. When changing logger behavior, preserve stale-run fallback because AI SDK telemetry lacks a reliable error hook for all failure modes.
+`createQgridLogger` records external provider calls into qgrid request logs. It skips qgrid provider calls to avoid double-logging, and it skips any external-provider generation whose `providerOptions.qgrid.logger` is `false`. This makes `logger: false` a single opt-out that produces zero native or telemetry request logs without changing the model call itself. When changing logger behavior, preserve stale-run fallback because AI SDK telemetry lacks a reliable error hook for all failure modes.

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

@@ -12,6 +12,7 @@ Use this reference before changing Anthropic provider behavior, Claude Code spaw
 - Config isolation
 - Input adaptation
 - Output adaptation
+- Fable refusal fallback
 - Structured output
 - 1M context
 
@@ -70,7 +71,7 @@ claude -p
   --model <canonical-model-or-1m-suffix>
   --system-prompt <text>                  # small system prompt
   --system-prompt-file <path>             # large system prompt
-  --thinking disabled
+  --thinking disabled                       # omitted for Fable 5 and Opus 5
   --effort <effort-or-low>
   --disable-slash-commands
   --session-id <uuid>
@@ -83,7 +84,7 @@ Important details:
 - `--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`.
-- `--thinking disabled`, `MAX_THINKING_TOKENS=0`, and adaptive thinking env suppression keep thinking off.
+- `--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
 
@@ -96,13 +97,13 @@ Included env:
 - `CLAUDE_CODE_OAUTH_TOKEN`
 - `CLAUDE_CONFIG_DIR`
 - `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`
-- `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1`
+- `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` except for Fable 5 and Opus 5
 - `CLAUDE_CODE_DISABLE_CLAUDE_MDS=1`
 - `CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1`
 - `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1`
 - `CLAUDE_CODE_DISABLE_WORKFLOWS=1`
 - `CLAUDE_CODE_ATTRIBUTION_HEADER=0`
-- `MAX_THINKING_TOKENS=0`
+- `MAX_THINKING_TOKENS=0` except for Fable 5 and Opus 5
 - `CLAUDE_CODE_DISABLE_1M_CONTEXT=1` when model does not support qgrid's 1M path
 - `MAX_STRUCTURED_OUTPUT_RETRIES` for structured output only
 
@@ -144,8 +145,43 @@ Anthropic native usage categories are mutually exclusive. qgrid normalizes them
 inputTokens = input_tokens + cache_creation_input_tokens + cache_read_input_tokens
 cachedInputTokens = cache_read_input_tokens
 cacheCreationInputTokens = cache_creation_input_tokens
+cacheCreationInputTokens5m = cache_creation.ephemeral_5m_input_tokens
+cacheCreationInputTokens1h = cache_creation.ephemeral_1h_input_tokens
 ```
 
+## Fable refusal fallback
+
+Fable 5 runs upstream safety classifiers. A refusal is a successful HTTP response with
+`stop_reason: "refusal"`, not an HTTP/provider error, and can happen before output or after
+partial streamed output. Claude Code handles the refusal fallback and can retry on Opus 4.8.
+This is distinct from the CLI `--fallback-model` flag, which is for overload on the default
+model. qgrid does not configure either mechanism or add another retry.
+
+The stream adapter must preserve all observable routing evidence:
+
+- `system.subtype = "model_refusal_fallback"` provides the original/fallback models and refusal details.
+- `assistant.message.model` identifies the model that produced that message.
+- `usage.iterations` contains the original `message` and `fallback_message` when available.
+- Treat `stop_reason`, rather than `stop_details` or empty content, as the authoritative refusal signal. Category and explanation are optional metadata.
+- `model_refusal_no_fallback` or a terminal `stop_reason: "refusal"` is an error, even if the outer result subtype says `success`. A successfully served fallback has a non-refusal terminal reason and a `fallback_message` iteration.
+
+`QueryOutput.model` is the actual serving model. `requestedModel` and `modelFallbacks` preserve
+the caller's requested model and routing history. Because qgrid uses a fresh Claude Code process
+for each request, any Claude Code session-sticky fallback state does not carry to the next request;
+each new Fable request may independently refuse and fall back again.
+
+Cost and usage must follow the upstream combined result. Prefer Claude Code's `total_cost_usd` and
+preserve `usage.iterations` only as attribution evidence; do not independently price every iteration
+and add them together. An upstream pre-output refusal is not billed, while work completed before a
+mid-stream refusal can be billed. Upstream fallback handling applies fallback credit where applicable,
+so a qgrid-side retry would risk duplicate work and incorrect cache-write billing.
+
+Upstream references:
+
+- [Refusals and fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback)
+- [Fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit)
+- [Claude Code CLI `--fallback-model`](https://code.claude.com/docs/en/cli-reference)
+
 ## 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.
@@ -156,8 +192,11 @@ qgrid strictifies schemas before provider dispatch. Claude Code `--json-schema`
 
 Model normalization strips provider prefix and `[1m]` for canonical model/cost keys.
 
-qgrid's measured 1M support set currently includes:
+qgrid's exact 1M support set currently includes:
 
+- `claude-fable-5`
+- `claude-opus-5`
+- `claude-sonnet-5`
 - `claude-sonnet-4-6`
 - `claude-opus-4-6`
 - `claude-opus-4-8`

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

@@ -4,7 +4,7 @@ Use this reference for qgrid startup, configuration, and runtime-facing environm
 
 ## CLI options
 
-- `--db <url>`: PostgreSQL URL in `postgres://user:password@host:port/dbname` or `postgresql://...` form. Parsed by `packages/cli/src/cli.ts` and copied into `QGRID_DB_*` env vars before server boot.
+- `--db <url>`: PostgreSQL URL in `postgres://user:password@host:port/dbname` or `postgresql://...` form. Parsed by `packages/cli/src/cli.ts` and copied into `SONAMU_DB_*` env vars before server boot.
 - `-p, --port <port>`: server port. Default `44900`. The CLI validates the port and refuses to start if it is already in use.
 - `--skip-update`: skip qgrid CLI self-update check.
 
@@ -19,17 +19,22 @@ The CLI also ensures runtime CLIs are installed/current enough:
 
 | Env | Default | Meaning |
 |---|---:|---|
-| `QGRID_DB_HOST` | `localhost` | PostgreSQL host. |
-| `QGRID_DB_PORT` | `5432` | PostgreSQL port. |
-| `QGRID_DB_USER` | `postgres` | PostgreSQL user. |
-| `QGRID_DB_PASSWORD` | `postgres` | PostgreSQL password. |
-| `QGRID_DB_NAME` | `qgrid` | PostgreSQL database. |
+| `SONAMU_DB_HOST` | `localhost` | PostgreSQL host. |
+| `SONAMU_DB_PORT` | `5432` | PostgreSQL port. |
+| `SONAMU_DB_USER` | `postgres` | PostgreSQL user. |
+| `SONAMU_DB_PASSWORD` | `postgres` | PostgreSQL password. |
+| `SONAMU_DB_NAME` | `qgrid` | PostgreSQL database. |
+| `NODE_ENV` | direct API: `development`; packaged CLI: `production` | Sonamu runtime profile. Use `staging` for remote non-production API deployments such as dev0. The profile does not create or rename the explicitly configured DB. |
 | `HOST` | `localhost` | Sonamu server listen host when running API directly. |
 | `PORT` | `44900` | Sonamu server listen port. In CLI mode this is derived from `--port`, not read as user input. |
 | `QGRID_PUBLIC_BASE_URL` | empty | Public base URL used to construct Anthropic OAuth callback URL. If unset, callback defaults to `http://localhost:${PORT}/callback`. |
 | `PROJECT_NAME` | `Qgrid` | Sonamu project name. Not the same as request log `projectName`. |
 
 Do not treat CLI bundle bootstrapping internals as user-facing qgrid configuration.
+The packaged CLI accepts only `staging` and `production`; `development` and `test`
+require the source workspace. Sonamu 0.10.3 also requires `.env` or
+`.env.<NODE_ENV>` to exist at the API root. Source deployments must retain one of
+those files, while the npm CLI bundle carries an empty `.env` marker itself.
 
 ## SDK/client env vars
 
@@ -44,7 +49,14 @@ When helping a user set up qgrid locally, check for `QGRID_PROJECT_NAME` or conf
 
 | Env | Default | Meaning |
 |---|---:|---|
-| `QGRID_WORKERS_PER_TOKEN` | `3` | OpenAI Codex workers per token. Capped at 5 in code. |
+| `QGRID_WORKERS_PER_TOKEN` | `5` | Legacy worker-count setting. It supplies the minimum worker count when `QGRID_OPENAI_MIN_WORKERS_PER_TOKEN` is absent. Clamped to 1..20. |
+| `QGRID_OPENAI_AUTOSCALE` | enabled | Set to `"false"` or `"0"` to keep the pool fixed at the minimum worker count. |
+| `QGRID_OPENAI_MIN_WORKERS_PER_TOKEN` | `QGRID_WORKERS_PER_TOKEN`, otherwise `5` | Minimum ready workers maintained for each active OpenAI token. Clamped to 1..20. |
+| `QGRID_OPENAI_MAX_WORKERS_PER_TOKEN` | `15` 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` | 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. |
+| `QGRID_OPENAI_MIN_HOST_AVAILABLE_GIB` | `20` | Refuse scale-up when current host available memory is below this value. |
 | `QGRID_OPENAI_THREAD_REUSE` | enabled | Set to `"false"` to disable OpenAI thread reuse and force cold thread behavior. |
 | `MAX_STRUCTURED_OUTPUT_RETRIES` | `1` for structured Anthropic calls | Claude Code structured-output retry count, clamped to at least 1 by qgrid. |
 
@@ -52,7 +64,7 @@ When helping a user set up qgrid locally, check for `QGRID_PROJECT_NAME` or conf
 
 `packages/api/src/index.ts` runs `bootstrapServer` (`server-bootstrap.ts`) with a strict init → migrate → listen order:
 
-1. `Sonamu.init()` loads `.env` from `packages/api/.env` when running API directly and configures the Sonamu database connection from `QGRID_DB_*`.
+1. `Sonamu.init()` loads Sonamu's native dotenv snapshot for the active `NODE_ENV` and reads the database connection from `SONAMU_DB_*`. Selecting `staging` alone does not create a staging DB; `SONAMU_DB_NAME` remains the explicit database name.
 2. `runRequiredMigrations` (`startup-migrations.ts`) applies latest migrations from `packages/api/src/migrations` before the server listens. Migration failure exits the process — qgrid must not boot against a schema missing required columns such as `tokens.weight`. This is a hard-fail; it used to be a soft-fail warn inside `onStart`.
 3. `Sonamu.createServer()` starts the server. Its `onStart` in `packages/api/src/sonamu.config.ts`:
    1. Ensures PostgreSQL `tokens_changed` triggers.

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

@@ -29,9 +29,12 @@ Key decisions:
 - `packages/ai-sdk` is the active public SDK. `packages/sdk` is deprecated and should be read only for legacy context.
 - 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.
 - `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.
 - The SDK should stay a thin adapter. Server APIs own request-log lifecycle, provider dispatch, structured-output emulation, and provider runtime details.
+- Request logging defaults to enabled. `providerOptions.qgrid.logger: false` is the single per-generation opt-out for both native qgrid logs and `createQgridLogger` telemetry logs; it must not alter generation or tool behavior.
 
 ## Tool Calling And Request-Log Lifecycle
 
@@ -48,6 +51,7 @@ Key decisions:
 - Tools and `jsonSchema` are mutually exclusive at the qgrid dispatcher boundary because both need the provider structured-output slot.
 - Tool-call request logs are a multi-step run: create run, append generate/tool steps, then finish run. This makes AI SDK multi-step behavior visible in the dashboard instead of logging only one opaque completion.
 - Tool results update the existing `tool_call` step by `request_log_id + tool_call_id`. They are not logged as a second unrelated completion row.
+- The server infers single-turn completion versus an open tool run from context and finish reason. The removed caller-selected `logMode` contract must not be recreated.
 - `runContext.requestLogId` is intentionally direct. qgrid SDK and server are in the same product boundary, so an opaque indirection was not worth the complexity.
 - Lifecycle endpoints remain public because `createQgridLogger` records non-qgrid AI SDK calls into qgrid logs without forcing those calls through the qgrid provider.
 - Structured-output failures should fail honestly. Especially on Claude Code, partial or invalid structured output must not be rescued into a fake success.
@@ -156,6 +160,8 @@ Key decisions:
 
 - The dashboard/logging layer is a core qgrid value, not an incidental web UI. It lets operators see cost, cache, TTFT, token routing, tool steps, and project-level workloads.
 - `createQgridLogger` exists so teams can keep using native AI SDK providers while still recording those calls in qgrid request logs. It should not throw into user code.
+- New log model identities use the existing `requested_model_name` and `model_name` fields in `provider/model` form, including external-provider telemetry logs. There is no separate provider column and no backfill of legacy prefixless rows.
+- A running parent has no confirmed serving model. Store its requested route separately, leave `model_name` null, and make dashboard running-state rendering depend on `status` rather than placeholder model text.
 - Request-log TTFT is the first generate-step TTFT. It intentionally measures generation responsiveness, not queue time or full request latency.
 - Cache-hit metrics must be derived consistently from normalized provider accounting. Keep metric logic centralized when possible.
 - Request-log list queries should avoid large text/blob columns unless the UI needs them. The list view is for scanning, not payload archival.

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

@@ -30,3 +30,13 @@ Before changing runtime-sensitive areas, search `docs/diagnosis`, `docs/solution
 Do not copy stale docs blindly. Use docs to identify decisions and then verify against current code.
 
 When a repo doc establishes or changes durable rationale for a qgrid feature, reflect the stable decision in `references/decision-rationale.md`. Keep the skill reference as a compact index of why the decision exists and where the source docs live; do not copy full plans or brainstorms into the skill.
+
+## Skill and wiki consistency
+
+`packages/cli/skills/qgrid` is the canonical qgrid skill. The CLI package ships this directory to consuming projects. The repository-local `.agents/skills/qgrid` directory is a checked mirror for agents working in this repository; do not edit the mirror as a separate source.
+
+- Run `pnpm qgrid-docs:sync` after changing the canonical skill.
+- Run `pnpm qgrid-docs:check` before finishing documentation or runtime-contract work.
+- `docs/qgrid-doc-map.json` maps each durable topic to code, canonical skill references, and the matching Notion page.
+- Code and tests remain the source of truth. Update the skill and Notion together when a code change alters a documented contract.
+- Keep dated operational snapshots, internal server addresses, and other environment-specific facts in Notion. Keep reusable runtime contracts in the skill.

package/skills/qgrid/references/openai-codex-runtime.md

@@ -12,7 +12,7 @@ Use this reference before changing OpenAI provider behavior, Codex worker lifecy
 - Queue and routing
 - Usage and notifications
 - Streaming
-- Image generation status
+- Image generation
 
 ## Process model
 
@@ -22,13 +22,21 @@ OpenAI tokens use persistent Codex app-server workers.
 - Worker: `packages/api/src/utils/providers/openai/codex-worker.ts`.
 - RPC client: `packages/api/src/utils/providers/openai/codex-rpc.ts`.
 - Process command: `codex app-server --listen stdio://`.
-- Workers per token: `QGRID_WORKERS_PER_TOKEN`, default 3, capped at 5.
-- Worker id: `tokenId * 10 + workerIndex`.
+- Workers per token: autoscaling defaults to 5–15 workers per active token, with a hard cap of 20.
+- `QGRID_WORKERS_PER_TOKEN` is the legacy baseline and now supplies the minimum when `QGRID_OPENAI_MIN_WORKERS_PER_TOKEN` is absent.
+- Worker id: `tokenId * 100 + workerIndex`.
 - Worker home: `/tmp/qgrid-codex/${tokenId}-${workerIndex}` when `workerIndex` exists.
 - Worker cwd: `${CODEX_HOME}/cwd`.
 
 Workers are persistent. Turns are single-flight per worker (`busy` flag). When all eligible workers are busy, requests enter an in-memory queue.
 
+Autoscaling is enabled unless `QGRID_OPENAI_AUTOSCALE` is `"false"` or `"0"`. It evaluates the pool every 5 seconds by default, starts scale-down after 10 idle minutes, and refuses scale-up when either memory guard would be crossed:
+
+- estimated qgrid worker RSS: `0.71 + 0.157 * totalWorkerCount` GiB, limited to 16 GiB by default;
+- current host available memory at scale-up evaluation time, required to be at least 20 GiB by default.
+
+All sizing and memory limits can be overridden with the environment variables listed in `cli-env-and-server-boot.md`.
+
 ## Codex configuration
 
 qgrid writes a worker-local `config.toml` under `CODEX_HOME` before spawning Codex. The intent is to use Codex as a plain generation backend, not as a coding agent.

package/skills/qgrid/references/prompt-cache-and-usage.md

@@ -97,7 +97,10 @@ Do not double-count cache subfields. This was a real dashboard bug: OpenAI cache
 - OpenAI cost normally uses qgrid's price table.
 - OpenAI image generation stores a separate `image_cost_usd` estimate. It assumes Codex's image tool is priced as `gpt-image-2` for the selected/default quality and size, because qgrid does not receive exact image tool usage from Codex.
 - Anthropic Claude Code may return `total_cost_usd`; qgrid prefers provider cost when present and positive.
-- Anthropic cache creation uses 5-minute cache write price in fallback tables.
+- Anthropic responses can split cache creation into `ephemeral_5m_input_tokens` and `ephemeral_1h_input_tokens`; preserve that split and price each TTL separately.
+- Claude Code automatically requests 1-hour cache TTL for subscription OAuth and 5-minute TTL for API-key or usage-credit paths. Only legacy responses without a TTL breakdown use the subscription path's 1-hour rate as qgrid's fallback.
+- Persist per-step `cost_usd`, `cost_source`, and the 5m/1h split. New request logs use that exact stored cost; only legacy rows with no `cost_source` are repriced from the current table.
+- When Fable refuses and Claude Code serves Opus, prefer Claude Code's positive `total_cost_usd`. Persist Fable as the requested model and Opus as the serving model instead of pricing the combined turn as Fable.
 - OpenAI long-context surcharge applies to the whole request when input exceeds the model threshold, not just the excess tokens.
 
 When changing models or prices, verify against current official pricing before editing the table.

package/skills/qgrid/references/provider-runtime-differences.md

@@ -5,8 +5,8 @@ Use this reference when comparing OpenAI and Anthropic behavior, debugging provi
 | Topic | OpenAI via Codex | Anthropic via Claude Code |
 |---|---|---|
 | Process lifetime | Persistent `codex app-server` workers | Fresh `claude` process per request |
-| Worker pool | Token x `QGRID_WORKERS_PER_TOKEN`, default 3, max 5 | No workers; in-memory token pool only |
-| Worker id | `tokenId * 10 + workerIndex` | `tokenId` |
+| Worker pool | Autoscaling pool per token, default 5–15 and hard-capped at 20 | No workers; in-memory token pool only |
+| Worker id | `tokenId * 100 + workerIndex` | `tokenId` |
 | Epoch | Worker spawn counter; changes on restart | Always `0` |
 | Request concurrency | One turn per worker; queue when all eligible workers busy | Fresh process per request |
 | Token selection | Smooth weighted RR picks a quota-eligible token with an idle worker, then a per-token worker cursor; reuse bypasses weights | Smooth weighted RR over quota-eligible tokens per request |
@@ -23,7 +23,7 @@ Use this reference when comparing OpenAI and Anthropic behavior, debugging provi
 | Cost source | qgrid model price fallback | Prefer Claude Code `total_cost_usd`, else qgrid price fallback |
 | Settings isolation | Per-worker `CODEX_HOME` and config.toml | Shared project cwd plus per-token `CLAUDE_CONFIG_DIR` |
 | Streaming close | Can interrupt Codex turn with `turn/interrupt` | Abort kills the fresh child process |
-| Image generation | In progress, OpenAI/Codex non-stream only | Explicitly unsupported |
+| Image generation | Implemented as an opt-in Codex `image_generation` tool path; non-stream only | Explicitly unsupported |
 
 ## Routing contract
 

package/skills/qgrid/references/request-log-run-lifecycle.md

@@ -2,43 +2,62 @@
 
 Use this reference when changing request logging, tool-call loop logging, telemetry logger integration, request log steps, or dashboard metrics.
 
-## Modes
+## Logging switch
 
-qgrid query supports `logMode`:
+qgrid query and stream inputs support `logger?: boolean`:
 
-- `auto`: save one request_log after a simple request succeeds.
-- `run`: create/update a run and append steps for multi-step/tool-call flows.
-- `none`: no automatic logging.
+- Omitted or `true`: request logging is enabled. This is the default.
+- `false`: the generation creates zero qgrid request-log parent or step rows.
 
-If `logMode` is omitted, `qgrid.frame.ts` uses `run` when `isStep` is true and `auto` otherwise.
+The AI SDK exposes the switch as `providerOptions.qgrid.logger`. `logger: false` changes observability only: generation, streaming, AI SDK tool execution, tool-result continuation, and provider thread coordination remain active. The SDK keeps pending tool-call correlation locally when no request-log id exists.
 
-## Query flow
+`logMode` has been removed and payloads that still contain it are rejected. Migrate old callers as follows:
 
-For `logMode: "run"`:
+- Omitted mode or `"auto"`: remove it; omit `logger` or use `logger: true`.
+- `"run"`: remove it; the server infers tool-run lifecycle.
+- `"none"`: replace it with `logger: false`.
 
-1. `beforeQuery(args)` creates or extends a run.
-2. `QgridDispatcher.query` or `queryStream` executes the provider call.
-3. `afterQuery(...)` records result/step data and returns `runContext`.
-4. qgrid merges lifecycle `requestLogId` with provider `threadCoord`.
-5. Errors call `finishRunWithError`; stream close can call abort handling.
+## Server-inferred lifecycle
 
-For `auto`:
+For every logger-enabled initial qgrid query or stream, the server owns the lifecycle:
 
-- qgrid saves a single request log row after the provider returns.
-- It records token name, project name, model, prompts, response, usage, duration, TTFT, driver cost, image cost estimate, effort, history, status, tool-call count, and image-generation flag.
-- Image results are also appended as synthetic `image_generation` tool-call steps so the detail page can inspect the generated image and pricing assumption.
+1. Create one parent request log with `status = running` before provider execution.
+2. Execute the provider call.
+3. Append the generate step and any pending tool-call steps.
+4. If the provider finishes with tool calls, keep the parent running and return its request-log id in `runContext`.
+5. If the provider finishes normally, aggregate the steps and finish the same parent row.
 
-## Tool-call loop
+A tool-result follow-up carries the returned `runContext` and tool results. The server completes the pending tool steps, appends the next generate step, and again decides from the provider finish reason whether to keep the run open or finish it. Callers do not select a single-request or run mode.
+
+Errors and client aborts finish the same parent as `error` or `aborted` and roll up usage, cost, fallback count, and cost provenance from every generate step that completed before termination. SSE client closure is authoritative regardless of the provider's abort error text; if a provider result arrives after closure, record its step usage and then leave the parent `aborted` without publishing `done`.
+
+Creating the initial `running` row is a precondition for a logger-enabled provider call. Once the provider has succeeded, however, a failure while appending or finalizing logs is best-effort: report the logging error and preserve the generated text/stream result instead of making logging failure replace a successful model result.
 
-The AI SDK provider tracks pending tool-call IDs. When the next AI SDK call contains all required tool results, it sends:
+Stale cleanup must target old runs that still have unresolved tool-call steps; a long provider request with no pending tool call is not stale merely because its parent row is still running. Cleanup and arriving tool follow-ups share a PostgreSQL transaction advisory lock per request-log id and recheck the unresolved step after acquiring it, so cleanup cannot overwrite an in-flight follow-up across server processes.
+Candidate discovery is only a hint; each candidate is rechecked and finalized in its own short Sonamu `@transactional` write operation. Use `getPuri("w")` throughout that operation so the advisory lock, aggregate reads, and terminal update stay on the same transaction connection.
+
+## Tool-call loop
 
-- existing `runContext`
-- `toolResults`
-- `logMode: "run"`
+The AI SDK provider tracks pending tool-call IDs. When the next AI SDK call contains all required tool results, it sends the existing logging `runContext` when one was returned and sends the tool results. With `logger: false`, it still correlates the pending calls locally and continues the generation without a request-log id.
 
 qgrid converts tool results into continuation input for providers. Cold fallback still includes a "continue using these results" text input.
 
-Tool calls are produced through qgrid structured-output emulation, not native provider tool calling. The request log lifecycle records the emulated generate step, pending tool-call step rows, tool results on follow-up, and the final generate step. For full semantics, read `tool-calling-and-multiturn.md`.
+Tool calls are produced through qgrid structured-output emulation, not native provider tool calling. The lifecycle records the emulated generate step, pending tool-call step rows, tool results on follow-up, and the final generate step. For full semantics, read `tool-calling-and-multiturn.md`.
+
+## Provider and model storage
+
+New request logs store routed model identity in the existing model fields; they do not add a separate provider column:
+
+- While the parent is running, `requested_model_name` is the full requested id such as `openai/gpt-5.4` and `model_name` is `NULL`.
+- Completed parent and generate-step model values use full `provider/model` ids.
+- `requested_model_name` preserves the exact requested route, including modifiers such as Anthropic `[1m]`; `model_name` is the actual canonical serving route. They differ after a Fable refusal fallback, for example requested Fable versus serving Opus.
+- A completed multi-step parent uses the final turn's requested and serving models. It never stores the literal model value `mixed`; usage and cost still aggregate across steps, and `cost_source` may be `mixed`.
+- Public qgrid `QueryOutput.model` and AI SDK response model metadata continue to report the provider runtime model without changing their response contract. Do not copy that prefixless response value directly into server-native storage.
+- `createQgridLogger` combines the telemetry model provider and model id for the requested value, and qualifies the observed step/final response model with that provider. AI SDK adapter ids such as `openai.responses` and `anthropic.messages` are normalized to their base provider before storage. Avoid duplicating a prefix when the model id already starts with the same provider.
+
+This is a forward-only storage normalization. Do not backfill legacy prefixless rows, and do not invent a new `provider` column. Dashboard and query consumers must tolerate both legacy prefixless values and new prefixed values. Treat `status` as authoritative: a running row has no confirmed serving model, so the dashboard should render an explicit running state rather than a model placeholder or fallback display.
+
+Provider-qualified ids widen `model_name` and `requested_model_name` from 50 to 255 characters on both request-log entities. Generate and apply the normal Sonamu schema migration before running the new server. Do not hand-edit generated types, hand-author a derivable migration, or rewrite existing model values as part of that width migration.
 
 ## Usage fields
 
@@ -47,14 +66,17 @@ Stored request log usage uses qgrid-standard semantics:
 - `input_tokens`: total input, including cache read/write.
 - `cache_read_tokens`: cached input read.
 - `cache_creation_tokens`: prompt cache write input.
+- `cache_creation_5m_tokens` / `cache_creation_1h_tokens`: nullable Anthropic TTL breakdown.
 - `output_tokens`: output tokens.
 - `cost_usd`: integer micro-USD in DB; displayed USD is `cost_usd / 1_000_000`.
+- `cost_source`: `provider`, `pricing_table`, or `mixed`. New rows keep the cost calculated at request time.
+- `fallback_count`: number of observed model fallbacks in the run/step.
 - `image_cost_usd`: integer micro-USD estimate for Codex image generation output.
 - `image_cost_method`: string such as `assumed:gpt-image-2:medium:1536x1024:png`.
 
-OpenAI/Codex: use per-turn `.last` usage from `thread/tokenUsage/updated`.
+OpenAI/Codex uses per-turn `.last` usage from `thread/tokenUsage/updated`.
 
-Anthropic: normalize native mutually exclusive categories by summing input + cache creation + cache read into total input.
+Anthropic normalizes native mutually exclusive categories by summing input + cache creation + cache read into total input. Prefer positive Claude Code `total_cost_usd`; otherwise calculate from the actual serving model and TTL split.
 
 For image requests, keep `cost_usd` as the Codex driver model token cost. Image output cost is separate because qgrid observes Codex's `image_generation` result, not the OpenAI Images API usage object. Treat `image_cost_usd` as a price-table estimate that may be inaccurate if Codex changes its underlying image accounting.
 
@@ -62,11 +84,11 @@ Reference images for image generation are not stored in `request_logs.user_promp
 
 ## Legacy normalization
 
-`RequestLogModel` normalizes legacy Anthropic rows where stored `input_tokens` may not include cache read/write. Keep this in mind when changing cost or display logic.
+`RequestLogModel` normalizes legacy Anthropic rows where stored `input_tokens` may not include cache read/write. Rows with `cost_source = NULL` are legacy and can be repriced from the current table; rows with a source retain their exact stored cost across price/promotion changes.
 
 ## TTFT
 
-TTFT is tracked by wrapping first provider delta:
+TTFT is tracked by wrapping the first provider delta:
 
 - OpenAI: first `item/agentMessage/delta`.
 - Anthropic: first text or structured partial JSON delta.
@@ -75,4 +97,4 @@ If missing, qgrid maps TTFT to `0` in `QueryOutput` and nullable/optional places
 
 ## Logger integration
 
-`packages/ai-sdk/src/logger.ts` lets non-qgrid providers write logs into qgrid. It skips model provider `qgrid` to avoid double logging. Preserve stale-run cleanup because AI SDK telemetry may emit start without a final event on provider failures.
+`packages/ai-sdk/src/logger.ts` lets non-qgrid providers write logs into qgrid through the public lifecycle endpoints. It skips model provider `qgrid` to avoid double logging and skips any generation with `providerOptions.qgrid.logger: false`. Therefore one disabled generation produces neither native qgrid logs nor `createQgridLogger` telemetry logs. Preserve its stale-run fallback because AI SDK telemetry may emit start without a final event on provider failures.

package/skills/qgrid/references/sonamu-api-web-flow.md

@@ -21,6 +21,19 @@ qgrid dashboard work is usually a Sonamu API/model/generated-client/web change,
 - Web components under `packages/web/src/components/qgrid` consume generated API shapes.
 - The main dashboard sidebar version should stay synced to `packages/cli/package.json`. `packages/web/vite.config.ts` reads that package version and exposes it as `__QGRID_CLI_VERSION__`; `Sidebar.tsx` displays it.
 
+## Migration workflow
+
+Sonamu entity definitions are the source of truth for managed database schema.
+
+1. Change the relevant `*.entity.json` files.
+2. Run `pnpm --dir packages/api sonamu migrate status` and inspect `preparedCodes`.
+3. Run `pnpm --dir packages/api sonamu migrate generate`.
+4. Inspect the generated, table-scoped migration files without rewriting them by hand.
+5. Apply them through Sonamu's migration target flow or qgrid's startup migration runner.
+6. Re-run migration status and require `pending: []` and `preparedCodes: []`.
+
+Do not hand-author a migration that Sonamu can derive from entity changes. If generation cannot represent the required operation, stop and make the exception explicit before changing migration code or database state. Never delete or edit a migration that has already shipped to another environment.
+
 ## Request log dashboard
 
 Request log changes usually touch:
@@ -35,6 +48,10 @@ Request log changes usually touch:
 
 Check list and detail views. Avoid loading large text columns in list views unless intentionally needed.
 
+For new request logs, the existing `requested_model_name` and `model_name` fields store full `provider/model` values; there is no separate request-log provider column. A running parent stores the requested id and keeps `model_name = NULL`, but the dashboard must treat `status` as authoritative and render only an explicit running state until the request finishes. Completed rows keep the existing requested-to-serving fallback display. If an error/aborted row has only a requested model, show that value explicitly as requested rather than as a serving model or an unknown placeholder. Legacy prefixless rows remain valid and are not backfilled.
+
+Provider-qualified ids widen `model_name` and `requested_model_name` from 50 to 255 characters on both the parent and step entities. Generate and inspect the Sonamu migration, and apply it before starting the new server. The width migration must not rewrite legacy model values or add a provider column. Keep generated API/web types synchronized through Sonamu rather than editing them by hand.
+
 Image-generation request logs add `is_image_generation`, `image_cost_usd`, and `image_cost_method`. The list view displays driver plus image cost as the total cost cell; the detail view shows driver cost and image cost separately and renders generated image data URLs from response/tool-step content.
 
 Reference input images for image generation render in the detail view under the user prompt from the first synthetic `image_generation` step's `tool_args.inputImages`. Keep the prompt itself text-only, redact large base64 in request JSON views, and avoid rendering duplicate input previews for multi-output image turns.

package/skills/qgrid/references/token-auth-quota-lifecycle.md

@@ -204,6 +204,12 @@ Anthropic token changes only affect the in-memory token pool because every reque
 - Null means no threshold gate.
 - Lookup failure is fail-open.
 - Individual over-threshold tokens are excluded from selection.
+- OpenAI keeps this exclusion as an in-memory `quota-blocked` runtime state without changing the
+  token's persisted `active` value or stopping its workers. It logs `over_threshold` only when a
+  token enters the blocked state, skips that token during normal burst scale-up, and logs
+  `recovered` once a later quota check falls below the threshold. Metadata generations prevent an
+  in-flight lookup from restoring a block after a threshold or lifecycle change. The state is not
+  persisted across server restarts.
 - If all ready/eligible tokens are over threshold, qgrid throws `QuotaThresholdExceededError`.
 - Log messages use `quota_threshold gate` with reasons such as `over_threshold`, `lookup_fail_open`, and `all_exceeded`.
 

package/skills/qgrid/references/tool-calling-and-multiturn.md

@@ -35,22 +35,22 @@ When `options.tools` contains function tools:
 1. Filter function tools.
 2. Convert them with `toQgridTool`.
 3. Send `tools` in `/api/qgrid/query` or `/api/qgrid/prepareStream`.
-4. Set `logMode: "run"`.
-5. Do not send `jsonSchema` response format at the same time.
+4. Forward the per-call `logger` switch when request logging is disabled.
+5. Do not send `jsonSchema` response format at the same time. The server infers whether the logged request becomes a multi-step run.
 
 When qgrid responds with `finishReason: "tool-calls"`:
 
 1. Map qgrid `content: [{ type: "tool-call" }]` to AI SDK tool-call content.
-2. Store the pending run's `runContext` and tool-call IDs in the provider instance registry.
+2. Store the pending tool-call IDs, local correlation state, and any returned `runContext` in the provider instance registry. Logging-enabled calls receive a request-log id; logging-disabled calls do not need one.
 3. Return finish reason `{ unified: "tool-calls", raw: "tool_call" }`.
 
 On the next AI SDK call, if prompt history contains tool results for all pending IDs:
 
 1. Extract tool results from AI SDK history.
 2. Match result IDs against the pending run registry.
-3. Send the matched run's previous `runContext`.
+3. Send the matched run's previous `runContext` when the server returned one.
 4. Send `toolResults`.
-5. Keep `logMode: "run"`.
+5. Keep the call's `logger` setting. The server decides from the context and finish reason whether the request-log parent remains open.
 
 If tool results do not match any pending run, qgrid warns and sends the request without stale `runContext`.
 The registry is keyed per pending run so concurrent `generateText(...tools...)` calls on the same qgrid model instance can finish in any order.
@@ -134,13 +134,14 @@ Anthropic follow-ups do not reuse Claude sessions. qgrid starts a fresh Claude p
 
 ## Request Logs
 
-Tool runs use `logMode: "run"`.
+Request logging defaults to enabled, and the server infers the tool-run lifecycle rather than accepting a caller-selected mode.
 
 - `beforeQuery` creates or continues a request log run.
 - A generate step is recorded after every LLM turn.
 - When `finishReason` is `tool-calls`, qgrid appends pending tool-call step rows.
 - The follow-up request fills tool-call results or errors.
 - The final `stop` response aggregates step usage and finishes the run.
-- Stale runs with no follow-up are marked error after 30 minutes.
+- Stale runs with unresolved tool-call steps are marked error after 30 minutes; long provider calls without pending tools are not swept solely for being `running`.
+- `providerOptions.qgrid.logger: false` creates no parent or step rows, while the SDK still executes tools and correlates follow-ups locally.
 
 Use `projectName` for tool-heavy workloads so request logs can be filtered by task/workflow and metrics remain interpretable.

package/skills/qgrid/references/verification-and-debugging.md

@@ -99,7 +99,7 @@ AI SDK structured output:
 - `scripts/qgrid-structured-ai-sdk-smoke.ts`
 - Uses local `packages/ai-sdk/src/index`.
 - Env: `QGRID_URL`, `SMOKE_MODEL`, `SMOKE_CASES`, `SMOKE_REPEAT`.
-- Useful for streamObject/structured-output regressions.
+- Uses AI SDK 6 `streamText` with `Output.object`; useful for structured-output regressions.
 
 Image generation: