@cartanova/qgrid-cli 2.7.9 → 2.9.0

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, 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, o as TokenService, p as object, u as setLocale, v as QueryClientProvider, w as Query, x as require_react, z as __exportAll } from "./assets/services.generated-y7xVOTCo.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-V1S8gqMS.js";
-import { n as require_shim, t as require_react_dom } from "./assets/react-dom-BFiG5Daf.js";
+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, 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, o as TokenService, p as object, u as setLocale, v as QueryClientProvider, w as Query, x as require_react, z as __exportAll } from "./assets/services.generated-buX3cJzR.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-C_k4R5n6.js";
+import { n as require_shim, t as require_react_dom } from "./assets/react-dom-CHRRsKwb.js";
 import minpath from "node:path";
 import minproc from "node:process";
 import { fileURLToPath as urlToPath } from "node:url";
@@ -46080,15 +46080,35 @@ function tokenTargetPayload(tokenName) {
 //#endregion
 //#region src/components/qgrid/ChatWidget.tsx
 var CHAT_PROJECT_NAME = "qgrid_chat";
-var DEFAULT_MODEL = "openai/gpt-5.6-terra";
-var MODEL_PRESETS = [
-	"openai/gpt-5.6-terra",
-	"openai/gpt-5.6-sol",
-	"openai/gpt-5.6-luna",
-	"openai/gpt-5.5",
-	"anthropic/claude-fable-5",
-	"anthropic/claude-sonnet-4-6"
-];
+var DEFAULT_MODEL = "anthropic/claude-fable-5-1";
+var MODEL_PRESET_GROUPS = [{
+	label: "OpenAI",
+	models: [
+		"openai/gpt-5.6-terra",
+		"openai/gpt-5.6-sol",
+		"openai/gpt-5.6-luna",
+		"openai/gpt-5.5",
+		"openai/gpt-5.3-codex-spark"
+	]
+}, {
+	label: "Anthropic",
+	models: [
+		"anthropic/claude-fable-5-1",
+		"anthropic/claude-fable-5",
+		"anthropic/claude-opus-5",
+		"anthropic/claude-sonnet-5",
+		"anthropic/claude-opus-4-8",
+		"anthropic/claude-opus-4-7",
+		"anthropic/claude-opus-4-6",
+		"anthropic/claude-opus-4-5",
+		"anthropic/claude-sonnet-4-6",
+		"anthropic/claude-sonnet-4-5",
+		"anthropic/claude-haiku-4-5",
+		"anthropic/claude-opus-4-1",
+		"anthropic/claude-opus-4",
+		"anthropic/claude-sonnet-4"
+	]
+}];
 var EFFORT_PRESETS = [
 	"low",
 	"medium",
@@ -46385,10 +46405,13 @@ function ChatWidget() {
 								onChange: (e) => setModel(e.target.value),
 								disabled: busy,
 								className: "min-w-0 flex-1 rounded-xl border border-sand-200/80 bg-white px-2 py-1.5 text-[12px] text-sand-800 focus:outline-none focus:border-sienna-300 disabled:opacity-50",
-								children: MODEL_PRESETS.map((m) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("option", {
-									value: m,
-									children: m
-								}, m))
+								children: MODEL_PRESET_GROUPS.map((group) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("optgroup", {
+									label: group.label,
+									children: group.models.map((m) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("option", {
+										value: m,
+										children: m
+									}, m))
+								}, group.label))
 							}), /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("select", {
 								value: effort,
 								onChange: (e) => setEffort(e.target.value),
@@ -46625,7 +46648,7 @@ function ChatWidget() {
 }
 //#endregion
 //#region src/components/Sidebar.tsx
-var qgridVersion = "2.7.9";
+var qgridVersion = "2.9.0";
 function Sidebar({ className }) {
 	const pathname = useRouterState({ select: (s) => s.location.pathname });
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("aside", {
@@ -68510,15 +68533,15 @@ function RootComponent() {
 }
 //#endregion
 //#region src/routes/tokens.tsx
-var $$splitComponentImporter$5 = () => import("./assets/tokens-PR42jF1J.js");
+var $$splitComponentImporter$5 = () => import("./assets/tokens-C32lycTe.js");
 var Route$5 = createFileRoute("/tokens")({ component: lazyRouteComponent($$splitComponentImporter$5, "component") });
 //#endregion
 //#region src/routes/settings.tsx
-var $$splitComponentImporter$4 = () => import("./assets/settings-JznSjwGQ.js");
+var $$splitComponentImporter$4 = () => import("./assets/settings-CFoXQaAg.js");
 var Route$4 = createFileRoute("/settings")({ component: lazyRouteComponent($$splitComponentImporter$4, "component") });
 //#endregion
 //#region src/routes/monit.tsx
-var $$splitComponentImporter$3 = () => import("./assets/monit-DrJ15xJL.js");
+var $$splitComponentImporter$3 = () => import("./assets/monit-BW2X1D23.js");
 var monitSearchSchema = object({ level: _enum([
 	"all",
 	"warn",
@@ -68530,7 +68553,7 @@ var Route$3 = createFileRoute("/monit")({
 });
 //#endregion
 //#region src/routes/logs.tsx
-var $$splitComponentImporter$2 = () => import("./assets/logs-2Tkqcncq.js");
+var $$splitComponentImporter$2 = () => import("./assets/logs-lBOU5eUP.js");
 var logsSearchSchema = object({
 	token: string$2().optional(),
 	project: string$2().optional(),
@@ -68544,11 +68567,11 @@ var Route$2 = createFileRoute("/logs")({
 });
 //#endregion
 //#region src/routes/index.tsx
-var $$splitComponentImporter$1 = () => import("./assets/routes-Ct3I9263.js");
+var $$splitComponentImporter$1 = () => import("./assets/routes-CxMHXfdH.js");
 var Route$1 = createFileRoute("/")({ component: lazyRouteComponent($$splitComponentImporter$1, "component") });
 //#endregion
 //#region src/routes/requests/show.tsx
-var $$splitComponentImporter = () => import("./assets/show-D8kuAFbc.js");
+var $$splitComponentImporter = () => import("./assets/show-CcZJO6WF.js");
 var showSearchSchema = object({ id: number$1() });
 var Route = createFileRoute("/requests/show")({
 	validateSearch: showSearchSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartanova/qgrid-cli",
-  "version": "2.7.9",
+  "version": "2.9.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/cartanova-ai/qgrid"

package/skills/qgrid/SKILL.md

@@ -5,6 +5,11 @@ description: Work on the qgrid repository, an LLM subscription-token proxy with
 
 # Qgrid
 
+## Command Scope
+
+Run the repository-specific `mise` commands in this skill only from the qgrid source
+repository. In a downstream project, use that project's configured task and tool runner.
+
 ## Start Here
 
 Use this skill for qgrid repository work. Treat qgrid as a runtime-contract-heavy system: model input travels through the active AI SDK provider, Sonamu API, provider dispatcher, provider-specific runtime, response mapping, request logging, and dashboard display.
@@ -42,10 +47,10 @@ Request logging is enabled by default. Use `providerOptions.qgrid.logger: false`
 - The old v1 SDK package (`packages/sdk`, `@cartanova/qgrid-sdk`) has been removed from the repository. It survives only as a deprecated npm artifact (1.9.0); do not resurrect it or write new code against it.
 - Let the server infer single-turn versus tool-run request-log lifecycle. Do not recreate caller-selected logging modes in the SDK or API examples.
 - Route provider models by prefix: `openai/*` goes to the OpenAI Codex runtime, `anthropic/*` goes to the Anthropic Claude Code runtime. Prefix-less model fallback is not implemented.
-- Treat Fable 5 safety fallback as upstream Claude Code behavior, not qgrid routing: a classifier refusal can retry on Opus 4.8. Do not add a second qgrid retry. Preserve requested Fable versus actual serving Opus, fallback history, and provider-reported cost; a fresh Claude Code process means the fallback is not sticky across qgrid requests.
+- Treat Fable (5 and 5.1) safety fallback as upstream Claude Code behavior, not qgrid routing: a classifier refusal can retry on Opus 5 or Opus 4.8 depending on refusal category. Do not add a second qgrid retry. Preserve requested Fable versus actual serving Opus, fallback history, and provider-reported cost; a fresh Claude Code process means the fallback is not sticky across qgrid requests.
 - Treat dashboard work as Sonamu API/model/generated-client/web work, not isolated frontend work.
 - Prefer `getPuri()` for Sonamu model queries. Treat `getDB()` as a legacy escape hatch only when Puri cannot express the required query. Inside `@transactional` methods, all participating queries must use `getPuri()`; `getDB()` does not reuse Sonamu's ambient transaction connection.
-- Never hand-author migration files for Sonamu-managed schema. Change the entity definition, inspect `sonamu migrate status`, and create migration files with `pnpm --dir packages/api sonamu migrate generate`. Inspect the generated files before applying them. If Sonamu cannot express a required schema change, stop and ask rather than silently replacing its workflow with a custom migration.
+- Never hand-author migration files for Sonamu-managed schema. In the qgrid source repository, change the entity definition, inspect `sonamu migrate status`, and create migration files with `mise exec -- pnpm --dir packages/api sonamu migrate generate`. Inspect the generated files before applying them. If Sonamu cannot express a required schema change, stop and ask rather than silently replacing its workflow with a custom migration.
 - Keep OpenAI Codex built-in tools, apps, plugins, skills, web search, shell, and environment instruction blocks disabled unless the user explicitly asks for agentic Codex behavior.
 - Treat OpenAI image generation as an opt-in Codex `image_generation` tool path. Inspect current code before modifying it; it is not a direct Images API call and its image cost is an estimate.
 
@@ -53,7 +58,7 @@ Request logging is enabled by default. Use `providerOptions.qgrid.logger: false`
 
 Choose verification by blast radius:
 
-- Type/lint/format: `pnpm check`.
+- In the qgrid source repository, run type/lint/format with `mise run check`.
 - Package tests: use the relevant package test command or targeted Vitest files.
 - Provider runtime changes: run targeted tests for `packages/api/src/utils/providers/**` and, when practical, the relevant smoke script in `scripts/` or `packages/api/scripts/`.
 - AI SDK changes: run `packages/ai-sdk` tests and inspect generated request payload behavior.

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

@@ -57,6 +57,10 @@ Do not write `providerOptions: { ... } satisfies QgridProviderOptions`: the expo
 
 `providerOptions.qgrid` supports:
 
+- `tokenName`: strict active-token targeting for both providers. Include the provider prefix and
+  match it to the model (`anthropic/yds` with `anthropic/*`, for example). Missing, inactive, or
+  over-threshold targets fail without falling back to another token. An explicitly empty value is
+  rejected by the SDK before transport; omission keeps weighted round-robin routing.
 - `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`: source for model-scoped opaque OpenAI prompt-cache affinity. Disabled for Anthropic models.
 - `effort`
@@ -143,6 +147,7 @@ Payload responsibilities:
 - Send `jsonSchema` whenever the response format top-level schema is `object`, including requests that also contain tools.
 - Send `history` as JSON string when prior messages exist.
 - Send `projectName` when configured.
+- Send `tokenName` when configured so generate and stream use the same strict target.
 - 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.
@@ -208,10 +213,10 @@ For tools plus structured output, qgrid serializes the final schema-constrained
 
 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:
+For a successful Fable refusal fallback (Fable 5 or 5.1):
 
-- `response.modelId` and `providerMetadata.qgrid.model` are the actual serving model, normally `claude-opus-4-8`.
-- `providerMetadata.qgrid.requestedModel` remains `claude-fable-5`.
+- `response.modelId` and `providerMetadata.qgrid.model` are the actual serving model, an Opus model such as `claude-opus-5` or `claude-opus-4-8`.
+- `providerMetadata.qgrid.requestedModel` remains the requested Fable model, for example `claude-fable-5-1`.
 - `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.
 

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

@@ -44,7 +44,12 @@ Anthropic tokens live in an in-memory `Map<tokenId, PooledToken>`.
 
 Quota threshold:
 
-- `quota_threshold` is checked through Anthropic quota usage.
+- `quota_threshold` checks `five_hour.utilization` for every model and also checks
+  `seven_day_overage_included.utilization` for the Fable family (Fable 5 and 5.1,
+  `isFableFamilyModel` in `anthropic-constants.ts`), using the higher utilization.
+- A runtime quota-exhausted result invalidates every 60-second usage-cache key used before and
+  after a possible OAuth refresh, so the next untargeted request rechecks usage and can select
+  another token.
 - Lookup failure is fail-open.
 - If all eligible tokens exceed threshold, throw `QuotaThresholdExceededError`.
 
@@ -72,7 +77,7 @@ claude -p
   --model <canonical-model-or-1m-suffix>
   --system-prompt <text>                  # small system prompt
   --system-prompt-file <path>             # large system prompt
-  --thinking disabled                       # omitted for Fable 5 and Opus 5
+  --thinking disabled                       # omitted for Fable 5/5.1 and Opus 5
   --effort <effort-or-low>
   --disable-slash-commands
   --session-id <uuid>
@@ -92,7 +97,7 @@ Important details:
 - 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.
+- `--thinking disabled`, `MAX_THINKING_TOKENS=0`, and adaptive thinking env suppression keep thinking off for existing models. Fable 5 and Fable 5.1 require always-on adaptive thinking (CLI catalog `rejects_disabled_thinking`). Opus 5 defaults to adaptive thinking and rejects disabled thinking at `xhigh`/`max` effort. qgrid omits all three suppressors for these models (`usesAdaptiveThinking`) and uses `effort` to control depth.
 
 ## Spawn env
 
@@ -105,13 +110,13 @@ Included env:
 - `CLAUDE_CODE_OAUTH_TOKEN`
 - `CLAUDE_CONFIG_DIR`
 - `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`
-- `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` except for Fable 5 and Opus 5
+- `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` except for Fable 5/5.1 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` except for Fable 5 and Opus 5
+- `MAX_THINKING_TOKENS=0` except for Fable 5/5.1 and Opus 5
 - `CLAUDE_CODE_DISABLE_1M_CONTEXT=1` when model does not support qgrid's 1M path
 - `MAX_STRUCTURED_OUTPUT_RETRIES` for streaming structured output only (not non-streaming `generate`)
 
@@ -180,11 +185,13 @@ cacheCreationInputTokens1h = cache_creation.ephemeral_1h_input_tokens
 
 ## Fable refusal fallback
 
-Fable 5 runs upstream safety classifiers. A refusal is a successful HTTP response with
+Fable 5 and Fable 5.1 run 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.
+partial streamed output. Claude Code handles the refusal fallback and can retry on another Opus
+model; the current CLI routes by refusal category (bio → Opus 5, cyber → Opus 4.8). Do not
+hardcode the fallback target in qgrid: read it from the stream evidence below. 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:
 
@@ -247,6 +254,7 @@ Model normalization strips provider prefix and `[1m]` for canonical model/cost k
 
 qgrid's exact 1M support set currently includes:
 
+- `claude-fable-5-1`
 - `claude-fable-5`
 - `claude-opus-5`
 - `claude-sonnet-5`

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

@@ -66,7 +66,7 @@ When helping a user set up qgrid locally, check for `QGRID_PROJECT_NAME` or conf
 |---|---:|---|
 | `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. |
-| `QGRID_TOKEN_WINDOW_KEEPALIVE_ENABLED` (setting `qgrid.tokenWindowKeepaliveEnabled`) | on | Anthropic 5-hour window keepalive. Only the literal `false` disables it; anything else leaves it on. Changing the setting reschedules immediately. Disabling is the only switch — there is no per-token opt-in. |
+| `QGRID_TOKEN_WINDOW_KEEPALIVE_ENABLED` | off | Marks this instance as the Anthropic 5-hour window keepalive runner (2.8.0, `ea7feb3`). Only the literal `true` enables it; set it on exactly one instance per shared DB so developer instances do not fire duplicates. Two more gates apply: the global setting `qgrid.tokenWindowKeepaliveEnabled` (`false` turns everything off; changing it reschedules immediately) and the per-token `tokens.keepalive_enabled` flag (default `false`, dashboard settings-panel toggle). In 2.7.6 this env was a default-on global switch with no per-token opt-in. |
 | `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

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

@@ -33,7 +33,7 @@ Key decisions:
 - 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.
+- Fable refusal fallback is an upstream Claude Code safety path to another Opus model (currently Opus 5 or Opus 4.8 by refusal category), 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 or hardcode the target.
 - 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.
 
@@ -140,8 +140,11 @@ Key decisions:
 - The token subscriber disables statement/idle timeouts for `LISTEN` and uses reconnect backoff.
 - `quota_threshold` is a routing guardrail, not a load balancer. It prevents an individual token from crossing a configured utilization percentage; it does not equalize traffic.
 - Threshold values are nullable integers from 1 to 100. `0` is not valid; `100` means exclude only at full utilization.
-- Provider criteria differ by primary window: Anthropic uses `five_hour.utilization`; OpenAI uses `primary.usedPercent`.
+- Provider criteria differ by primary window: Anthropic uses `five_hour.utilization` plus the
+  Fable-only `seven_day_overage_included.utilization` when applicable; OpenAI uses
+  `primary.usedPercent`.
 - Threshold gates are by token id, not token name. Names are display/logging labels and can change.
+- Token window keepalive is opt-in at two levels since 2.8.0 (`ea7feb3`): an instance fires only with env `QGRID_TOKEN_WINDOW_KEEPALIVE_ENABLED=true`, and only for tokens with `keepalive_enabled = true`. The runner gate exists because developer instances sharing the production DB fired duplicate pings under the 2.7.6 default-on switch; the per-token flag lets shared or credit-metered accounts stay out. The cost is that upgrades start with zero targets until both are set.
 - Lookup failure is fail-open with logs/metrics. Hard failure happens only when usage was read successfully and the token is over threshold.
 - OpenAI applies the gate during token selection. An affinity-preferred token over threshold must fall back to another eligible token when possible.
 

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

@@ -35,15 +35,15 @@ When a repo doc establishes or changes durable rationale for a qgrid feature, re
 
 `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.
+- In the qgrid source repository, run `mise run qgrid-docs:sync` after changing the canonical skill.
+- In the qgrid source repository, run `mise run 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.
 
 ## Retract pre-release caveats after shipping
 
-Documenting a contract before it ships is fine, but the caveat must be retracted once it does. Wording like "not deployed yet", "based on the working tree", "migration is still untracked", or "package version is still X" becomes a false statement the moment the release lands, and `pnpm qgrid-docs:check` will not catch it — that script validates the skill mirror and `docs/qgrid-doc-map.json` paths only, never Notion body text.
+Documenting a contract before it ships is fine, but the caveat must be retracted once it does. Wording like "not deployed yet", "based on the working tree", "migration is still untracked", or "package version is still X" becomes a false statement the moment the release lands, and `mise run qgrid-docs:check` will not catch it — that task validates the skill mirror and `docs/qgrid-doc-map.json` paths only, never Notion body text.
 
 - When you add a pre-release caveat, record the retraction in the release page at the same time. Do not rely on memory.
 - After a release, search the wiki for `미배포`, `배포되지 않았`, `working tree`, `untracked`, `아직`, and the previous version number.

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

@@ -48,7 +48,7 @@ Tool calls are produced through qgrid structured-output emulation, not native pr
 
 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`.
+- While the parent is running, `requested_model_name` is the full requested id such as `openai/gpt-5.6-terra` 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`.

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

@@ -26,10 +26,12 @@ qgrid dashboard work is usually a Sonamu API/model/generated-client/web change,
 ## Migration workflow
 
 Sonamu entity definitions are the source of truth for managed database schema.
+These commands apply only inside the qgrid source repository. Downstream projects must use
+their own configured task and tool runner.
 
 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`.
+2. Run `mise exec -- pnpm --dir packages/api sonamu migrate status` and inspect `preparedCodes`.
+3. Run `mise exec -- 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: []`.
@@ -62,6 +64,8 @@ Tool contract visibility: the detail page renders a Tools panel between Response
 
 Chat token targeting: the dashboard chat panel can pin a conversation to one account. It defaults to automatic distribution and lists only active tokens whose provider matches the selected model, sending the choice as `tokenName` so the request lands on exactly that account with no fallback. Changing either the model or the token resets the existing conversation coordinates, because a thread's prompt cache belongs to the account that built it. A selection that disappears — deactivated or deleted — is cleared automatically, but the selection is preserved while the token list is still loading so a slow fetch does not silently reset the user's choice.
 
+Chat model presets: the model `<select>` lists the served subset of `QgridSupportedModel` grouped by provider (`MODEL_PRESET_GROUPS` in `ChatWidget.tsx`), newest first, and defaults to `anthropic/claude-fable-5-1`. Ids that the ChatGPT-subscription Codex route no longer serves (`gpt-5.4` and `gpt-5.4-mini` retired 2026-08-31 with `gpt-5.6-terra` / `gpt-5.6-luna` as replacements; `gpt-5.2` and `gpt-5.3-codex` removed earlier) and the catalog-less `claude-sonnet-4-7` stay in the SDK type but are excluded here. web does not depend on ai-sdk, so a new model must be added in both places.
+
 The monit tab's vitals strip shows per-provider in-flight counts, an in-flight sparkline, token chips with quota gauges (fed by the dispatcher's 60-second rate-limits cache; `resetsAt` arrives as ms epoch), and a 1-hour per-provider request/error/cache-hit stats line polled separately every 30 seconds.
 
 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

@@ -34,11 +34,13 @@ Use this reference before changing token storage, OAuth flows, token activation,
 - `credentials`: JSONB credentials.
 - `name`: display/logging name.
 - `active`: whether provider dispatchers may use it.
+- `reauth_required`: whether a permanent refresh failure proved that OAuth login must be repeated.
 - `ord`: dashboard ordering.
 - `quota_threshold`: nullable integer percentage, validated as 1..100 when present.
 - `weight`: non-null integer 1..100, database default 1. Relative share for weighted round-robin routing of new requests. Weight does not enable or disable a token; that stays on `active`.
 
-On creation, `TokenModel.save` applies defaults `quota_threshold = 80` and `weight = 1` independently for any field not provided (skipped entirely when `id` is present).
+On creation, the database defaults `reauth_required = false`; `TokenModel.save` also applies `quota_threshold = 80` and `weight = 1` independently for any field not provided (skipped entirely when `id` is present).
+`TokenModel.save` is internal only; callers use the curated qgrid token APIs so they cannot write lifecycle fields directly.
 
 OpenAI credentials:
 
@@ -77,7 +79,7 @@ Duplicate account replacement is account-identifier based:
 - `addToken(provider, credentials, name)`: saves a token directly.
 - `updateToken(id, name?, quotaThreshold?, weight?)`: partial field update through `TokenModel.updateFields`; omitted fields preserve stored values, so one control cannot overwrite another control's setting. `weight` is validated as an integer 1..100. The web client uses a hand-written `useUpdateTokenMutation` hook instead of the generated tanstack-mutation client for this endpoint.
 - `removeToken(id)`: deletes token row.
-- `toggleToken(id)`: flips `active`.
+- `toggleToken(id)`: atomically flips `active`; it refuses to reactivate a token with `reauth_required = true`, because only OAuth can restore a dead login.
 - `stats()`: reports dispatcher cache stats.
 - `health()`: reports active token cache count and subscriber status.
 - `usage(tokenId?)`: returns provider usage/rate-limit summary.
@@ -113,7 +115,8 @@ Usage/quota:
 
 - Usage API is `https://api.anthropic.com/api/oauth/usage`.
 - qgrid caches Anthropic usage by access-token suffix for 60 seconds.
-- Quota threshold uses `five_hour.utilization`.
+- Quota threshold uses `five_hour.utilization`; Fable family models (Fable 5 and 5.1) additionally
+  use the usage-credit `seven_day_overage_included.utilization`, and either window can exclude the token.
 - Usage lookup failure is fail-open for routing.
 
 ## OpenAI OAuth And Refresh Flow
@@ -153,7 +156,7 @@ Triggers notify on:
 
 - INSERT
 - DELETE
-- UPDATE when `active`, `credentials`, `provider`, `name`, or `quota_threshold` changes.
+- UPDATE when `active`, `reauth_required`, `credentials`, `provider`, `name`, or `quota_threshold` changes.
 - UPDATE when `weight` changes, through a separate `tokens_weight_changed_upd` trigger owned by the versioned migration `20260710090000_alter_tokens_add_weight.ts`. The boot-time setup SQL intentionally leaves `weight` out of its WHEN clause (test-enforced in `token-trigger-setup.test.ts`) so exactly one trigger fires per weight-only change.
 
 `TokenSubscriber`:
@@ -200,14 +203,15 @@ Anthropic token changes only affect the in-memory token pool because every reque
 When a refresh fails in a way that only re-login can fix, qgrid removes the token from routing instead of letting every subsequent request 401.
 
 - Detection lives at the existing refresh failure points, not a background scanner. OpenAI classifies on the error code (`refresh_token_expired`, `refresh_token_reused`, `refresh_token_invalidated`) regardless of HTTP status; Anthropic treats refresh 400/401 as auth-dead.
-- Before deactivating, qgrid re-reads the token and confirms the refresh token used by the failed attempt still matches the stored one. Anthropic refresh tokens rotate, so a late retry carrying an already-rotated token is a normal race, not a death — those are logged and skipped. `QgridFrame.refreshToken` also dedups concurrent refreshes per token.
-- Deactivation is one conditional `active=true → false` update. The process whose update affects a row is the only one that sends the Slack death notification, so a shared database produces exactly one alert per event.
-- The provider's last active token is never auto-deactivated. A systemic failure (client_id revocation, OAuth contract change) would otherwise empty the pool; qgrid logs an error, keeps the token, and sends its own Slack alert. That path leaves no state change behind, so every following request would re-alert — a per-provider 30-minute cooldown holds it to one. The cooldown is in-process, so N instances can each emit once per window.
+- Before deactivating, qgrid locks the token row and confirms the full credentials used by the failed attempt still match the stored credentials. A successful concurrent refresh therefore wins without a stale failure killing the rotated login. `QgridFrame.refreshToken` also dedups concurrent refreshes per token.
+- Auth death is one conditional `reauth_required=false → true` transaction. Provider-scoped advisory locking serializes the last-active decision, and the update also sets `active=false` when another active token exists. The process whose update affects a row is the only one that sends the Slack death notification, so a shared database produces exactly one alert per event. Manual active toggles never set `reauth_required`, and an expired inactive token cannot be reactivated without completing OAuth.
+- A successful refresh clears a concurrent stale `reauth_required` mark but preserves `active`, so it never overrides an operator's manual inactive choice.
+- The provider's last active token is marked `reauth_required=true` but never auto-deactivated. A systemic failure (client_id revocation, OAuth contract change) would otherwise empty the pool; qgrid logs an error, keeps the token, and sends its own urgent Slack alert. The persisted flag gates repeat alerts across every instance.
 - The other notification is registration: every completed login sends one alert, whether the account is new or replacing an existing row through the account dedup. Manually toggling a token back to active is not a registration and sends nothing.
-- Quiet hours suppress non-urgent Slack notifications: weekends, plus 20:00–08:00 on weekdays, in `Asia/Seoul`. All three parts are settings (`slack.quietFromHour`, `slack.quietUntilHour`, `slack.notifyOnWeekends`), defaulting to that window. The hour is computed through `Intl` with an explicit timezone rather than `getHours()` — dev0 runs in UTC, where "20:00" would land at 05:00 Korean time. Expiry alerts repeat, so one dropped in quiet hours returns on the first cycle of the next working window. The last-active-token death alert sets `urgent: true` and ignores quiet hours: it means the provider pool is empty, which cannot wait for the next working day.
+- Quiet hours suppress non-urgent Slack notifications: weekends, plus 20:00–08:00 on weekdays, in `Asia/Seoul`. All three parts are settings (`slack.quietFromHour`, `slack.quietUntilHour`, `slack.notifyOnWeekends`), defaulting to that window. The hour is computed through `Intl` with an explicit timezone rather than `getHours()` — dev0 runs in UTC, where "20:00" would land at 05:00 Korean time. Expiry alerts repeat, so one dropped in quiet hours returns on the first cycle of the next working window. The last-active-token death alert sets `urgent: true` and ignores quiet hours: it means that provider has no usable login, which cannot wait for the next working day.
 - `slack.enabled` exists because holidays cannot be expressed as a recurring rule — substitute holidays, one-off national days, and company closures change every year, so an operator turns notifications off directly instead. It gates the same non-urgent path as quiet hours, which keeps the escape hatch for pool-empty alerts identical in both mechanisms.
 - Notifications are fail-open: unset `SLACK_BOT_TOKEN`/`SLACK_CHANNEL_ID` is a silent no-op, and send failures (including HTTP 200 with `ok:false`) only warn. Payloads carry an internal reason code such as `anthropic:400`, never the raw provider response body.
-- `expired-token-reminder.ts` repeats the session-expiry alert for tokens that are still inactive, because the one-shot alert is lost on anyone not watching the channel at that moment and re-login only happens when a person does it. It reuses the same `세션 만료` title rather than inventing a second name — there is one event, so a differently-named alert would read as a separate problem. It runs once at startup and then every `SLACK_EXPIRY_REMINDER_INTERVAL_MINUTES` (unset or 0 disables), batches every inactive token into one message, and sends nothing when none are inactive. The startup run matters because a restart is exactly when someone is watching, and waiting a full interval to learn a token is already dead is backwards; the cost is one extra alert per restart — a periodic "all clear" trains people to ignore the channel.
+- `expired-token-reminder.ts` repeats the session-expiry alert only for tokens with `reauth_required = true`; manually inactive tokens are not expired sessions. It reuses the same `세션 만료` title rather than inventing a second name — there is one event, so a differently-named alert would read as a separate problem. It runs once at startup and then every `SLACK_EXPIRY_REMINDER_INTERVAL_MINUTES` (unset or 0 disables), batches every expired token into one message, and sends nothing when none require re-login. The startup run matters because a restart is exactly when someone is watching, and waiting a full interval to learn a token is already dead is backwards; the cost is one extra alert per restart — a periodic "all clear" trains people to ignore the channel.
 - Owners are mentioned through `SLACK_USER_MAP` (`tokenName:SlackUserId`) on every token notification, not just the reminder. The map is explicit rather than resolved through `users.list`: Slack handles diverge from token names often enough (`haze`→`haze.lee`, `byeongjun`→`potados`) that auto-matching drops the mention silently, and an alert nobody is tagged in has no one to act on it. Shared accounts are left out of the map on purpose and appear by name only. Each instance sends its own reminder — unlike deactivation there is no state change to gate on, and a few duplicates a day cost less than a locking scheme.
 
 ## Quota Threshold Semantics
@@ -234,18 +238,21 @@ When a refresh fails in a way that only re-login can fix, qgrid removes the toke
 - A targeted request never falls back. Missing, inactive, or over-threshold targets fail rather than silently serving from another account — the whole point of addressing a token is that the answer comes from that account.
 - Targeted selection does not consume weighted round-robin state. Without that guarantee, background targeting such as keepalive would skew the token distribution of ordinary traffic.
 - Targeting is distinct from cache affinity. Affinity sets `preferredTokenId` as a preference and still falls back when the token is ineligible; explicit targeting adds `requirePreferredToken` so the same field becomes strict. The Anthropic path only ever receives explicit targeting — affinity coordinates are not forwarded there, so making it strict cannot break affinity behavior.
-- Exposure boundary: `tokenName` is not part of the AI SDK provider options. It is reachable on the qgrid frame wire and used by the dashboard chat token picker and internal callers; SDK consumers keep round-robin.
+- Exposure boundary: raw qgrid callers and AI SDK consumers can pass `tokenName`; the AI SDK sends
+  it from `providerOptions.qgrid.tokenName` on both generate and stream. Callers that omit it keep
+  weighted round-robin routing, while an explicitly empty SDK value fails before transport.
 
 ## Token Window Keepalive
 
 Anthropic's 5-hour usage window anchors on the first request, so an unused token has no window at all — `five_hour.resets_at` is null until something is sent, and windows are per-account and independent. The practical cost is that starting work starts the clock: burn the quota in two hours and the remaining three are dead.
 
-Keepalive breaks that coupling by burning the window clock during idle time. Every active Anthropic token gets one cheap request as soon as its window expires, so windows always run and a workday lands mid-window rather than on a boundary. Across an eight-hour day this raises the number of windows the day can touch from a fixed 2 to an expected 2.6.
+Keepalive breaks that coupling by burning the window clock during idle time. Every keepalive-enabled active Anthropic token gets one cheap request as soon as its window expires, so windows always run and a workday lands mid-window rather than on a boundary. Across an eight-hour day this raises the number of windows the day can touch from a fixed 2 to an expected 2.6.
 
-- Scope is every active Anthropic token. There is no per-token opt-in; the only control is the global switch.
+- Since 2.8.0 (`ea7feb3`) keepalive is opt-in at two levels. The runner instance must have env `QGRID_TOKEN_WINDOW_KEEPALIVE_ENABLED=true` (default off; set it on one instance per shared DB), and a token is a target only when `tokens.keepalive_enabled` is `true` (default `false`, toggled in the dashboard settings panel). The global setting `qgrid.tokenWindowKeepaliveEnabled` is a kill switch (`false` disables everything), not a substitute for either gate. In 2.7.6 every instance fired for every active token.
+- Operational trap: the 2.8.0 migration adds `keepalive_enabled` as default `false` without backfilling existing tokens. After upgrading, both the runner env and the per-token toggles must be set, or keepalive silently schedules zero tokens. This happened on dev0 after the 2026-08-31 self-update; a lingering 2.7.6 instance masked it until 2026-09-01. Diagnose with `GET /api/setting/listSettings` (`keepaliveRunnerEnabled`), `GET /api/token/findMany?subset=A` (`keepalive_enabled`), and the latest request log under project `qgrid-token-window-keepalive`.
 - The next fire is scheduled from the token's real `resetsAt` rather than a fixed five-hour timer, so a provider-side change to the window length is followed automatically.
 - Per-token fire guards prevent repeats: 61 seconds after a successful fire (the usage API caches for a minute, so an immediate re-read would still show the old window) and five hours after a failure. Guards survive rescheduling — only timers are replaced — and the guard is recorded before the request is sent so a reschedule mid-flight cannot fire a second time.
 - Rescheduling happens only when target-set membership changes (active/provider). Credential rotation updates the token row and fires the change notification, but it does not change membership and must not trigger a sweep; otherwise every OAuth refresh would re-poll usage for every token.
-- Multiple instances each fire. A ping into an already-open window does nothing, so the duplicate is harmless and cheaper than a locking scheme — the same reasoning the expiry reminder uses.
+- Only runner instances fire. If more than one instance is marked as runner, a ping into an already-open window does nothing, so the duplicate is harmless and cheaper than a locking scheme — the same reasoning the expiry reminder uses.
 - Fires are logged under the `qgrid-token-window-keepalive` project name so they can be excluded from traffic statistics.
 - Known limits: the first sweep after boot has no concurrency cap, so N empty windows mean N simultaneous fires; and a failed fire costs that token five hours of window misalignment.

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

@@ -12,36 +12,39 @@ Use this reference to choose tests, smoke scripts, and first debugging targets f
 
 ## Package Scripts
 
+The commands in this section apply only inside the qgrid source repository. In a downstream
+project, use that project's configured task and tool runner.
+
 Root:
 
-- `pnpm check`: oxlint plus oxfmt check for the repo.
-- `pnpm build`: recursive package build.
-- `pnpm dev`: parallel package dev servers.
+- `mise run check`: qgrid docs consistency, oxlint, and oxfmt check for the repo.
+- `mise run build`: recursive package build.
+- `mise run dev`: parallel package dev servers.
 
 API package `qgrid-api`:
 
-- `pnpm --filter qgrid-api test`: Vitest run.
-- `pnpm --filter qgrid-api test:watch`: standalone watch mode.
-- `pnpm --filter qgrid-api build`: Sonamu build.
-- `pnpm --filter qgrid-api sonamu`: run Sonamu CLI.
+- `mise exec -- pnpm --filter qgrid-api test`: Vitest run.
+- `mise exec -- pnpm --filter qgrid-api test:watch`: standalone watch mode.
+- `mise exec -- pnpm --filter qgrid-api build`: Sonamu build.
+- `mise exec -- pnpm --filter qgrid-api sonamu`: run Sonamu CLI.
 
 AI SDK package `@cartanova/qgrid-ai-sdk`:
 
-- `pnpm --filter @cartanova/qgrid-ai-sdk test`.
-- `pnpm --filter @cartanova/qgrid-ai-sdk build`.
-- `pnpm --filter @cartanova/qgrid-ai-sdk e2e`.
-- `pnpm --filter @cartanova/qgrid-ai-sdk e2e:tools-output`.
-- `pnpm --filter @cartanova/qgrid-ai-sdk e2e:logger`.
+- `mise exec -- pnpm --filter @cartanova/qgrid-ai-sdk test`.
+- `mise exec -- pnpm --filter @cartanova/qgrid-ai-sdk build`.
+- `mise exec -- pnpm --filter @cartanova/qgrid-ai-sdk e2e`.
+- `mise exec -- pnpm --filter @cartanova/qgrid-ai-sdk e2e:tools-output`.
+- `mise exec -- pnpm --filter @cartanova/qgrid-ai-sdk e2e:logger`.
 
 CLI package `@cartanova/qgrid-cli`:
 
-- `pnpm --filter @cartanova/qgrid-cli build`.
-- `pnpm --filter @cartanova/qgrid-cli bundle` builds the API first and copies the server bundle.
+- `mise exec -- pnpm --filter @cartanova/qgrid-cli build`.
+- `mise exec -- pnpm --filter @cartanova/qgrid-cli bundle` builds the API first and copies the server bundle.
 
 Web package `qgrid-web`:
 
-- `pnpm --filter qgrid-web dev`.
-- `pnpm --filter qgrid-web preview`.
+- `mise exec -- pnpm --filter qgrid-web dev`.
+- `mise exec -- pnpm --filter qgrid-web preview`.
 
 The old v1 SDK package (`packages/sdk`) has been removed from the repository; all public-SDK verification goes through `packages/ai-sdk`.