@cartanova/qgrid-cli 2.8.0 → 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.8.0";
+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.8.0",
+  "version": "2.9.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/cartanova-ai/qgrid"

package/skills/qgrid/SKILL.md

@@ -47,7 +47,7 @@ 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. 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.

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

@@ -213,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

@@ -45,7 +45,8 @@ Anthropic tokens live in an in-memory `Map<tokenId, PooledToken>`.
 Quota threshold:
 
 - `quota_threshold` checks `five_hour.utilization` for every model and also checks
-  `seven_day_overage_included.utilization` for Fable 5, using the higher utilization.
+  `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.
@@ -76,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>
@@ -96,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
 
@@ -109,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`)
 
@@ -184,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:
 
@@ -251,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.
 
@@ -144,6 +144,7 @@ Key decisions:
   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/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

@@ -64,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,8 +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`; Fable 5 additionally uses the model-specific
-  `seven_day_overage_included.utilization`, and either window can exclude the token.
+- 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
@@ -154,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`:
@@ -201,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
@@ -243,12 +246,13 @@ When a refresh fails in a way that only re-login can fix, qgrid removes the toke
 
 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.