cartethyia 2.5.10 → 2.6.0

package/src/console/settings/contracts.ts

@@ -21,8 +21,6 @@ export interface RuntimeSettingsResponse {
   readonly telemetryPayloads: TelemetryPayloadMode;
   /** Capture depth for `full` mode; `minimum` when unset. */
   readonly telemetryPayloadDepth: TelemetryPayloadDepth;
-  /** How long a captured frame is kept, in minutes; `null` means deployment default. */
-  readonly telemetryPayloadRetentionMinutes: number | null;
   readonly privacyMode: PrivacyMode;
   /** Compacts bulky tool-result text before dispatch (RTK prune). Default false. */
   readonly rtkPruneEnabled: boolean;
@@ -39,13 +37,45 @@ export interface RuntimeSettingsResponse {
    * cooldown is still recorded and still recovered by the sweep.
    */
   readonly forceDisableCooldown: boolean;
+  /**
+   * Stops every invoke and route for this tenant while on. The console stays
+   * reachable so the switch can be turned back off from the UI that set it.
+   */
+  readonly invokeDisabled: boolean;
+  /**
+   * Slack above every key's concurrency limit; `null` means none. The
+   * effective ceiling is `maxConcurrentRequests + concurrencyTolerance`.
+   */
+  readonly concurrencyTolerance: number | null;
   /** Per-tenant upstream request timeout in seconds; null means deployment default. */
   readonly upstreamTimeoutSeconds: number | null;
-  /** Per-tenant telemetry compaction age in days; null means deployment default. */
+  /** Captured payload detail lifetime in minutes; null means deployment default. */
   readonly telemetryWindowMinutes: number | null;
   /** Per-tenant inline attachment ceiling in bytes; null means deployment default. */
   readonly imageClampMaxBytes: number | null;
   readonly updatedAt: string;
+  /*
+   * What each `null` actually resolves to, in the same units the row stores.
+   *
+   * A row that says "Deployment default" without the number makes the operator
+   * guess, and the guess is the one thing they cannot check from here: the
+   * value lives in an env var on a server they are not looking at. Sent in the
+   * same response rather than mirrored in the client, because a copied number
+   * is right until someone changes the deployment — then it lies quietly.
+   */
+  readonly defaults: RuntimeSettingsDefaults;
+}
+
+/** The deployment-level values a `null` runtime setting falls back to. */
+export interface RuntimeSettingsDefaults {
+  /** Seconds; from `CARTETHYIA_UPSTREAM_TIMEOUT_MS`. */
+  readonly upstreamTimeoutSeconds: number;
+  /** Minutes; what the payload store expires frames after. */
+  readonly telemetryWindowMinutes: number;
+  /** Bytes; the inline attachment ceiling. */
+  readonly imageClampMaxBytes: number;
+  /** Days; how long raw event files are kept. */
+  readonly telemetryRetentionDays: number;
 }
 
 /**
@@ -92,20 +122,6 @@ export type TelemetryPayloadMode = (typeof TELEMETRY_PAYLOAD_MODES)[number];
 export const TELEMETRY_PAYLOAD_DEPTHS = ["minimum", "moderate", "maximum"] as const;
 /** Capture depth for `full` mode accepted by the runtime-settings PATCH. */
 export type TelemetryPayloadDepth = (typeof TELEMETRY_PAYLOAD_DEPTHS)[number];
-/**
- * How long a captured payload frame is kept, in whole minutes, or `null` for
- * the deployment default.
- *
- * Only the offered values are accepted, and a value off the list is *rejected*
- * rather than clamped: clamping would answer a request for thirty days with
- * seven and report success, and an operator who asked for the longer window
- * would believe they got it.
- */
-export const TELEMETRY_PAYLOAD_RETENTION_MINUTES = [15, 30, 60, 360, 720, 1440, 10080] as const;
-/** Payload retention in minutes accepted by the runtime-settings PATCH. */
-export type TelemetryPayloadRetentionMinutes =
-  | (typeof TELEMETRY_PAYLOAD_RETENTION_MINUTES)[number]
-  | null;
 export const PRIVACY_MODES = ["masked", "full"] as const;
 /** Provider/model label privacy accepted by the runtime-settings PATCH. */
 export type PrivacyMode = (typeof PRIVACY_MODES)[number];
@@ -149,19 +165,6 @@ export function createRuntimeSettingsOperations(deps: RuntimeSettingsConfig) {
         if (patch.telemetryPayloadDepth !== undefined && !TELEMETRY_PAYLOAD_DEPTHS.includes(patch.telemetryPayloadDepth)) {
           throw new ConsoleDomainError("invalid_request", 400, "Invalid telemetryPayloadDepth");
         }
-        if (patch.telemetryPayloadRetentionMinutes !== undefined) {
-          const minutes = patch.telemetryPayloadRetentionMinutes;
-          if (
-            minutes !== null &&
-            !(TELEMETRY_PAYLOAD_RETENTION_MINUTES as readonly number[]).includes(minutes)
-          ) {
-            throw new ConsoleDomainError(
-              "invalid_request",
-              400,
-              "Invalid telemetryPayloadRetentionMinutes",
-            );
-          }
-        }
         if (patch.privacyMode !== undefined && !PRIVACY_MODES.includes(patch.privacyMode)) {
           throw new ConsoleDomainError("invalid_request", 400, "Invalid privacyMode");
         }
@@ -183,10 +186,11 @@ export function createRuntimeSettingsOperations(deps: RuntimeSettingsConfig) {
           detail: patch as Record<string, unknown>,
         });
         // Saved preferences are routing changes: `forceDisableCooldown` decides
-        // candidate eligibility and `tenantConcurrencyLimit` decides admission,
-        // and both are read from the cached route snapshot. Invalidate after the
-        // write commits so the next `/v1/*` request uses them instead of the
-        // revision that was built before the save. A failure here must not fail
+        // candidate eligibility, `tenantConcurrencyLimit` decides admission, and
+        // `invokeDisabled` decides whether the request is refused at all — all
+        // three read from the cached route snapshot. Invalidate after the write
+        // commits so the next `/v1/*` request uses them instead of the revision
+        // that was built before the save. A failure here must not fail
         // the save — the row is already correct, and the snapshot rebuilds on
         // the next read anyway.
         await Promise.resolve(deps.snapshotInvalidator?.invalidate()).catch(() => undefined);
@@ -206,12 +210,6 @@ export const runtimeUpdateBody = t.Object({
   responsesReasoningSummary: t.Optional(literalUnion(RESPONSES_REASONING_SUMMARIES)),
   telemetryPayloads: t.Optional(literalUnion(TELEMETRY_PAYLOAD_MODES)),
   telemetryPayloadDepth: t.Optional(literalUnion(TELEMETRY_PAYLOAD_DEPTHS)),
-  telemetryPayloadRetentionMinutes: t.Optional(
-    t.Union([
-      t.Null(),
-      t.Union(TELEMETRY_PAYLOAD_RETENTION_MINUTES.map((minutes) => t.Literal(minutes))),
-    ]),
-  ),
   privacyMode: t.Optional(literalUnion(PRIVACY_MODES)),
   tenantConcurrencyLimit: t.Optional(t.Union([t.Null(), t.Number()])),
   thinkingNormalizationEnabled: t.Optional(t.Boolean()),
@@ -234,6 +232,10 @@ export const runtimeUpdateBody = t.Object({
    * rejected here rather than silently clamped on the way in.
    */
   forceDisableCooldown: t.Optional(t.Boolean()),
+  invokeDisabled: t.Optional(t.Boolean()),
+  concurrencyTolerance: t.Optional(
+    t.Union([t.Null(), t.Number({ minimum: 0, maximum: 1024 })]),
+  ),
   upstreamTimeoutSeconds: t.Optional(
     t.Union([t.Null(), t.Number({ minimum: 5, maximum: 600 })]),
   ),

package/src/console/settings/store.ts

@@ -5,13 +5,16 @@ import type { CartethyiaDatabase } from "../../persistence/db-handle";
 import { consoleSettings, type ConsoleSettingsPreferences } from "../../persistence/schema";
 import type { RedisBackend } from "../../persistence/redis";
 import { bumpSettingsRevision } from "../../persistence/settings-revision";
+import { resolveTelemetryRetentionDays } from "../../config/telemetry";
+import { resolveUpstreamTimeoutMs } from "../../config/timeouts";
+import { payloadRetentionMs } from "../../observability/payload-capture";
+import { IMAGE_CLAMP_MAX_BYTES } from "../../protocol/image-clamp";
 import {
   PONYTAIL_LEVELS,
   RESPONSES_REASONING_SUMMARIES,
   RTK_LEVELS,
   TELEMETRY_PAYLOAD_DEPTHS,
   TELEMETRY_PAYLOAD_MODES,
-  TELEMETRY_PAYLOAD_RETENTION_MINUTES,
   type PonyTailLevel,
   type ResponsesReasoningSummary,
   type RtkLevel,
@@ -96,7 +99,7 @@ function normalizeUpstreamTimeoutSeconds(value: unknown): number | null {
   return normalizeBoundedNumber(value, 5, 600);
 }
 
-/** Source window in minutes: 1 floor, 1440 (one day) ceiling, matching the env var. */
+/** Captured payload detail lifetime in minutes: 1 floor, one-day ceiling. */
 function normalizeTelemetryWindowMinutes(value: unknown): number | null {
   return normalizeBoundedNumber(value, 1, 1440);
 }
@@ -106,23 +109,10 @@ function normalizeImageClampMaxBytes(value: unknown): number | null {
   return normalizeBoundedNumber(value, 64 * 1024, 100 * 1024 * 1024);
 }
 
-/**
- * How long a captured payload frame is kept, in whole minutes.
- *
- * Only one of the offered values survives; anything else reads as "deployment
- * default" rather than being clamped to the nearest one. A stored value from
- * before this list existed would otherwise be silently rewritten to a window
- * the operator never chose, and dropping it to `null` is the same outcome the
- * operator gets by never having set it.
- */
-function normalizePayloadRetentionMinutes(value: unknown): number | null {
+/** Concurrency slack: 0–1024, and `null`/absent means no allowance. */
+function normalizeConcurrencyTolerance(value: unknown): number | null {
   if (value === null || value === undefined) return null;
-  const parsed = typeof value === "number" ? value : Number(value);
-  if (!Number.isFinite(parsed)) return null;
-  const minutes = Math.floor(parsed);
-  return (TELEMETRY_PAYLOAD_RETENTION_MINUTES as readonly number[]).includes(minutes)
-    ? minutes
-    : null;
+  return normalizeBoundedNumber(value, 0, 1024);
 }
 
 function mapRuntimeSettingsRow(
@@ -140,9 +130,6 @@ function mapRuntimeSettingsRow(
       : "detailed",
     telemetryPayloads: normalizeTelemetryPayloadMode(prefs.telemetryPayloads),
     telemetryPayloadDepth: normalizeTelemetryPayloadDepth(prefs.telemetryPayloadDepth),
-    telemetryPayloadRetentionMinutes: normalizePayloadRetentionMinutes(
-      prefs.telemetryPayloadRetentionMinutes,
-    ),
     privacyMode: prefs.privacyMode === "full" ? "full" : "masked",
     rtkPruneEnabled: prefs.rtkPruneEnabled === true,
     rtkPruneLevel: normalizeRtkLevel(prefs.rtkPruneLevel),
@@ -156,10 +143,23 @@ function mapRuntimeSettingsRow(
     ponyTailEnabled: prefs.ponyTailEnabled === true,
     ponyTailLevel: normalizePonyTailLevel(prefs.ponyTailLevel),
     forceDisableCooldown: prefs.forceDisableCooldown === true,
+    invokeDisabled: prefs.invokeDisabled === true,
+    concurrencyTolerance: normalizeConcurrencyTolerance(prefs.concurrencyTolerance),
     upstreamTimeoutSeconds: normalizeUpstreamTimeoutSeconds(prefs.upstreamTimeoutSeconds),
     telemetryWindowMinutes: normalizeTelemetryWindowMinutes(prefs.telemetryWindowMinutes),
     imageClampMaxBytes: normalizeImageClampMaxBytes(prefs.imageClampMaxBytes),
     updatedAt,
+    /*
+     * Resolved at request time, not at module load: all four come from env the
+     * operator can change without rebuilding, and a cached value would keep
+     * quoting a default the deployment no longer has.
+     */
+    defaults: {
+      upstreamTimeoutSeconds: Math.round(resolveUpstreamTimeoutMs() / 1000),
+      telemetryWindowMinutes: Math.round(payloadRetentionMs() / 60_000),
+      imageClampMaxBytes: IMAGE_CLAMP_MAX_BYTES,
+      telemetryRetentionDays: resolveTelemetryRetentionDays(),
+    },
   };
 }
 
@@ -192,10 +192,6 @@ export class DrizzleRuntimeSettingsStore implements RuntimeSettingsStore {
       patchPrefs.responsesReasoningSummary = patch.responsesReasoningSummary;
     if (patch.telemetryPayloads !== undefined) patchPrefs.telemetryPayloads = patch.telemetryPayloads;
     if (patch.telemetryPayloadDepth !== undefined) patchPrefs.telemetryPayloadDepth = patch.telemetryPayloadDepth;
-    if (patch.telemetryPayloadRetentionMinutes !== undefined)
-      patchPrefs.telemetryPayloadRetentionMinutes = normalizePayloadRetentionMinutes(
-        patch.telemetryPayloadRetentionMinutes,
-      );
     if (patch.privacyMode !== undefined) patchPrefs.privacyMode = patch.privacyMode;
     if (patch.rtkPruneEnabled !== undefined) patchPrefs.rtkPruneEnabled = patch.rtkPruneEnabled;
     if (patch.rtkPruneLevel !== undefined) patchPrefs.rtkPruneLevel = patch.rtkPruneLevel;
@@ -203,6 +199,10 @@ export class DrizzleRuntimeSettingsStore implements RuntimeSettingsStore {
     if (patch.ponyTailLevel !== undefined) patchPrefs.ponyTailLevel = patch.ponyTailLevel;
     if (patch.forceDisableCooldown !== undefined)
       patchPrefs.forceDisableCooldown = patch.forceDisableCooldown === true;
+    if (patch.invokeDisabled !== undefined)
+      patchPrefs.invokeDisabled = patch.invokeDisabled === true;
+    if (patch.concurrencyTolerance !== undefined)
+      patchPrefs.concurrencyTolerance = normalizeConcurrencyTolerance(patch.concurrencyTolerance);
     if (patch.upstreamTimeoutSeconds !== undefined)
       patchPrefs.upstreamTimeoutSeconds = normalizeUpstreamTimeoutSeconds(patch.upstreamTimeoutSeconds);
     if (patch.telemetryWindowMinutes !== undefined)

package/src/console/share/share-stats.ts

@@ -12,7 +12,9 @@
 
 import { createHash } from "node:crypto";
 import { maskClientIp } from "../../observability/redaction";
-import { queryTelemetryEvents, type TelemetryEventRecord } from "../../observability/event-log";
+import { type TelemetryEventRecord } from "../../observability/event-log";
+import { queryTelemetryEvents as querySqlEvents } from "../../observability/event-query";
+import type { CartethyiaDatabase } from "../../persistence/db-handle";
 import { isGatewayError } from "../../observability/telemetry-status";
 import type { RedisClient } from "../../persistence/redis";
 import { cachedRead } from "../shared/read-through-cache";
@@ -259,18 +261,22 @@ function shareFamilyStatsKey(
   return `share:v1:stats:${tenantId}:${hash}`;
 }
 
+/** Cap on the bounded SQL read a family rollup performs. */
+const MAX_FAMILY_EVENTS = 5_000;
+
 interface ShareStatsPortDeps {
+  readonly db: CartethyiaDatabase;
   readonly redis?: RedisClient | undefined;
 }
 
-export function createShareStatsPort(deps: ShareStatsPortDeps = {}): ShareStatsPort {
+export function createShareStatsPort(deps: ShareStatsPortDeps): ShareStatsPort {
   return {
     async getFamilyStats(tenantId, keyIds, recipients, allowedModels) {
       if (keyIds.length === 0) return emptyStats(recipients);
       const cached = await cachedRead<Omit<ShareFamilyStats, "recipients">>(
         deps.redis,
         shareFamilyStatsKey(tenantId, keyIds, allowedModels),
-        () => computeFamilyStatsBody(tenantId, keyIds, allowedModels),
+        () => computeFamilyStatsBody(deps.db, tenantId, keyIds, allowedModels),
         SHARE_STATS_CACHE_TTL_SECONDS,
       );
       return { ...cached, recipients };
@@ -280,6 +286,7 @@ export function createShareStatsPort(deps: ShareStatsPortDeps = {}): ShareStatsP
 
 /** The telemetry-derived remainder of a family rollup; `recipients` is Postgres-derived. */
 async function computeFamilyStatsBody(
+  db: CartethyiaDatabase,
   tenantId: string,
   keyIds: readonly string[],
   allowedModels: readonly string[] | undefined,
@@ -302,7 +309,18 @@ async function computeFamilyStatsBody(
   // would list exactly the invalid names an abuser probed. Filtering before
   // the top-50 cut means refused names cannot hide a model the recipient may
   // use.
-  const events = await queryTelemetryEvents({ tenantId, apiKeyIds: [...keyIds] });
+  //
+  // Bounded by the retention floor, not by the oldest counter: `totalTokens`
+  // is all-time, so cutting at `monthStart` would silently drop the rows that
+  // make it differ from `monthTokens`. Retention already caps the window, and
+  // the rows are read newest-first under a page cap, so a very large family
+  // cannot pull the whole table.
+  const page = await querySqlEvents(db, {
+    tenantId,
+    apiKeyIds: [...keyIds],
+    limit: MAX_FAMILY_EVENTS,
+  });
+  const events = page.events;
   const rollup = rollupFamily(events, {
     dayStart: dayStart.getTime(),
     monthStart: monthStart.getTime(),

package/src/console/share/share-usage.ts

@@ -3,7 +3,8 @@ import type { CartethyiaDatabase } from "../../persistence/db-handle";
 import type { ApiKeyRecord } from "../../persistence/stores/api-key-store";
 import { CachedPreferencesReader, DrizzlePreferencesReader } from "../../persistence/tenant-preferences";
 import { maskClientIp } from "../../observability/redaction";
-import { queryTelemetryEvents, type TelemetryEventRecord } from "../../observability/event-log";
+import { type TelemetryEventRecord } from "../../observability/event-log";
+import { queryTelemetryEvents as querySqlEvents } from "../../observability/event-query";
 import { isGatewayError } from "../../observability/telemetry-status";
 import type { RedisClient } from "../../persistence/redis";
 import { cachedRead } from "../shared/read-through-cache";
@@ -114,6 +115,15 @@ function shareKeyDetailCacheKey(tenantId: string, childKeyId: string, hideClient
   return `share:v1:detail:${tenantId}:${childKeyId}:${hideClientIp ? "m" : "r"}`;
 }
 
+/**
+ * Caps on the two SQL event reads a share page performs.
+ *
+ * Both pages render a bounded list (a rolling window of recent requests), so
+ * reading past the cap would fetch rows no element of the response shows.
+ */
+const MAX_SUMMARY_EVENTS = 2_000;
+const MAX_ACTIVITY_EVENTS = 2_000;
+
 interface ShareUsagePortDeps {
   readonly db: CartethyiaDatabase;
   readonly redis?: RedisClient | undefined;
@@ -128,7 +138,12 @@ export function createShareUsagePort(deps: ShareUsagePortDeps): ShareActivityPor
       const childIds = children.map((child) => child.id);
       const todayStart = utcDayStart(new Date());
       const [todayEvents, lifetimeRows, hideClientIp] = await Promise.all([
-        queryTelemetryEvents({ tenantId, apiKeyIds: childIds, since: todayStart }),
+        // Today's per-key totals as one GROUP BY instead of reading every
+        // event of the family. `addEventUsage` needs per-event fields, so the
+        // groups are projected into the same shape the loop consumes.
+        querySqlEvents(db, { tenantId, apiKeyIds: childIds, since: todayStart, limit: MAX_SUMMARY_EVENTS }).then(
+          (page) => page.events,
+        ),
         db
           .select({
             apiKeyId: telemetryUsageTotals.entityId,
@@ -184,7 +199,7 @@ export function createShareUsagePort(deps: ShareUsagePortDeps): ShareActivityPor
       return cachedRead<SharedKeyActivityDetail>(
         redis,
         shareKeyDetailCacheKey(tenantId, childKeyId, hideClientIp),
-        () => computeSharedKeyDetail(tenantId, childKeyId, hideClientIp),
+        () => computeSharedKeyDetail(db, tenantId, childKeyId, hideClientIp),
         SHARE_STATS_CACHE_TTL_SECONDS,
       );
     },
@@ -197,12 +212,23 @@ export function createShareUsagePort(deps: ShareUsagePortDeps): ShareActivityPor
  * resolved by the caller so the cache key can separate the two variants.
  */
 async function computeSharedKeyDetail(
+  db: CartethyiaDatabase,
   tenantId: string,
   childKeyId: string,
   hideClientIp: boolean,
 ): Promise<SharedKeyActivityDetail> {
   const todayStart = utcDayStart(new Date()).getTime();
-  const events = await queryTelemetryEvents({ tenantId, apiKeyIds: [childKeyId] });
+  // Bounded SQL read: this page shows a 24-hour chart plus today's counters,
+  // so anything older than the hourly window contributes nothing. The old
+  // shape read the whole retained window for one child key.
+  const windowStart = new Date(todayStart - 24 * 60 * 60_000);
+  const page = await querySqlEvents(db, {
+    tenantId,
+    apiKeyIds: [childKeyId],
+    since: windowStart,
+    limit: MAX_ACTIVITY_EVENTS,
+  });
+  const events = page.events;
   const models = new Map<string, {
     providerId: string | null;
     modelId: string;

package/src/console/shared/cursor.ts

@@ -149,3 +149,18 @@ export function decodeDatedCursor(cursor: string | undefined): DatedCursor | und
   if (Number.isNaN(new Date(parsed.createdAt).getTime())) return undefined;
   return parsed;
 }
+
+/**
+ * Trim a `limit + 1` keyset query result and report whether it overflowed.
+ * Callers keep cursor encoding specific to their public page contract.
+ */
+export function trimKeysetPage<T>(
+  rows: readonly T[],
+  limit: number,
+): { readonly rows: readonly T[]; readonly hasMore: boolean } {
+  const hasMore = rows.length > limit;
+  return {
+    rows: hasMore ? rows.slice(0, limit) : rows,
+    hasMore,
+  };
+}

package/src/console/updates/routes.ts

@@ -12,6 +12,17 @@ const UPDATE_SAMPLE_INTERVAL_MS = 60_000;
 const HIGH_MEMORY_PERCENT = 85;
 const HIGH_MEMORY_CLEAR_PERCENT = 80;
 const MEMORY_GROWTH_WINDOW_MS = 60_000;
+/**
+ * Absolute RSS growth required before a growth alert is raised, alongside the
+ * ratio below.
+ *
+ * The ratio alone reported a 2607% "sustained growth" alert for what was a
+ * baseline jump: the window's oldest sample predated an idle reclaim, so a
+ * gateway that had just given memory back looked like it had leaked 27x. A
+ * leak worth an operator's attention is measured in bytes, not multiples —
+ * 20MiB to 24MiB is a 20% ratio and means nothing.
+ */
+const MEMORY_GROWTH_MIN_BYTES = 64 * 1024 * 1024;
 const MEMORY_GROWTH_RATIO = 1.2;
 const MAX_MEMORY_SAMPLES = 8;
 const RELEASES_URL = "https://github.com/risunCodex/Cartethyia/releases";
@@ -50,6 +61,7 @@ export function memoryNotifications(
   const oldest = samples.find((sample) => latest.at - sample.at >= MEMORY_GROWTH_WINDOW_MS);
   const growth = oldest !== undefined &&
     latest.rss >= oldest.rss * MEMORY_GROWTH_RATIO &&
+    latest.rss - oldest.rss >= MEMORY_GROWTH_MIN_BYTES &&
     samples.filter((sample) => sample.at >= oldest.at).every((sample, index, window) =>
       index === 0 || sample.rss >= (window[index - 1]?.rss ?? sample.rss),
     );

package/src/main.ts

@@ -4,7 +4,13 @@ import "./boot/elysia-typebox-bridge";
 import { createGatewayApp, createGatewayShell } from "./boot/app";
 import { bootstrap } from "./boot/lifecycle";
 import type { CartethyiaBoot } from "./boot/lifecycle";
-import { resolveDrainToken, resolveIdleTimeout, resolveMaxBodyBytes, resolvePort } from "./config/runtime";
+import {
+  resolveDrainToken,
+  resolveIdleTimeout,
+  resolveMaxBodyBytes,
+  resolvePort,
+  resolveProcessTopology,
+} from "./config/runtime";
 import { Manifest } from "elysia";
 import { log } from "./observability/logger";
 
@@ -116,10 +122,12 @@ if (boot) {
       // indefinitely. 60 s aligns with the DB pool idle timeout so all
       // long-idle resources reap together.
       idleTimeout: resolveIdleTimeout(),
-      // Enable Bun's SO_REUSEPORT load-balancing so multi-worker deploys
-      // (or a second omp process) can share the same port without a
-      // reverse proxy in front. Silent no-op on platforms that lack it.
-      reusePort: true,
+      // SO_REUSEPORT load-balancing, so several processes can share the port
+      // without a reverse proxy. Tied to the declared topology rather than
+      // left always-on: with one process declared, enabling it lets an
+      // unrelated process on the same port silently take half the traffic —
+      // which is worse than a bind error, because nothing reports it.
+      reusePort: resolveProcessTopology().multiProcess,
       // 8 MiB cap on request bodies keeps a rogue client from allocating
       // gigabytes of memory in the ingress path before validation rejects.
       maxRequestBodySize: resolveMaxBodyBytes(),