opencode-plugboard 0.4.1 → 0.6.0

package/src/metrics.ts

@@ -0,0 +1,176 @@
+/**
+ * Process metrics in the Prometheus text exposition format (version 0.0.4), hand-rolled: no
+ * dependency, no I/O. One registry lives in the process runtime (`src/runtime.ts`), so counts
+ * survive a plugin generation being replaced. `GET /metrics` renders it (opt-in, `metrics: true`).
+ *
+ * Labels are bounded by construction and carry ids only: `app` is a configured key name (or
+ * `_none` before authentication succeeded), `route` is one of the known routes or `unknown`,
+ * `status` a response code, `outcome` one of a fixed set, `param` a sampling parameter name from
+ * `src/openai/sampling.ts`. Never a model string, key, path or client-supplied text.
+ */
+
+import type { PlugUsage } from "./contract.js"
+
+/** `app` label of a request that was not authenticated (app names cannot contain an underscore). */
+export const NO_APP = "_none"
+
+/** What a request ended as, for the `outcome` label. */
+export type Outcome = "ok" | "rejected" | "failed" | "timeout" | "disconnected"
+
+/** Collapses the request log's outcome string and the response status into the bounded `outcome` label. */
+export function outcomeLabel(logOutcome: string, status: number): Outcome {
+  if (logOutcome === "timeout" || logOutcome === "disconnected") return logOutcome
+  if (logOutcome === "error") return "failed"
+  if (status >= 500) return "failed"
+  if (status >= 400) return "rejected"
+  return "ok"
+}
+
+/** Process-level values the registry does not own; read from the runtime at scrape time. */
+export interface RuntimeSnapshot {
+  /** Accepted plugin generations currently serving. */
+  readonly generations: number
+  /** Whether the event pump is subscribed. */
+  readonly pumpRunning: boolean
+  /** Request guards outstanding (sessions the runtime still owns, including ones past their response). */
+  readonly guards: number
+  /** Runtime start, epoch ms. */
+  readonly startedAt: number
+}
+
+/** Request duration buckets, seconds: model calls run from under a second to many minutes. */
+const BUCKETS = [0.1, 0.5, 1, 2.5, 5, 10, 30, 60, 120, 300, 600]
+
+const escapeLabel = (value: string): string => value.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/"/g, '\\"')
+const escapeHelp = (value: string): string => value.replace(/\\/g, "\\\\").replace(/\n/g, "\\n")
+const labelText = (names: ReadonlyArray<string>, values: ReadonlyArray<string>): string =>
+  names.length === 0 ? "" : `{${names.map((name, index) => `${name}="${escapeLabel(values[index] ?? "")}"`).join(",")}}`
+
+class Counter {
+  private readonly series = new Map<string, { values: string[]; total: number }>()
+  constructor(
+    readonly name: string,
+    readonly help: string,
+    private readonly labels: ReadonlyArray<string>,
+  ) {}
+  add(values: ReadonlyArray<string>, amount = 1): void {
+    if (!(amount > 0) || !Number.isFinite(amount)) return
+    const key = values.join("\u0000")
+    const entry = this.series.get(key)
+    if (entry) entry.total += amount
+    else this.series.set(key, { values: [...values], total: amount })
+  }
+  render(): string[] {
+    const lines = [`# HELP ${this.name} ${escapeHelp(this.help)}`, `# TYPE ${this.name} counter`]
+    for (const { values, total } of this.series.values()) lines.push(`${this.name}${labelText(this.labels, values)} ${total}`)
+    return lines
+  }
+}
+
+class Histogram {
+  private readonly series = new Map<string, { values: string[]; counts: number[]; sum: number; count: number }>()
+  constructor(
+    readonly name: string,
+    readonly help: string,
+    private readonly labels: ReadonlyArray<string>,
+  ) {}
+  observe(values: ReadonlyArray<string>, seconds: number): void {
+    if (!(seconds >= 0) || !Number.isFinite(seconds)) return
+    const key = values.join("\u0000")
+    let entry = this.series.get(key)
+    if (!entry) this.series.set(key, (entry = { values: [...values], counts: BUCKETS.map(() => 0), sum: 0, count: 0 }))
+    BUCKETS.forEach((bound, index) => {
+      if (seconds <= bound) entry.counts[index]! += 1
+    })
+    entry.sum += seconds
+    entry.count += 1
+  }
+  render(): string[] {
+    const lines = [`# HELP ${this.name} ${escapeHelp(this.help)}`, `# TYPE ${this.name} histogram`]
+    for (const { values, counts, sum, count } of this.series.values()) {
+      const names = [...this.labels, "le"]
+      BUCKETS.forEach((bound, index) => lines.push(`${this.name}_bucket${labelText(names, [...values, String(bound)])} ${counts[index]}`))
+      lines.push(`${this.name}_bucket${labelText(names, [...values, "+Inf"])} ${count}`)
+      lines.push(`${this.name}_sum${labelText(this.labels, values)} ${sum}`)
+      lines.push(`${this.name}_count${labelText(this.labels, values)} ${count}`)
+    }
+    return lines
+  }
+}
+
+const gauge = (name: string, help: string, value: number): string[] => [
+  `# HELP ${name} ${escapeHelp(help)}`,
+  `# TYPE ${name} gauge`,
+  `${name} ${value}`,
+]
+
+export interface Metrics {
+  /** A request entered the handler. Pair with `requestFinished`. */
+  requestStarted(): void
+  requestFinished(input: { readonly app: string; readonly route: string; readonly status: number; readonly outcome: Outcome; readonly ms: number }): void
+  /** Token usage of one model call, as a non-overlapping breakdown (see `plugboard_tokens_total`). */
+  tokens(app: string, usage: PlugUsage): void
+  /** Sampling parameters dropped for one request. */
+  dropped(params: ReadonlyArray<string>): void
+  /** One history sweep ended. */
+  sweep(result: "ok" | "failed" | "timeout", removed: number): void
+  /** The exposition text. Called from a request that is itself in flight, which is not counted. */
+  render(snapshot: RuntimeSnapshot): string
+}
+
+export function createMetrics(): Metrics {
+  let inFlight = 0
+  const requests = new Counter("plugboard_requests_total", "Requests handled, by app, route, response status and outcome.", ["app", "route", "status", "outcome"])
+  const duration = new Histogram("plugboard_request_duration_seconds", "Time from request start to the end of the response, by app and route.", ["app", "route"])
+  const tokens = new Counter(
+    "plugboard_tokens_total",
+    "Tokens of completed model calls, by app and kind. Kinds do not overlap: input is uncached prompt tokens, cache_read and cache_write are cached prompt tokens, output excludes reasoning.",
+    ["app", "kind"],
+  )
+  const dropped = new Counter("plugboard_dropped_params_total", "Sampling parameters dropped because the target model rejects them, by parameter.", ["param"])
+  const sweeps = new Counter("plugboard_history_sweeps_total", "History sweeps that ended, by result.", ["result"])
+  const removed = new Counter("plugboard_history_sessions_removed_total", "Request sessions removed by history sweeps.", [])
+
+  return {
+    requestStarted: () => void inFlight++,
+    requestFinished({ app, route, status, outcome, ms }) {
+      inFlight = Math.max(0, inFlight - 1)
+      requests.add([app, route, String(status), outcome])
+      duration.observe([app, route], ms / 1000)
+    },
+    tokens(app, usage) {
+      const cacheRead = usage.cacheReadTokens ?? 0
+      const cacheWrite = usage.cacheWriteTokens ?? 0
+      const reasoning = usage.reasoningTokens ?? 0
+      tokens.add([app, "input"], Math.max(0, (usage.inputTokens ?? 0) - cacheRead - cacheWrite))
+      tokens.add([app, "cache_read"], cacheRead)
+      tokens.add([app, "cache_write"], cacheWrite)
+      tokens.add([app, "output"], Math.max(0, (usage.outputTokens ?? 0) - reasoning))
+      tokens.add([app, "reasoning"], reasoning)
+    },
+    dropped(params) {
+      for (const param of params) dropped.add([param])
+    },
+    sweep(result, count) {
+      sweeps.add([result])
+      removed.add([], count)
+    },
+    render(snapshot) {
+      const lines = [
+        ...requests.render(),
+        ...duration.render(),
+        // The scrape itself is in flight; do not report it.
+        ...gauge("plugboard_requests_in_flight", "Requests being handled right now, not counting this scrape.", Math.max(0, inFlight - 1)),
+        ...tokens.render(),
+        ...dropped.render(),
+        ...sweeps.render(),
+        ...removed.render(),
+        ...gauge("plugboard_generations", "Accepted plugin generations (one per OpenCode Location) serving requests.", snapshot.generations),
+        ...gauge("plugboard_event_pump_up", "1 while the event pump is subscribed to the OpenCode event bus, else 0 (it starts with the first request).", snapshot.pumpRunning ? 1 : 0),
+        ...gauge("plugboard_session_guards", "Request guards outstanding: request sessions plugboard still owns, including ones whose response has ended.", snapshot.guards),
+        ...gauge("plugboard_start_time_seconds", "Start of the plugboard runtime in this process, Unix time.", Math.floor(snapshot.startedAt / 1000)),
+      ]
+      return lines.join("\n") + "\n"
+    },
+  }
+}

package/src/openai/response.ts

@@ -63,6 +63,34 @@ export const encodeError = (error: PlugError): object => ({
   error: { message: error.message, type: ERROR_TYPES[error.kind], param: error.param ?? null, code: error.code ?? null },
 })
 
+/** Epoch ms -> ISO 8601, or undefined for a value Date cannot represent. */
+const isoDate = (ms: number | undefined): string | undefined => {
+  if (ms === undefined) return undefined
+  const date = new Date(ms)
+  return Number.isNaN(date.getTime()) ? undefined : date.toISOString()
+}
+
+/**
+ * The `plugboard` object of a model entry: what the catalog knows beyond the OpenAI fields. Absent
+ * facts are omitted. `cost` is USD per million tokens (an entry with `aboveContext` applies when
+ * the prompt exceeds that many tokens; the entry without it is the base price); `released` is ISO 8601.
+ */
+const encodePlugboard = (model: ListedModel["model"]) => ({
+  capabilities: model.capabilities ?? {},
+  contextLimit: model.contextLimit,
+  limit: model.limits,
+  modalities: model.modalities,
+  cost: model.cost?.map(({ input, output, cacheRead, cacheWrite, aboveContext }) => ({
+    input,
+    output,
+    cache: { read: cacheRead, write: cacheWrite },
+    ...(aboveContext === undefined ? {} : { aboveContext }),
+  })),
+  status: model.status,
+  family: model.family,
+  released: isoDate(model.released),
+})
+
 /** `GET /v1/models` body. */
 export const encodeModelList = (models: ReadonlyArray<ListedModel>): object => ({
   object: "list",
@@ -71,7 +99,7 @@ export const encodeModelList = (models: ReadonlyArray<ListedModel>): object => (
     object: "model",
     created: 0,
     owned_by: ref.providerID,
-    plugboard: { capabilities: model.capabilities ?? {}, contextLimit: model.contextLimit },
+    plugboard: encodePlugboard(model),
   })),
 })
 

package/src/openai/route.ts

@@ -1,6 +1,8 @@
 /**
  * OpenAI front-end route table: `GET /healthz`, `GET /v1/models`, `GET /v1/models/{id}`,
  * `POST /v1/chat/completions`, and the dispatch of `POST /v1/responses` to `src/responses/route.ts`.
+ * Observability and first-run routes (`src/discovery.ts`, `src/metrics.ts`): `GET /` and `GET /v1`
+ * (keyless discovery), the authenticated `GET /v1/status`, and `GET /metrics` (option `metrics`).
  *
  * The flow is: establish cancellation and the deadline, check origin, authenticate, parse, resolve
  * the model, call the ModelCaller, encode. Parsing, policy and encoding are imported directly;
@@ -10,11 +12,16 @@
  * Response header `x-plugboard-session: <id>` carries the id of the history record the call
  * writes (the `ModelCaller` reports it through `CallContext.onRecord`). It is set before the
  * response headers go out (JSON body or first SSE chunk); an id reported after that is ignored.
+ *
+ * Response header `x-plugboard-request-id: <id>` is set on every response, before anything else
+ * can fail. The same id is the `id` of the request's log line, and of every other log line emitted
+ * while the request is being handled (`withRequestId` in `src/log.ts`).
  */
 
 import type { IncomingMessage, ServerResponse } from "node:http"
-import { authenticate, type PlugboardOptions } from "../config.js"
+import { DEFAULT_APP, authenticate, type PlugboardOptions } from "../config.js"
 import { isPlugError, type CatalogModel, type ModelCaller, type PlugError, type PlugRequest } from "../contract.js"
+import { buildDiscovery, buildStatus, renderDiscoveryHtml, sendText } from "../discovery.js"
 import {
   BodyError,
   RequestAborted,
@@ -28,9 +35,11 @@ import {
   sseWriter,
   type RequestScope,
 } from "../http.js"
-import { errorMessage, log, logError } from "../log.js"
+import { errorMessage, log, logError, withRequestId } from "../log.js"
+import { NO_APP, outcomeLabel, type Metrics } from "../metrics.js"
 import { listAvailableModels, resolveModel } from "../models.js"
 import { serveResponses } from "../responses/route.js"
+import { processMetrics, processStatus, type RuntimeStatus } from "../runtime.js"
 import { parseChatRequest } from "./request.js"
 import { collectCompletion, encodeError, encodeModelList, streamCompletion } from "./response.js"
 import { dropRejected } from "./sampling.js"
@@ -41,12 +50,36 @@ export interface RouteHost {
   readonly caller: ModelCaller
   /** The serving Location's enabled models. */
   loadCatalog(): Promise<ReadonlyArray<CatalogModel>>
+  /** Metrics registry; the process runtime's by default. Only written to when option `metrics` is on. */
+  readonly metrics?: Metrics
+  /** Runtime facts for `/v1/status` and `/metrics`; the process runtime's by default. */
+  readonly status?: () => RuntimeStatus
 }
 
 const SESSION_HEADER = "x-plugboard-session"
+const REQUEST_ID_HEADER = "x-plugboard-request-id"
 const DROPPED_HEADER = "x-plugboard-dropped-params"
 const MODEL_PREFIX = "/v1/models/"
-const KNOWN_ROUTES = ["GET /v1/models", "POST /v1/chat/completions", "POST /v1/responses"]
+const KNOWN_ROUTES = ["GET /v1/models", "POST /v1/chat/completions", "POST /v1/responses", "GET /v1/status"]
+/** Pages anyone may fetch; they decide for themselves how much to show (see `src/discovery.ts`). */
+const DISCOVERY_ROUTES = ["GET /", "GET /v1"]
+/** Allows a page's inline style and nothing else: no scripts, images, fonts or frames. */
+const PAGE_HEADERS = { "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'", "x-frame-options": "DENY", "referrer-policy": "no-referrer" }
+
+/** Records the token usage of every finished model call (see `plugboard_tokens_total`); events pass through untouched. */
+function metered(caller: ModelCaller, metrics: Metrics): ModelCaller {
+  return {
+    stream(request, context) {
+      const inner = caller.stream(request, context)
+      return (async function* () {
+        for await (const event of inner) {
+          if (event.type === "finish" && event.usage) metrics.tokens(context.app, event.usage)
+          yield event
+        }
+      })()
+    },
+  }
+}
 
 const decodeSegment = (raw: string): string => {
   try {
@@ -67,10 +100,28 @@ interface RequestInfo {
   dropped?: string
 }
 
-export function createOpenAiRoute(host: RouteHost) {
+export function createOpenAiRoute(routeHost: RouteHost) {
+  // Metrics are written only when the option is on: off means no bookkeeping, no wrapped event stream.
+  const metrics = routeHost.options.metrics ? (routeHost.metrics ?? processMetrics()) : undefined
+  const runtimeStatus = routeHost.status ?? processStatus
+  const host: RouteHost = metrics ? { ...routeHost, caller: metered(routeHost.caller, metrics) } : routeHost
+  /** Routes with a handler of their own. `GET /metrics` exists only when enabled; otherwise it is an unknown path. */
+  const known = (route: string) => KNOWN_ROUTES.includes(route) || DISCOVERY_ROUTES.includes(route) || (metrics !== undefined && route === "GET /metrics")
+
   const fail = (response: ServerResponse, error: PlugError, close = false) =>
     sendJson(response, error.status, encodeError(error), { close })
 
+  /** The catalog for a page that can do without it: a failure is logged and reported as absent; an abort still ends the request. */
+  async function optionalCatalog(scope: RequestScope): Promise<ReadonlyArray<CatalogModel> | undefined> {
+    try {
+      return await scope.race(host.loadCatalog())
+    } catch (caught) {
+      if (caught instanceof RequestAborted) throw caught
+      logError("catalog.failed", { error: errorMessage(caught) })
+      return undefined
+    }
+  }
+
   /** The route proper. Throws `BodyError`, `RequestAborted` or an unexpected error; `handle` maps them. */
   async function serve(request: IncomingMessage, response: ServerResponse, scope: RequestScope, info: RequestInfo): Promise<void> {
     let url: URL
@@ -83,14 +134,35 @@ export function createOpenAiRoute(host: RouteHost) {
     const modelId = request.method === "GET" && path.startsWith(MODEL_PREFIX) && path.length > MODEL_PREFIX.length ? decodeSegment(path.slice(MODEL_PREFIX.length)) : undefined
     const route = `${request.method} ${modelId !== undefined ? "/v1/models/{id}" : path}`
     // Arbitrary client paths stay out of the log.
-    info.route = modelId !== undefined || KNOWN_ROUTES.includes(route) || route === "GET /healthz" ? route : "unknown"
+    info.route = modelId !== undefined || known(route) || route === "GET /healthz" ? route : "unknown"
 
     const rejected = checkOrigin(request, host.options)
     if (rejected) return fail(response, rejected)
 
     if (route === "GET /healthz") return sendJson(response, 200, { ok: true })
 
-    if (modelId === undefined && !KNOWN_ROUTES.includes(route)) {
+    // First-run pages: reachable without a key, so what they show depends on the caller (`buildDiscovery`).
+    // With `keys` set, a request without credentials gets the minimal page; wrong credentials are a 401.
+    if (DISCOVERY_ROUTES.includes(route)) {
+      const keyed = Object.keys(host.options.keys).length > 0
+      let app: string | undefined = keyed ? undefined : DEFAULT_APP
+      if (keyed && request.headers.authorization !== undefined) {
+        const auth = authenticate(host.options, request.headers.authorization)
+        if (isPlugError(auth)) return fail(response, auth)
+        app = auth.app
+      }
+      info.app = app
+      const doc = buildDiscovery({ options: host.options, app, catalog: app === undefined ? undefined : await optionalCatalog(scope) })
+      if (route === "GET /v1") return sendJson(response, 200, doc)
+      return sendText(response, 200, "text/html; charset=utf-8", renderDiscoveryHtml(doc), PAGE_HEADERS)
+    }
+
+    // Authenticate before anything reveals which routes exist: an unauthenticated caller sees 401 for every path but /healthz and the first-run pages.
+    const auth = authenticate(host.options, request.headers.authorization)
+    if (isPlugError(auth)) return fail(response, auth)
+    info.app = auth.app
+
+    if (modelId === undefined && !known(route)) {
       return fail(response, {
         status: 404,
         kind: "not_found",
@@ -99,9 +171,14 @@ export function createOpenAiRoute(host: RouteHost) {
       })
     }
 
-    const auth = authenticate(host.options, request.headers.authorization)
-    if (isPlugError(auth)) return fail(response, auth)
-    info.app = auth.app
+    if (route === "GET /v1/status") {
+      const catalog = await optionalCatalog(scope)
+      return sendJson(response, 200, buildStatus({ options: host.options, app: auth.app, runtime: runtimeStatus(), catalog }))
+    }
+
+    if (route === "GET /metrics" && metrics) {
+      return sendText(response, 200, "text/plain; version=0.0.4; charset=utf-8", metrics.render(runtimeStatus()))
+    }
 
     if (route === "GET /v1/models" || modelId !== undefined) {
       const listed = listAvailableModels(host.options, await scope.race(host.loadCatalog()))
@@ -136,6 +213,7 @@ export function createOpenAiRoute(host: RouteHost) {
     if (sampled && sampled.dropped.length > 0) {
       info.dropped = sampled.dropped.join(",")
       response.setHeader(DROPPED_HEADER, info.dropped)
+      metrics?.dropped(sampled.dropped)
     }
     const call: PlugRequest = { ...parsed.request, ...(sampled ? { generation: sampled.generation } : {}), ref }
     const { exchange } = parsed
@@ -179,9 +257,16 @@ export function createOpenAiRoute(host: RouteHost) {
 
   /** Never rejects: every failure ends in a response (or a closed socket) and one log line. */
   return async function handle(request: IncomingMessage, response: ServerResponse): Promise<void> {
+    // Generated here, never taken from the client: the id is echoed and logged, so it must not be attacker-controlled text.
+    const id = crypto.randomUUID().replaceAll("-", "").slice(0, 12)
+    if (!response.headersSent) response.setHeader(REQUEST_ID_HEADER, id)
+    return withRequestId(id, () => run(request, response, id))
+  }
+
+  async function run(request: IncomingMessage, response: ServerResponse, id: string): Promise<void> {
     const started = Date.now()
-    const id = crypto.randomUUID().slice(0, 8)
     const info: RequestInfo = { route: "unparsed" }
+    metrics?.requestStarted()
     const scope = beginRequest(request, response, host.options.requestTimeoutMs)
     let outcome = "ok"
     let error: string | undefined
@@ -221,8 +306,11 @@ export function createOpenAiRoute(host: RouteHost) {
       try {
         finishRequest(request, response)
       } catch {}
-      if (info.route !== "GET /healthz" || outcome !== "ok") {
-        const fields = { id, route: info.route, app: info.app, model: info.model, dropped: info.dropped, status: response.statusCode, ms: Date.now() - started, outcome, error }
+      const ms = Date.now() - started
+      metrics?.requestFinished({ app: info.app ?? NO_APP, route: info.route, status: response.statusCode, outcome: outcomeLabel(outcome, response.statusCode), ms })
+      // Probes and scrapes that succeed are not worth a line each.
+      if ((info.route !== "GET /healthz" && info.route !== "GET /metrics") || outcome !== "ok") {
+        const fields = { id, route: info.route, app: info.app, model: info.model, dropped: info.dropped, status: response.statusCode, ms, outcome, error }
         if (outcome === "error" || response.statusCode >= 500) logError("request.failed", fields)
         else log("request", fields)
       }

package/src/runtime.ts

@@ -19,9 +19,12 @@
  *     requests in flight fail with a 502 instead of waiting for their deadline;
  *   - the session store (src/session/state.ts), which outlives the listener and owns the request
  *     guards, their cleanup timers included;
- *   - the history sweep state: every registered request session is indexed in the host's plugin
+ *  - the history sweep state: every registered request session is indexed in the host's plugin
  *     storage and, at most every `SWEEP_INTERVAL_MS`, a sweep prunes old ones past the `history`
- *     limits (src/session/prune.ts). Both start from request handling (the store's `register`).
+ *     limits (src/session/prune.ts). Both start from request handling (the store's `register`);
+ *  - the metrics registry (src/metrics.ts) and the runtime start time, so counters and uptime
+ *     outlive any one generation. `processMetrics` / `processStatus` read them for `/metrics`,
+ *     `/v1/status` and the discovery pages.
  *
  * Registration is explicit: `registerGeneration` returns whether the generation was accepted. A
  * rejected one (different `listen`, options that differ from the live ones, foreign runtime) never
@@ -43,7 +46,8 @@
 import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http"
 import { Cause, Effect, Stream } from "effect"
 import { isPlugError, type CatalogModel, type PlugError } from "./contract.js"
-import { errorMessage, log, logError } from "./log.js"
+import { errorMessage, log, logError, outsideRequest, setLogFormat } from "./log.js"
+import { createMetrics, type Metrics, type RuntimeSnapshot } from "./metrics.js"
 import { ensureAppDir } from "./session/history.js"
 import type { HistoryPort } from "./session/host.js"
 import { recordSession, sweepHistory, type HistoryLimits } from "./session/prune.js"
@@ -96,8 +100,12 @@ const SWEEP_DEADLINE_MS = 60_000
 const BACKEND_TIMEOUT_MS = 15_000
 const BACKEND_POLL_MS = 25
 
-/** 4: adds the history sweep state and the session store's register hook. 3: confirmed directories and rejected generations. */
-const VERSION = 4
+/** How often a listener that could not bind tries again, and how often it repeats the error while it still cannot (#87). */
+const BIND_RETRY_MS = 15_000
+const BIND_REMINDER_MS = 5 * 60_000
+
+/** 6: the listener retries a failed bind (new fields on `Listener`). 5: adds the metrics registry and the start time. 4: the history sweep state and the session store's register hook. 3: confirmed directories and rejected generations. */
+const VERSION = 6
 const KEY = Symbol.for("opencode-plugboard.runtime")
 
 interface Listener {
@@ -107,6 +115,11 @@ interface Listener {
   fingerprint: string
   mismatchLogged: boolean
   bound: boolean
+  /** Failed bind attempts since the last success: while this is above 0 nothing receives requests on the port. */
+  bindFailures: number
+  /** When the bind failure was last logged (epoch ms). */
+  bindLoggedAt: number
+  retryTimer?: ReturnType<typeof setTimeout>
   graceTimer?: ReturnType<typeof setTimeout>
 }
 
@@ -140,6 +153,10 @@ interface Runtime {
   readonly rejected: Map<string, number>
   /** History sweep rate limit: no sweep starts before `nextAt` (epoch ms) or while one `running`. */
   readonly sweep: { nextAt: number; running: boolean }
+  /** Process-wide counters, shared by every generation (see src/metrics.ts). */
+  readonly metrics: Metrics
+  /** When this runtime was created, epoch ms. */
+  readonly startedAt: number
   listener?: Listener
   /** Present while a fiber is subscribed to the server event bus. */
   pump?: Pump
@@ -149,6 +166,8 @@ const REJECTED: Registration = { accepted: false, dispose() {}, confirmed: () =>
 
 /** Used when a foreign-version runtime owns the process: never registered into, never dispatched to. */
 const detachedSessions = createSessionStore()
+const detachedMetrics = createMetrics()
+const detachedStartedAt = Date.now()
 let foreignVersionLogged = false
 
 /** The process runtime, created on first use; undefined when a different version already owns the process. */
@@ -163,6 +182,8 @@ function runtime(): Runtime | undefined {
       confirmed: new Set(),
       rejected: new Map(),
       sweep: { nextAt: 0, running: false },
+      metrics: createMetrics(),
+      startedAt: Date.now(),
     }
     slot[KEY] = created
     return created
@@ -185,9 +206,12 @@ function trackSession(rt: Runtime, app: string, sessionID: string): void {
   if (!history) return logError("history.index_skipped", { app, sessionID, reason: "no live generation" })
   // No limits, no index: an unbounded index would grow opencode.db by a row per request forever (#85).
   if (history.limits.maxSessions === undefined && history.limits.maxAgeDays === undefined) return
-  void recordSession(history.port, app, sessionID, Date.now())
-    .catch((error) => logError("history.index_failed", { app, sessionID, error: errorMessage(error) }))
-    .then(() => maybeSweep(rt, history))
+  // Not about the request that happened to create the session: its log lines carry no request id.
+  void outsideRequest(() =>
+    recordSession(history.port, app, sessionID, Date.now())
+      .catch((error) => logError("history.index_failed", { app, sessionID, error: errorMessage(error) }))
+      .then(() => maybeSweep(rt, history)),
+  )
 }
 
 /**
@@ -212,10 +236,15 @@ async function maybeSweep(rt: Runtime, history: GenerationInput["history"]): Pro
         timer.unref?.()
       }),
     ])
-    if (!result) return logError("history.sweep_timeout", { limit: SWEEP_DEADLINE_MS })
+    if (!result) {
+      rt.metrics.sweep("timeout", 0)
+      return logError("history.sweep_timeout", { limit: SWEEP_DEADLINE_MS })
+    }
     if (result.more) rt.sweep.nextAt = Date.now() + SWEEP_BACKLOG_MS
+    rt.metrics.sweep("ok", result.removed)
     log("history.swept", { ...result, durationMs: Date.now() - now })
   } catch (error) {
+    rt.metrics.sweep("failed", 0)
     logError("history.sweep_failed", { error: errorMessage(error) })
   } finally {
     clearTimeout(timer)
@@ -226,6 +255,34 @@ async function maybeSweep(rt: Runtime, history: GenerationInput["history"]): Pro
 /** The session store shared by every generation in the process. */
 export const sessionStore = (): SessionStore => runtime()?.sessions ?? detachedSessions
 
+/** The metrics registry shared by every generation in the process (a detached one under a foreign-version runtime). */
+export const processMetrics = (): Metrics => runtime()?.metrics ?? detachedMetrics
+
+/** What `/v1/status` and the discovery pages report about the process, besides the model catalog. */
+export interface RuntimeStatus extends RuntimeSnapshot {
+  readonly runtimeVersion: number
+  /** The shared listener's address, and whether it is bound; absent before the first generation registered. */
+  readonly listener?: { readonly host: string; readonly port: number; readonly bound: boolean }
+  /** The serving generation's Location is a confirmed app directory (else the newest generation serves). */
+  readonly servingConfirmed: boolean
+}
+
+/** A synchronous snapshot of the runtime: no host call, no filesystem. */
+export function processStatus(): RuntimeStatus {
+  const rt = runtime()
+  if (!rt) return { runtimeVersion: VERSION, generations: 0, pumpRunning: false, guards: detachedSessions.size(), startedAt: detachedStartedAt, servingConfirmed: false }
+  const serving = preferred(rt)
+  return {
+    runtimeVersion: rt.version,
+    generations: rt.generations.length,
+    pumpRunning: rt.pump !== undefined,
+    guards: rt.sessions.size(),
+    startedAt: rt.startedAt,
+    servingConfirmed: serving !== undefined && rt.confirmed.has(serving.directory),
+    ...(rt.listener ? { listener: { host: rt.listener.listen.host, port: rt.listener.listen.port, bound: rt.listener.bound } } : {}),
+  }
+}
+
 /** The generation that serves requests and supplies the catalog: the newest confirmed app-directory one, else the newest. */
 function preferred(rt: Runtime): Generation | undefined {
   for (let index = rt.generations.length - 1; index >= 0; index--) if (rt.confirmed.has(rt.generations[index]!.directory)) return rt.generations[index]
@@ -264,7 +321,7 @@ const unavailable = (response: ServerResponse, message: string) => {
 }
 
 function startListener(rt: Runtime, listen: { host: string; port: number }, fingerprint: string): Listener {
-  const listener: Listener = { server: createServer(), listen, fingerprint, mismatchLogged: false, bound: false }
+  const listener: Listener = { server: createServer(), listen, fingerprint, mismatchLogged: false, bound: false, bindFailures: 0, bindLoggedAt: 0 }
   listener.server.on("request", (request, response) => {
     const current = preferred(rt)
     if (!current) return unavailable(response, "plugboard is reloading")
@@ -277,22 +334,39 @@ function startListener(rt: Runtime, listen: { host: string; port: number }, fing
   })
   listener.server.on("error", (error: NodeJS.ErrnoException) => {
     if (listener.bound) return logError("listener.error", { code: error.code, error: error.message })
-    // Never bound: another process (or an older runtime) owns the port. Log once, stay inert.
-    logError(error.code === "EADDRINUSE" ? "listener.address_in_use" : "listener.failed", {
-      listen: `${listen.host}:${listen.port}`,
-      error: error.message,
-    })
+    // Not bound: another process (or an older runtime) owns the port, so nothing here receives
+    // requests while clients may be sending their keys and prompts to whoever holds it. Say so
+    // loudly (error level, again every few minutes), keep trying, and mention it on every
+    // generation that registers meanwhile (`registerGeneration`).
+    listener.bindFailures++
+    if (Date.now() - listener.bindLoggedAt >= BIND_REMINDER_MS) {
+      listener.bindLoggedAt = Date.now()
+      logError(error.code === "EADDRINUSE" ? "listener.address_in_use" : "listener.failed", {
+        listen: `${listen.host}:${listen.port}`,
+        error: error.message,
+        status: "not serving: clients of this port reach another process",
+        action: "stop the process that holds the port or change `listen`; plugboard retries every 15s",
+      })
+    }
+    listener.retryTimer = setTimeout(() => {
+      listener.retryTimer = undefined
+      if (rt.listener === listener && !listener.bound) listener.server.listen(listen.port, listen.host)
+    }, BIND_RETRY_MS)
+    listener.retryTimer.unref?.()
   })
-  listener.server.listen(listen.port, listen.host, () => {
+  listener.server.on("listening", () => {
     listener.bound = true
-    log("listener.listening", { listen: `${listen.host}:${listen.port}` })
+    log("listener.listening", { listen: `${listen.host}:${listen.port}`, ...(listener.bindFailures > 0 ? { recoveredAfterFailedBinds: listener.bindFailures } : {}) })
+    listener.bindFailures = 0
   })
+  listener.server.listen(listen.port, listen.host)
   return listener
 }
 
 function closeListener(rt: Runtime, listener: Listener): void {
   if (rt.listener !== listener) return
   rt.listener = undefined
+  clearTimeout(listener.retryTimer)
   try {
     rt.pump?.stop()
   } catch {}
@@ -356,6 +430,13 @@ export function registerGeneration(input: GenerationInput): Registration {
   }
   if (listener.graceTimer) clearTimeout(listener.graceTimer)
   listener.graceTimer = undefined
+  if (listener.bindFailures > 0) {
+    logError("listener.not_serving", {
+      listen: `${listen.host}:${listen.port}`,
+      status: "another process holds the port; this generation serves nothing",
+      action: "stop that process or change `listen`",
+    })
+  }
   const generation: Generation = {
     directory,
     handler: input.handler,
@@ -367,6 +448,9 @@ export function registerGeneration(input: GenerationInput): Registration {
     activated: rt.confirmed.has(directory),
   }
   rt.generations.push(generation)
+  // Accepted generations share the live options, so this is the live `logFormat` (log lines are process-wide).
+  const options = input.options as { readonly logFormat?: unknown } | null
+  setLogFormat(options?.logFormat === "json" ? "json" : "text")
   return {
     accepted: true,
     confirmed: () => rt.confirmed.has(directory),
@@ -399,7 +483,8 @@ export function registerGeneration(input: GenerationInput): Registration {
 export function ensurePump(subscribe: () => Stream.Stream<unknown, unknown, never>): void {
   const rt = runtime()
   if (!rt || rt.pump) return
-  const fiber = Effect.runFork(subscribe().pipe(Stream.runForEach((event) => Effect.sync(() => rt.sessions.dispatch(event)))))
+  // The pump serves every request; its log lines must not carry the id of the request that started it.
+  const fiber = outsideRequest(() => Effect.runFork(subscribe().pipe(Stream.runForEach((event) => Effect.sync(() => rt.sessions.dispatch(event))))))
   const pump: Pump = {
     stopped: false,
     stop: () => {