cartethyia 2.7.8 → 2.8.0

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";
@@ -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

@@ -39,7 +39,7 @@ import { setPendingUsageSource } from "../security/api-key-auth";
 import { HealthEventFlushBuffer, setHealthEventBuffer } from "../persistence/health-event-flush";
 import { subscribePeerSettingsRevisions } from "../persistence/settings-revision";
 import { deleteExpiredSessions } from "../console/auth/session-service";
-import { InMemoryIpAbuseStore, IpAbuseProtectionService, RedisIpAbuseStore } from "../security/abuse";
+import { InMemoryIpAbuseStore, IpAbuseProtectionService, RedisIpAbuseStore, type IpAbuseStore } from "../security/abuse";
 import { checkReadiness } from "../persistence/readiness";
 import { ProxyRequestPreparer } from "../transport/request/preparer";
 import { DrizzleNetworkPoolLoader } from "../network/pool/loader";
@@ -62,7 +62,7 @@ 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";
@@ -104,6 +104,8 @@ export interface ProductionDeps {
   proxyPreparer: ProxyRequestPreparer;
   networkBindingFactory: ValidatedNetworkBindingFactory;
   ipAbuseProtection: IpAbuseProtectionService;
+  /** The abuse store backing manual IP bans and the ban list. */
+  ipAbuseStore: IpAbuseStore;
   readiness: () => Promise<ReadinessCheckResult>;
   scheduledTasks: ScheduledTaskRegistry;
   poolAgentResolver: PoolAgentResolver;
@@ -593,6 +595,11 @@ export async function buildProductionDeps(): Promise<ProductionDeps> {
     name: "client-version-monitor",
     intervalMs: CLIENT_VERSION_MONITOR_INTERVAL_MS,
     initialDelayMs: CLIENT_VERSION_INITIAL_DELAY_MS,
+    // Pure outbound reads with no shared rows/files: they must not be gated
+    // by the process-wide busy latch, or a nearly-continuous heavy sweep
+    // (quota-refresh) starves this monitor at its single initial tick and
+    // every 30-minute interval after it.
+    skipGate: true,
     run: refreshProviderClientVersions,
   });
 
@@ -606,13 +613,13 @@ export async function buildProductionDeps(): Promise<ProductionDeps> {
   // first open after an expiry always blocks on the provider.
   //
   // It also carries the daily check-in ride-along: each account refreshed
-  // here gets its once-per-day WorkBuddy/CodeBuddy credit grant claimed in
+  // here gets its once-per-day CodeBuddy credit grant claimed in
   // the same pass (one attempt per account per day, guarded by a day
   // marker), so no second timer duplicates the credential resolution.
   //
   // Registered in **every** mode, not only when Redis is present: gating it on
   // Redis would cost Lite proactive quota warming and the check-in ride-along
-  // above that claims the once-per-day WorkBuddy/CodeBuddy credit grant. The
+  // above that claims the once-per-day CodeBuddy credit grant. The
   // whole sweep chain accepts `RedisClient | undefined` and falls back to the
   // in-process TTL cache and an in-process day marker, so Redis is an
   // optimization here rather than a precondition — which is exactly what
@@ -739,6 +746,7 @@ export async function buildProductionDeps(): Promise<ProductionDeps> {
     }),
     networkBindingFactory,
     ipAbuseProtection,
+    ipAbuseStore: ipStore,
     readiness,
     scheduledTasks,
     poolAgentResolver,

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/cooldowns.ts

@@ -119,7 +119,7 @@ export function resolveAccountAuthRejectedCooldownMs(): number {
  * Deliberately a *base*, not the 24h flat penalty it replaced. `11140` has two
  * documented causes our classifier cannot separate from the response alone: the
  * user's prompt failed a safety review, **and** sending the wrong desktop
- * `User-Agent` brand (`workbuddy/shared.ts`). A flat 24h meant that after we
+ * `User-Agent` brand (`codebuddy/shared.ts`). A flat 24h meant that after we
  * fixed a header regression every buddy account stayed dead for up to a further
  * day, and one unsafe prompt cost a whole account a day.
  *

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

@@ -173,12 +173,6 @@ export const CONFIG_SPEC = {
    */
   CARTETHYIA_DISABLED_TASKS: { kind: "list" },
 
-  /**
-   * Force the Qoder UMID bridge to the mini-ELF bundle on Linux
-   * (`1` = always mini, `0` = never mini; absent = auto-detect containers).
-   */
-  CARTETHYIA_QODER_UMID_MINI: { kind: "int", default: 0, min: 0, max: 1 },
-
   /**
    * How long a day's telemetry is kept, in days.
    *
@@ -270,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 },

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];
 

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

@@ -78,25 +78,53 @@ function parseSharedChildrenQuery(query: URLSearchParams): SharedChildrenPageOpt
   return { limit, offset, sortBy, order, status };
 }
 
+/**
+ * Drops the auth-cache snapshot for a key family: the parent first, then
+ * every child.
+ *
+ * Parent policy is live-inherited by children at auth time, so their cached
+ * snapshots must die with the parent — otherwise a denylist / budget edit
+ * looks like a no-op for up to AUTH_CACHE_TTL_MS per child.
+ */
+function invalidateFamilyCaches(keyId: string, children: readonly ApiKeyRecord[]): void {
+  invalidateApiKeyCache(keyId);
+  for (const child of children) invalidateApiKeyCache(child.id);
+}
+
+/**
+ * Purges admission counters for a key family: the parent first, then every
+ * child.
+ *
+ * Share children admit under the parent id, so the parent's counter must die
+ * with a revoked/regenerated parent too — otherwise a family budget can be
+ * bypassed by a counter seeded under the old credential.
+ */
+async function purgeFamilyAdmission(
+  admissionService: { purgeKey(apiKeyId: string): Promise<void> },
+  keyId: string,
+  children: readonly ApiKeyRecord[],
+): Promise<void> {
+  await Promise.all([
+    admissionService.purgeKey(keyId),
+    ...children.map((child) => admissionService.purgeKey(child.id)),
+  ]);
+}
+
 export function createApiKeyOperations(config: ApiKeyConfig) {
   const operations = {
-    async listKeys(access: AccessDecision | undefined): Promise<ApiKeyResponse[]> {
+    async listKeys(access: AccessDecision | undefined, includeChildren = false): Promise<ApiKeyResponse[]> {
         const authorized = requireTenantScope(access, "dashboard:read");
         const records = await config.store.list(authorized.tenantId);
         const topLevel = records.filter(
           (record) => record.revokedAt === undefined && record.parentKeyId === undefined,
         );
-        // A share template's own counter is the live family accumulator now:
-        // every recipient commit adds to it (see ApiKeyAdmissionService
-        // commitUsage), so reporting it raw gives the enforced family total.
-        // No telemetry add-on is needed, and adding it here would double-count.
-        return Promise.all(
-          topLevel.map(async (record) => {
-            const response = sanitizeApiKeyResponse(record);
-            if (record.keyMode !== "share") return response;
-            return response;
-          }),
-      );
+        // Share children are omitted from the main key list (they belong to a
+        // template), but the Banned Users search wants them so a child can be
+        // found and banned by hand.
+        const visible = includeChildren
+          ? records.filter((record) => record.revokedAt === undefined)
+          : topLevel;
+        return visible.map(sanitizeApiKeyResponse);
     },
     async listActiveBannedKeys(access: AccessDecision | undefined): Promise<ApiKeyResponse[]> {
       const authorized = requireTenantScope(access, "dashboard:read");
@@ -337,11 +365,7 @@ export function createApiKeyOperations(config: ApiKeyConfig) {
       });
       if (!updated) throw new ConsoleDomainError("key_not_found", 404, "Key not found");
       const children = await config.store.listChildren(authorized.tenantId, keyId);
-      // Parent policy is live-inherited by children at auth time, so their
-      // cached snapshots must die with the parent — otherwise a denylist /
-      // budget edit looks like a no-op for up to AUTH_CACHE_TTL_MS per child.
-      invalidateApiKeyCache(keyId);
-      for (const child of children) invalidateApiKeyCache(child.id);
+      invalidateFamilyCaches(keyId, children);
       // The allow/deny list and prefix decide which models `/v1/models`
       // returns, which is a different cache from the auth snapshot: the
       // listing is cached per (tenant, key, mode, list, prefix), so editing
@@ -391,10 +415,7 @@ export function createApiKeyOperations(config: ApiKeyConfig) {
         // Drop stale admission counters so a newly lowered one-time/recurring
         // budget cannot be bypassed by a counter seeded under the looser limit.
         // Share children admit under the parent id, so purge the parent too.
-        await Promise.all([
-          config.admissionService.purgeKey(keyId),
-          ...children.map((child) => config.admissionService.purgeKey(child.id)),
-        ]);
+        await purgeFamilyAdmission(config.admissionService, keyId, children);
       }
       // Adding a daily/monthly ceiling to a key that already spent in the
       // current bucket must not hand it a full fresh budget: seed the counter
@@ -441,12 +462,8 @@ export function createApiKeyOperations(config: ApiKeyConfig) {
       const children = await config.store.listChildren(authorized.tenantId, keyId);
       const removed = await config.store.remove(authorized.tenantId, keyId);
       if (!removed) throw new ConsoleDomainError("key_not_found", 404, "Key not found");
-      invalidateApiKeyCache(keyId);
-      for (const child of children) invalidateApiKeyCache(child.id);
-      await Promise.all([
-        config.admissionService.purgeKey(keyId),
-        ...children.map((child) => config.admissionService.purgeKey(child.id)),
-      ]);
+      invalidateFamilyCaches(keyId, children);
+      await purgeFamilyAdmission(config.admissionService, keyId, children);
       await config.auditSink?.record({
         access: authorized,
         action: "api_key.deleted",
@@ -620,8 +637,9 @@ export function createApiKeyOperations(config: ApiKeyConfig) {
         keyPrefix: generated.prefix,
       });
       if (!updated) throw new ConsoleDomainError("key_not_found", 404, "Key not found");
-      invalidateApiKeyCache(keyId);
-      await config.admissionService.purgeKey(keyId);
+      // Regeneration is personal-key only, so the family is the key itself.
+      invalidateFamilyCaches(keyId, []);
+      await purgeFamilyAdmission(config.admissionService, keyId, []);
       const shareStore = config.shareStore;
       let share: ShareKeyResponse | null = null;
       if (shareStore) {
@@ -921,9 +939,10 @@ function jsonNull(): Response {
 export function createApiKeyRoutes(config: ApiKeyConfig): AnyElysia {
   const factory = createApiKeyOperations(config);
   return new Elysia({ prefix: "/api-keys" })
-    .get("/", async ({ request, set }) => {
+    .get("/", async ({ request, set, query }) => {
       try {
-        return await factory.listKeys(config.accessResolver(request));
+        const includeChildren = query?.["includeChildren"] === "1" || query?.["includeChildren"] === "true";
+        return await factory.listKeys(config.accessResolver(request), includeChildren);
       } catch (error) {
         return errorResponse(error, set, "API-key operation failed");
       }

package/src/console/auth/account-reset.ts

@@ -23,7 +23,7 @@
  * the operator to type it rather than press Enter on a menu row.
  */
 import { GatewayError } from "../../protocol/gateway-error";
-import { isLoopbackPeer, tokenMatches } from "../../transport/drain-endpoint";
+import { requireLoopbackAdmin } from "../../transport/drain-endpoint";
 
 interface ConsoleAccountResetDeps {
   /** Shared secret; the route is registered only when this is set. */
@@ -40,14 +40,12 @@ export function createConsoleAccountResetHandler(
   deps: ConsoleAccountResetDeps,
 ): (context: { request: Request; body: unknown }) => Promise<Response> {
   return async ({ request, body }) => {
-    if (!isLoopbackPeer(deps.resolvePeerAddress(request)))
-      throw new GatewayError(
-        "policy_rejected",
-        403,
-        "console account reset 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"), deps.token))
-      throw new GatewayError("authentication_failed", 401, "invalid reset token (request {requestId}). Wrong key, right door — check the token 🔑");
+    requireLoopbackAdmin(request, {
+      peer: deps.resolvePeerAddress(request),
+      token: deps.token,
+      policyRejectedMessage: "console account reset is only available from loopback (request {requestId}). This operation is only allowed from a trusted loopback connection — no hard feelings 🫂",
+      authenticationFailedMessage: "invalid reset token (request {requestId}). Wrong key, right door — check the token 🔑",
+    });
     const confirm =
       body !== null && typeof body === "object" && "confirm" in body
         ? body.confirm

package/src/console/backup/contracts.ts

@@ -20,6 +20,8 @@
  * as sensitive as the database.
  */
 import { getTableColumns, getTableName, type Column, type Table } from "drizzle-orm";
+import type { BackupInspection } from "./service";
+import type { DeleteAllScope } from "./store";
 import { resolveMaxBodyBytes } from "../../config/runtime";
 import {
   apiKeys,
@@ -393,6 +395,8 @@ export type BackupSection = "config" | "telemetry";
 
 export const BACKUP_SECTIONS: readonly BackupSection[] = ["config", "telemetry"];
 
+export type { BackupInspection, DeleteAllScope };
+
 export interface BackupPayload {
   readonly app: typeof BACKUP_APP;
   readonly version: number;

package/src/console/backup/export-endpoint.ts

@@ -22,7 +22,7 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { GatewayError } from "../../protocol/gateway-error";
-import { isLoopbackPeer, tokenMatches } from "../../transport/drain-endpoint";
+import { requireLoopbackAdmin } from "../../transport/drain-endpoint";
 import { tablesForSection } from "./contracts";
 import { compressBackupStream, exportBackupStream } from "./store";
 import type { CartethyiaDatabase } from "../../persistence/db-handle";
@@ -52,10 +52,12 @@ export function createBackupExportHandler(
     // both: neither refusal is about the body. The first is where the request
     // came from, the second is the credential it carried — and `invalid_request`
     // told an operator to fix a body that was never the problem.
-    if (!isLoopbackPeer(deps.resolvePeerAddress(request)))
-      throw new GatewayError("policy_rejected", 403, "backup export 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"), deps.token))
-      throw new GatewayError("authentication_failed", 401, "invalid export token (request {requestId}). Wrong key, right door — check the token 🔑");
+    requireLoopbackAdmin(request, {
+      peer: deps.resolvePeerAddress(request),
+      token: deps.token,
+      policyRejectedMessage: "backup export is only available from loopback (request {requestId}). This operation is only allowed from a trusted loopback connection — no hard feelings 🫂",
+      authenticationFailedMessage: "invalid export token (request {requestId}). Wrong key, right door — check the token 🔑",
+    });
 
     const directory =
       body !== null && typeof body === "object" && "directory" in body

package/src/console/cli-tools/service.ts

@@ -8,7 +8,6 @@ import type {
   CliMappingSettings,
   DownloadResult,
   ToolDef,
-  ToolInjector,
   ToolStatus,
 } from "./contracts";
 import { TOOL_IDS, TOOL_REGISTRY, type ToolId, type ToolRegistryEntry } from "./contracts";
@@ -47,11 +46,6 @@ function toToolRegistryEntry(def: ToolDef): ToolRegistryEntry {
   };
 }
 
-function injectorFor(toolId: string): ToolInjector | null {
-  const injector = INJECTORS[toolId as ToolId];
-  return injector ?? null;
-}
-
 /** Operator-facing summary of what an apply actually did. */
 function applyMessage(outcome: ApplyOutcome, toolId: string, fileMessage: string): string {
   switch (outcome) {
@@ -139,8 +133,8 @@ export class CliToolService {
   }
 
   async getStatus(toolId: string): Promise<ToolStatus | null> {
-    const injector = injectorFor(toolId);
-    if (injector === null) return null;
+    const injector = INJECTORS[toolId as ToolId];
+    if (injector === undefined) return null;
     return injector.getStatus();
   }
 
@@ -249,8 +243,8 @@ export class CliToolService {
   }
 
   async downloadConfig(toolId: string, input: ApplyInput): Promise<DownloadResult | null> {
-    const injector = injectorFor(toolId);
-    if (injector === null) return null;
+    const injector = INJECTORS[toolId as ToolId];
+    if (injector === undefined) return null;
     if (!input.endpoint || !input.apiKey) return null;
     try {
       return await injector.download(input);
@@ -281,8 +275,8 @@ export class CliToolService {
     apiKeyId: string,
     input: ApplyInput & { mode?: "file" | "remote" | "both" },
   ): Promise<ApplyConfigResult | null> {
-    const injector = injectorFor(toolId);
-    if (injector === null) return null;
+    const injector = INJECTORS[toolId as ToolId];
+    if (injector === undefined) return null;
     const mode = input.mode ?? "both";
     const wantsFile = mode === "file" || mode === "both";
     const wantsRemote = mode === "remote" || mode === "both";