cartethyia 2.7.9 → 2.8.1

package/dist/dashboard/precompressed-assets.json

@@ -1,77 +1,77 @@
 {
-  "count": 121,
+  "count": 122,
   "assets": [
-    "assets/BannedPage-BxoG1MrL.js",
-    "assets/CliToolDetailPage-ixwgKk53.js",
-    "assets/CliToolsPage-BmttNV3U.js",
-    "assets/CombosPage-BE3qwwfC.js",
-    "assets/ConsoleLogPage-CRZdmMIX.js",
-    "assets/CustomizationPage-Dv_FJ6Er.js",
-    "assets/HealthEventsModal-CoVrw2sM.js",
-    "assets/InjectSystemPromptPanel-BOoO8rpz.js",
-    "assets/LoginPage-ChJuNNVN.js",
-    "assets/ModelPicker-BZAJtPg1.js",
-    "assets/OverviewPage-BE40s3u5.js",
-    "assets/ProviderDetailPage-sfLoQtPV.js",
-    "assets/ProviderIcon-CQ6bPUf_.js",
-    "assets/ProvidersPage-DcepmPWo.js",
-    "assets/ProxyPage-BJ87Pp0U.js",
-    "assets/QuotaPage-gkSyRAKa.js",
-    "assets/SettingsPage-C5HPWqEv.js",
-    "assets/SetupPage-CFNcATJJ.js",
-    "assets/StudioPage-YoD4tY5l.js",
+    "assets/BannedPage-Dq530awD.js",
+    "assets/CliToolDetailPage-DZzaS-7S.js",
+    "assets/CliToolsPage-DaZZ3cqP.js",
+    "assets/CombosPage-BlC_xdkX.js",
+    "assets/ConsoleLogPage-D-rqeVtG.js",
+    "assets/CustomizationPage-7xT5yg2E.js",
+    "assets/HealthEventsModal-Clq8E9cW.js",
+    "assets/InjectSystemPromptPanel-6Teoq9Se.js",
+    "assets/LoginPage-CZuI0MAR.js",
+    "assets/ModelPicker-C1hNTlkr.js",
+    "assets/OverviewPage-0yfhSI1C.js",
+    "assets/ProviderDetailPage-xqTxdQ4c.js",
+    "assets/ProviderIcon-Ddhm1InL.js",
+    "assets/ProvidersPage-C3fYuu6i.js",
+    "assets/ProxyPage-CHtJtZ3u.js",
+    "assets/QuotaPage-D1RV_2BX.js",
+    "assets/SettingsPage-BzZAvYSX.js",
+    "assets/SetupPage--s-EfEIL.js",
+    "assets/StudioPage-BjXFGSK4.js",
     "assets/ToolIcon-CfeLA-Z_.js",
-    "assets/UsagePage-DxjaAhb_.js",
-    "assets/api-keys-BTlkq_Uk.js",
-    "assets/app-B7kIWFm5.js",
-    "assets/app-BX2nnKqs.css",
+    "assets/UsagePage-CP8F8BN7.js",
+    "assets/api-keys-2hc12Uz2.js",
+    "assets/app-C0gTXEoN.js",
+    "assets/app-DGXbNfAR.css",
     "assets/arrow-left-CpBxkoxI.js",
     "assets/arrow-right-Dl5yKnp8.js",
     "assets/arrow-up-59ms1iiT.js",
-    "assets/assert-CndthXFQ.js",
+    "assets/assert-BMcj1xZE.js",
     "assets/backup-file-gdKIlg8U.js",
-    "assets/badge-DdbT_7Am.js",
+    "assets/badge-DkRUuVfz.js",
     "assets/ban-durations-B58FyRxC.js",
-    "assets/banner-CsGN-nbm.js",
+    "assets/banner-CDjW841Q.js",
     "assets/brain-Cwed_72z.js",
-    "assets/card-mgZ_TLLZ.js",
+    "assets/card-Bto5UlL9.js",
     "assets/chevron-left-Bf6CaTSJ.js",
     "assets/chevron-right-BXIy5l3h.js",
     "assets/circle-alert-CntYHV5v.js",
     "assets/circle-check-BU3v_mFW.js",
     "assets/circle-question-mark-Cz4un8sH.js",
-    "assets/cli-tools-A1-v8-03.js",
-    "assets/clipboard-button-CJ4Zty89.js",
+    "assets/cli-tools-DaH6g9hL.js",
+    "assets/clipboard-button-BYKBCzjk.js",
     "assets/database-Dz9N3zGd.js",
-    "assets/dialog-B5L2jPQ_.js",
+    "assets/dialog-DL0Zftwv.js",
     "assets/dialog-actions-B1axpEg7.js",
     "assets/download-dRFo5_Wu.js",
-    "assets/drawer-DkjUouAj.js",
-    "assets/entry-B-LVLV6o.js",
-    "assets/entry-CAhdYl3B.js",
-    "assets/entry-D2xD0Tmd.js",
+    "assets/drawer-Dpx_UXaS.js",
+    "assets/entry-BV7-1NoM.js",
+    "assets/entry-CGvdNU6r.js",
+    "assets/entry-DScKYvZj.js",
     "assets/eye-C_hawfH4.js",
     "assets/eye-off-Bk5g2luF.js",
     "assets/fingerprint-pattern-BWuHtbW4.js",
-    "assets/formatters-CrsdLVsn.js",
+    "assets/formatters-BS3DZlZj.js",
     "assets/gauge-BbIMy7MB.js",
     "assets/house-h9AZlJuT.js",
     "assets/image-BPaouViG.js",
-    "assets/index-BU64Lqvp.js",
-    "assets/inline-B2aDLyyg.js",
-    "assets/input-BCVkdR9d.js",
+    "assets/index-SQnvvTWX.js",
+    "assets/inline-Dl-cuLK0.js",
+    "assets/input-Bfx0EzRc.js",
     "assets/jsx-runtime-CXUMngI_.js",
     "assets/key-round-UkavsGxp.js",
     "assets/layers-2-glBbjl.js",
-    "assets/layout-DNcAdMK-.js",
-    "assets/list-row-DgrIH0hw.js",
-    "assets/live-Cae01iu8.js",
+    "assets/layout-BxhbQ_JS.js",
+    "assets/list-row-D49Y4ptn.js",
+    "assets/live-CbVTdX9V.js",
     "assets/log-in-BmRjy60c.js",
     "assets/message-circle-CCxGwRvv.js",
     "assets/mutation-BQ0ccH_A.js",
-    "assets/network-CRib7H_2.js",
-    "assets/numbers-BKQE8Xpz.js",
-    "assets/pagination-ecPvG_8g.js",
+    "assets/network-JGvDveof.js",
+    "assets/numbers-Dw6kiew-.js",
+    "assets/pagination-iUoI8GeE.js",
     "assets/pencil-768ysRAr.js",
     "assets/plus-DIdX_g-x.js",
     "assets/power-off-Yjw9GMJh.js",
@@ -95,22 +95,23 @@
     "assets/providers/parallel.svg",
     "assets/providers/tokenharbor.svg",
     "assets/providers/windsurf.svg",
+    "assets/providers/zro.svg",
     "assets/query-keys-IKLh0YFd.js",
-    "assets/quota-DJ1QlAOq.js",
+    "assets/quota-DiPD6UKH.js",
     "assets/refresh-cw-BqJFk4sU.js",
     "assets/rotate-ccw-CufcqITi.js",
     "assets/route-CNSNj9Zm.js",
-    "assets/routing-Ckm1UXuC.js",
+    "assets/routing-8jZr-3WE.js",
     "assets/scaling-nWE4Cx8f.js",
     "assets/search-JOKus9rb.js",
-    "assets/select-ChoFWyKz.js",
+    "assets/select-oO1FxMVb.js",
     "assets/settings-2-Ds9DQp0t.js",
-    "assets/settings-CKjFPlKW.js",
+    "assets/settings-CLr3kdIx.js",
     "assets/shield-BMQNxORh.js",
     "assets/shield-check-DVS0Foqh.js",
-    "assets/stack-DWCwU3fh.js",
-    "assets/state-Cg3VL5J_.js",
-    "assets/switch-Db70BMix.js",
+    "assets/stack-Y3pDteZr.js",
+    "assets/state-CArX_Iak.js",
+    "assets/switch-DwlwmDO-.js",
     "assets/terminal-0_IjPWTk.js",
     "assets/tokens-COzario9.js",
     "assets/trash-Cppn5c3R.js",
@@ -118,7 +119,7 @@
     "assets/use-modal-focus-By7oJoGd.js",
     "assets/use-reduced-motion-C4B0R6Sz.js",
     "assets/use-timeout-BwcBBRrT.js",
-    "assets/useMutation-BqdE0LuM.js",
+    "assets/useMutation-DJ9GYEgf.js",
     "assets/wrench-B6E1oEuY.js",
     "assets/zap-C4EeVW4q.js",
     "index.html"

package/migrations/full-postgres/0046_add_accounts_quota_plan_fetched_at.sql

@@ -0,0 +1,7 @@
+-- Freshness stamp for `quota_plan`: the plan column is a bare string, so
+-- routing cannot tell a fresh read from a stale one. This timestamp is written
+-- together with `quota_plan` on a successful quota fetch and lets the routing
+-- engine downgrade a plan older than the freshness horizon to `unknown`
+-- instead of trusting it blindly.
+ALTER TABLE "provider_accounts"
+  ADD COLUMN IF NOT EXISTS "quota_plan_fetched_at" timestamptz;

package/migrations/full-postgres/0047_add_provider_device_flow_proxy.sql

@@ -0,0 +1,17 @@
+-- Adds `provider_routing_settings.device_flow_proxy` (text, NOT NULL, default
+-- 'random') — how device-code OAuth flows (start + poll) choose their egress.
+--
+--   'random' (default) — route the device-authorization and token-poll
+--     requests through a randomly selected active network pool. The upstream
+--     sees a rotating IP, which prevents "multiple codes from one IP"
+--     detection for Cursor/Grok/device-code providers.
+--   'direct' — always dial direct egress (the old behavior). Explicitly
+--     selected by the operator, e.g. when pools are unavailable or the
+--     provider must see one stable address.
+--
+-- Idempotency comes from the migration ledger, not from the statement: the
+-- runner records the file inside the same transaction, so a file that has
+-- already run is never re-executed. The baseline is generated from
+-- `0000_baseline.sql` alone and does not carry this column.
+ALTER TABLE "provider_routing_settings"
+  ADD COLUMN IF NOT EXISTS "device_flow_proxy" text NOT NULL DEFAULT 'random';

package/migrations/lite-sqlite3/0046_add_accounts_quota_plan_fetched_at.sql

@@ -0,0 +1,4 @@
+-- SQLite mirror of `full-postgres/0046_add_accounts_quota_plan_fetched_at.sql`:
+-- the timestamp column is stored as an ISO-8601 text string.
+ALTER TABLE "provider_accounts"
+  ADD COLUMN "quota_plan_fetched_at" text;

package/migrations/lite-sqlite3/0047_add_provider_device_flow_proxy.sql

@@ -0,0 +1,19 @@
+-- Adds `provider_routing_settings.device_flow_proxy` (text, NOT NULL, default
+-- 'random') — how device-code OAuth flows (start + poll) choose their egress.
+--
+--   'random' (default) — route the device-authorization and token-poll
+--     requests through a randomly selected active network pool. The upstream
+--     sees a rotating IP, which prevents "multiple codes from one IP"
+--     detection for Cursor/Grok/device-code providers.
+--   'direct' — always dial direct egress (the old behavior). Explicitly
+--     selected by the operator, e.g. when pools are unavailable or the
+--     provider must see one stable address.
+--
+-- SQLite stores text as-is; a default is baked into the column so existing
+-- rows read as 'random' without a backfill.
+--
+-- Idempotency comes from the migration ledger, not from the statement: the
+-- runner records the file inside the same transaction, so a file that has
+-- already run is never re-executed. The baseline is generated from
+-- `0000_baseline.sql` alone and does not carry this column.
+ALTER TABLE "provider_routing_settings" ADD COLUMN "device_flow_proxy" text NOT NULL DEFAULT 'random';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cartethyia",
-  "version": "2.7.9",
+  "version": "2.8.1",
   "description": "A powerful, self-hosted reverse proxy for OpenAI- and Anthropic-compatible AI clients, powered by native Bun and Elysia. It serves both protocols from a single server, routes every model across any configured provider, and translates requests and responses in real time — streaming and prompt caching included. Underneath it runs a full delivery engine: per-account health tracking, quota and cooldown enforcement, automatic failover across pools and providers, usage accounting, and telemetry. Point OpenCode, Cline, Claude Code, Codex, or any compatible client at Cartethyia and it keeps its native protocol while the gateway absorbs every provider-specific difference behind it. Runs on embedded SQLite or external PostgreSQL with optional Redis coordination, ships as a global CLI with a system-tray console, and needs only Bun 1.4+ alongside Node.js/npm.",
   "license": "GPL-3.0-only",
   "type": "module",

package/src/boot/app.ts

@@ -10,7 +10,7 @@ import { chatAdapter } from "../transport/surface/chat/adapter";
 import { responsesAdapter } from "../transport/surface/responses/adapter";
 import { messagesAdapter } from "../transport/surface/messages/adapter";
 import { completionAdapter } from "../transport/surface/completion";
-import { SurfaceAdapterRegistry } from "../transport/surface/adapters";
+import { SurfaceAdapterRegistry, type SurfaceAdapter } from "../transport/surface/adapters";
 import { GatewayError, publicGatewayErrorBody } from "../protocol/gateway-error";
 import { shutdownError, shutdownNotice } from "../transport/shutdown-notice";
 import type { CanonicalAdapter } from "../transport/contracts";
@@ -47,7 +47,7 @@ import {
 import { createTokenCountHandler } from "../transport/dispatch/token-count";
 
 import { createTransportPipeline } from "../transport/guards/pipeline";
-import { createDrainHandler, isLoopbackPeer, tokenMatches } from "../transport/drain-endpoint";
+import { createDrainHandler, requireLoopbackAdmin } from "../transport/drain-endpoint";
 import { createConsoleAccountResetHandler } from "../console/auth/account-reset";
 import { resetConsoleAuthState } from "../console/auth/account-reset-store";
 import { createBackupExportHandler } from "../console/backup/export-endpoint";
@@ -58,7 +58,7 @@ import type { ReadinessCheckResult } from "../persistence/readiness";
 import type { RouteSnapshotService } from "../transport/routing/route-model";
 import type { TrustedProxyBoundary } from "../config/network";
 import { resolveClientIdentity } from "../security/ip-boundary";
-import type { ValidatedNetworkBindingFactory } from "../network/pool/resolver";
+import type { ValidatedNetworkBindingFactory } from "../network/egress/factory";
 import { metrics } from "../observability/metrics";
 import type { RuntimeMetricsSampler } from "../observability/runtime-metrics";
 import { API_CONTENT_SECURITY_POLICY, X_FRAME_OPTIONS } from "../security/outbound-headers";
@@ -210,7 +210,7 @@ export function createGatewayApp(deps: GatewayAppDeps) {
     deps.mode === "route-only"
       ? (deps.checkRedis ?? checkRedisConnection)
       : checkRedisConnection;
-  const registry = new SurfaceAdapterRegistry([
+  const registry = new SurfaceAdapterRegistry<SurfaceAdapter & CanonicalAdapter>([
     chatAdapter,
     responsesAdapter,
     messagesAdapter,
@@ -424,12 +424,7 @@ export function createGatewayApp(deps: GatewayAppDeps) {
       db: deps.db,
       stateStore: requestStateStore,
       surfaceRegistry: registry,
-      adapters: new Map<string, CanonicalAdapter>([
-        ["chat", chatAdapter],
-        ["responses", responsesAdapter],
-        ["messages", messagesAdapter],
-        ["completion", completionAdapter],
-      ]),
+      adapters: new Map<string, CanonicalAdapter>(registry.bySurface()),
       preparer: deps.proxyPreparer,
       readiness: deps.readiness,
       trustedProxyBoundary: deps.trustedProxyBoundary,
@@ -652,10 +647,12 @@ export function createGatewayApp(deps: GatewayAppDeps) {
         // well-formed. What refused it is where it came from — the client asked
         // for something only the local host may ask. `invalid_request` told an
         // operator to fix the body, when the body was never the problem.
-        if (!isLoopbackPeer(peerAddresses.get(request) ?? null))
-          throw new GatewayError("policy_rejected", 403, "task trigger is only available from loopback (request {requestId}). This operation is only allowed from a trusted loopback connection — no hard feelings 🫂");
-        if (!tokenMatches(request.headers.get("x-drain-token"), token))
-          throw new GatewayError("authentication_failed", 401, "invalid drain token (request {requestId}). Wrong key, right door — check the token 🔑");
+        requireLoopbackAdmin(request, {
+          peer: peerAddresses.get(request) ?? null,
+          token,
+          policyRejectedMessage: "task trigger is only available from loopback (request {requestId}). This operation is only allowed from a trusted loopback connection — no hard feelings 🫂",
+          authenticationFailedMessage: "invalid drain token (request {requestId}). Wrong key, right door — check the token 🔑",
+        });
         const name = params.name;
         if (!tasks.names().includes(name))
           throw new GatewayError("not_found", 404, `no such task: ${name} (request {requestId}). Nothing here but dust — check the task name 🌙`);

package/src/boot/dependencies.ts

@@ -43,12 +43,10 @@ import { InMemoryIpAbuseStore, IpAbuseProtectionService, RedisIpAbuseStore, type
 import { checkReadiness } from "../persistence/readiness";
 import { ProxyRequestPreparer } from "../transport/request/preparer";
 import { DrizzleNetworkPoolLoader } from "../network/pool/loader";
-import {
-  PoolAgentResolver,
-  ValidatedNetworkBindingFactory,
-} from "../network/pool/resolver";
+import { PoolAgentResolver } from "../network/pool/resolver";
+import { ValidatedNetworkBindingFactory } from "../network/egress/factory";
 import { NetworkPoolSelector } from "../network/pool/selector";
-import { restorePoolProbeVerdicts, restoreProviderCooldownMarkers } from "../network/pool-cooldown-store";
+import { restorePoolProbeVerdicts, restoreProviderCooldownMarkers } from "../network/pool/cooldown-store";
 import { ScheduledTaskRegistry } from "../workers/scheduler";
 import { quotaRefreshSweep } from "../workers/quota-refresh-sweep";
 import { registerZcodeGiftClaimTask } from "../workers/zcode-gift-claim";
@@ -62,12 +60,12 @@ import {
 } from "../workers/buddy-growth-tasks";
 import { createAccountSecretResolver } from "../providers/operations/provider-credential-service";
 import { quotaCacheSize } from "../providers/quota/cache";
-import { modelCatalogCacheSize } from "../providers/operations/model-catalog-cache";
+import { modelCatalogCacheSize } from "../providers/operations/provider-caches";
 import { preferencesReaderFor } from "../persistence/tenant-preferences";
 import { sweepExpiredCooldowns } from "../providers/operations/account-health-service";
 import { DrizzleTelemetryStore } from "../persistence/stores/telemetry-store";
 import { TelemetryPayloadCapture } from "../observability/payload-capture";
-import { sweepExpiredPoolCooldowns } from "../network/pool-health-machine";
+import { sweepExpiredPoolCooldowns } from "../network/pool/health";
 import { TelemetryBatchBuffer } from "../observability/telemetry-buffer";
 import { RuntimeMetricsSampler } from "../observability/runtime-metrics";
 import {

package/src/boot/flush.ts

@@ -0,0 +1,20 @@
+// Shared drain sequence for the process's queued writers. The console's manual
+// "flush now" and the shutdown coordinator's telemetry flush must drain exactly
+// the same buffers in the same order — a fourth writer added to one path but
+// not the other would silently stop reaching the disk on one of them.
+//
+// The deps are the minimal write surface each buffer exposes: a `flush()` that
+// resolves when the buffer is drained. The concrete buffers satisfy it, and a
+// test can substitute stubs without casting.
+export interface FlushAllBuffersDeps {
+  readonly telemetryBuffer: { flush(): Promise<void> };
+  readonly usageFlush: { flush(): Promise<void> };
+  readonly healthEventFlush: { flush(): Promise<void> };
+}
+
+/** Drains every buffered writer, in the canonical order. */
+export async function flushAllBuffers(deps: FlushAllBuffersDeps): Promise<void> {
+  await deps.telemetryBuffer.flush();
+  await deps.usageFlush.flush();
+  await deps.healthEventFlush.flush();
+}

package/src/boot/lifecycle.ts

@@ -2,6 +2,7 @@ import { closeDb } from "../persistence/boot";
 import { closeRedis } from "../persistence/redis";
 import { buildProductionDeps } from "./dependencies";
 import type { ProductionDeps } from "./dependencies";
+import { flushAllBuffers } from "./flush";
 import { withTimeout } from "./timeout";
 import { resolveShutdownDrainWindowMs } from "../config/runtime";
 import { log } from "../observability/logger";
@@ -35,8 +36,11 @@ export class ShutdownCoordinator {
   ) {
     this.hooks = hooks ?? {};
     this.drainWindowMs = opts?.drainWindowMs ?? 20_000;
-    this.drainTimeoutMs = opts?.drainTimeoutMs ?? 5_000;
-    this.flushTimeoutMs = opts?.flushTimeoutMs ?? 2_000;
+    // Defaults mirror what `bootstrap()` passes (8_000 / 1_000; drainWindowMs
+    // 20_000 is the spec default `resolveShutdownDrainWindowMs()` returns), so
+    // reasoning about drain timing from the class alone matches production.
+    this.drainTimeoutMs = opts?.drainTimeoutMs ?? 8_000;
+    this.flushTimeoutMs = opts?.flushTimeoutMs ?? 1_000;
   }
 
   /**
@@ -217,9 +221,7 @@ export async function bootstrap(): Promise<CartethyiaBoot> {
     shutdownCoordinator: new ShutdownCoordinator(
       {
         flushTelemetry: async () => {
-          await deps.telemetryBuffer.flush();
-          await deps.usageFlush.flush();
-          await deps.healthEventFlush.flush();
+          await flushAllBuffers(deps);
         },
         closePools: async () => {
           await boot.server?.stop();

package/src/config/providers.ts

@@ -94,11 +94,12 @@ export function resolveGithubEnterpriseDomain(): string {
 export type GithubCopilotMode = "opencode-copilot" | "vscode-client-real";
 
 /**
- * Which GitHub Copilot wire identity the adapter uses. Defaults to
- * `opencode-copilot` (raw GitHub OAuth token + minimal OpenCode headers),
- * which is the proven-most-stable path (one token, no mint expiry). The
- * `vscode-client-real` mode matches the VS Code reference client exactly but
- * requires a freshly minted Copilot token.
+ * Selects the complete GitHub Copilot profile for OAuth login/refresh,
+ * inference, discovery, and quota identity. `opencode-copilot` is the default
+ * and uses the raw GitHub OAuth token with OpenCode identity. `vscode-client-real`
+ * uses the VS Code OAuth app and a minted Copilot token. Existing accounts must
+ * be re-authenticated after changing profiles; the upstream OAuth app binding
+ * prevents converting credentials between profiles.
  */
 export function resolveGithubCopilotMode(): GithubCopilotMode {
   const raw = readText(

package/src/config/routing.ts

@@ -0,0 +1,26 @@
+// Routing configuration knobs.
+import { CONFIG_SPEC, readInt } from "./spec";
+
+/** Routing reserve percent (0–100). Accounts at/below this remaining-quota % are demoted. */
+export function accountReservePct(): number {
+  return readInt(
+    "CARTETHYIA_ACCOUNT_RESERVE_PCT",
+    CONFIG_SPEC.CARTETHYIA_ACCOUNT_RESERVE_PCT,
+  );
+}
+
+/** Session-sticky warm window in ms. 0 disables stickiness. */
+export function routingStickyWarmMs(): number {
+  return readInt(
+    "CARTETHYIA_ROUTING_STICKY_WARM_MS",
+    CONFIG_SPEC.CARTETHYIA_ROUTING_STICKY_WARM_MS,
+  );
+}
+
+/** LRU cap on remembered session→account sticky state per provider. */
+export function routingStickyMaxSessions(): number {
+  return readInt(
+    "CARTETHYIA_ROUTING_STICKY_MAX_SESSIONS",
+    CONFIG_SPEC.CARTETHYIA_ROUTING_STICKY_MAX_SESSIONS,
+  );
+}

package/src/config/spec-metadata.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared metadata for config docs and tests.
+ *
+ * `CONFIG_SPEC` declares the gateway's spec-driven variables. These constants
+ * name the deliberate asymmetries around it so `.env.example`, the generated
+ * reference, and the drift tests all project the same exception lists.
+ */
+
+/** Keys in `CONFIG_SPEC` that are intentionally absent from `.env.example`. */
+export const SPEC_ONLY_ENV_EXAMPLE_KEYS: Readonly<Record<string, true>> = {
+  // Setup wizard writes this directly; a sample would mislead copy/paste.
+  CARTETHYIA_API_KEY: true,
+  // Opt-in diagnostics; sampling them would nudge operators to enable them.
+  CARTETHYIA_FORCED_GC: true,
+  CARTETHYIA_RUNTIME_METRICS_INTERVAL_MS: true,
+  // Advanced knobs documented in the generated configuration reference.
+  CARTETHYIA_DISABLED_TASKS: true,
+  // Install-identity directory; only operators who need a stable identity
+  // across restarts touch it, and the reference covers it.
+  CARTETHYIA_INSTALL_ID_DIR: true,
+  CARTETHYIA_OAUTH_CALLBACK_PORT: true,
+  // Provider-specific overrides. Readers live in `src/config/providers.ts`;
+  // the majority of installs do not need them in the starter sample.
+  CARTETHYIA_KIMI_OAUTH_HOST: true,
+  CARTETHYIA_KIMI_QUOTA_BASE_URL: true,
+  CARTETHYIA_GITHUB_ENTERPRISE_DOMAIN: true,
+  CARTETHYIA_OPENCODE_UNAVAILABLE_FREE: true,
+  // Telemetry retention is deployment-level and documented in the reference.
+  CARTETHYIA_TELEMETRY_RETENTION_DAYS: true,
+  CARTETHYIA_TELEMETRY_PAYLOAD_MAX_BYTES: true,
+};
+
+/** Keys in `.env.example` that `CONFIG_SPEC` does not declare. */
+export const ENV_EXAMPLE_ONLY_KEYS: Readonly<Record<string, true>> = {
+  // Read outside `src/config/` by their owning modules.
+  CARTETHYIA_DB_MODE: true,
+  NODE_ENV: true,
+  LOG_LEVEL: true,
+  DATABASE_URL: true,
+  DATABASE_POOL_MAX: true,
+  DATABASE_POOL_IDLE_FLOOR: true,
+  REDIS_URL: true,
+  CARTETHYIA_DATA_DIR: true,
+  CARTETHYIA_TELEMETRY_PAYLOAD_DIR: true,
+  CARTETHYIA_CONFIG_DIR: true,
+  DASHBOARD_PORT: true,
+  VITE_BACKEND_URL: true,
+  // Test-runner-only knob, not read by the gateway runtime.
+  CARTETHYIA_TEST_JOBS: true,
+};
+
+/**
+ * Operator-visible variables that are intentionally outside `CONFIG_SPEC` and
+ * therefore omitted from the generated configuration reference.
+ */
+export const CONFIG_REFERENCE_EXTERNAL_VARIABLES = [
+  "CARTETHYIA_DB_MODE",
+  "DATABASE_URL",
+  "REDIS_URL",
+  "NODE_ENV",
+  "LOG_LEVEL",
+  "DATABASE_POOL_MAX",
+  "DATABASE_POOL_IDLE_FLOOR",
+  "CARTETHYIA_DATA_DIR",
+  "CARTETHYIA_TELEMETRY_PAYLOAD_DIR",
+  "CARTETHYIA_CONFIG_DIR",
+  "DASHBOARD_PORT",
+  "VITE_BACKEND_URL",
+  "CARTETHYIA_TEST_DATABASE_URL",
+  "CARTETHYIA_TEST_JOBS",
+  "CARTETHYIA_REDIS_URL",
+] as const;

package/src/config/spec.ts

@@ -264,6 +264,26 @@ export const CONFIG_SPEC = {
   CARTETHYIA_ACCOUNT_AUTH_REJECTED_COOLDOWN_MS: { kind: "int", default: 300_000, min: 0, max: 86_400_000 },
   CARTETHYIA_ACCOUNT_POLICY_BLOCK_COOLDOWN_MS: { kind: "int", default: 300_000, min: 0, max: 86_400_000 },
   CARTETHYIA_ACCOUNT_DISABLED_RECOVERY_MS: { kind: "int", default: 86_400_000, min: 0, max: 604_800_000 },
+  /**
+   * Routing reserve: an account whose remaining quota fraction falls at or
+   * below this percent is demoted behind non-reserve siblings during ordering
+   * (it is still eligible and still routed — a reserve is a preference, never
+   * an exclusion). 0 disables reserve demotion for every account.
+   */
+  CARTETHYIA_ACCOUNT_RESERVE_PCT: { kind: "int", default: 20, min: 0, max: 100 },
+  /**
+   * Session stickiness warm window (milliseconds). Within this window after an
+   * account last served a session id, routing prefers that account when it is
+   * still eligible — prompt-cache warmth is worth more than perfect load
+   * balance. Past the window, the sticky account is only an ordering hint.
+   * 0 disables stickiness.
+   */
+  CARTETHYIA_ROUTING_STICKY_WARM_MS: { kind: "int", default: 300_000, min: 0, max: 86_400_000 },
+  /**
+   * Hard ceiling on distinct session ids whose sticky state is retained in
+   * memory per provider (LRU). Evicted sessions simply lose their preference.
+   */
+  CARTETHYIA_ROUTING_STICKY_MAX_SESSIONS: { kind: "int", default: 256, min: 1, max: 10_000 },
 
   // Proxy pool agents
   CARTETHYIA_PROXY_MAX_SOCKETS: { kind: "int", default: 100, min: 1, max: 100_000 },
@@ -306,15 +326,15 @@ export const CONFIG_SPEC = {
    */
   CARTETHYIA_GITHUB_ENTERPRISE_DOMAIN: { kind: "text", default: "" },
   /**
-   * Which wire identity the GitHub Copilot Auto/chat path presents to the
-   * upstream:
+   * Selects the complete GitHub Copilot OAuth and wire profile:
+   *
+   * - `opencode-copilot` (default): OpenCode OAuth app, raw GitHub token, and
+   *   OpenCode identity for login, refresh, inference, discovery, and quota.
+   * - `vscode-client-real`: VS Code OAuth app, minted Copilot token, and the
+   *   VS Code reference identity for those surfaces.
    *
-   * - `opencode-copilot` (default): the long-lived GitHub OAuth token + minimal
-   *   OpenCode headers. One token, no mint step, no short-lived minted-token
-   *   expiry. This is the most stable in practice.
-   * - `vscode-client-real`: a freshly minted Copilot token + the full VS Code
-   *   reference headers. Matches the VS Code client exactly, but requires the
-   *   minted token (expires ~25 min) and the reference identity.
+   * Restart after changing this setting and re-authenticate GitHub accounts;
+   * OAuth credentials cannot be converted between the two upstream apps.
    */
   CARTETHYIA_GITHUB_COPILOT_MODE: { kind: "text", default: "opencode-copilot" },
   // Only the literal true opts active ZCode accounts into daily gift claims.

package/src/console/api-keys/contracts.ts

@@ -11,7 +11,7 @@ import { type ShareLinkStore, type ShareLinkSummary } from "../../persistence/st
 import { API_KEY_MODES, API_KEY_CONCURRENCY_SCOPES, type ApiKeyMode, type ApiKeyModelAccessMode, type ShareLinkKind } from "../../persistence/schema";
 import { isValidTenantKeyScope, type AccessScope } from "../../security/access-control";
 import { normalizeClientRouterId } from "../../security/client-router-fingerprint";
-import type { ShareActivityPort } from "../share/share-usage";
+import type { ShareActivityPort, SharedKeySummary } from "../share/share-usage";
 import { ConsoleDomainError } from "../shared/errors";
 import { pickDefined } from "../shared/object";
 import type { ConsoleAccessResolver } from "../auth/access";
@@ -35,6 +35,17 @@ export type {
   SharedKeySummary,
   SharedKeyActivityDetail,
 } from "../share/share-usage";
+
+/** Paged response of the share-child list endpoint. */
+export interface SharedKeyPage {
+  readonly rows: readonly SharedKeySummary[];
+  readonly total: number;
+  readonly active: number;
+  readonly revoked: number;
+  /** Family-wide lifetime tokens consumed, independent of the page. */
+  readonly consumed: number;
+}
+
 /** How a share template's concurrency cap applies to its recipients. */
 export type ConcurrencyScope = (typeof API_KEY_CONCURRENCY_SCOPES)[number];