cartethyia 2.5.9 → 2.6.0

package/scripts/cli/update.ts

@@ -1,40 +1,40 @@
-/**
- * The update path.
- *
- * npm cannot replace this package's directory while a process is executing out
- * of it (EBUSY on Windows). So we spawn the installer as a detached process,
- * print a short notice, and exit — the installer runs after this process is gone.
- * After install, it attempts to restart the gateway (systemd if available, else
- * `cartethyia start`), so the new version comes up automatically.
- * Cross-OS: uses npm.cmd on Windows.
- */
-import { spawn } from "node:child_process";
-
-export function updateCommand(): string {
-  return "npm install -g cartethyia@latest --prefer-online";
-}
-
-export function runDetachedUpdate(): void {
-  const isWin = process.platform === "win32";
-  const shell = isWin ? "cmd.exe" : "/bin/sh";
-  const install = "npm install -g cartethyia@latest --prefer-online";
-  const restart = isWin
-    ? "cartethyia start"
-    : "systemctl restart cartethyia 2>/dev/null || cartethyia start";
-  const script = `${install} && ${restart}`;
-  const args = isWin ? ["/c", script] : ["-c", script];
-  const child = spawn(shell, args, {
-    detached: true,
-    stdio: "ignore",
-  });
-  child.unref();
-}
-
-export function printUpdateInstructions(from: string, to: string | null): void {
-  console.log("");
-  console.log(`Update available: ${from} \u2192 ${to ?? "latest"}`);
-  console.log("");
-  console.log("Starting detached update; this process will exit now.");
-  console.log("The gateway will restart automatically after the install.");
-  console.log("");
+/**
+ * The update path.
+ *
+ * npm cannot replace this package's directory while a process is executing out
+ * of it (EBUSY on Windows). So we spawn the installer as a detached process,
+ * print a short notice, and exit — the installer runs after this process is gone.
+ * After install, it attempts to restart the gateway (systemd if available, else
+ * `cartethyia start`), so the new version comes up automatically.
+ * Cross-OS: uses npm.cmd on Windows.
+ */
+import { spawn } from "node:child_process";
+
+export function updateCommand(): string {
+  return "npm install -g cartethyia@latest --prefer-online";
+}
+
+export function runDetachedUpdate(): void {
+  const isWin = process.platform === "win32";
+  const shell = isWin ? "cmd.exe" : "/bin/sh";
+  const install = "npm install -g cartethyia@latest --prefer-online";
+  const restart = isWin
+    ? "cartethyia start"
+    : "systemctl restart cartethyia 2>/dev/null || cartethyia start";
+  const script = `${install} && ${restart}`;
+  const args = isWin ? ["/c", script] : ["-c", script];
+  const child = spawn(shell, args, {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+}
+
+export function printUpdateInstructions(from: string, to: string | null): void {
+  console.log("");
+  console.log(`Update available: ${from} \u2192 ${to ?? "latest"}`);
+  console.log("");
+  console.log("Starting detached update; this process will exit now.");
+  console.log("The gateway will restart automatically after the install.");
+  console.log("");
 }

package/scripts/cli/version.ts

@@ -1,67 +1,67 @@
-import { resolvePackagePath } from "../../src/config/package-paths";
-
-export async function readRequiredBunVersion(): Promise<string> {
-  const metadata: unknown = await Bun.file(resolvePackagePath("package.json")).json();
-  if (metadata === null || typeof metadata !== "object" || !("engines" in metadata) ||
-    metadata.engines === null || typeof metadata.engines !== "object" ||
-    !("bun" in metadata.engines) || typeof metadata.engines.bun !== "string") {
-    throw new Error("Cartethyia's required Bun version is unavailable in package.json");
-  }
-  const minimum = metadata.engines.bun.trim().replace(/^>=\s*/, "");
-  if (!/^\d+(?:\.\d+){0,2}$/.test(minimum)) throw new Error(`Unsupported Bun engine requirement: ${metadata.engines.bun}`);
-  return minimum;
-}
-
-export function bunVersionAtLeast(actual: string, minimum: string): boolean {
-  const left = actual.split(".").map((part) => Number.parseInt(part, 10) || 0);
-  const right = minimum.split(".").map((part) => Number.parseInt(part, 10) || 0);
-  const length = Math.max(left.length, right.length);
-  for (let i = 0; i < length; i += 1) {
-    const a = left[i] ?? 0;
-    const b = right[i] ?? 0;
-    if (a !== b) return a > b;
-  }
-  return true;
-}
-
-export async function assertBunVersion(): Promise<void> {
-  const minimum = await readRequiredBunVersion();
-  if (bunVersionAtLeast(Bun.version, minimum)) return;
-  throw new Error(`Bun ${minimum} or newer is required (found ${Bun.version}). Install it from https://bun.sh and run this command again.`);
-}
-
-/** Reads the version from the installed package manifest. */
-export async function readInstalledVersion(): Promise<string> {
-  const metadata: unknown = await Bun.file(resolvePackagePath("package.json")).json();
-  if (
-    metadata === null ||
-    typeof metadata !== "object" ||
-    !("version" in metadata) ||
-    typeof metadata.version !== "string"
-  ) {
-    throw new Error("Cartethyia package version is unavailable");
-  }
-  return metadata.version;
-}
-
-/** Asks the npm registry for the newest published version, or null on failure. */
-export async function readLatestPublishedVersion(): Promise<string | null> {
-  try {
-    const response = await fetch("https://registry.npmjs.org/cartethyia/latest", {
-      signal: AbortSignal.timeout(4_000),
-    });
-    if (!response.ok) return null;
-    const metadata: unknown = await response.json();
-    if (
-      metadata !== null &&
-      typeof metadata === "object" &&
-      "version" in metadata &&
-      typeof metadata.version === "string"
-    ) {
-      return metadata.version;
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
+import { resolvePackagePath } from "../../src/config/package-paths";
+
+export async function readRequiredBunVersion(): Promise<string> {
+  const metadata: unknown = await Bun.file(resolvePackagePath("package.json")).json();
+  if (metadata === null || typeof metadata !== "object" || !("engines" in metadata) ||
+    metadata.engines === null || typeof metadata.engines !== "object" ||
+    !("bun" in metadata.engines) || typeof metadata.engines.bun !== "string") {
+    throw new Error("Cartethyia's required Bun version is unavailable in package.json");
+  }
+  const minimum = metadata.engines.bun.trim().replace(/^>=\s*/, "");
+  if (!/^\d+(?:\.\d+){0,2}$/.test(minimum)) throw new Error(`Unsupported Bun engine requirement: ${metadata.engines.bun}`);
+  return minimum;
+}
+
+export function bunVersionAtLeast(actual: string, minimum: string): boolean {
+  const left = actual.split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const right = minimum.split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const length = Math.max(left.length, right.length);
+  for (let i = 0; i < length; i += 1) {
+    const a = left[i] ?? 0;
+    const b = right[i] ?? 0;
+    if (a !== b) return a > b;
+  }
+  return true;
+}
+
+export async function assertBunVersion(): Promise<void> {
+  const minimum = await readRequiredBunVersion();
+  if (bunVersionAtLeast(Bun.version, minimum)) return;
+  throw new Error(`Bun ${minimum} or newer is required (found ${Bun.version}). Install it from https://bun.sh and run this command again.`);
+}
+
+/** Reads the version from the installed package manifest. */
+export async function readInstalledVersion(): Promise<string> {
+  const metadata: unknown = await Bun.file(resolvePackagePath("package.json")).json();
+  if (
+    metadata === null ||
+    typeof metadata !== "object" ||
+    !("version" in metadata) ||
+    typeof metadata.version !== "string"
+  ) {
+    throw new Error("Cartethyia package version is unavailable");
+  }
+  return metadata.version;
+}
+
+/** Asks the npm registry for the newest published version, or null on failure. */
+export async function readLatestPublishedVersion(): Promise<string | null> {
+  try {
+    const response = await fetch("https://registry.npmjs.org/cartethyia/latest", {
+      signal: AbortSignal.timeout(4_000),
+    });
+    if (!response.ok) return null;
+    const metadata: unknown = await response.json();
+    if (
+      metadata !== null &&
+      typeof metadata === "object" &&
+      "version" in metadata &&
+      typeof metadata.version === "string"
+    ) {
+      return metadata.version;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}

package/scripts/cli/wordmark.ts

@@ -1,58 +1,58 @@
-/**
- * The console wordmark.
- *
- * Rendered with half-block characters so each letter is two pixel rows tall in
- * one character cell, and coloured with a horizontal gradient across the
- * Cartethyia blue-grey range. The caller decides whether to print it: a
- * non-colour terminal, or one narrower than the wordmark, should skip it.
- */
-
-const WORDMARK: readonly string[] = [
-  " ██████╗ █████╗ ██████╗ ████████╗███████╗████████╗██╗  ██╗██╗   ██╗██╗ █████╗ ",
-  "██╔════╝██╔══██╗██╔══██╗╚══██╔══╝██╔════╝╚══██╔══╝██║  ██║╚██╗ ██╔╝██║██╔══██╗",
-  "██║     ███████║██████╔╝   ██║   █████╗     ██║   ███████║ ╚████╔╝ ██║███████║",
-  "██║     ██╔══██║██╔══██╗   ██║   ██╔══╝     ██║   ██╔══██║  ╚██╔╝  ██║██╔══██║",
-  "╚██████╗██║  ██║██║  ██║   ██║   ███████╗   ██║   ██║  ██║   ██║   ██║██║  ██║",
-  " ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝   ╚══════╝   ╚═╝   ╚═╝  ╚═╝   ╚═╝   ╚═╝╚═╝  ╚═╝",
-];
-
-/** Blue-grey gradient: dim at the edges, brighter through the middle. */
-const GRADIENT: readonly [number, number, number][] = [
-  [90, 120, 150],
-  [120, 160, 200],
-  [150, 200, 240],
-  [120, 160, 200],
-  [90, 120, 150],
-];
-
-const RESET = "\u001b[0m";
-
-/**
- * Returns the wordmark lines with per-column colour, or an empty array when the
- * terminal is too narrow or colour is disabled.
- */
-export function renderWordmark(columns = process.stdout.columns ?? 80): string[] {
-  if (process.env.NO_COLOR !== undefined) return [];
-  const width = WORDMARK[0]!.length;
-  if (columns < width) return [];
-
-  const coloured: string[] = [];
-  for (const row of WORDMARK) {
-    let line = "";
-    let current = -1;
-    for (let column = 0; column < row.length; column += 1) {
-      const band = Math.min(
-        GRADIENT.length - 1,
-        Math.floor((column / width) * GRADIENT.length),
-      );
-      const [r, g, b] = GRADIENT[band]!;
-      if (band !== current) {
-        line += `\u001b[38;2;${r};${g};${b}m`;
-        current = band;
-      }
-      line += row[column];
-    }
-    coloured.push(`${line}${RESET}`);
-  }
-  return coloured;
-}
+/**
+ * The console wordmark.
+ *
+ * Rendered with half-block characters so each letter is two pixel rows tall in
+ * one character cell, and coloured with a horizontal gradient across the
+ * Cartethyia blue-grey range. The caller decides whether to print it: a
+ * non-colour terminal, or one narrower than the wordmark, should skip it.
+ */
+
+const WORDMARK: readonly string[] = [
+  " ██████╗ █████╗ ██████╗ ████████╗███████╗████████╗██╗  ██╗██╗   ██╗██╗ █████╗ ",
+  "██╔════╝██╔══██╗██╔══██╗╚══██╔══╝██╔════╝╚══██╔══╝██║  ██║╚██╗ ██╔╝██║██╔══██╗",
+  "██║     ███████║██████╔╝   ██║   █████╗     ██║   ███████║ ╚████╔╝ ██║███████║",
+  "██║     ██╔══██║██╔══██╗   ██║   ██╔══╝     ██║   ██╔══██║  ╚██╔╝  ██║██╔══██║",
+  "╚██████╗██║  ██║██║  ██║   ██║   ███████╗   ██║   ██║  ██║   ██║   ██║██║  ██║",
+  " ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝   ╚══════╝   ╚═╝   ╚═╝  ╚═╝   ╚═╝   ╚═╝╚═╝  ╚═╝",
+];
+
+/** Blue-grey gradient: dim at the edges, brighter through the middle. */
+const GRADIENT: readonly [number, number, number][] = [
+  [90, 120, 150],
+  [120, 160, 200],
+  [150, 200, 240],
+  [120, 160, 200],
+  [90, 120, 150],
+];
+
+const RESET = "\u001b[0m";
+
+/**
+ * Returns the wordmark lines with per-column colour, or an empty array when the
+ * terminal is too narrow or colour is disabled.
+ */
+export function renderWordmark(columns = process.stdout.columns ?? 80): string[] {
+  if (process.env.NO_COLOR !== undefined) return [];
+  const width = WORDMARK[0]!.length;
+  if (columns < width) return [];
+
+  const coloured: string[] = [];
+  for (const row of WORDMARK) {
+    let line = "";
+    let current = -1;
+    for (let column = 0; column < row.length; column += 1) {
+      const band = Math.min(
+        GRADIENT.length - 1,
+        Math.floor((column / width) * GRADIENT.length),
+      );
+      const [r, g, b] = GRADIENT[band]!;
+      if (band !== current) {
+        line += `\u001b[38;2;${r};${g};${b}m`;
+        current = band;
+      }
+      line += row[column];
+    }
+    coloured.push(`${line}${RESET}`);
+  }
+  return coloured;
+}

package/src/boot/app.ts

@@ -45,6 +45,7 @@ import {
 import { createTokenCountHandler } from "../transport/dispatch/token-count";
 
 import { createTransportPipeline } from "../transport/guards/pipeline";
+import { defaultProcessConcurrencyController } from "../transport/guards/concurrency-guard";
 import { createDrainHandler, isLoopbackPeer, tokenMatches } from "../transport/drain-endpoint";
 import { createConsoleAccountResetHandler } from "../console/auth/account-reset";
 import { resetConsoleAuthState } from "../console/auth/account-reset-store";
@@ -244,6 +245,10 @@ export function createGatewayApp(deps: GatewayAppDeps) {
     deps.mode === "production" ? deps.shutdownCoordinator : undefined,
   );
   deps.runtimeMetricsSampler?.bindInFlight(() => requestStateStore.inFlightCount());
+  // The concurrency ceiling is derived (memory limit ÷ body budget), so it is
+  // published as a gauge: an operator reading "shedding at 16 in flight" needs
+  // to see that 16 IS the limit on this box, not that the process is broken.
+  deps.runtimeMetricsSampler?.bindConcurrencyLimit(defaultProcessConcurrencyController.limit());
   // Shutdown ordering: abort in-flight proxy controllers first so the
   // bounded drain observes cancellation and finalizers run before
   // telemetry flush and pool close. The reason is threaded through so the
@@ -379,6 +384,16 @@ export function createGatewayApp(deps: GatewayAppDeps) {
       telemetry: deps.telemetryBuffer,
       ...(deps.modelStrikes ? { modelStrikes: deps.modelStrikes } : {}),
       ...(deps.consoleApi?.redis ? { redis: deps.consoleApi.redis } : {}),
+      // Bound at construction so the guard holds the sampler's live snapshot
+      // rather than a value captured at boot.
+      ...(deps.runtimeMetricsSampler
+        ? { memorySnapshot: () => deps.runtimeMetricsSampler?.memorySnapshot() }
+        : {}),
+      // Reads the cached route snapshot, which the settings route invalidates
+      // when the switch is saved — so flipping it takes effect on the next
+      // request and adds no query to the proxy path.
+      isInvokeDisabled: async (tenantId) =>
+        (await deps.snapshotService.getSnapshot())?.invokeDisabledTenants?.has(tenantId),
     });
     transportPipeline.mountRoot(app);
     const proxyDeps: ProviderProxyHandlerDeps = {
@@ -657,7 +672,7 @@ export function createGatewayApp(deps: GatewayAppDeps) {
       createShareRouter({
         db: deps.db,
         shareStore: new DrizzleShareLinkStore(deps.db),
-        stats: createShareStatsPort({ redis: deps.consoleApi?.redis }),
+        stats: createShareStatsPort({ db: deps.db, redis: deps.consoleApi?.redis }),
         resolveClientIp: (request) => {
           const peer = peerAddresses.get(request);
           return peer

package/src/boot/dependencies.ts

@@ -3,6 +3,9 @@ import { assertPoolFitsServerCapacity, bootDatabase, ensureMigrated } from "../p
 import { poolMaxFromEnv } from "../persistence/db-pg";
 import type { CartethyiaDatabase } from "../persistence/db-handle";
 import { resolveRedisBackend, resolveRedisClient } from "../persistence/redis";
+import { resolveProcessTopology, type ProcessTopology } from "../config/runtime";
+import { createRedisMaintenanceLeaseStore } from "../workers/maintenance-lease";
+import { resolveDbMode } from "../persistence/db-mode";
 import type { RedisClient } from "../persistence/redis";
 import {
   bundledModelCatalog,
@@ -71,8 +74,6 @@ 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 { foldDayIndex, listEventDays } from "../observability/event-day-index";
-import { resolveTelemetryCompactIntervalMs } from "../config/telemetry";
 import { sweepExpiredPoolCooldowns } from "../network/pool-health-machine";
 import { TelemetryBatchBuffer } from "../observability/telemetry-buffer";
 import { RuntimeMetricsSampler } from "../observability/runtime-metrics";
@@ -86,6 +87,7 @@ import {
 import { resolveSsrfPolicy, resolveTrustedProxyBoundary } from "../config/network";
 import type { TrustedProxyBoundary } from "../config/network";
 import { resolveTelemetryRetentionDays } from "../config/telemetry";
+import { resolveConcurrencyTolerance } from "../config/resources";
 import { CONFIG_SPEC, readInt, readList } from "../config/spec";
 import type { ProviderAdapter } from "../providers/provider-contracts";
 import type { ProviderRegistry } from "../providers/provider-registry";
@@ -145,9 +147,89 @@ const OAUTH_REFRESH_INTER_ITEM_DELAY_MS = 1_500;
 const CLIENT_VERSION_MONITOR_INTERVAL_MS = 30 * 60_000;
 const CLIENT_VERSION_INITIAL_DELAY_MS = 10_000;
 
+/** Bound on the boot-time Redis probe: a start must fail, not hang. */
+const REDIS_PROBE_TIMEOUT_MS = 2_000;
+
+async function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  const { promise: timeout, reject } = Promise.withResolvers<never>();
+  const timer = setTimeout(() => reject(new Error("timeout")), ms);
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Bounded Redis reachability probe: fails rather than hangs. */
+async function redisIsReachable(): Promise<boolean> {
+  const client = resolveRedisClient();
+  if (!client) return false;
+  try {
+    const result = await withTimeout(client.ping(), REDIS_PROBE_TIMEOUT_MS);
+    return result === "PONG";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Refuses to start a multi-process deployment whose shared state is not
+ * actually shared.
+ *
+ * Every process shares one port via `SO_REUSEPORT`, so the kernel balances
+ * across them — and each process keeps its own in-memory admission counters,
+ * quota cache, and cooldown map. Those are only correct when they live in
+ * Redis. Starting anyway does not fail loudly; it enforces every per-key limit
+ * N times over, which then reads as "the limit did not work".
+ *
+ * Redis is checked by PING with a hard bound, not merely for being configured:
+ * a configured-but-unreachable Redis is the failure mode that matters, and an
+ * unbounded connect at boot would hang the start instead of failing it.
+ */
+async function assertMultiProcessPreconditions(
+  topology: ProcessTopology,
+  redisReachable: () => Promise<boolean>,
+): Promise<void> {
+  if (!topology.multiProcess) return;
+  if (process.platform !== "linux") {
+    throw Object.assign(
+      new Error(
+        `CARTETHYIA_PROCESS_COUNT=${topology.count} requires Linux (SO_REUSEPORT); ` +
+          `this process is on ${process.platform}`,
+      ),
+      { code: "multi_process_unsupported_platform" },
+    );
+  }
+  if (resolveDbMode() !== "full") {
+    throw Object.assign(
+      new Error(
+        `CARTETHYIA_PROCESS_COUNT=${topology.count} requires CARTETHYIA_DB_MODE=full (PostgreSQL); ` +
+          "two processes on one SQLite file corrupt it — there is no cross-process lock in the driver",
+      ),
+      { code: "multi_process_requires_postgres" },
+    );
+  }
+  const reachable = await redisReachable();
+  if (!reachable) {
+    throw Object.assign(
+      new Error(
+        `CARTETHYIA_PROCESS_COUNT=${topology.count} requires a REACHABLE Redis: admission counters, ` +
+          "quotas, and cooldowns are per-process without one, so every per-key limit would be " +
+          `enforced ${topology.count} times over`,
+      ),
+      { code: "multi_process_requires_redis" },
+    );
+  }
+}
+
 export async function buildProductionDeps(): Promise<ProductionDeps> {
   const startupStartedAt = performance.now();
   const startupMemoryBefore = process.memoryUsage();
+  // Resolved first and validated before any connection is opened: a
+  // half-configured multi-process deploy that starts anyway looks healthy
+  // until a per-key limit is enforced N times over.
+  const topology = resolveProcessTopology();
+  await assertMultiProcessPreconditions(topology, redisIsReachable);
   const handle = await measureStartupPhase("database-connect", bootDatabase);
   const db = handle.db;
   // One rule, no mode flag: REDIS_URL set → shared client, unset → memory.
@@ -157,7 +239,7 @@ export async function buildProductionDeps(): Promise<ProductionDeps> {
     await ensureMigrated();
     // Pool sizing is an external-server concern; the embedded backend has no
     // connection budget to fit into.
-    if (handle.kind === "pg") await assertPoolFitsServerCapacity(poolMaxFromEnv());
+    if (handle.kind === "pg") await assertPoolFitsServerCapacity(poolMaxFromEnv(), topology.count);
   });
   await measureStartupPhase("provider-seed", () => seedBundledProviders(db));
   // Boot-only: retire global rows for providers the bundle has dropped, so a
@@ -193,7 +275,6 @@ export async function buildProductionDeps(): Promise<ProductionDeps> {
     tenantId: string | null,
   ): Promise<readonly { accountId: string; inflight: number }[]> => {
     if (providerId === "" || tenantId === null) return [];
-    const snapshot = await routingEngine.accountInflightSnapshot();
     const accounts = await new DrizzleProviderCatalogStore(db, {
       telemetryBuffer,
       bundledModelCatalog: bundledCatalog,
@@ -202,10 +283,20 @@ export async function buildProductionDeps(): Promise<ProductionDeps> {
       snapshotInvalidator: snapshotService,
     }).listAccounts(tenantId, providerId);
     const owned = new Set(accounts.map((account) => account.id));
+    // Scoped read: only the provider's own candidates for this tenant are
+    // queried, so the console read costs one exact MGET over the accounts it
+    // is about to report on — not a fleet-wide `KEYS` scan whose cost is the
+    // size of every bucket every process ever wrote.
+    const routeSnapshot = await snapshotService.getSnapshot();
+    const ownedCandidates = routeSnapshot.candidates.filter(
+      (candidate) =>
+        candidate.provider_id === providerId &&
+        candidate.provider_account_id !== undefined &&
+        owned.has(candidate.provider_account_id),
+    );
+    const snapshot = await routingEngine.accountInflightSnapshot(ownedCandidates);
     const totals = new Map<string, number>();
     for (const [bucket, count] of snapshot) {
-      const prefix = `${providerId}:`;
-      if (!bucket.startsWith(prefix)) continue;
       const accountId = bucket.slice(bucket.lastIndexOf(":") + 1);
       if (!owned.has(accountId)) continue;
       totals.set(accountId, (totals.get(accountId) ?? 0) + count);
@@ -260,6 +351,13 @@ export async function buildProductionDeps(): Promise<ProductionDeps> {
       const children = await store.sumChildrenConsumed(apiKeyId);
       return (row.lifetimeTokensConsumed ?? 0) + children;
     },
+    // Slack above every key's concurrency limit. A tenant preference an
+    // operator sets in the runtime settings modal, falling back to the
+    // deployment default so an unset row does not silently lose the allowance.
+    (tenantId) =>
+      preferencesReaderFor(db)
+        .readPreferences(tenantId)
+        .then((prefs) => prefs?.concurrencyTolerance ?? resolveConcurrencyTolerance()),
   );
   const ipStore = redis
     ? new RedisIpAbuseStore(redis)
@@ -282,8 +380,14 @@ export async function buildProductionDeps(): Promise<ProductionDeps> {
   // One list covers every periodic task: a small deployment can cut the
   // heaviest sweeps (quota refresh, OAuth refresh, client-version polling)
   // without the codebase growing a flag per task.
+  // Leases coordinate the SHARED sweeps across processes. Absent Redis there is
+  // nothing to coordinate with, and the registry's local one-at-a-time rule is
+  // the correct (and only) guard.
   const scheduledTasks = new ScheduledTaskRegistry(
     readList("CARTETHYIA_DISABLED_TASKS", CONFIG_SPEC.CARTETHYIA_DISABLED_TASKS) ?? [],
+    {
+      ...(redis ? { lease: createRedisMaintenanceLeaseStore(redis) } : {}),
+    },
   );
   if (redis) {
     scheduledTasks.register({
@@ -295,6 +399,8 @@ export async function buildProductionDeps(): Promise<ProductionDeps> {
   scheduledTasks.register({
     name: "account-health-sweep",
     intervalMs: 30_000,
+    // Recovers cooldowns deployment-wide and invalidates the shared snapshot.
+    shared: true,
     run: async () => {
       const recovered = await sweepExpiredCooldowns(db);
       const poolRecovered = await sweepExpiredPoolCooldowns(db);
@@ -306,27 +412,11 @@ export async function buildProductionDeps(): Promise<ProductionDeps> {
   scheduledTasks.register({
     name: "telemetry-payload-cleanup",
     intervalMs: 15 * 60_000,
+    // Deletes payload frames for every tenant: two passes over the same
+    // batches is duplicated work, not speedup.
+    shared: true,
     run: () => payloadCapture.cleanupExpired(),
   });
-  scheduledTasks.register({
-    name: "telemetry-index-fold",
-    intervalMs: resolveTelemetryCompactIntervalMs(),
-    // Brings each day's index up to date with the bytes appended since the last
-    // pass, so a usage read is a small JSON read rather than a parse of the
-    // whole period. Folding is incremental and idempotent: a crash only leaves
-    // the watermark behind, and the next pass re-reads the tail.
-    run: async () => {
-      const days = await listEventDays();
-      let folded = 0;
-      for (const day of days) {
-        const result = await foldDayIndex(day).catch(() => ({ folded: 0 }));
-        folded += result.folded;
-      }
-      if (folded > 0) {
-        log.info(`[telemetry] indexed ${folded} event(s) across ${days.length} day(s)`);
-      }
-    },
-  });
   scheduledTasks.register({
     name: "console-session-sweep",
     // Sessions live 48 h, so an hourly sweep deleted nothing 47 times out of
@@ -334,11 +424,15 @@ export async function buildProductionDeps(): Promise<ProductionDeps> {
     // be expired. Half the session lifetime is the point where a pass can
     // actually find work, and still leaves a full grace period after it.
     intervalMs: 12 * 60 * 60_000,
+    shared: true,
     run: () => deleteExpiredSessions(db),
   });
   scheduledTasks.register({
     name: "telemetry-retention",
     intervalMs: 6 * 60 * 60_000,
+    // Retention deletes rows and files for the whole deployment; a second
+    // concurrent pass would churn the same batches.
+    shared: true,
     run: () =>
       telemetryStore.pruneTelemetry(
         new Date(Date.now() - resolveTelemetryRetentionDays() * 24 * 60 * 60_000),
@@ -365,7 +459,16 @@ export async function buildProductionDeps(): Promise<ProductionDeps> {
     modelCatalogEntries: () => modelCatalogCacheSize(),
     // Late-bound via bindInFlight once the request state store exists.
     inFlight: () => 0,
+    // The buffer is built below; the closure keeps the sampler from holding a
+    // reference during construction.
+    telemetryBacklog: () => telemetryBuffer?.snapshot(),
   });
+  // One sample NOW, not on the first tick. The headroom guard reads
+  // `memorySnapshot()` on every gateway request and treats `undefined` as
+  // "unknown" — so without this the guard would spend its first interval
+  // (seconds, at the configured cadence) unable to shed at all, which is
+  // exactly the window a cold start is most likely to be short of memory.
+  runtimeMetricsSampler.sample();
   scheduledTasks.register({
     name: "runtime-metrics",
     intervalMs: readInt(

package/src/config/package-paths.ts

@@ -24,6 +24,30 @@ export function resolvePackagePath(...segments: string[]): string {
   return resolve(PACKAGE_ROOT, ...segments);
 }
 
+/** Outfile `bun build --compile` writes when no `--outfile` is given. */
+export const DEFAULT_BINARY_OUTFILE = "dist/cartethyia";
+
+/**
+ * The artifact path `bun build --compile` actually writes for `outfile`.
+ *
+ * Bun appends `.exe` when it compiles for Windows, so the extensionless
+ * `dist/cartethyia` handed to it never exists on that platform. This is the one
+ * place that knows where the compiled binary lands; `scripts/build/` resolves
+ * its target from here instead of re-deriving the name, because a launcher that
+ * probed the requested path reported "run bun run build first" immediately
+ * after a successful build.
+ *
+ * It sits in `src/config/` rather than `scripts/build/` because the launcher
+ * ships in the npm package and `scripts/build/` does not: a shipped module that
+ * imported the build script crashed every installed copy of `carte` with
+ * `Cannot find module '../build/compile'`.
+ */
+export function compiledBinaryPath(outfile: string = DEFAULT_BINARY_OUTFILE): string {
+  return process.platform === "win32" && !outfile.toLowerCase().endsWith(".exe")
+    ? `${outfile}.exe`
+    : outfile;
+}
+
 /** User-writable directory for the npm-installed CLI's configuration. */
 export function resolveUserConfigDir(env: NodeJS.ProcessEnv = process.env): string {
   if (process.platform === "win32") {