@telorun/runner-core 0.5.2

package/src/routes/io.ts

@@ -0,0 +1,265 @@
+import type { FastifyInstance, FastifyPluginAsync, FastifyRequest } from "fastify";
+import type { WebSocket } from "@fastify/websocket";
+
+import { isTerminal } from "../contract.js";
+import type { BufferedBytes } from "../session/byte-ring-buffer.js";
+import type { SessionRegistry } from "../session/registry.js";
+
+export interface IoRouteDeps {
+  registry: SessionRegistry;
+  corsOrigins: string[] | "*";
+}
+
+const RESIZE_THROTTLE_MS = 50;
+const SEQ_PREFIX_BYTES = 4;
+/** Upper bound on cols/rows accepted from the client. xterm + a fit addon
+ *  produce values in the low thousands at extreme zoom; anything past this
+ *  is either nonsense or a malicious client trying to feed
+ *  `Number.MAX_SAFE_INTEGER` straight to the workload. */
+const MAX_RESIZE_DIMENSION = 10_000;
+const TERMINAL_DRAIN_INTERVAL_MS = 50;
+const TERMINAL_DRAIN_MAX_MS = 2_000;
+
+interface ControlFrame {
+  type: string;
+  cols?: number;
+  rows?: number;
+}
+
+export function ioRoute(deps: IoRouteDeps): FastifyPluginAsync {
+  return async (app: FastifyInstance) => {
+    app.get<{ Params: { id: string }; Querystring: { lastSeq?: string } }>(
+      "/v1/sessions/:id/io",
+      { websocket: true },
+      (socket, req) => handleIo(socket, req, deps),
+    );
+  };
+}
+
+function handleIo(
+  socket: WebSocket,
+  req: FastifyRequest<{ Params: { id: string }; Querystring: { lastSeq?: string } }>,
+  deps: IoRouteDeps,
+): void {
+  // Origin allowlist runs INSIDE the handler (post-handshake) rather than
+  // in a preValidation hook. Reason: a 403 HTTP response on a failed
+  // upgrade is invisible to browser WebSocket clients — they only ever
+  // see close code 1006 (abnormal closure), which is indistinguishable
+  // from a transient network failure and triggers exponential-backoff
+  // reconnect loops forever. Closing with an application code (4403) the
+  // browser CAN read lets the client fail fast.
+  const origin = headerString(req.headers.origin);
+  if (!isOriginAllowed(deps.corsOrigins, origin)) {
+    closeWith(socket, 4403, "forbidden_origin");
+    return;
+  }
+
+  const sessionId = req.params.id;
+  const entry = deps.registry.get(sessionId);
+  if (!entry) {
+    closeWith(socket, 4404, "session not found");
+    return;
+  }
+
+  const lastSeq = parseLastSeq(req.query.lastSeq);
+
+  // Subscribe BEFORE snapshotting the replay buffer. This is load-bearing:
+  // a `pushBytes` that fires between snapshot and subscribe would otherwise
+  // be lost, with no way for either side to detect the gap. Bytes that
+  // arrive during the deferred window are queued; once replay is sent, the
+  // queue is drained (filtering anything seq-overlapping with replay) and
+  // the handler switches to direct-send mode.
+  let mode: "deferred" | "direct" = "deferred";
+  const liveQueue: BufferedBytes[] = [];
+  const unsubscribe = deps.registry.subscribeBytes(sessionId, (buffered) => {
+    if (socket.readyState !== socket.OPEN) return;
+    if (mode === "deferred") {
+      liveQueue.push(buffered);
+    } else {
+      sendBytesFrame(socket, buffered);
+    }
+  });
+
+  const { entries, hasGap } = entry.byteBuffer.replay(lastSeq);
+
+  // If the session is already terminal AND the byte buffer holds nothing
+  // newer than what the client already saw, there's no live channel to
+  // attach to — close 4410 so the client falls back to status-only display.
+  if (isTerminal(entry.status) && entries.length === 0 && liveQueue.length === 0) {
+    unsubscribe();
+    closeWith(socket, 4410, "session terminal, nothing to replay");
+    return;
+  }
+
+  // Confirm the resume point so the client can validate its own bookkeeping.
+  sendJson(socket, { type: "seq", seq: lastSeq });
+  if (hasGap) {
+    sendJson(socket, { type: "gap", reason: "buffer_evicted" });
+  }
+  for (const buffered of entries) {
+    sendBytesFrame(socket, buffered);
+  }
+
+  // Drain any live pushes that landed during the deferred window. Replay
+  // entries are seq-monotonic, so anything queued with seq <= the last
+  // replayed seq is a duplicate and must be dropped.
+  const lastReplayedSeq =
+    entries.length > 0 ? entries[entries.length - 1]!.seq : lastSeq;
+  for (const buffered of liveQueue) {
+    if (buffered.seq > lastReplayedSeq) {
+      sendBytesFrame(socket, buffered);
+    }
+  }
+  liveQueue.length = 0;
+  // Synchronous flip — JS event loop guarantees no pushBytes can fire
+  // between the drain loop above and this assignment, so the handler
+  // doesn't need to lock.
+  mode = "direct";
+
+  let resizeTimer: NodeJS.Timeout | null = null;
+  let pendingResize: { cols: number; rows: number } | null = null;
+  const flushResize = (): void => {
+    resizeTimer = null;
+    const next = pendingResize;
+    pendingResize = null;
+    if (!next) return;
+    // Session may have exited between schedule and flush; backends treat
+    // resize on a gone workload as a no-op.
+    entry.session?.resize(next.cols, next.rows);
+  };
+
+  socket.on("message", (raw, isBinary) => {
+    if (isBinary) {
+      const session = entry.session;
+      if (!session) return;
+      const buf = raw instanceof Buffer ? raw : Buffer.from(raw as ArrayBuffer);
+      session.writeStdin(buf);
+      return;
+    }
+    const text = raw.toString();
+    let parsed: ControlFrame;
+    try {
+      parsed = JSON.parse(text) as ControlFrame;
+    } catch {
+      return;
+    }
+    if (parsed.type === "resize") {
+      const cols = clampDimension(parsed.cols);
+      const rows = clampDimension(parsed.rows);
+      if (cols === null || rows === null) return;
+      pendingResize = { cols, rows };
+      if (resizeTimer === null) {
+        resizeTimer = setTimeout(flushResize, RESIZE_THROTTLE_MS);
+      }
+    }
+  });
+
+  // Close the socket when the session reaches terminal status — replay
+  // already covered the buffered bytes, no live bytes will arrive after
+  // this, and clients can rely on socket close as their "stream finished"
+  // signal alongside the SSE status frame. We poll `bufferedAmount` so
+  // that an immediate close doesn't drop frames still queued on the
+  // server-side socket.
+  let drainTimer: NodeJS.Timeout | null = null;
+  const drainAndClose = (deadline: number): void => {
+    drainTimer = null;
+    if (socket.readyState !== socket.OPEN) return;
+    if (socket.bufferedAmount === 0 || Date.now() >= deadline) {
+      try {
+        socket.close(1000, "session terminal");
+      } catch {
+        /* already closed */
+      }
+      return;
+    }
+    drainTimer = setTimeout(() => drainAndClose(deadline), TERMINAL_DRAIN_INTERVAL_MS);
+  };
+
+  const unsubscribeStatus = deps.registry.subscribe(sessionId, (buffered) => {
+    if (buffered.event.type !== "status") return;
+    if (!isTerminal(entry.status)) return;
+    if (drainTimer !== null) return;
+    drainAndClose(Date.now() + TERMINAL_DRAIN_MAX_MS);
+  });
+
+  // Late-connect case: the session was already terminal at connect time
+  // and had replayable bytes (so we didn't take the 4410 fast path). The
+  // status subscription above will never fire — so the socket would
+  // otherwise stay open forever after replay completes. Schedule directly.
+  if (isTerminal(entry.status) && drainTimer === null) {
+    drainAndClose(Date.now() + TERMINAL_DRAIN_MAX_MS);
+  }
+
+  const cleanup = (): void => {
+    unsubscribe();
+    unsubscribeStatus();
+    if (resizeTimer) clearTimeout(resizeTimer);
+    if (drainTimer) clearTimeout(drainTimer);
+  };
+  socket.on("close", cleanup);
+  socket.on("error", cleanup);
+}
+
+/** Wire format for a binary frame: `[seq:4 BE][payload:N]`. The 4-byte
+ *  prefix lets the client de-sync detect — it knows the authoritative seq
+ *  for every byte received, instead of inferring from frame count. Replay
+ *  duplicates and reconnect resumes both lean on this. */
+function sendBytesFrame(socket: WebSocket, buffered: BufferedBytes): void {
+  if (socket.readyState !== socket.OPEN) return;
+  const prefix = Buffer.alloc(SEQ_PREFIX_BYTES);
+  prefix.writeUInt32BE(buffered.seq, 0);
+  try {
+    socket.send(Buffer.concat([prefix, buffered.bytes]));
+  } catch {
+    /* socket closed under our feet */
+  }
+}
+
+function closeWith(socket: WebSocket, code: number, reason: string): void {
+  try {
+    socket.close(code, reason);
+  } catch {
+    /* socket already closed */
+  }
+}
+
+function sendJson(socket: WebSocket, payload: unknown): void {
+  if (socket.readyState !== socket.OPEN) return;
+  try {
+    socket.send(JSON.stringify(payload));
+  } catch {
+    /* socket closed under our feet */
+  }
+}
+
+function parseLastSeq(raw: string | undefined): number {
+  if (!raw) return 0;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n >= 0 ? n : 0;
+}
+
+function headerString(value: string | string[] | undefined): string | undefined {
+  if (Array.isArray(value)) return value[0];
+  return value;
+}
+
+function clampDimension(raw: unknown): number | null {
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return null;
+  const floored = Math.floor(n);
+  if (floored < 1) return null;
+  return Math.min(floored, MAX_RESIZE_DIMENSION);
+}
+
+function isOriginAllowed(
+  corsOrigins: string[] | "*",
+  origin: string | undefined,
+): boolean {
+  if (corsOrigins === "*") return true;
+  // Browsers ALWAYS send Origin on WebSocket upgrades — a missing Origin
+  // means the request is from a non-browser (curl, internal script, an
+  // attacker who stripped the header). When an explicit allowlist is
+  // configured, an absent Origin is a rejection.
+  if (!origin) return false;
+  return corsOrigins.includes(origin);
+}

package/src/routes/probe.ts

@@ -0,0 +1,35 @@
+import type { FastifyInstance, FastifyPluginAsync } from "fastify";
+
+import type { RunnerBackend } from "../backend.js";
+import type { ProbeConfig } from "../contract.js";
+
+export interface ProbeRouteDeps {
+  backend: RunnerBackend;
+}
+
+const bodySchema = {
+  type: "object",
+  required: ["config"],
+  additionalProperties: false,
+  properties: {
+    config: {
+      type: "object",
+      required: ["image", "pullPolicy"],
+      additionalProperties: false,
+      properties: {
+        image: { type: "string", minLength: 1 },
+        pullPolicy: { type: "string", enum: ["missing", "always", "never"] },
+      },
+    },
+  },
+} as const;
+
+export function probeRoute(deps: ProbeRouteDeps): FastifyPluginAsync {
+  return async (app: FastifyInstance) => {
+    app.post<{ Body: { config: ProbeConfig } }>(
+      "/v1/probe",
+      { schema: { body: bodySchema } },
+      async (req) => deps.backend.probe(req.body.config),
+    );
+  };
+}

package/src/routes/sessions.ts

@@ -0,0 +1,270 @@
+import type { FastifyInstance, FastifyPluginAsync, FastifyReply } from "fastify";
+
+import { isEventFrame } from "@telorun/debug-wire";
+import type { RunnerBackend } from "../backend.js";
+import {
+  ACCEPTED_TERMS_HEADER,
+  SessionStartError,
+  type RunnerTerms,
+  type SessionConfig,
+  type StartSessionRequest,
+} from "../contract.js";
+import { BundlePathError, normalizeBundlePath } from "../session/bundle-path.js";
+import { generateSessionId } from "../session/session-id.js";
+import { SessionLimitError, type SessionRegistry } from "../session/registry.js";
+import { streamSessionEvents } from "../sse/channel.js";
+
+export interface SessionsRouteDeps {
+  backend: RunnerBackend;
+  registry: SessionRegistry;
+  corsOrigins: string[] | "*";
+  /** The runner's own default registry URL, surfaced to the workload as
+   *  TELO_REGISTRY_URL when the request doesn't override it. */
+  defaultRegistryUrl?: string;
+  /** When set, a session may only start if the client acknowledges this exact
+   *  terms version via the `x-telo-accepted-terms` header. */
+  terms?: RunnerTerms;
+  /** Backend-supplied config gate. Returns an error message to reject the
+   *  request with `400 invalid_config`, or `undefined` to accept. The runner is
+   *  the source of truth, so this re-checks what `/v1/capabilities` advertises
+   *  (e.g. an `image` allowlist) against a client that skipped the editor. */
+  validateConfig?: (config: SessionConfig) => string | undefined;
+}
+
+const startBodySchema = {
+  type: "object",
+  required: ["bundle", "env", "config"],
+  properties: {
+    bundle: {
+      type: "object",
+      required: ["entryRelativePath", "files"],
+      properties: {
+        entryRelativePath: { type: "string", minLength: 1 },
+        files: {
+          type: "array",
+          items: {
+            type: "object",
+            required: ["relativePath", "contents"],
+            properties: {
+              relativePath: { type: "string", minLength: 1 },
+              contents: { type: "string" },
+            },
+          },
+        },
+      },
+    },
+    env: {
+      type: "object",
+      additionalProperties: { type: "string" },
+    },
+    ports: {
+      type: "array",
+      items: {
+        type: "object",
+        required: ["port", "protocol"],
+        properties: {
+          port: { type: "integer", minimum: 1, maximum: 65535 },
+          protocol: { type: "string", enum: ["tcp", "udp"] },
+        },
+      },
+    },
+    config: {
+      type: "object",
+      required: ["image", "pullPolicy"],
+      properties: {
+        image: { type: "string", minLength: 1 },
+        pullPolicy: { type: "string", enum: ["missing", "always", "never"] },
+        registryUrl: { type: "string", minLength: 1 },
+      },
+    },
+    inspect: { type: "boolean" },
+  },
+} as const;
+
+export function sessionsRoute(deps: SessionsRouteDeps): FastifyPluginAsync {
+  return async (app: FastifyInstance) => {
+    app.post<{ Body: StartSessionRequest }>(
+      "/v1/sessions",
+      { schema: { body: startBodySchema } },
+      async (req, reply) => {
+        // Terms enforcement — the server is the source of truth, so a client that
+        // skips the editor gate still can't start a session without acknowledging
+        // the current terms version.
+        if (deps.terms) {
+          const raw = req.headers[ACCEPTED_TERMS_HEADER];
+          const accepted = Array.isArray(raw) ? raw[0] : raw;
+          if (accepted !== deps.terms.version) {
+            reply.code(428).send({ error: "terms_required", terms: deps.terms });
+            return;
+          }
+        }
+        return startSession(app, deps, req.body, reply);
+      },
+    );
+
+    app.get<{ Params: { id: string } }>("/v1/sessions/:id", async (req, reply) => {
+      const entry = deps.registry.get(req.params.id);
+      if (!entry) {
+        reply.code(404).send({ error: "not_found", message: `session '${req.params.id}' not in registry` });
+        return;
+      }
+      reply.send({
+        sessionId: entry.sessionId,
+        status: entry.status,
+        createdAt: entry.createdAt.toISOString(),
+        exitedAt: entry.exitedAt?.toISOString(),
+      });
+    });
+
+    app.delete<{ Params: { id: string } }>("/v1/sessions/:id", async (req, reply) => {
+      const entry = deps.registry.get(req.params.id);
+      if (!entry) {
+        reply.code(204).send();
+        return;
+      }
+      entry.userStopped = true;
+      if (entry.session) {
+        try {
+          await entry.session.stop();
+        } catch (err) {
+          app.log.error({ err, sessionId: entry.sessionId }, "failed to stop session");
+          reply.code(500).send({ error: "stop_failed", message: (err as Error).message });
+          return;
+        }
+      }
+      reply.code(204).send();
+    });
+
+    app.get<{ Params: { id: string }; Querystring: { lastEventId?: string } }>(
+      "/v1/sessions/:id/events",
+      async (req, reply) =>
+        streamSessionEvents({
+          registry: deps.registry,
+          req,
+          reply,
+          sessionId: req.params.id,
+          corsOrigins: deps.corsOrigins,
+        }),
+    );
+  };
+}
+
+async function startSession(
+  app: FastifyInstance,
+  deps: SessionsRouteDeps,
+  body: StartSessionRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  const sessionId = generateSessionId();
+
+  let entryRelative: string;
+  try {
+    // Traversal guard for the entry path and every bundle file — a `../foo`
+    // would let the workload read or execute paths outside its session dir.
+    // Validated here (backend-neutral) so a bad path is a 400, not a backend
+    // 500, regardless of how the backend ultimately delivers the bundle.
+    entryRelative = normalizeBundlePath(body.bundle.entryRelativePath);
+    for (const file of body.bundle.files) normalizeBundlePath(file.relativePath);
+  } catch (err) {
+    if (err instanceof BundlePathError) {
+      reply.code(400).send({ error: "invalid_bundle", message: err.message });
+      return;
+    }
+    throw err;
+  }
+
+  // Backend config gate (e.g. an image allowlist). The advertised capabilities
+  // constrain the editor; this enforces the same against any client.
+  if (deps.validateConfig) {
+    const message = deps.validateConfig(body.config);
+    if (message) {
+      reply.code(400).send({ error: "invalid_config", message });
+      return;
+    }
+  }
+
+  let entry: ReturnType<SessionRegistry["register"]>;
+  try {
+    entry = deps.registry.register({ sessionId });
+  } catch (err) {
+    if (err instanceof SessionLimitError) {
+      reply.code(409).send({ error: "too_many_sessions", message: err.message });
+      return;
+    }
+    throw err;
+  }
+
+  // Surface a TELO_REGISTRY_URL to the workload so the telo CLI inside picks
+  // it up. Precedence: body.env explicit value > body.config.registryUrl
+  // (per-request override) > runner's own default. Trim client-supplied URLs
+  // so stray whitespace from an editor input doesn't flow into the workload.
+  const configRegistryUrl = body.config.registryUrl?.trim() || undefined;
+  const registryUrl = configRegistryUrl ?? deps.defaultRegistryUrl;
+  const sessionEnv =
+    registryUrl && !("TELO_REGISTRY_URL" in body.env)
+      ? { ...body.env, TELO_REGISTRY_URL: registryUrl }
+      : body.env;
+
+  // Respond as soon as the session is registered — BEFORE the backend starts.
+  // `backend.start()` now spans the on-cluster image build and pod bring-up,
+  // which can take seconds-to-minutes; awaiting it here would hide the event
+  // stream until the workload is already up, so the client never sees build /
+  // provision / boot progress live. Returning the streamUrl first lets the
+  // client connect immediately; start runs in the background and its progress,
+  // output, and terminal status flow over the stream.
+  reply.code(201).send({
+    sessionId,
+    streamUrl: `/v1/sessions/${sessionId}/events`,
+    createdAt: entry.createdAt.toISOString(),
+  });
+
+  deps.backend
+    .start({
+      sessionId,
+      bundle: body.bundle,
+      entryRelativePath: entryRelative,
+      env: sessionEnv,
+      ports: body.ports ?? [],
+      config: body.config,
+      inspect: body.inspect ?? false,
+      onStatus: (status) => deps.registry.emit(sessionId, { type: "status", status }),
+      onProgress: (phase, message, done) =>
+        deps.registry.emit(sessionId, { type: "progress", phase, message, done }),
+      onOutput: (chunk) => deps.registry.pushBytes(sessionId, chunk),
+      // Relay only kernel *event* frames to the client. stdout/stderr already
+      // arrive over the byte channel (onOutput), so forwarding log frames would
+      // double the traffic and let log spam evict lifecycle events from the
+      // byte-capped replay buffer. The editor discards relayed logs anyway.
+      onDebug: (frame) => {
+        if (isEventFrame(frame)) deps.registry.emit(sessionId, { type: "debug", frame });
+      },
+      isUserStopped: () => entry.userStopped,
+    })
+    .then(async (session) => {
+      entry.session = session;
+      // Pre-start DELETE race: a DELETE received during backend.start (e.g.
+      // while an image build was running) can't stop a workload that didn't
+      // exist yet — it set userStopped and returned 204. Now that the workload
+      // is live, honor the earlier DELETE.
+      if (entry.userStopped) {
+        try {
+          await session.stop();
+        } catch (err) {
+          app.log.warn({ err, sessionId }, "failed to stop after race with pre-start DELETE");
+        }
+      }
+    })
+    .catch((err) => {
+      // The 201 is already sent, so a start failure surfaces as a terminal
+      // `failed` status on the stream (the registry schedules eviction on a
+      // terminal status; the SSE channel delivers it, then closes).
+      const message =
+        err instanceof SessionStartError
+          ? `${err.stage}: ${err.message}`
+          : err instanceof Error
+            ? err.message
+            : String(err);
+      app.log.error({ err, sessionId }, "session start failed");
+      deps.registry.emit(sessionId, { type: "status", status: { kind: "failed", message } });
+    });
+}

package/src/server.ts

@@ -0,0 +1,108 @@
+import Fastify, { type FastifyBaseLogger, type FastifyInstance } from "fastify";
+import cors from "@fastify/cors";
+import websocket from "@fastify/websocket";
+
+import type { RunnerBackend } from "./backend.js";
+import type { RunnerCoreConfig } from "./config.js";
+import type { RunnerCapabilities, SessionConfig } from "./contract.js";
+import { capabilitiesRoute } from "./routes/capabilities.js";
+import { healthRoute } from "./routes/health.js";
+import { ioRoute } from "./routes/io.js";
+import { probeRoute } from "./routes/probe.js";
+import { sessionsRoute } from "./routes/sessions.js";
+import { SessionRegistry } from "./session/registry.js";
+
+export interface ServerDeps {
+  backend: RunnerBackend;
+  config: RunnerCoreConfig;
+  /** The concrete runner's package version, surfaced on /v1/health. */
+  version: string;
+  /** The runner's self-description + editable config schema, served on
+   *  /v1/capabilities so the editor renders a generic runner config form. A
+   *  getter is re-resolved per request — use it when the config surface changes
+   *  at runtime (e.g. a base-image catalog refreshed from a registry). */
+  capabilities: RunnerCapabilities | (() => RunnerCapabilities);
+  /** Runner's default registry URL, passed to workloads as TELO_REGISTRY_URL. */
+  defaultRegistryUrl?: string;
+  /** Backend config gate, enforced on `POST /v1/sessions` before the workload
+   *  starts (e.g. an `image` allowlist). Rejects with `400 invalid_config`. */
+  validateConfig?: (config: SessionConfig) => string | undefined;
+  registry?: SessionRegistry;
+}
+
+export interface ServerHandle {
+  app: FastifyInstance;
+  registry: SessionRegistry;
+}
+
+export async function buildServer(deps: ServerDeps): Promise<ServerHandle> {
+  const app = Fastify({
+    logger: { level: deps.config.logLevel },
+  });
+
+  // CORS: SSE and fetch from the editor's browser origin are cross-origin by
+  // default. A runner with no auth is driven by whoever can reach the port, so
+  // default to `*` and let operators narrow via RUNNER_CORS_ORIGINS.
+  await app.register(cors, {
+    origin: deps.config.corsOrigins,
+    methods: ["GET", "POST", "DELETE", "OPTIONS"],
+  });
+
+  await app.register(websocket);
+
+  const registry =
+    deps.registry ??
+    new SessionRegistry({
+      maxSessions: deps.config.maxSessions,
+      exitTtlMs: deps.config.exitTtlMs,
+      replayBufferBytes: deps.config.replayBufferBytes,
+    });
+
+  // Terms are stable across the process — resolve the capabilities once for them
+  // even when `capabilities` is a getter (the route still re-resolves per request).
+  const capabilitiesValue =
+    typeof deps.capabilities === "function" ? deps.capabilities() : deps.capabilities;
+
+  await app.register(healthRoute(deps.version));
+  await app.register(capabilitiesRoute(deps.capabilities));
+  await app.register(probeRoute({ backend: deps.backend }));
+  await app.register(
+    sessionsRoute({
+      backend: deps.backend,
+      registry,
+      corsOrigins: deps.config.corsOrigins,
+      defaultRegistryUrl: deps.defaultRegistryUrl,
+      validateConfig: deps.validateConfig,
+      // The capabilities document is the single source of the runner's terms;
+      // the session route enforces what /v1/capabilities advertises.
+      terms: capabilitiesValue.terms,
+    }),
+  );
+  await app.register(ioRoute({ registry, corsOrigins: deps.config.corsOrigins }));
+
+  return { app, registry };
+}
+
+/**
+ * Stop every live session. Used by graceful shutdown — marks each entry
+ * userStopped and stops its backend workload so nothing leaks past process
+ * exit. Backend-neutral: it only touches the abstract `BackendSession`.
+ */
+export async function stopAllSessions(
+  registry: SessionRegistry,
+  log: Pick<FastifyBaseLogger, "info" | "warn">,
+): Promise<void> {
+  const live = registry.list().filter((e) => e.session !== null && e.exitedAt === null);
+  if (live.length === 0) return;
+  log.info({ count: live.length }, "stopping live sessions before shutdown");
+  await Promise.all(
+    live.map(async (entry) => {
+      entry.userStopped = true;
+      try {
+        await entry.session?.stop();
+      } catch (err) {
+        log.warn({ err, sessionId: entry.sessionId }, "failed to stop session during shutdown");
+      }
+    }),
+  );
+}