opencode-plugboard 0.0.0-stage → 0.2.1

package/src/openai/route.ts

@@ -0,0 +1,214 @@
+/**
+ * OpenAI front-end route table: `GET /healthz`, `GET /v1/models`, `GET /v1/models/{id}`,
+ * `POST /v1/chat/completions`.
+ *
+ * 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;
+ * only effects (the model caller, the catalog and the serving generation's options) arrive
+ * through `RouteHost`.
+ *
+ * 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.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http"
+import { authenticate, type PlugboardOptions } from "../config.js"
+import { isPlugError, type CatalogModel, type ModelCaller, type PlugError, type PlugRequest } from "../contract.js"
+import {
+  BodyError,
+  RequestAborted,
+  beginRequest,
+  boundEvents,
+  checkJsonContentType,
+  checkOrigin,
+  finishRequest,
+  readJsonBody,
+  sendJson,
+  sseWriter,
+  type RequestScope,
+} from "../http.js"
+import { errorMessage, log, logError } from "../log.js"
+import { listAvailableModels, resolveModel } from "../models.js"
+import { parseChatRequest } from "./request.js"
+import { collectCompletion, encodeError, encodeModelList, streamCompletion } from "./response.js"
+
+/** What the serving generation supplies per request. */
+export interface RouteHost {
+  readonly options: PlugboardOptions
+  readonly caller: ModelCaller
+  /** The serving Location's enabled models. */
+  loadCatalog(): Promise<ReadonlyArray<CatalogModel>>
+}
+
+const SESSION_HEADER = "x-plugboard-session"
+const MODEL_PREFIX = "/v1/models/"
+const KNOWN_ROUTES = ["GET /v1/models", "POST /v1/chat/completions"]
+
+const decodeSegment = (raw: string): string => {
+  try {
+    return decodeURIComponent(raw)
+  } catch {
+    return raw
+  }
+}
+
+/** What a request log line may carry: ids and outcomes only. */
+interface RequestInfo {
+  route: string
+  app?: string
+  model?: string
+  /** Set when a response committed as 200 and then failed (a stream error frame): the log outcome and the error code. */
+  failed?: string
+}
+
+export function createOpenAiRoute(host: RouteHost) {
+  const fail = (response: ServerResponse, error: PlugError, close = false) =>
+    sendJson(response, error.status, encodeError(error), { close })
+
+  /** 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
+    try {
+      url = new URL(request.url ?? "/", "http://127.0.0.1")
+    } catch {
+      return fail(response, { status: 400, kind: "invalid_request", code: "invalid_request_target", message: "Malformed request target" })
+    }
+    const path = url.pathname
+    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"
+
+    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)) {
+      return fail(response, {
+        status: 404,
+        kind: "not_found",
+        code: "not_found",
+        message: `No route for ${request.method} ${path}`,
+      })
+    }
+
+    const auth = authenticate(host.options, request.headers.authorization)
+    if (isPlugError(auth)) return fail(response, auth)
+    info.app = auth.app
+
+    if (route === "GET /v1/models" || modelId !== undefined) {
+      const listed = listAvailableModels(host.options, await scope.race(host.loadCatalog()))
+      if (modelId === undefined) return sendJson(response, 200, encodeModelList(listed))
+      const item = listed.find((m) => m.id === modelId)
+      if (!item) {
+        return fail(response, {
+          status: 404,
+          kind: "not_found",
+          code: "model_not_found",
+          param: "model",
+          message: `Model ${modelId} is not available`,
+        })
+      }
+      info.model = item.id
+      return sendJson(response, 200, (encodeModelList([item]) as { data: object[] }).data[0])
+    }
+
+    const unsupported = checkJsonContentType(request)
+    if (unsupported) return fail(response, unsupported)
+
+    const body = await readJsonBody(request, scope.signal)
+    const parsed = parseChatRequest(body, host.options)
+    if (isPlugError(parsed)) return fail(response, parsed)
+    const catalog = await scope.race(host.loadCatalog())
+    const ref = resolveModel(host.options, parsed.request.model, catalog, parsed.reasoningEffort)
+    if (isPlugError(ref)) return fail(response, ref)
+    info.model = `${ref.providerID}/${ref.id}${ref.variant ? `#${ref.variant}` : ""}`
+    const call: PlugRequest = { ...parsed.request, ref }
+    const { exchange } = parsed
+
+    // Abandoned requests (client gone, deadline passed) must never reach the model caller.
+    if (scope.signal.aborted) throw scope.signal.reason
+    const events = boundEvents(
+      host.caller.stream(call, {
+        app: auth.app,
+        signal: scope.signal,
+        onRecord: (recordID) => {
+          if (response.headersSent || response.destroyed || !/^[\x21-\x7e]+$/.test(recordID)) return
+          response.setHeader(SESSION_HEADER, recordID)
+        },
+      }),
+      scope,
+    )
+
+    if (exchange.stream) {
+      // Nothing is committed until the encoder writes its first frame, so a failure before any
+      // wire-visible output (including suppressed reasoning or structured prose) is a real HTTP error.
+      const sse = sseWriter(response, scope.signal)
+      const { failure } = await streamCompletion(sse.paced(events), exchange, sse.write)
+      if (!sse.started && !response.headersSent) {
+        if (!scope.signal.aborted || scope.timedOut) fail(response, failure ?? { status: 502, kind: "server", message: "No response from the model" })
+      } else {
+        if (failure) info.failed = failure.code ?? failure.kind
+        if (!response.writableEnded) response.end()
+      }
+      return
+    }
+
+    const result = await collectCompletion(events, exchange)
+    sendJson(response, result.status, result.body)
+  }
+
+  /** 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> {
+    const started = Date.now()
+    const id = crypto.randomUUID().slice(0, 8)
+    const info: RequestInfo = { route: "unparsed" }
+    const scope = beginRequest(request, response, host.options.requestTimeoutMs)
+    let outcome = "ok"
+    let error: string | undefined
+    try {
+      try {
+        await serve(request, response, scope, info)
+      } catch (caught) {
+        if (caught instanceof RequestAborted) {
+          outcome = caught.kind
+          if (caught.kind === "timeout") {
+            if (response.headersSent) response.end()
+            else fail(response, scope.timeoutError, true)
+          }
+        } else if (caught instanceof BodyError) {
+          outcome = `body_${caught.status}`
+          // 413: the client may still be sending; answer, then close (see `finishRequest`).
+          fail(response, { status: caught.status, kind: "invalid_request", message: caught.message }, caught.status === 413)
+        } else {
+          // Unexpected: the message goes to the log only; the client gets a generic one.
+          outcome = "error"
+          error = errorMessage(caught)
+          if (response.headersSent) {
+            if (!response.writableEnded) response.end()
+          } else fail(response, { status: 500, kind: "server", message: "Internal server error" })
+        }
+      }
+      if (outcome === "ok" && scope.signal.aborted) outcome = scope.timedOut ? "timeout" : "disconnected"
+      else if (outcome === "ok" && info.failed !== undefined) {
+        outcome = "error"
+        error = info.failed
+      } else if (outcome === "ok" && response.statusCode >= 400) outcome = `status_${response.statusCode}`
+    } catch (caught) {
+      outcome = "error"
+      error = errorMessage(caught)
+    } finally {
+      scope.dispose()
+      try {
+        finishRequest(request, response)
+      } catch {}
+      if (info.route !== "GET /healthz" || outcome !== "ok") {
+        const fields = { id, route: info.route, app: info.app, model: info.model, status: response.statusCode, ms: Date.now() - started, outcome, error }
+        if (outcome === "error" || response.statusCode >= 500) logError("request.failed", fields)
+        else log("request", fields)
+      }
+    }
+  }
+}

package/src/runtime.ts

@@ -0,0 +1,463 @@
+/**
+ * Process runtime: the one owner of everything that outlives a plugin generation.
+ *
+ * OpenCode loads the plugin once per Location, so many generations exist at once, and the module
+ * itself may be re-evaluated per Location or on reload. The runtime therefore lives on
+ * `globalThis` under a versioned key and holds:
+ *   - the generation list: the ACCEPTED generations (request handler, catalog loader), newest
+ *     last. A generation whose Location is a confirmed plugboard app directory is the preferred
+ *     owner: it serves requests and supplies the catalog; without one the newest generation does;
+ *   - the confirmed directories: app directories (real paths strictly inside the canonical data
+ *     root) that `ensureBackend` has verified asynchronously. Nothing in setup touches the
+ *     filesystem, so a Location is unconfirmed, and plugboard's hook and transforms stay no-ops
+ *     there, until a request has confirmed its directory (fail closed);
+ *   - the HTTP listener lifetime: the first generation binds the port, later ones join; when the
+ *     last generation is gone the listener waits a grace period (a config reload recreates every
+ *     generation at once) before closing; requests arriving with no live generation get 503;
+ *   - the event pump lifetime: one fiber on the host's default runtime, owned by no generation
+ *     scope, forwarding bus events of request sessions to the session store. If it dies, the
+ *     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.
+ *
+ * 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
+ * serves and must not install hooks or seeds. `ensureBackend` is the per-directory readiness gate
+ * the session caller awaits before creating a session: it confirms the app directory, boots its
+ * Location from request handling when no generation is there yet, and fails with
+ * `backend_unavailable` (503) when the generation there is rejected or never becomes ready.
+ *
+ * Version policy: a runtime written by a different version is never touched or replaced; this
+ * module then behaves as inert (no listener, no pump, an empty detached session store) and logs
+ * once that the server needs a restart.
+ *
+ * Freeze safety: everything a generation calls from plugin setup or a finalizer here is
+ * synchronous and makes no call on the plugin context or the filesystem. `Registration.dispose`
+ * only mutates state and arms an unref'd timer; the pump is started lazily by request handling,
+ * never awaited. `ensureBackend` and `Registration.refresh` run from request handling only.
+ */
+
+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 { ensureAppDir } from "./session/history.js"
+import { createSessionStore, type SessionStore } from "./session/state.js"
+
+export type Handler = (request: IncomingMessage, response: ServerResponse) => void
+
+export interface Registration {
+  /** False when the generation was rejected: it serves nothing and must not install hooks or seeds. */
+  readonly accepted: boolean
+  /** Synchronous; safe in a finalizer. */
+  dispose(): void
+  /**
+   * Whether `ensureBackend` has confirmed this generation's Location as a plugboard app directory.
+   * Synchronous, no filesystem; false until then. Everything plugboard installs for app
+   * directories (context hook, agent deny, seed tools) must be a no-op while this is false.
+   */
+  confirmed(): boolean
+  /** Setup has finished installing the app-directory registrations (the context hook is in place). */
+  ready(): void
+}
+
+export interface GenerationInput {
+  readonly listen: { readonly host: string; readonly port: number }
+  /** The parsed options. Generations must agree on them; compared by canonical JSON (key order is irrelevant). */
+  readonly options: unknown
+  /** This generation's Location directory as the host reports it. Compared as a string with the real path `ensureAppDir` returns; never resolved against the filesystem here. */
+  readonly directory: string
+  readonly handler: Handler
+  /** The enabled models as this generation's Location sees them. */
+  readonly loadCatalog: () => Promise<ReadonlyArray<CatalogModel>>
+  /**
+   * Rebuild what depends on `Registration.confirmed()` (the agent and tool transforms) after it
+   * flipped to true for a generation that was set up before. Called from request handling only,
+   * never from setup or a finalizer.
+   */
+  readonly refresh: () => Promise<void>
+}
+
+const GRACE_MS = 10_000
+/** How long `ensureBackend` waits for a Location to boot and its generation to become ready. */
+const BACKEND_TIMEOUT_MS = 15_000
+const BACKEND_POLL_MS = 25
+
+/** 3: the runtime tracks confirmed directories and rejected generations (a version-2 runtime lacks both). */
+const VERSION = 3
+const KEY = Symbol.for("opencode-plugboard.runtime")
+
+interface Listener {
+  readonly server: Server
+  readonly listen: { readonly host: string; readonly port: number }
+  /** Canonical JSON of the parsed options of the generations the listener serves; later generations must match it. */
+  fingerprint: string
+  mismatchLogged: boolean
+  bound: boolean
+  graceTimer?: ReturnType<typeof setTimeout>
+}
+
+interface Generation {
+  readonly directory: string
+  readonly handler: Handler
+  readonly loadCatalog: GenerationInput["loadCatalog"]
+  readonly refresh: GenerationInput["refresh"]
+  /** The context hook and transforms are installed (setup got to its end). */
+  hooked: boolean
+  /** The transforms have been rebuilt since `confirmed` became true for the directory. */
+  activated: boolean
+  activating?: Promise<void>
+}
+
+interface Pump {
+  /** Set by `stop`: the end of the fiber is then expected. */
+  stopped: boolean
+  stop(): void
+}
+
+interface Runtime {
+  readonly version: number
+  readonly sessions: SessionStore
+  /** Accepted generations only, newest last. */
+  readonly generations: Generation[]
+  /** App directories (real paths, strictly inside the canonical data root) confirmed by `ensureBackend`. */
+  readonly confirmed: Set<string>
+  /** Live rejected generations per directory: tells "rejected" from "no generation yet". */
+  readonly rejected: Map<string, number>
+  listener?: Listener
+  /** Present while a fiber is subscribed to the server event bus. */
+  pump?: Pump
+}
+
+const REJECTED: Registration = { accepted: false, dispose() {}, confirmed: () => false, ready() {} }
+
+/** Used when a foreign-version runtime owns the process: never registered into, never dispatched to. */
+const detachedSessions = createSessionStore()
+let foreignVersionLogged = false
+
+/** The process runtime, created on first use; undefined when a different version already owns the process. */
+function runtime(): Runtime | undefined {
+  const slot = globalThis as Record<symbol, unknown>
+  const existing = slot[KEY] as { readonly version: number } | undefined
+  if (!existing) {
+    const created: Runtime = { version: VERSION, sessions: createSessionStore(), generations: [], confirmed: new Set(), rejected: new Map() }
+    slot[KEY] = created
+    return created
+  }
+  if (existing.version === VERSION) return existing as Runtime
+  if (!foreignVersionLogged) {
+    foreignVersionLogged = true
+    logError("runtime.foreign_version", { found: existing.version, expected: VERSION, action: "restart the server" })
+  }
+  return undefined
+}
+
+/** The session store shared by every generation in the process. */
+export const sessionStore = (): SessionStore => runtime()?.sessions ?? detachedSessions
+
+/** 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]
+  return rt.generations.at(-1)
+}
+
+/**
+ * The catalog of the preferred accepted generation. `fallback` (the caller's own loader) is only
+ * used when no generation is registered, which a live request does not normally see.
+ */
+export function loadServingCatalog(fallback: () => Promise<ReadonlyArray<CatalogModel>>): Promise<ReadonlyArray<CatalogModel>> {
+  const rt = runtime()
+  return (rt ? (preferred(rt)?.loadCatalog ?? fallback) : fallback)()
+}
+
+/** JSON with object keys sorted at every level, so equal options compare equal whatever their key order. */
+function canonicalJson(value: unknown): string {
+  const canonical = (item: unknown): unknown => {
+    if (Array.isArray(item)) return item.map(canonical)
+    if (typeof item !== "object" || item === null) return item
+    return Object.fromEntries(
+      Object.entries(item)
+        .filter(([, entry]) => entry !== undefined)
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(([key, entry]) => [key, canonical(entry)]),
+    )
+  }
+  return JSON.stringify(canonical(value))
+}
+
+const unavailable = (response: ServerResponse, message: string) => {
+  if (response.headersSent) return response.end()
+  const body = JSON.stringify({ error: { message, type: "server_error", code: "unavailable" } })
+  response.writeHead(503, { "content-type": "application/json", "content-length": Buffer.byteLength(body) })
+  response.end(body)
+}
+
+function startListener(rt: Runtime, listen: { host: string; port: number }, fingerprint: string): Listener {
+  const listener: Listener = { server: createServer(), listen, fingerprint, mismatchLogged: false, bound: false }
+  listener.server.on("request", (request, response) => {
+    const current = preferred(rt)
+    if (!current) return unavailable(response, "plugboard is reloading")
+    try {
+      current.handler(request, response)
+    } catch (error) {
+      logError("listener.handler_failed", { error: errorMessage(error) })
+      unavailable(response, "plugboard handler failed")
+    }
+  })
+  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,
+    })
+  })
+  listener.server.listen(listen.port, listen.host, () => {
+    listener.bound = true
+    log("listener.listening", { listen: `${listen.host}:${listen.port}` })
+  })
+  return listener
+}
+
+function closeListener(rt: Runtime, listener: Listener): void {
+  if (rt.listener !== listener) return
+  rt.listener = undefined
+  try {
+    rt.pump?.stop()
+  } catch {}
+  listener.server.close()
+  listener.server.closeAllConnections()
+  if (listener.bound) log("listener.closed")
+}
+
+/**
+ * Join (or create) the shared listener. The first accepted generation's options are the
+ * listener's (`fingerprint`, canonical JSON of the parsed options): a generation whose options
+ * differ is rejected and logs once while any generation is live, so a project config entry can
+ * never serve with weaker auth than the live one. When none is live (config reload) the next
+ * generation's options are adopted. A different `listen` needs a server restart and is rejected.
+ * A rejected generation is not in the generation list: it never serves, supplies no catalog, and
+ * the caller must not install hooks or seeds for it.
+ */
+export function registerGeneration(input: GenerationInput): Registration {
+  const rt = runtime()
+  if (!rt) return REJECTED
+  const { listen, directory } = input
+  const reject = (): Registration => {
+    rt.rejected.set(directory, (rt.rejected.get(directory) ?? 0) + 1)
+    let disposed = false
+    return {
+      accepted: false,
+      confirmed: () => false,
+      ready() {},
+      dispose() {
+        if (disposed) return
+        disposed = true
+        const left = (rt.rejected.get(directory) ?? 1) - 1
+        if (left > 0) rt.rejected.set(directory, left)
+        else rt.rejected.delete(directory)
+      },
+    }
+  }
+  const fingerprint = canonicalJson(input.options)
+  const listener = (rt.listener ??= startListener(rt, listen, fingerprint))
+  if (listener.listen.host !== listen.host || listener.listen.port !== listen.port) {
+    if (!listener.mismatchLogged) {
+      listener.mismatchLogged = true
+      logError("listener.listen_mismatch", {
+        bound: `${listener.listen.host}:${listener.listen.port}`,
+        requested: `${listen.host}:${listen.port}`,
+        action: "this Location is rejected; restart the server after changing `listen`",
+      })
+    }
+    return reject()
+  }
+  if (listener.fingerprint !== fingerprint) {
+    if (rt.generations.length > 0) {
+      if (!listener.mismatchLogged) {
+        listener.mismatchLogged = true
+        logError("listener.options_mismatch", { action: "this Location is rejected; global config is authoritative" })
+      }
+      return reject()
+    }
+    listener.fingerprint = fingerprint
+    listener.mismatchLogged = false
+  }
+  if (listener.graceTimer) clearTimeout(listener.graceTimer)
+  listener.graceTimer = undefined
+  const generation: Generation = {
+    directory,
+    handler: input.handler,
+    loadCatalog: input.loadCatalog,
+    refresh: input.refresh,
+    hooked: false,
+    // A directory confirmed before this Location booted needs no rebuild: its transforms already read `confirmed()` as true.
+    activated: rt.confirmed.has(directory),
+  }
+  rt.generations.push(generation)
+  return {
+    accepted: true,
+    confirmed: () => rt.confirmed.has(directory),
+    ready() {
+      generation.hooked = true
+    },
+    dispose() {
+      const index = rt.generations.indexOf(generation)
+      if (index !== -1) rt.generations.splice(index, 1)
+      if (rt.listener !== listener || rt.generations.length > 0 || listener.graceTimer) return
+      listener.graceTimer = setTimeout(() => {
+        listener.graceTimer = undefined
+        if (rt.generations.length === 0) closeListener(rt, listener)
+      }, GRACE_MS)
+      listener.graceTimer.unref?.()
+    },
+  }
+}
+
+/**
+ * Start the process-wide event pump if it is not running. The bus is server-wide, so the store
+ * drops everything that is not a registered request session before it is buffered. The pump is
+ * stopped when the listener closes and restarted by the next caller. `subscribe` is the calling
+ * generation's bus subscription; it is only invoked when a pump actually starts.
+ *
+ * If the fiber ends without `stop` (the subscription failed or was closed), no more events
+ * reach the store: every registered request is failed with a 502 and the pump is restarted by
+ * the next request.
+ */
+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)))))
+  const pump: Pump = {
+    stopped: false,
+    stop: () => {
+      pump.stopped = true
+      fiber.interruptUnsafe()
+    },
+  }
+  rt.pump = pump
+  fiber.addObserver((exit) => {
+    if (rt.pump === pump) rt.pump = undefined
+    if (pump.stopped) return
+    const failed = rt.sessions.failAll({
+      status: 502,
+      kind: "server",
+      code: "event_stream_lost",
+      message: "Lost the event stream of the OpenCode server",
+    })
+    logError("pump.stopped", {
+      exit: exit._tag,
+      failedRequests: failed,
+      ...(exit._tag === "Failure" ? { error: (Cause.pretty(exit.cause).split("\n")[0] ?? "").slice(0, 200) } : {}),
+    })
+  })
+}
+
+const backendUnavailable = (message: string): PlugError => ({ status: 503, kind: "server", code: "backend_unavailable", message })
+
+/** Rejects when `signal` aborts; the underlying promise is left running (its late result or error is swallowed). */
+function abortable<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => reject(new Error("aborted"))
+    if (signal.aborted) return onAbort()
+    signal.addEventListener("abort", onAbort, { once: true })
+    promise.then(
+      (value) => (signal.removeEventListener("abort", onAbort), resolve(value)),
+      (error) => (signal.removeEventListener("abort", onAbort), reject(error)),
+    )
+  })
+}
+
+const sleep = (ms: number, signal: AbortSignal) =>
+  new Promise<void>((resolve) => {
+    if (signal.aborted) return resolve()
+    const timer = setTimeout(done, ms)
+    function done() {
+      clearTimeout(timer)
+      signal.removeEventListener("abort", done)
+      resolve()
+    }
+    signal.addEventListener("abort", done, { once: true })
+  })
+
+/** Rebuild the transforms of a generation set up before its directory was confirmed; shared by concurrent requests. */
+function activate(generation: Generation): Promise<void> {
+  generation.activating ??= generation.refresh().then(
+    () => void (generation.activated = true),
+    (error) => {
+      generation.activating = undefined
+      throw error
+    },
+  )
+  return generation.activating
+}
+
+/**
+ * The per-directory readiness gate (docs/architecture.md): resolves with undefined once an
+ * accepted generation in the app directory of `app` is ready to rewrite request sessions, else
+ * with a `PlugError`, so the caller never prompts a session that no context hook would rewrite.
+ * Only ever called from request handling, never from plugin setup.
+ *
+ * 1. Create and canonicalize the app directory asynchronously (`ensureAppDir`: symlink
+ *    containment, the resolved directory must be strictly inside the canonical data root).
+ * 2. Confirm it (before booting, so a Location that boots now sees it at setup).
+ * 3. No generation there yet: `boot(directory)` makes the host boot the Location (any host call
+ *    scoped to that directory that builds it; the entry passes `ctx.agent.list({ location })`),
+ *    which loads the plugin there. Abandoned, not interrupted, when the request ends.
+ * 4. Generations set up before the directory was confirmed get their transforms rebuilt
+ *    (`GenerationInput.refresh`).
+ * 5. Wait, bounded by `signal` and a timeout, until a generation there is accepted (so it runs
+ *    with the live options) and has installed its hook. A generation that was rejected (options
+ *    or `listen` differ) is a 503 `backend_unavailable` at once.
+ */
+export async function ensureBackend(
+  app: string,
+  signal: AbortSignal,
+  boot: (directory: string) => Promise<unknown>,
+): Promise<PlugError | undefined> {
+  const rt = runtime()
+  if (!rt) return backendUnavailable("A different plugboard runtime owns this server process; restart the server")
+  try {
+    const directory = await ensureAppDir(app)
+    if (isPlugError(directory)) return directory
+    const bounded = AbortSignal.any([signal, AbortSignal.timeout(BACKEND_TIMEOUT_MS)])
+    rt.confirmed.add(directory)
+
+    let booted = false
+    while (true) {
+      if (bounded.aborted)
+        return backendUnavailable(
+          signal.aborted ? "The request ended before the app directory was ready" : "Timed out waiting for the plugboard app directory to load its backend",
+        )
+      const here = rt.generations.filter((generation) => generation.directory === directory)
+      if (here.length === 0) {
+        if ((rt.rejected.get(directory) ?? 0) > 0)
+          return backendUnavailable("The plugboard app directory was rejected (its plugin options or `listen` differ from the live ones)")
+        if (!booted) {
+          booted = true
+          try {
+            await abortable(boot(directory), bounded)
+          } catch (error) {
+            if (bounded.aborted) continue
+            logError("backend.boot_failed", { app, error: errorMessage(error) })
+            return backendUnavailable("Could not start the plugboard app directory")
+          }
+          continue
+        }
+      } else {
+        try {
+          await abortable(Promise.all(here.filter((generation) => !generation.activated).map(activate)), bounded)
+        } catch (error) {
+          if (bounded.aborted) continue
+          throw error
+        }
+        if (here.some((generation) => generation.hooked && generation.activated)) return undefined
+      }
+      await sleep(BACKEND_POLL_MS, bounded)
+    }
+  } catch (error) {
+    if (signal.aborted) return backendUnavailable("The request ended before the app directory was ready")
+    logError("backend.check_failed", { app, error: errorMessage(error) })
+    return backendUnavailable("Could not prepare the plugboard app directory")
+  }
+}