cartethyia 2.5.3 → 2.5.6

package/src/transport/request/state.ts

@@ -100,23 +100,36 @@ export interface ProxyRequestState {
    * Remote-diagnosis field: the drawer reads empty for reasons invisible from
    * the client — the tenant's capture mode, a missing tenant, a non-terminal
    * attempt — and without the reason an operator cannot tell "not configured"
-   * from "broken". The four panels are the only surface that could previously
-   * hint at it, and they look identical in both cases.
+   * from "broken". The four panels are the only surface that could hint at it,
+   * and they look identical in both cases.
    */
   payloadCaptureState?: PayloadCaptureState;
   /**
    * This request's resolved payload-capture preference, memoized on the request.
    *
    * The preference is a tenant setting, so it cannot change between attempts of
-   * one request. It was resolved twice — once per attempt to decide whether to
-   * tee the provider body, and again on the terminal attempt to decide what to
-   * store — so a request with several attempts paid for it several times.
-   * Memoized here, the second read is free and the two cannot disagree about
-   * whether capture is on.
+   * one request. It is read twice — once per attempt to decide whether to tee
+   * the provider body, and again on the terminal attempt to decide what to
+   * store — so memoizing it here makes the second read free and keeps the two
+   * from disagreeing about whether capture is on.
    */
   payloadCapturePreference?:
-    | { readonly ok: true; readonly mode: TelemetryPayloadMode; readonly depth: TelemetryPayloadDepth }
+    | {
+        readonly ok: true;
+        readonly mode: TelemetryPayloadMode;
+        readonly depth: TelemetryPayloadDepth;
+        readonly retentionMs: number;
+      }
     | { readonly ok: false };
+  /**
+   * This request's resolved inline-attachment ceiling, memoized for the same
+   * reason the capture preference is: it is a tenant setting, so it cannot
+   * change between attempts, and reading it per attempt would pay for it
+   * several times on a request that fails over.
+   *
+   * `undefined` means the deployment default.
+   */
+  imageClampMaxBytes?: number;
   /**
    * Set by the dispatch handler synchronously before returning a streaming
    * response. `afterResponse` lifecycle hooks read it to skip finalization

package/src/transport/request/tenant-preferences.ts

@@ -13,6 +13,66 @@ import type { PreparedProxyRequest } from "./preparer";
 import { normalizeThinkingConfig } from "../translation/thinking";
 import { compressRequest } from "./rtk/compress-request";
 import { preferencesReaderFor } from "../../persistence/tenant-preferences";
+import { resolveUpstreamTimeoutMs } from "../../config/timeouts";
+
+/**
+ * Re-arms the request deadline from the tenant's timeout override.
+ *
+ * The initial deadline is armed before authentication, when the tenant is not
+ * yet known, so a per-tenant timeout can only be applied here — once the
+ * snapshot says who is asking. `extendDeadline` keeps the timer, the state
+ * field, and the in-flight record in step, so the backstop sweep cannot
+ * force-release a request whose budget legitimately grew.
+ *
+ * Non-fatal: a settings read outage leaves the deployment default in place
+ * rather than failing a dispatchable request.
+ */
+export async function applyTenantDeadlineOverride(
+  tenantId: string,
+  db: CartethyiaDatabase,
+  extend: (ms: number) => void,
+): Promise<void> {
+  try {
+    const prefs = await preferencesReaderFor(db).readPreferences(tenantId);
+    const seconds = prefs?.upstreamTimeoutSeconds;
+    if (typeof seconds !== "number" || !Number.isFinite(seconds) || seconds <= 0) return;
+    const wanted = Math.floor(seconds * 1000);
+    // Only ever shorten or leave alone a deadline that has already begun: an
+    // override longer than the default cannot give back time the request has
+    // already spent, and arming a longer one would silently extend a budget
+    // the caller's own client has likely abandoned.
+    const remaining = Math.min(wanted, resolveUpstreamTimeoutMs());
+    extend(remaining);
+  } catch {
+    // Non-fatal
+  }
+}
+
+/**
+ * The tenant's inline-attachment byte ceiling, or `undefined` for the default.
+ *
+ * Read through the shared revision-keyed preference reader, so the cost is a
+ * memory hit rather than a Postgres round trip — this is consulted while
+ * building a request body, on the dispatch path.
+ *
+ * Non-fatal: a settings read outage falls back to the deployment default,
+ * which is the safe direction (the default refuses less, but it never admits
+ * something no upstream will take).
+ */
+export async function resolveTenantImageClampMaxBytes(
+  db: CartethyiaDatabase,
+  tenantId: string | undefined,
+): Promise<number | undefined> {
+  if (tenantId === undefined) return undefined;
+  try {
+    const prefs = await preferencesReaderFor(db).readPreferences(tenantId);
+    const bytes = prefs?.imageClampMaxBytes;
+    if (typeof bytes !== "number" || !Number.isFinite(bytes) || bytes <= 0) return undefined;
+    return Math.floor(bytes);
+  } catch {
+    return undefined;
+  }
+}
 
 /**
  * Applies request shaping owned by tenant preferences and deployment config:

package/src/transport/routing/admission.ts

@@ -60,6 +60,10 @@ function admissionDirective(candidate: RouteCandidate): AdmissionDirective {
 /** The one shape of an admission rejection: the metric, then the decision. */
 function capacityRejected(): AdmissionDecision {
   metrics.proxy_admission_total.inc(1, { reason: "provider_capacity" });
+  // `reason` is the routing-internal label, not the public code. It stays the
+  // string the router and its tests match on; the envelope code is
+  // `provider_capacity_exhausted` so this layer cannot be confused with an
+  // API-key `max_concurrent` rejection (which owns `capacity_exhausted`).
   return { admitted: false, reason: "capacity_exhausted" };
 }
 

package/src/transport/routing/route-catalog.ts

@@ -3,6 +3,7 @@
 import { asc, eq, ne } from "drizzle-orm";
 import type { CartethyiaDatabase } from "../../persistence/db-handle";
 import {
+  consoleSettings,
   models,
   modelAliases,
   modelCombos,
@@ -383,7 +384,7 @@ class RouteCatalogRepository {
   constructor(private readonly db: CartethyiaDatabase) {}
 
   async loadRouteCatalogSnapshot(tenantId?: string): Promise<RouteCatalogSnapshotResult> {
-    const [providerRows, modelRows, accountRows, aliasRows, comboRows, routingRows, poolRows, disabledModelRows, cliMappingRows, cliMappingSettingRows, poolSettingRows] =
+    const [providerRows, modelRows, accountRows, aliasRows, comboRows, routingRows, poolRows, disabledModelRows, cliMappingRows, cliMappingSettingRows, poolSettingRows, settingsRows] =
       await Promise.all([
         this.db.select(PROVIDER_COLUMNS).from(providers).where(eq(providers.enabled, true)),
         this.db.select(MODEL_COLUMNS).from(models),
@@ -400,8 +401,38 @@ class RouteCatalogRepository {
         this.db.select(CLI_MAPPING_COLUMNS).from(cliToolMappings),
         this.db.select(CLI_MAPPING_SETTING_COLUMNS).from(cliToolSettings),
         this.db.select(POOL_SETTING_COLUMNS).from(poolRoutingSettings),
+        // The cooldown override is a console_settings preference, read inside
+        // the same fan-out rather than per request: one more row set on a
+        // query that already runs, instead of a Postgres round trip on every
+        // admitted request.
+        this.db
+          .select({ tenantId: consoleSettings.tenantId, preferences: consoleSettings.preferences })
+          .from(consoleSettings),
       ]);
     const mergedModelRows = mergeModelCatalog(modelRows);
+    /**
+     * Tenants that asked to ignore an account-wide cooldown.
+     *
+     * Read-only override: the cooldown is still on the row, still shown in
+     * Health, and still recovered by the sweep. This only stops it from
+     * excluding the candidate, so turning the setting off needs no cleanup.
+     *
+     * Per-(account, model) cooldowns are deliberately NOT overridden — see the
+     * preference's own doc.
+     */
+    const cooldownOverrideTenants = new Set<string>();
+    for (const row of settingsRows ?? []) {
+      if (row.preferences?.forceDisableCooldown === true && row.tenantId) {
+        cooldownOverrideTenants.add(row.tenantId);
+      }
+    }
+    /**
+     * A shared account has no tenant of its own (`tenant_id IS NULL`), so a
+     * tenant-keyed override would never match it — yet a shared account is
+     * exactly the one every tenant dials, and parking it stops all of them.
+     * When any tenant asks, the override covers shared accounts too.
+     */
+    const anyTenantOverrides = cooldownOverrideTenants.size > 0;
 
     // Compile tenant-scoped disables into a lookup keyed by the same
     // composite identity the `models` table uses. A disabled key suppresses
@@ -701,16 +732,40 @@ class RouteCatalogRepository {
           // Expired cooldowns read as healthy here without a fire-and-forget
           // write: AccountHealthSweeper materializes the recovery every 30s,
           // so the builder stays a pure read (no UPDATE racing the request).
+          //
+          // `forceDisableCooldown` skips the exclusion entirely. The cooldown
+          // is still real and still recorded — it simply stops deciding
+          // routing. That is what makes the setting reversible: nothing was
+          // written, so turning it off needs no cleanup, and Health still
+          // reports the truth about the account.
           if (account.cooldownUntil && account.cooldownUntil.getTime() > Date.now()) {
-            candidate.health_status = "cooldown";
-            candidate.cooldown_kind = hardCooldownCategory(account.lastErrorCategory)
-              ? "hard"
-              : "soft";
-            // The deadline rides with the exclusion it explains. `plan()` reads
-            // it to answer the all-cooling case with the real reset instead of
-            // a bare 429, so a client backs off for the window that is actually
-            // open rather than inventing one.
-            candidate.cooldown_until = account.cooldownUntil.getTime();
+            const overrideActive =
+              rowTenantId === null
+                ? anyTenantOverrides
+                : cooldownOverrideTenants.has(rowTenantId);
+            if (overrideActive) {
+              // The account is still cooling — this only stops it from being
+              // excluded. `plan()` reads `cooldown_until` to answer the
+              // all-cooling case, so it stays populated either way.
+              //
+              // Neither `health_status` nor `cooldown_kind` is set: the
+              // evaluator excludes a hard cooldown on `health_status ===
+              // "cooldown"` alone, so stamping it here would keep excluding
+              // the very accounts the override exists to reach — a spent quota
+              // or a policy block, which are the ones an operator actually
+              // wants to override.
+              candidate.cooldown_until = account.cooldownUntil.getTime();
+            } else {
+              candidate.health_status = "cooldown";
+              candidate.cooldown_kind = hardCooldownCategory(account.lastErrorCategory)
+                ? "hard"
+                : "soft";
+              // The deadline rides with the exclusion it explains. `plan()`
+              // reads it to answer the all-cooling case with the real reset
+              // instead of a bare 429, so a client backs off for the window
+              // that is actually open rather than inventing one.
+              candidate.cooldown_until = account.cooldownUntil.getTime();
+            }
           }
         }
 

package/src/transport/routing/route-model.ts

@@ -255,8 +255,8 @@ export interface AdmissionController {
  * Translates the evaluator's internal reason codes into operator English.
  *
  * These names are the vocabulary the routing layers use with each other —
- * `model_cooldown`, `cooldown_hard`, `locked` — and they used to be printed
- * verbatim into the public message, so the client read an enum instead of an
+ * `model_cooldown`, `cooldown_hard`, `locked` — not something to print into the
+ * public message, where the client would read an enum instead of an
  * explanation. The codes stay in the envelope's `reasons` field for anyone who
  * wants them; the sentence carries what they mean.
  *
@@ -324,11 +324,43 @@ export function capabilityUnsupportedError(capability: string): GatewayError {
   );
 }
 
-export function capacityExhaustedError(): GatewayError {
+/**
+ * Every candidate in the plan refused admission: each account is already
+ * serving its configured max-inflight.
+ *
+ * Deliberately NOT `capacity_exhausted`. That code also belongs to the API-key
+ * admission layer (`security/admission`, reason `concurrency-limit`), which
+ * enforces a key's own `max_concurrent`. Sharing one code made the two
+ * indistinguishable on the wire: an operator who raised the provider's
+ * max-inflight saw no change because the rejection was the *key's* ceiling, and
+ * vice versa. Distinct codes let each be read off the envelope alone.
+ *
+ * The counts are carried in `details` because the interesting question is never
+ * "was it rejected" but "was every account really full, or did the plan only
+ * carry one candidate" — the latter is a routing/eligibility problem that
+ * raising the ceiling will not fix.
+ */
+export function capacityExhaustedError(context?: {
+  readonly providerId?: string;
+  readonly model?: string;
+  readonly candidateCount?: number;
+  readonly maxInflight?: number;
+}): GatewayError {
+  const onlyOne = context?.candidateCount === 1;
   return new GatewayError(
-    "capacity_exhausted",
+    "provider_capacity_exhausted",
     429,
-    "Every account is at its concurrency limit. Retry shortly; if it persists, raise the provider's max-inflight or add an account.",
+    onlyOne
+      ? "The only account routing this model is at its concurrency limit. Retry shortly; if it persists, raise the provider's max-inflight or add another account."
+      : "Every account is at its concurrency limit. Retry shortly; if it persists, raise the provider's max-inflight or add an account.",
+    {
+      ...(context?.providerId !== undefined ? { providerId: context.providerId } : {}),
+      ...(context?.model !== undefined ? { model: context.model } : {}),
+      ...(context?.candidateCount !== undefined
+        ? { candidate_count: context.candidateCount }
+        : {}),
+      ...(context?.maxInflight !== undefined ? { maxInflight: context.maxInflight } : {}),
+    },
   );
 }
 
@@ -423,10 +455,10 @@ export class InMemoryRouteSnapshotService implements RouteSnapshotService {
    *
    * The tag is what keeps a mutation from being lost. A build reads the catalog
    * over ten Postgres round-trips, so a dashboard write can land while one is
-   * in flight. Without the tag two things went wrong: a reader that arrived
-   * *after* the mutation was handed the still-running pre-mutation build, and
-   * that build then overwrote the cache the mutation had just cleared — so the
-   * data plane served the old routing until some later write invalidated it
+   * in flight. Without the tag two things go wrong: a reader that arrives
+   * *after* the mutation is handed the still-running pre-mutation build, and
+   * that build then overwrites the cache the mutation has just cleared — so the
+   * data plane serves stale routing until some later write invalidates it
    * again. A build may only be reused by readers at its own revision, and may
    * only populate the cache if no mutation happened while it ran.
    */
@@ -491,9 +523,9 @@ export class InMemoryRouteSnapshotService implements RouteSnapshotService {
           ]),
         )
       : undefined;
-    // One literal for both routing modes. These used to be two verbatim copies
-    // that differed only by the `providerRouting` key, so a snapshot field added
-    // to one branch would silently vanish on the other.
+    // One literal for both routing modes: two verbatim copies differing only by
+    // the `providerRouting` key would mean a snapshot field added to one branch
+    // silently vanishes on the other.
     const snapshot = deepFreeze({
       revision,
       candidates: Object.freeze([...built.candidates]) as readonly RouteCandidate[],
@@ -508,8 +540,8 @@ export class InMemoryRouteSnapshotService implements RouteSnapshotService {
     });
     // A mutation during the build means this snapshot describes a catalog that
     // has already been superseded. Returning it is fine — the caller asked
-    // before the mutation — but caching it would strand the data plane on the
-    // old routing until the next write.
+    // before the mutation — but caching it would strand the data plane on stale
+    // routing until the next write.
     if (revision === this.revision) this.snapshot = snapshot;
     return snapshot;
   }

package/src/transport/routing/router.ts

@@ -226,10 +226,10 @@ function spreadDeadline(cooldownUntil: number | undefined): { cooldown_until?: n
  * The soonest moment a quota window the caller is blocked on refills.
  *
  * A usage-floor exclusion is time-bounded by construction — the floor compares
- * the *remaining* allowance, and the window states when that allowance resets —
- * but the exclusion used to carry no deadline, so `plan()` could not tell a
- * client how long to wait and `earliestResetMs` reported nothing. The minimum
- * across windows, for the same reason `earliestResetMs` takes it: the account
+ * the *remaining* allowance, and the window states when that allowance resets.
+ * The exclusion carries a deadline so `plan()` can tell a client how long to
+ * wait and `earliestResetMs` reports a value. The minimum across windows, for
+ * the same reason `earliestResetMs` takes it: the account
  * can serve again as soon as its first window refills, so quoting the slowest
  * would hold the client off longer than necessary.
  *
@@ -317,9 +317,8 @@ export class EligibilityEvaluator {
       return { eligible: false, reason: "model_cooldown", candidate, ...spreadDeadline(state.cooldown_until) };
     if (state.health_status === "cooldown" && state.cooldown_kind === "hard")
       return { eligible: false, reason: "cooldown_hard", candidate, ...spreadDeadline(state.cooldown_until) };
-    // The floor is checked here, not after selection: the old minimum-balance
-    // feature computed the number and never consulted it, so an account below
-    // its floor still won the route. An account with no reading is left
+    // The floor is checked here, not after selection: an account below its
+    // floor must not win the route. An account with no reading is left
     // eligible — a missing quota fetch is not proof the allowance is gone.
     if (belowUsageFloor(state))
       return {
@@ -487,8 +486,8 @@ export class RoutingEngine {
    * Stamps each account with its provider's usage floor and the quota reading
    * the console last fetched, so eligibility can reject an account that has
    * spent down to the floor. The reading is the live cache, not the route
-   * snapshot: a snapshot rebuilt every few minutes would route on a stale
-   * balance, which is how the old floor let a spent account through.
+   * snapshot: a snapshot rebuilt every few minutes routes on a stale balance
+   * and lets a spent account through.
    */
   private async applyUsageFloor(
     candidates: readonly RouteCandidate[],
@@ -598,10 +597,10 @@ export class RoutingEngine {
           d.reason === "model_cooldown" ||
           // A usage-floor exclusion whose window states a reset is the same
           // shape as the two above: the account is resting until a named
-          // instant, not broken. It used to fall through to 503, which told
-          // the client the model was down while every account serving it was
-          // merely waiting for its window to refill — the "503 DOWN while the
-          // model is allowed" report again. Only a floor with *no* stated
+          // instant, not broken. Falling through to 503 tells the client the
+          // model is down while every account serving it is merely waiting for
+          // its window to refill — the "503 DOWN while the model is allowed"
+          // report again. Only a floor with *no* stated
           // reset stays unavailable: there is nothing to retry against yet.
           (d.reason === "quota_exhausted" && typeof d.cooldown_until === "number"),
       );
@@ -828,7 +827,15 @@ export class RoutingEngine {
       const admitted = await this.admission.admit(candidate);
       if (admitted.admitted) return this.reservations.acquire(candidate, plan.revision);
     }
-    throw capacityExhaustedError();
+    // Last candidate's identity names the provider the plan was actually for;
+    // every candidate shares it, so any one of them is representative.
+    const last = plan.candidates[plan.candidates.length - 1];
+    throw capacityExhaustedError({
+      ...(last?.provider_id !== undefined ? { providerId: last.provider_id } : {}),
+      ...(plan.resolved_model !== undefined ? { model: plan.resolved_model } : {}),
+      candidateCount: plan.candidates.length,
+      ...(last?.max_inflight !== undefined ? { maxInflight: last.max_inflight } : {}),
+    });
   }
   async release(reservation: Reservation): Promise<void> {
     await this.admission.release(reservation);

package/src/transport/surface/completion.ts

@@ -45,9 +45,8 @@ function stopReason(events: readonly CanonicalEvent[]): string | null {
 }
 
 /**
- * Completion wire usage. Delegates to the chat builder (same wire family) —
- * completion responses now carry cache/reasoning details instead of dropping
- * them (intended fix; previously only the three totals were forwarded).
+ * Completion wire usage. Delegates to the chat builder (same wire family), so
+ * completion responses carry cache/reasoning details, not just the three totals.
  */
 function usage(events: readonly CanonicalEvent[]): OpenAiUsage | undefined {
   const terminal = [...events].reverse().find((event) => event.type === "terminal");

package/src/transport/surface/dialects.ts

@@ -79,12 +79,11 @@ function parseToolObject(item: Record<string, unknown>, dialect: ToolDialect): T
     }
   } else if (dialect === "responses") {
     // A Responses caller may still send the Chat-shaped envelope — the two
-    // spellings are interchangeable in the wild, and a client that posts
-    // `{"type":"function","function":{"parameters":…}}` here previously fell
-    // through to `schema = item`, which shipped the whole tool object upstream
-    // as the parameter schema and came back as
-    // `invalid_function_parameters` (CodeBuddy 11129). Unwrap it the way the
-    // Chat dialect does before falling back to the flat Responses spelling.
+    // spellings are interchangeable in the wild. Unwrap it the way the Chat
+    // dialect does before falling back to the flat Responses spelling; taking
+    // `schema = item` instead ships the whole tool object upstream as the
+    // parameter schema and comes back as `invalid_function_parameters`
+    // (CodeBuddy 11129).
     const wrapped = isRecord(item["function"]) ? item["function"] : undefined;
     schema =
       item["input_schema"] ??

package/src/transport/surface/responses/encode.ts

@@ -704,6 +704,44 @@ export class ResponsesEventEncoder extends SurfaceStreamEncoder<CanonicalEvent,
       throw new ResponsesLifecycleError("Responses stream ended without a terminal event");
     return [];
   }
+
+  /**
+   * Encodes a fatal stream error as `response.error` followed immediately by
+   * `response.failed`.
+   *
+   * The OpenAI Responses SDK (and any strict client) requires a terminal
+   * lifecycle event (`response.completed`, `response.failed`, or
+   * `response.incomplete`) to close the stream cleanly.  Emitting only
+   * `response.error` and then closing the SSE connection causes the SDK to
+   * throw "stream closed before a terminal response event was received".
+   *
+   * `response.error` is kept so the client can surface the error message;
+   * `response.failed` immediately follows so the client's state machine
+   * reaches a terminal state and stops waiting.
+   */
+  encodeError(input: {
+    readonly origin: string;
+    readonly code: string;
+    readonly message: string;
+    readonly details: unknown;
+  }): ResponsesWireEvent[] {
+    if (this.terminal) return [];
+    this.terminal = true;
+    const errorEvent = this.emit("response.error", {
+      origin: input.origin,
+      code: input.code,
+      message: input.message,
+      details: input.details,
+    });
+    const response = this.responseObject("failed");
+    response["error"] = {
+      type: "server_error",
+      code: input.code,
+      message: input.message,
+    };
+    const failedEvent = this.emit("response.failed", { response });
+    return [errorEvent, failedEvent];
+  }
 }
 
 /** Encode synchronous canonical events into ordered Responses wire events. */

package/src/transport/surface/responses/parse.ts

@@ -456,6 +456,10 @@ function parseInputItem(item: ResponsesInputItem): {
         encrypted_content: encrypted,
       };
       if (summary !== undefined) reasoningPart.summary = summary;
+      // The upstream binds encrypted reasoning to the item id it was issued
+      // for; a replay under a different id is rejected outright.
+      const itemId = typeof item["id"] === "string" ? item["id"] : undefined;
+      if (itemId !== undefined) reasoningPart.item_id = itemId;
       return {
         message: { role: "assistant", content: [reasoningPart] },
         metadata: itemMetadata(item),

package/src/transport/translation/capabilities.ts

@@ -334,9 +334,8 @@ export function deriveRequiredCapabilities(
   for (const key of Object.keys(request.generation_controls)) {
     // `extension:*` keys are passthrough hints to the wire codec, not route
     // capabilities: the codec reads the names it understands and drops the
-    // rest. Gating them here used to strip every hint (this set was never
-    // populated), degrading `include_usage`, `prompt_cache_key`, `user`,
-    // `metadata`, etc. and re-warning per request.
+    // rest. Gating them here would strip `include_usage`, `prompt_cache_key`,
+    // `user`, `metadata`, etc. and re-warn per request.
     if (key.startsWith("extension:")) continue;
     capabilities.push(`generation_control:${key}`);
   }

package/src/transport/translation/quirks.ts

@@ -180,9 +180,9 @@ export function applyParamQuirks(
   const quirk = findParamQuirk(providerId, request.model);
   // The thinking-sampling strip is universal, not quirk-gated: extended
   // thinking rejects temperature/top_p/top_k on every Messages-wire upstream.
-  // Previously the early return below skipped it for any provider without a
-  // PARAM_QUIRKS row (only anthropic/claude had one), so strict upstreams got
-  // a 400 the strip exists to prevent. Declarative rows still apply after.
+  // It runs before the early return below so a provider with no PARAM_QUIRKS
+  // row still gets it — otherwise a strict upstream takes a 400 the strip
+  // exists to prevent. Declarative rows still apply after.
 
   let controls = request.generation_controls;
   let changed = false;

package/src/workers/buddy-growth-tasks.ts

@@ -22,6 +22,7 @@ import { randomUUID } from "node:crypto";
 import type { CartethyiaDatabase } from "../persistence/db-handle";
 import { buddyTaskLedger, providerAccounts } from "../persistence/schema";
 import { log } from "../observability/logger";
+import { sleep } from "../shared/sleep";
 import { buddyAccountUid } from "../providers/integrations/buddy/buddy-oauth-shared";
 import {
   adoptFirstBuddy,
@@ -207,12 +208,6 @@ async function forAccount(
   return run(call);
 }
 
-/** Pause between accounts, so one pass does not look like a burst upstream. */
-function sleep(ms: number): Promise<void> {
-  const { promise, resolve } = Promise.withResolvers<void>();
-  setTimeout(resolve, ms);
-  return promise;
-}
 /** Walks the accounts, skipping any already settled today. */
 async function runTask(
   deps: BuddyTaskDeps,
@@ -353,10 +348,10 @@ export function buddyTrialTask(deps: BuddyTaskDeps) {
  * Growth-activity report: the `/v2/report` batch that lights the login streak and
  * scores the daily growth event.
  *
- * It used to ride the quota sweep with no ledger of its own, which meant eight
- * POSTs per account *per sweep* (two rounds of four events) because the sweep
- * ran every minute. It is its own once-a-day task here, gated by the same
- * (day, account, task) ledger as every other growth task.
+ * It is a once-a-day task with its own ledger, gated by the same
+ * (day, account, task) ledger as every other growth task: running it on the
+ * quota sweep would post two rounds of four events per account per sweep, and
+ * the sweep runs every minute.
  *
  * The report is not a credit claim, so its failure never marks an account
  * unhealthy — the result is logged and the ledger is stamped either way.

package/src/workers/daily-checkin.ts

@@ -120,9 +120,8 @@ export function ledgerKey(dayKey: string, accountId: string): string {
  * With Redis the `SET NX EX` is the cross-process guard (two gateway instances
  * cannot both attempt the same account). Without it the ledger *table* is the
  * guard, and its composite PK makes the insert atomic — so Lite records the
- * attempt it just made instead of silently returning `true`, which is what left
- * the console unable to answer "attempted today" and showing "Check-in due"
- * forever.
+ * attempt it just made instead of silently returning `true`, which leaves the
+ * console unable to answer "attempted today" and shows "Check-in due" forever.
  */
 async function reserveDaySlot(
   db: CartethyiaDatabase | undefined,
@@ -160,8 +159,8 @@ async function reserveDaySlot(
  * Releases today's slot for many accounts in one round-trip.
  *
  * The sweep reserves a slot per account as it walks the wave; releasing them
- * one at a time on the error path turned every failed pass into a Redis RTT per
- * failed account. A pass that budgets out with twenty failures paid twenty
+ * one at a time on the error path turns every failed pass into a Redis RTT per
+ * failed account. A pass that budgets out with twenty failures pays twenty
  * round-trips for bookkeeping that has no bearing on the claim itself.
  *
  * A pipeline is used when Redis is present (one `MULTI/DEL` for the whole
@@ -246,8 +245,8 @@ export async function markCheckinAttempted(args: {
  * The read belongs next to the writes because there are two places the marker
  * can live — the Redis key when Redis is present, the `daily_checkin_ledger`
  * row when it is not — and only this module knows which one its own writes
- * used. A caller that read the Redis key directly answered "not attempted" on
- * every Lite deployment, where the sweep had written the row.
+ * used. A caller that reads the Redis key directly answers "not attempted" on
+ * every Lite deployment, where the sweep writes the row.
  *
  * Absent or unreadable means unknown, never "not claimed": the sweep may
  * simply not have reached the account yet.
@@ -355,9 +354,9 @@ export function supportsDailyCheckin(providerId: string): boolean {
  * Wraps a proxy-bound fetcher so a 403 falls back to a direct connection once.
  *
  * A proxy that answers 403 (auth, expired pool credential, a provider that
- * rejects the egress) used to fail the whole claim even though the account's
- * own credential was fine — the proxy was the only thing wrong. One direct
- * retry costs nothing when the proxy was healthy (the first attempt already
+ * rejects the egress) would fail the whole claim even though the account's own
+ * credential was fine — the proxy is the only thing wrong. One direct retry
+ * costs nothing when the proxy was healthy (the first attempt already
  * succeeded) and rescues the claim when it was not.
  *
  * The fallback only fires on 403, not on every error: a 401 means the account
@@ -375,15 +374,10 @@ export function withDirectFallback(fetcher: typeof fetch): typeof fetch {
   return wrapped;
 }
 /**
- * The outcome of one daily check-in pass: the claim alone.
- *
- * The growth-activity report is no longer part of this pass — it moved to its
- * own once-a-day growth task (`buddy-activity-report`) with its own ledger, so
-/**
- * Runs the full daily growth pass for one account, once per calendar day: the
- * check-in claim alone. The growth-activity report moved to its own once-a-day
- * growth task (`buddy-activity-report`) with its own ledger, so it is not
- * re-POSTed on every sweep. See `buddy-growth-tasks.ts`.
+ * The outcome of one daily check-in pass: the claim alone. The
+ * growth-activity report runs as its own once-a-day growth task
+ * (`buddy-activity-report`) with its own ledger, so it is not re-POSTed on
+ * every sweep. See `buddy-growth-tasks.ts`.
  */
 export type DailyGrowthPassResult = {
   readonly checkin: DailyCheckinResult;
@@ -448,10 +442,10 @@ export async function attemptDailyGrowthPass(args: {
 
   // Only a transient `error` releases the slot so a later pass today can retry
   // (network, 5xx). `unavailable` is the status probe answering that no
-  // activity is running — retrying that every pass spent the account's daily
-  // slot on a door the provider had closed, and releasing the marker was also
-  // what erased the evidence that anything had been attempted: the console then
-  // read "Check-in due" forever while the sweep retried once a minute.
+  // activity is running — retrying that every pass spends the account's daily
+  // slot on a door the provider has closed, and releasing the marker also
+  // erases the evidence that anything was attempted: the console then reads
+  // "Check-in due" forever while the sweep retries once a minute.
   // `already_claimed`, `not_eligible`, and `event_ended` are terminal for the
   // day and keep the slot.
   return { checkin };