cartethyia 2.7.3 → 2.7.5

package/src/console/routing/pools/relay-deploy.ts

@@ -36,7 +36,7 @@ export const RELAY_TARGETS: readonly RelayTarget[] = ["cloudflare", "vercel", "d
  * The same handler body runs on Workers and Vercel Edge (`export default {
  * fetch }`); the Deno entry wraps it in `Deno.serve`.
  */
-export const RELAY_WORKER_SOURCE = `// Cartethyia hosted relay.
+const RELAY_WORKER_SOURCE = `// Cartethyia hosted relay.
 //
 // Forwards a request to the origin named by the x-relay-target header, at the
 // path named by x-relay-path. Deployed to Cloudflare Workers / Vercel Edge.
@@ -83,7 +83,7 @@ export default handler;
 `;
 
 /** A Deno Deploy entry wraps the shared handler in `Deno.serve`. */
-export const RELAY_DENO_SOURCE = `${RELAY_WORKER_SOURCE}
+const RELAY_DENO_SOURCE = `${RELAY_WORKER_SOURCE}
 Deno.serve((request) => handler.fetch(request));
 `;
 
@@ -111,7 +111,7 @@ export interface RelayDeployResult {
 }
 
 /** Outbound fetch seam (the validated fetch), so tests can stub deploys. */
-export type RelayFetch = (url: string, init: RequestInit) => Promise<Response>;
+type RelayFetch = (url: string, init: RequestInit) => Promise<Response>;
 
 function generateName(prefix: string): string {
   return `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
@@ -151,7 +151,7 @@ async function deployCloudflare(
   request: RelayDeployRequest,
 ): Promise<RelayDeployResult> {
   const accountId = request.accountId?.trim();
-  if (!accountId) throw new GatewayError("invalid_request", 400, "Cloudflare account id is required");
+  if (!accountId) throw new GatewayError("invalid_request", 400, "Cloudflare account id is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
   const projectName = request.projectName?.trim() || generateName("relay");
   const scriptUrl = `https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(accountId)}/workers/scripts/${encodeURIComponent(projectName)}`;
   const form = new FormData();
@@ -174,7 +174,7 @@ async function deployCloudflare(
     body: form,
   });
   if (!upload.ok)
-    throw new GatewayError("platform_unavailable", upload.status, `Cloudflare deploy failed: ${await readError(upload)}`);
+    throw new GatewayError("platform_unavailable", upload.status, `Cloudflare deploy failed (request {requestId}): ${await readError(upload)}. Flip the switch back on when ready 🔌`);
   // Enable the workers.dev route; a failure here is non-fatal because the
   // subdomain lookup below decides the final URL and reports its own error.
   await fetchImpl(`${scriptUrl}/subdomain`, {
@@ -190,7 +190,7 @@ async function deployCloudflare(
     throw new GatewayError(
       "platform_unavailable",
       subdomainRes.status,
-      `Worker uploaded but its workers.dev subdomain could not be read: ${await readError(subdomainRes)}`,
+      `Worker uploaded but its workers.dev subdomain could not be read (request {requestId}): ${await readError(subdomainRes)}. Flip the switch back on when ready 🔌`,
     );
   const subdomainData = (await subdomainRes.json().catch(() => ({}))) as {
     result?: { subdomain?: string };
@@ -200,7 +200,7 @@ async function deployCloudflare(
     throw new GatewayError(
       "platform_unavailable",
       502,
-      "Worker uploaded but no workers.dev subdomain is configured for this Cloudflare account.",
+      "Worker uploaded but no workers.dev subdomain is configured for this Cloudflare account (request {requestId}). Flip the switch back on when ready 🔌",
     );
   return { target: "cloudflare", projectName, relayUrl: `https://${projectName}.${subdomain}.workers.dev` };
 }
@@ -251,7 +251,7 @@ async function deployVercel(
     }),
   });
   if (!deployRes.ok)
-    throw new GatewayError("platform_unavailable", deployRes.status, `Vercel deploy failed: ${await readError(deployRes)}`);
+    throw new GatewayError("platform_unavailable", deployRes.status, `Vercel deploy failed (request {requestId}): ${await readError(deployRes)}. Flip the switch back on when ready 🔌`);
   // Pin the region again after the deploy created the project: the PATCH above
   // is a no-op on first deploy (the project does not exist yet), and a redeploy
   // is what Vercel requires for a region change to take effect anyway. The SSO
@@ -280,7 +280,7 @@ async function deployVercel(
   }).catch(() => undefined);
   const deployment = (await deployRes.json().catch(() => ({}))) as { url?: string };
   if (!deployment.url)
-    throw new GatewayError("platform_unavailable", 502, "Vercel deploy returned no URL");
+    throw new GatewayError("platform_unavailable", 502, "Vercel deploy returned no URL (request {requestId}). Flip the switch back on when ready 🔌");
   return {
     target: "vercel",
     projectName,
@@ -300,11 +300,11 @@ async function deployDeno(
     body: JSON.stringify({ project: projectName, entryPoint: "main.ts", files: { "main.ts": RELAY_DENO_SOURCE } }),
   });
   if (!deployRes.ok)
-    throw new GatewayError("platform_unavailable", deployRes.status, `Deno deploy failed: ${await readError(deployRes)}`);
+    throw new GatewayError("platform_unavailable", deployRes.status, `Deno deploy failed (request {requestId}): ${await readError(deployRes)}. Flip the switch back on when ready 🔌`);
   const deployment = (await deployRes.json().catch(() => ({}))) as { url?: string; domains?: string[] };
   const url = deployment.url ?? deployment.domains?.[0];
   if (!url)
-    throw new GatewayError("platform_unavailable", 502, "Deno deploy returned no URL");
+    throw new GatewayError("platform_unavailable", 502, "Deno deploy returned no URL (request {requestId}). Flip the switch back on when ready 🔌");
   return {
     target: "deno",
     projectName,
@@ -333,6 +333,6 @@ export async function deployRelay(
   request: RelayDeployRequest,
 ): Promise<RelayDeployResult> {
   if (!request.token.trim())
-    throw new GatewayError("invalid_request", 400, `${request.target} API token is required`);
+    throw new GatewayError("invalid_request", 400, `${request.target} API token is required (request {requestId}). Wrong key, right door — check the credential 🔑`);
   return DEPLOYERS[request.target](fetchImpl, request);
 }

package/src/console/routing/pools/routes.ts

@@ -1,5 +1,5 @@
 // Network-pool control-plane HTTP routes. The only module that touches Elysia.
-import { Elysia, t } from "elysia";
+import { Elysia, t, type AnyElysia } from "elysia";
 import { consoleErrorHandler } from "../../shared/errors";
 import { literalUnion } from "../../shared/elysia-schema";
 import { RELAY_TARGETS, type RelayDeployRequest } from "./relay-deploy";
@@ -56,7 +56,7 @@ const importPoolsBody = t.Object({
   family: t.Optional(t.Union([t.String(), t.Null()])),
   labelPrefix: t.Optional(t.String()),
 });
-export function createNetworkPoolRoutes(config: NetworkPoolConfig): Elysia {
+export function createNetworkPoolRoutes(config: NetworkPoolConfig): AnyElysia {
   const factory = createNetworkPoolOperations(config);
   return new Elysia({ prefix: "/network/pools" })
     .error(consoleErrorHandler("Network pool operation failed"))
@@ -207,5 +207,5 @@ export function createNetworkPoolRoutes(config: NetworkPoolConfig): Elysia {
           body as Partial<PoolStrategySetting>,
         );
 },
-    ) as unknown as Elysia;
+    );
 }

package/src/console/routing/pools/store.ts

@@ -1,7 +1,9 @@
 // Drizzle-backed console persistence for network pools.
+import { randomUUID } from "node:crypto";
 import { and, asc, eq, inArray, sql } from "drizzle-orm";
 import type { CartethyiaDatabase } from "../../../persistence/db-handle";
-import { networkPools, poolRoutingSettings } from "../../../persistence/schema";
+import { networkPools, poolRoutingSettings, providerPoolAccounts } from "../../../persistence/schema";
+import { providerRateLimitIsIpScoped } from "../../../providers/provider-metadata";
 import {
   DEFAULT_POOL_STRATEGY,
   type CreateNetworkPoolRequest,
@@ -444,6 +446,24 @@ export class DrizzleNetworkPoolStore implements NetworkPoolStore {
       ...(record.family !== undefined ? { family: record.family } : {}),
     }));
     await this.db.insert(networkPools).values(values);
+
+    // Materialize pool-as-account rows for ip-scoped, credential-less
+    // providers (OpenCode Free today): the operator sees the egress in the
+    // provider's Accounts card, and routing excludes a spent egress like a
+    // cooling account. Every other provider gets no row.
+    if (providerRateLimitIsIpScoped("opencode")) {
+      const now = new Date();
+      const poolAccounts = values.map((value) => ({
+        id: randomUUID(),
+        tenantId: value.tenantId,
+        networkPoolId: value.id,
+        providerId: "opencode",
+        label: `Pool ${value.id.slice(0, 8)}`,
+        createdAt: now,
+        updatedAt: now,
+      }));
+      await this.db.insert(providerPoolAccounts).values(poolAccounts);
+    }
     return values.length;
   }
 

package/src/console/settings/contracts.ts

@@ -53,6 +53,12 @@ export interface RuntimeSettingsResponse {
   readonly telemetryWindowMinutes: number | null;
   /** Per-tenant inline attachment ceiling in bytes; null means deployment default. */
   readonly imageClampMaxBytes: number | null;
+  /**
+   * Ordered vision-model ids used to describe images when the selected model
+   * is not image-capable. Empty means the legacy `[image]` placeholder is
+   * used instead.
+   */
+  readonly visionHandoffModels: readonly string[];
   readonly updatedAt: string;
   /*
    * What each `null` actually resolves to, in the same units the row stores.
@@ -67,7 +73,7 @@ export interface RuntimeSettingsResponse {
 }
 
 /** The deployment-level values a `null` runtime setting falls back to. */
-export interface RuntimeSettingsDefaults {
+interface RuntimeSettingsDefaults {
   /** Seconds; from `CARTETHYIA_UPSTREAM_TIMEOUT_MS`. */
   readonly upstreamTimeoutSeconds: number;
   /** Minutes; what the payload store expires frames after. */
@@ -122,7 +128,7 @@ 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];
-export const PRIVACY_MODES = ["masked", "full"] as const;
+const PRIVACY_MODES = ["masked", "full"] as const;
 /** Provider/model label privacy accepted by the runtime-settings PATCH. */
 export type PrivacyMode = (typeof PRIVACY_MODES)[number];
 /** PonyTail directive intensity accepted by the runtime-settings PATCH. */
@@ -130,6 +136,9 @@ export type PonyTailLevel = (typeof PONYTAIL_LEVELS)[number];
 /** RTK prune strength accepted by the runtime-settings PATCH. */
 export type RtkLevel = (typeof RTK_LEVELS)[number];
 
+/** Upper bound on the number of ordered vision-handoff models. */
+export const VISION_HANDOFF_MAX_MODELS = 8;
+
 export function createRuntimeSettingsOperations(deps: RuntimeSettingsConfig) {
   const operations = {
     async get(access: AccessDecision | undefined): Promise<RuntimeSettingsResponse> {
@@ -178,6 +187,23 @@ export function createRuntimeSettingsOperations(deps: RuntimeSettingsConfig) {
         if (patch.rtkPruneLevel !== undefined && !RTK_LEVELS.includes(patch.rtkPruneLevel)) {
           throw new ConsoleDomainError("invalid_request", 400, "Invalid rtkPruneLevel");
         }
+        if (patch.visionHandoffModels !== undefined) {
+          if (!Array.isArray(patch.visionHandoffModels)) {
+            throw new ConsoleDomainError("invalid_request", 400, "visionHandoffModels must be an array of model ids");
+          }
+          if (patch.visionHandoffModels.length > VISION_HANDOFF_MAX_MODELS) {
+            throw new ConsoleDomainError(
+              "invalid_request",
+              400,
+              `visionHandoffModels may list at most ${VISION_HANDOFF_MAX_MODELS} models`,
+            );
+          }
+          for (const model of patch.visionHandoffModels) {
+            if (typeof model !== "string" || model.trim().length === 0) {
+              throw new ConsoleDomainError("invalid_request", 400, "visionHandoffModels entries must be non-empty model ids");
+            }
+          }
+        }
         const updated = await deps.store.update(a.tenantId, patch);
         await deps.auditSink?.record({
           access: a,
@@ -245,4 +271,5 @@ export const runtimeUpdateBody = t.Object({
   imageClampMaxBytes: t.Optional(
     t.Union([t.Null(), t.Number({ minimum: 64 * 1024, maximum: 100 * 1024 * 1024 })]),
   ),
+  visionHandoffModels: t.Optional(t.Array(t.String())),
 });

package/src/console/settings/routes.ts

@@ -1,4 +1,4 @@
-import { Elysia } from "elysia";
+import { Elysia, type AnyElysia } from "elysia";
 import {
   createRuntimeSettingsOperations,
   runtimeUpdateBody,
@@ -7,7 +7,7 @@ import {
   type UpdateRuntimeSettingsRequest,
 } from "./contracts";
 
-export function createRuntimeSettingsRoutes(config: RuntimeSettingsConfig): Elysia {
+export function createRuntimeSettingsRoutes(config: RuntimeSettingsConfig): AnyElysia {
   const factory = createRuntimeSettingsOperations(config);
   return new Elysia({ prefix: "/settings/runtime" })
     .get("/", async ({ request, set }) => {
@@ -26,5 +26,5 @@ export function createRuntimeSettingsRoutes(config: RuntimeSettingsConfig): Elys
       } catch (e) {
         return runtimeSettingsErrorResponse(e, set);
       }
-    }) as unknown as Elysia;
+    });
 }

package/src/console/settings/store.ts

@@ -15,6 +15,7 @@ import {
   RTK_LEVELS,
   TELEMETRY_PAYLOAD_DEPTHS,
   TELEMETRY_PAYLOAD_MODES,
+  VISION_HANDOFF_MAX_MODELS,
   type PonyTailLevel,
   type ResponsesReasoningSummary,
   type RtkLevel,
@@ -115,6 +116,22 @@ function normalizeConcurrencyTolerance(value: unknown): number | null {
   return normalizeBoundedNumber(value, 0, 1024);
 }
 
+/** Ordered vision-handoff models: non-empty strings, trimmed, de-duplicated. */
+function normalizeVisionHandoffModels(value: unknown): readonly string[] {
+  if (!Array.isArray(value)) return [];
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const entry of value) {
+    if (typeof entry !== "string") continue;
+    const model = entry.trim();
+    if (model.length === 0 || seen.has(model)) continue;
+    seen.add(model);
+    out.push(model);
+    if (out.length >= VISION_HANDOFF_MAX_MODELS) break;
+  }
+  return out;
+}
+
 function mapRuntimeSettingsRow(
   row: typeof consoleSettings.$inferSelect | undefined,
   redisBackend: RedisBackend,
@@ -148,6 +165,7 @@ function mapRuntimeSettingsRow(
     upstreamTimeoutSeconds: normalizeUpstreamTimeoutSeconds(prefs.upstreamTimeoutSeconds),
     telemetryWindowMinutes: normalizeTelemetryWindowMinutes(prefs.telemetryWindowMinutes),
     imageClampMaxBytes: normalizeImageClampMaxBytes(prefs.imageClampMaxBytes),
+    visionHandoffModels: normalizeVisionHandoffModels(prefs.visionHandoffModels),
     updatedAt,
     /*
      * Resolved at request time, not at module load: all four come from env the
@@ -211,6 +229,8 @@ export class DrizzleRuntimeSettingsStore implements RuntimeSettingsStore {
       );
     if (patch.imageClampMaxBytes !== undefined)
       patchPrefs.imageClampMaxBytes = normalizeImageClampMaxBytes(patch.imageClampMaxBytes);
+    if (patch.visionHandoffModels !== undefined)
+      patchPrefs.visionHandoffModels = normalizeVisionHandoffModels(patch.visionHandoffModels);
 
     const rows = await this.db
       .insert(consoleSettings)

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

@@ -4,7 +4,7 @@ import { globalOrOwnedBy } from "../../persistence/tenant-scope";
 // Share URLs reveal policy and allow one child key to be created per canonical
 // client IP. The child bearer is returned only by the successful issue call.
 
-import { Elysia } from "elysia";
+import { Elysia, type AnyElysia } from "elysia";
 import { and, eq, sql } from "drizzle-orm";
 import type { CartethyiaDatabase } from "../../persistence/db-handle";
 import { apiKeys, models, providers } from "../../persistence/schema";
@@ -34,12 +34,83 @@ const MIN_TOKEN_LENGTH = 20;
 /**
  * Cadence of the share stats SSE snapshot.
  *
- * Raised with `SHARE_STATS_CACHE_TTL_SECONDS` (10 s). At 2 s the tick was
- * shorter than the rollup's own cache TTL, so every push re-parsed the whole
- * retained telemetry window — the interval was the thing making this read
- * expensive, not the number of viewers. Short enough to still read as live.
+ * Roughly one tenth of the cache TTL (`SHARE_STATS_CACHE_TTL_SECONDS`, 300
+ * s), so nearly every tick is served from the cache and the cold-compute
+ * path runs at most once per five minutes per family. Short enough to still
+ * read as live.
  */
-const SHARE_STATS_STREAM_INTERVAL_MS = 10_000;
+const SHARE_STATS_STREAM_INTERVAL_MS = 30_000;
+
+/**
+ * A subscriber of the process-wide share-stats sampler. A recipient is keyed
+ * by its family (`tenantId` + template key) so one sampler tick can push to
+ * many links without a per-connection timer.
+ */
+type ShareStatsListener = (family: ShareFamilyStats) => void;
+
+/**
+ * One sampler per gateway for share-stats SSE delivery. Previously each
+ * `/share/:token/stats/stream` connection ran its own 30s timer and re-read
+ * the family rollup; with N open tabs that is N timers and N rollups all
+ * reading the same data. Now a single process-level sampler ticks on the
+ * shared cadence and fans each computed rollup out to the subscribers whose
+ * family it matches. Timers run only while at least one stream is open.
+ */
+function createShareStatsSampler(config: {
+  readonly db: CartethyiaDatabase;
+  readonly shareStore: ShareLinkStore;
+  readonly stats: ShareStatsPort;
+}): { subscribe(token: string, listener: ShareStatsListener): () => void } {
+  const subscribers = new Map<string, Set<ShareStatsListener>>();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const tick = async (): Promise<void> => {
+    // One resolve per family token: a recipient with several tabs shares one
+    // rollup, and a family with no open stream is never computed.
+    const tokens = new Set(subscribers.keys());
+    for (const token of tokens) {
+      const listeners = subscribers.get(token);
+      if (listeners === undefined || listeners.size === 0) continue;
+      try {
+        const family = await resolveFamilyStats(config.db, config.shareStore, config.stats, token);
+        if (family === null) continue;
+        for (const listener of listeners) listener(family);
+      } catch {
+        // A transient read must not interrupt the sampler.
+      }
+    }
+  };
+
+  const start = (): void => {
+    if (timer !== undefined) return;
+    timer = setTimeout(async function run() {
+      timer = setTimeout(run, SHARE_STATS_STREAM_INTERVAL_MS);
+      await tick();
+    }, SHARE_STATS_STREAM_INTERVAL_MS);
+  };
+
+  const stop = (): void => {
+    if (timer !== undefined) clearTimeout(timer);
+    timer = undefined;
+  };
+
+  return {
+    subscribe(token, listener) {
+      let listeners = subscribers.get(token);
+      if (listeners === undefined) {
+        listeners = new Set();
+        subscribers.set(token, listeners);
+      }
+      listeners.add(listener);
+      if (subscribers.size > 0) start();
+      return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0) subscribers.delete(token);
+        if (subscribers.size === 0) stop();
+      };
+    },
+  };
+}
 
 /**
  * Context and capabilities for one allowed model, sourced from the public
@@ -56,7 +127,7 @@ export interface ShareModelInfo {
   readonly webSearch: boolean;
 }
 
-export interface ShareRouterOptions {
+interface ShareRouterOptions {
   readonly db: CartethyiaDatabase;
   readonly shareStore: ShareLinkStore;
   /** Resolves the normalized client IP through the trusted-proxy boundary. */
@@ -89,12 +160,12 @@ function json(body: unknown, status = 200): Response {
 function notFound(refusal: ShareLinkRefusal = "not_found"): Response {
   const message =
     refusal === "expired"
-      ? "This share link has expired"
+      ? "This share link has expired (request {requestId}). Time for a fresh one 🌷"
       : refusal === "revoked"
-        ? "This share link's key has been revoked"
+        ? "This share link's key has been revoked (request {requestId}). Ask for a new one 📩"
         : refusal === "disabled"
-          ? "This share link's key is paused"
-          : "Share link is unavailable";
+          ? "This share link's key is paused (request {requestId}). Re-enable it when ready 🌱"
+          : "Share link is unavailable (request {requestId}). This link leads nowhere — check it again 🔗";
   const error = new GatewayError(`link_${refusal}`, 404, message);
   return json(publicGatewayErrorBody(error), error.status);
 }
@@ -261,8 +332,14 @@ async function resolveFamilyStats(
 }
 
 /** Creates the public enrollment page and one-time shared-key issuance route. */
-export function createShareRouter(options: ShareRouterOptions): Elysia {
+export function createShareRouter(options: ShareRouterOptions): AnyElysia {
   const { db, shareStore } = options;
+  // The sampler is shared by every stats stream this router serves; it is a
+  // no-op when the composition omits `stats` (tests that do not exercise the
+  // stream), because `tick` never runs with no subscribers.
+  const statsSampler = options.stats === undefined
+    ? undefined
+    : createShareStatsSampler({ db, shareStore, stats: options.stats });
 
   return new Elysia()
     /**
@@ -296,6 +373,7 @@ export function createShareRouter(options: ShareRouterOptions): Elysia {
         oneTimeLimit: row.lifetimeTokenBudget,
         requestsPerMinute: row.requestsPerMinute,
         maxConcurrentRequests: row.maxConcurrentRequests,
+        concurrencyScope: row.concurrencyScope ?? "family",
         modelPrefix: row.modelPrefix,
         models,
         modelInfo,
@@ -442,49 +520,39 @@ export function createShareRouter(options: ShareRouterOptions): Elysia {
     /**
      * Live family activity for the share page's stats section, pushed over SSE.
      *
-     * The stream sends one snapshot immediately on connect, then re-reads on a
-     * short cadence so the recipient watches the shared quota move instead of
-     * refreshing. Telemetry is buffered server-side and drained in under a
-     * second, so a DB re-read on this cadence is as fresh as an event bus would
-     * be. Same bearer token and same masked-IP rollup as the one-shot route; a
-     * token that stops resolving closes the stream rather than reporting zeros.
+     * The stream sends one snapshot immediately on connect, then pushes on a
+     * shared sampler cadence so the recipient watches the shared quota move
+     * instead of refreshing. Telemetry is buffered server-side and drained in
+     * under a second, so the sampler's DB re-read is as fresh as an event bus
+     * would be. Same bearer token and same masked-IP rollup as the one-shot
+     * route; a token that stops resolving closes the stream rather than
+     * reporting zeros.
      */
     .get("/share/:token/stats/stream", async ({ params, request }) => {
       if (typeof params.token !== "string") return notFound();
       const token = params.token;
       if (token.length < MIN_TOKEN_LENGTH) return notFound();
       const stats = options.stats;
-      if (!stats) return json({ error: { code: "stats_unavailable", message: "Stats are unavailable" } }, 503);
+      if (!stats || statsSampler === undefined) {
+        return json({ error: { code: "stats_unavailable", message: "Stats are unavailable" } }, 503);
+      }
+      const sampler = statsSampler;
       return consoleSseResponse(
         createConsoleSseStream(request.signal, (sender) => {
-          let closed = false;
-          let timer: ReturnType<typeof setTimeout> | undefined;
-          const push = async () => {
-            const family = await resolveFamilyStats(db, shareStore, stats, token);
-            if (closed) return;
+          const unsubscribe = sampler.subscribe(token, (family) => sender.send("stats", family));
+          // Bootstrap: deliver the link's current rollup immediately, and close
+          // the stream if the token no longer resolves — the same terminal
+          // behavior the per-connection timer had on a dead link.
+          void resolveFamilyStats(db, shareStore, stats, token).then((family) => {
             if (family === null) {
               sender.send("error", { code: "link_not_found" });
-              closed = true;
-              return;
+              unsubscribe();
+            } else {
+              sender.send("stats", family);
             }
-            sender.send("stats", family);
-          };
-          const schedule = () => {
-            timer = setTimeout(() => {
-              if (closed) return;
-              void push().finally(() => {
-                if (!closed) schedule();
-              });
-            }, SHARE_STATS_STREAM_INTERVAL_MS);
-          };
-          void push().finally(() => {
-            if (!closed) schedule();
-          });
-          return () => {
-            closed = true;
-            clearTimeout(timer);
-          };
+          }).catch(() => undefined);
+          return unsubscribe;
         }),
       );
-    }) as unknown as Elysia;
+    })
 }