backeer-opencode 0.8.2 → 0.10.0

package/src/live-bridge.js

@@ -1,5 +1,5 @@
 import { createServer } from "node:http"
-import { randomUUID, timingSafeEqual } from "node:crypto"
+import { randomUUID, timingSafeEqual, createHash } from "node:crypto"
 import { resolve } from "node:path"
 import { createV1LiveClient } from "./live-bridge-client.js"
 import { createLiveConnectionNotifier, LIVE_HEARTBEAT_MS, LIVE_RECONNECT_MS } from "./live-connection.js"
@@ -7,7 +7,6 @@ import { createBridgeSanitizer, validBridgeID } from "./live-bridge-events.js"
 import { questionSnapshot, resolveQuestionAnswers } from "./live-questions.js"
 import { PLUGIN_VERSION } from "./updates.js"
 
-const LIMITS = { events: 256, bytes: 2_000_000, clients: 8, commands: 1024, commandTTL: 86_400_000, body: 32_768, requests: 16 }
 function failure(status, code) { return Object.assign(new Error(code), { status, code }) }
 function json(response, status, value) {
   if (!response.destroyed && !response.headersSent) {
@@ -17,10 +16,7 @@ function json(response, status, value) {
 }
 async function readBody(request) {
   const chunks = []
-  let bytes = 0
   for await (const chunk of request) {
-    bytes += chunk.length
-    if (bytes > LIMITS.body) throw failure(413, "body_too_large")
     chunks.push(chunk)
   }
   try { return JSON.parse(Buffer.concat(chunks).toString("utf8")) } catch { throw failure(400, "invalid_json") }
@@ -41,41 +37,46 @@ export async function createLiveBridge({ config, client, directory, reporter })
   const sanitizer = createBridgeSanitizer([token, config.token])
   const epoch = randomUUID()
   const events = [], streams = new Set(), commands = new Map(), states = new Map()
-  let sequence = 0, bytes = 0, active = 0, disposed = false, disposeTask
-  let lookups = 0
-  const lookupWaiters = new Set()
+  let sequence = 0, disposed = false, disposeTask
+  const lookupWaiters = new Set(), lookups = new Map()
   const cursor = () => `${epoch}:${sequence}`
 
-  function lookup(id) {
+  function lookup(id, signal) {
     if (disposed) return Promise.reject(failure(503, "bridge_closed"))
-    if (lookups >= 16) return Promise.reject(failure(429, "session_lookup_busy"))
-    lookups++
+    let entry = lookups.get(id)
+    if (!entry) {
+      entry = { waiters: new Set() }
+      lookups.set(id, entry)
+      const settled = (ok, value) => {
+        lookups.delete(id)
+        for (const finish of [...entry.waiters]) finish(ok, value)
+      }
+      // Retrying readers share one in-flight native lookup for the exact ID.
+      // Aborted HTTP readers are removable subscribers, not retained Promise callbacks.
+      Promise.resolve().then(() => api.get(id)).then(value => settled(true, value), error => settled(false, error))
+    }
     return new Promise((resolve, reject) => {
-      let finished = false
-      const finish = (complete, value) => {
-        if (finished) return
-        finished = true
-        clearTimeout(timer)
+      const finish = (ok, value) => {
+        if (!entry.waiters.delete(finish)) return
         lookupWaiters.delete(cancel)
-        complete(value)
+        signal?.removeEventListener("abort", aborted)
+        if (ok) resolve(value)
+        else reject(value)
       }
-      const cancel = () => finish(reject, failure(503, "bridge_closed"))
-      const timer = setTimeout(() => finish(reject, failure(504, "session_lookup_timed_out")), 1000)
+      const cancel = () => finish(false, failure(503, "bridge_closed"))
+      const aborted = () => finish(false, failure(499, "request_cancelled"))
+      entry.waiters.add(finish)
       lookupWaiters.add(cancel)
-      // The caller's deadline does not release this slot: unsupported SDK
-      // cancellation must not let timed-out, still-running calls accumulate.
-      Promise.resolve().then(() => api.get(id)).then(
-        (value) => { lookups--; finish(resolve, value) },
-        (error) => { lookups--; finish(reject, error) },
-      )
+      signal?.addEventListener("abort", aborted, { once: true })
+      if (signal?.aborted) aborted()
     })
   }
 
-  async function session(id) {
+  async function session(id, signal) {
     if (!validBridgeID(id) || id === "global") throw failure(400, "invalid_session")
     let info
-    try { info = await lookup(id) } catch (error) {
-      if (["session_lookup_busy", "session_lookup_timed_out", "bridge_closed"].includes(error.code)) throw error
+    try { info = await lookup(id, signal) } catch (error) {
+      if (["bridge_closed", "request_cancelled"].includes(error.code)) throw error
       throw failure(404, "session_not_found")
     }
     if (info?.id !== id || typeof info.time?.archived === "number") {
@@ -95,18 +96,12 @@ export async function createLiveBridge({ config, client, directory, reporter })
     const removed = streams.delete(stream)
     clearInterval(stream.heartbeat)
     stream.queue.length = 0
-    stream.queuedBytes = 0
     if (removed && !streams.size && !disposed) connectionNotifications.update(false)
   }
   function write(stream, value) {
     if (!streams.has(stream)) return
     if (stream.blocked) {
       stream.queue.push(value)
-      stream.queuedBytes += Buffer.byteLength(value)
-      if (stream.queuedBytes > LIMITS.bytes) {
-        removeStream(stream)
-        stream.response.destroy()
-      }
       return
     }
     if (!stream.response.write(value)) {
@@ -124,17 +119,9 @@ export async function createLiveBridge({ config, client, directory, reporter })
     if (safe.type === "session.status") states.set(safe.sessionID, safe.data.status)
     if (safe.type === "session.idle") states.set(safe.sessionID, "idle")
     if (safe.type === "session.deleted") states.delete(safe.sessionID)
-    if (states.size > 256) states.delete(states.keys().next().value)
     const record = { id: `${epoch}:${++sequence}`, ...safe, timestamp: Date.now() }
-    let frame = `id: ${record.id}\nevent: backeer.event\ndata: ${JSON.stringify(record)}\n\n`
-    if (Buffer.byteLength(frame) > 32_768) {
-      record.data = { truncated: true }
-      frame = `id: ${record.id}\nevent: backeer.event\ndata: ${JSON.stringify(record)}\n\n`
-    }
-    const size = Buffer.byteLength(frame)
-    events.push({ sequence, sessionID: record.sessionID, frame, size })
-    bytes += size
-    while (events.length > LIMITS.events || bytes > LIMITS.bytes) bytes -= events.shift().size
+    const frame = `id: ${record.id}\nevent: backeer.event\ndata: ${JSON.stringify(record)}\n\n`
+    events.push({ sequence, sessionID: record.sessionID, frame })
     for (const stream of streams) if (!stream.sessionID || stream.sessionID === record.sessionID) write(stream, frame)
   }
   function authorized(request) {
@@ -145,7 +132,7 @@ export async function createLiveBridge({ config, client, directory, reporter })
   }
   function parseCursor(value) {
     if (!value) return { after: 0 }
-    const match = /^([a-f0-9-]{36}):(\d{1,16})$/.exec(value)
+    const match = /^([a-f0-9-]{36}):(\d+)$/.exec(value)
     if (!match) throw failure(400, "invalid_cursor")
     if (match[1] !== epoch) return { gap: "stream_restarted" }
     const after = Number(match[2])
@@ -154,9 +141,6 @@ export async function createLiveBridge({ config, client, directory, reporter })
     return { after }
   }
   function cachedCommand(requestId, sessionID, signature) {
-    for (const [id, command] of commands) {
-      if (command.settled && Date.now() - command.created >= LIMITS.commandTTL) commands.delete(id)
-    }
     const existing = commands.get(requestId)
     if (existing && (existing.sessionID !== sessionID || existing.signature !== signature)) {
       throw failure(409, "request_id_conflict")
@@ -166,17 +150,16 @@ export async function createLiveBridge({ config, client, directory, reporter })
   async function execute(requestId, sessionID, signature, operation, questionId) {
     let command = cachedCommand(requestId, sessionID, signature)
     if (!command) {
-      if (commands.size >= LIMITS.commands) throw failure(429, "command_window_full")
       // Another chat/mobile/native UI may answer too: OpenCode is authoritative.
       // Reserve locally before calling it so concurrent request IDs cannot submit twice.
       if (questionId && [...commands.values()].some(item => item.sessionID === sessionID && item.questionId === questionId)) {
         throw failure(409, "question_reply_already_submitted")
       }
-      command = { sessionID, signature, questionId, created: Date.now(), settled: false,
+      command = { sessionID, signature, questionId,
         result: { requestId, sessionID, ...(questionId ? { questionId } : {}),
           status: questionId ? "answered" : "accepted" } }
       commands.set(requestId, command)
-      command.task = Promise.resolve().then(operation).finally(() => { command.settled = true })
+      command.task = Promise.resolve().then(operation).then(() => undefined)
     }
     await command.task
     return command.result
@@ -186,7 +169,6 @@ export async function createLiveBridge({ config, client, directory, reporter })
     const pending = await api.questions(sessionID)
     if (!Array.isArray(pending)) throw failure(502, "invalid_question_list")
     const own = pending.filter(item => item.sessionID === sessionID)
-    if (own.length > 16) throw failure(413, "too_many_questions")
     return own
   }
   async function route(request, response) {
@@ -195,10 +177,9 @@ export async function createLiveBridge({ config, client, directory, reporter })
         request.headers["x-backeer-project"] !== encodeURIComponent(directory)) {
       return json(response, 409, { error: "project_mismatch" })
     }
-    if (active >= LIMITS.requests) return json(response, 429, { error: "bridge_busy" })
-    active++
-    const timeout = setTimeout(() => json(response, 504, { error: "request_timed_out" }), 15_000)
-    timeout.unref()
+    const controller = new AbortController()
+    const closed = () => controller.abort()
+    response.once("close", closed)
     try {
       const url = new URL(request.url, "http://127.0.0.1")
       if (url.username || url.password) throw failure(400, "invalid_url")
@@ -207,7 +188,7 @@ export async function createLiveBridge({ config, client, directory, reporter })
         const values = Array.isArray(result) ? result : result?.data
         if (!Array.isArray(values)) throw failure(502, "invalid_session_list")
         const own = []
-        for (const info of values.slice(0, 100)) {
+        for (const info of values) {
           if (!validBridgeID(info?.id) || typeof info.time?.archived === "number") continue
           if (api.ownsSession ? await api.ownsSession(info) : (info.location?.directory ?? info.directory) === directory) own.push(info)
         }
@@ -224,11 +205,9 @@ export async function createLiveBridge({ config, client, directory, reporter })
       }
       if (request.method === "GET" && url.pathname === "/v1/events") {
         const selected = url.searchParams.get("sessionID") || undefined
-        if (selected) await session(selected)
+        if (selected) await session(selected, controller.signal)
         const parsed = parseCursor(url.searchParams.get("after") ?? request.headers["last-event-id"])
         if (response.headersSent) return
-        if (streams.size >= LIMITS.clients) throw failure(429, "too_many_streams")
-        clearTimeout(timeout)
         response.writeHead(200, {
           "content-type": "text/event-stream", "cache-control": "no-cache, no-transform",
           "x-accel-buffering": "no", connection: "keep-alive",
@@ -238,7 +217,7 @@ export async function createLiveBridge({ config, client, directory, reporter })
           return
         }
         const stream = { response, sessionID: selected, heartbeat: undefined,
-          blocked: false, queue: [], queuedBytes: 0 }
+          blocked: false, queue: [] }
         streams.add(stream)
         connectionNotifications.update(true)
         request.socket.setTimeout(0)
@@ -248,7 +227,6 @@ export async function createLiveBridge({ config, client, directory, reporter })
           stream.blocked = false
           while (streams.has(stream) && !stream.blocked && stream.queue.length) {
             const next = stream.queue.shift()
-            stream.queuedBytes -= Buffer.byteLength(next)
             write(stream, next)
           }
         })
@@ -263,13 +241,12 @@ export async function createLiveBridge({ config, client, directory, reporter })
         }
         return
       }
-      const match = /^\/v1\/sessions\/([A-Za-z0-9_-]{1,160})(\/instructions|\/questions(?:\/([A-Za-z0-9_-]{1,160})\/answers)?)?$/.exec(url.pathname)
+      const match = /^\/v1\/sessions\/([A-Za-z0-9_-]+)(\/instructions|\/questions(?:\/([A-Za-z0-9_-]+)\/answers)?)?$/.exec(url.pathname)
       if (!match) throw failure(404, "route_not_found")
-      if (request.method === "GET" && !match[2]) return json(response, 200, await session(match[1]))
+      if (request.method === "GET" && !match[2]) return json(response, 200, await session(match[1], controller.signal))
       if (request.method === "GET" && match[2] === "/questions") {
-        await session(match[1])
+        await session(match[1], controller.signal)
         const result = { questions: (await questions(match[1])).map(item => questionSnapshot(item, sanitizer.text)) }
-        if (Buffer.byteLength(JSON.stringify(result)) > 240_000) throw failure(413, "questions_too_large")
         return json(response, 200, result)
       }
       if (request.method !== "POST" || !match[2]) throw failure(405, "method_not_allowed")
@@ -278,8 +255,8 @@ export async function createLiveBridge({ config, client, directory, reporter })
       if (match[3]) {
         if (!body || !validBridgeID(body.requestId) || !/^[a-f0-9]{64}$/.test(body.revision) ||
             Object.keys(body).some(key => !["requestId", "revision", "answers"].includes(key))) throw failure(400, "invalid_question_answer")
-        await session(match[1])
-        const signature = JSON.stringify({ questionId: match[3], revision: body.revision, answers: body.answers })
+        await session(match[1], controller.signal)
+        const signature = createHash("sha256").update(JSON.stringify({ questionId: match[3], revision: body.revision, answers: body.answers })).digest("hex")
         const existing = cachedCommand(body.requestId, match[1], signature)
         if (existing) { await existing.task; return json(response, 200, existing.result) }
         const pending = (await questions(match[1])).find(item => item.id === match[3])
@@ -293,25 +270,24 @@ export async function createLiveBridge({ config, client, directory, reporter })
       }
       if (match[2] !== "/instructions") throw failure(405, "method_not_allowed")
       if (!body || !validBridgeID(body.requestId) || typeof body.prompt !== "string" ||
-          !body.prompt.trim() || body.prompt.length > 16_000 ||
+          !body.prompt.trim() ||
           Object.keys(body).some((key) => !["requestId", "prompt"].includes(key))) throw failure(400, "invalid_instruction")
-      await session(match[1])
+      await session(match[1], controller.signal)
       if (response.headersSent || disposed) return
-      const signature = JSON.stringify({ prompt: body.prompt })
+      const signature = createHash("sha256").update(JSON.stringify({ prompt: body.prompt })).digest("hex")
       const existing = cachedCommand(body.requestId, match[1], signature)
       const result = await execute(body.requestId, match[1], signature, () => api.prompt(match[1], body.prompt))
       return json(response, existing ? 200 : 202, result)
     } catch (error) {
       json(response, error.status ?? 502, { error: error.code ?? "opencode_request_failed" })
     } finally {
-      active--
-      clearTimeout(timeout)
+      response.removeListener("close", closed)
     }
   }
   const server = createServer((request, response) => { void route(request, response) })
-  server.requestTimeout = 15_000
-  server.headersTimeout = 10_000
-  server.keepAliveTimeout = 5_000
+  server.requestTimeout = 0
+  server.headersTimeout = 0
+  server.keepAliveTimeout = 0
   await new Promise((resolve, reject) => {
     server.once("error", reject)
     server.listen(options.port ?? 43871, "127.0.0.1", () => { server.off("error", reject); resolve() })
@@ -329,6 +305,7 @@ export async function createLiveBridge({ config, client, directory, reporter })
         events.length = 0
         states.clear()
         commands.clear()
+        lookups.clear()
         sanitizer.clear()
         api.dispose?.()
       })

package/src/live-control-client.js

@@ -4,9 +4,10 @@ import { isAbsolute } from "node:path"
 import { LIVE_RECONNECT_MS, LIVE_STALE_MS } from "./live-connection.js"
 import { checkWindowsTokenAcl } from "./live-token-permissions.js"
 import { liveErrorMessages } from "./live-errors.js"
+import { connectionDiagnostic } from "./live-diagnostics.js"
 
-const CURSOR = /^[A-Za-z0-9_-]{1,80}:\d{1,16}$/
-const SESSION = /^[A-Za-z0-9_-]{1,160}$/
+const CURSOR = /^[A-Za-z0-9_-]+:\d+$/
+const SESSION = /^[A-Za-z0-9_-]+$/
 
 export function liveControlOrigin(url) {
   const parsed = new URL(url)
@@ -27,12 +28,12 @@ export async function readLiveControlToken(path) {
     (constants.O_NONBLOCK ?? 0))
   try {
     const stat = await file.stat()
-    if (!stat.isFile() || stat.size > 4096 || (process.platform !== "win32" && (stat.mode & 0o077) !== 0) ||
+    if (!stat.isFile() || (process.platform !== "win32" && (stat.mode & 0o077) !== 0) ||
         (typeof process.getuid === "function" && stat.uid !== process.getuid())) {
       throw new Error("Live-control token must be an owner-only regular file")
     }
     const token = (await file.readFile("utf8")).trim()
-    if (!/^[A-Za-z0-9_-]{32,256}$/.test(token)) {
+    if (!/^[A-Za-z0-9_-]{32,}$/.test(token)) {
       throw new Error("Live-control token file is invalid")
     }
     return token
@@ -68,14 +69,16 @@ function parseFrame(frame) {
   return { type, id, value: JSON.parse(data.join("\n")) }
 }
 
-// One persistent SSE connection per MCP process; no interval polling or unbounded history.
+// One persistent SSE connection per MCP process; no interval polling or imposed history quota.
 export class LiveControlClient {
   constructor({ url = "http://127.0.0.1:43871", token, fetchImpl = fetch,
-    maxEvents = 500, maxBufferBytes = 1024 * 1024, reconnectMs = LIVE_RECONNECT_MS, expectedDirectory } = {}) {
+    maxEvents = Infinity, maxBufferBytes = Infinity, reconnectMs = LIVE_RECONNECT_MS, expectedDirectory, sessionId } = {}) {
     const origin = liveControlOrigin(url)
-    if (typeof token !== "string" || !/^[A-Za-z0-9_-]{32,256}$/.test(token)) throw new Error("Live-control token is invalid")
+    if (typeof token !== "string" || !/^[A-Za-z0-9_-]{32,}$/.test(token)) throw new Error("Live-control token is invalid")
     this.url = origin
     this.token = token
+    if (sessionId !== undefined) checkedSession(sessionId)
+    this.sessionId = sessionId
     this.projectHeaders = expectedDirectory === undefined ? {} : { "X-Backeer-Project": encodeURIComponent(expectedDirectory) }
     this.fetch = fetchImpl
     this.maxEvents = maxEvents
@@ -92,6 +95,12 @@ export class LiveControlClient {
     this.floor = undefined
     this.task = null
     this.starting = null
+    this.reconnectAttempts = 0
+    this.successfulConnections = 0
+    this.lastConnectedAt = null
+    this.lastDisconnectedAt = null
+    this.nextRetryAt = null
+    this.lastDiagnostic = null
   }
 
   async request(path, { method = "GET", body, signal, timeoutMs = 10000 } = {}) {
@@ -100,7 +109,8 @@ export class LiveControlClient {
     this.controller.signal.addEventListener("abort", abort, { once: true })
     signal?.addEventListener("abort", abort, { once: true })
     if (this.controller.signal.aborted || signal?.aborted) controller.abort()
-    const timer = setTimeout(abort, timeoutMs)
+    let timedOut = false
+    const timer = setTimeout(() => { timedOut = true; abort() }, timeoutMs)
     try {
       const response = await this.fetch(this.url + path, {
         method, redirect: "error", signal: controller.signal,
@@ -109,22 +119,29 @@ export class LiveControlClient {
         ...(body ? { body: JSON.stringify(body) } : {}),
       })
       if (!response.ok) {
-        // Read only a bounded JSON code; return exclusively local allowlisted
+        // Read the JSON code but return exclusively local allowlisted
         // messages, never original upstream error text or arbitrary JSON data.
-        let code
+        let code, connectionCode
         try {
           if (response.headers.get("content-type")?.includes("application/json")) {
-            const value = JSON.parse(await boundedText(response, 4096))
+            const value = JSON.parse(await responseText(response))
             if (Object.hasOwn(liveErrorMessages, value?.error)) code = value.error
+            if (value?.error === "project_mismatch") connectionCode = "project_mismatch"
           }
         } catch { /* Retain the generic status without exposing remote content. */ }
         finally { await response.body?.cancel().catch(() => {}) }
         const diagnostic = code ? `: ${liveErrorMessages[code]}` : ""
         throw Object.assign(new Error(`Live-control request failed (HTTP ${response.status})${diagnostic}`),
-          { status: response.status, ...(code ? { code } : {}) })
+          { status: response.status, ...(code ? { code } : {}), ...(connectionCode ? { connectionCode } : {}) })
       }
-      const text = await boundedText(response, 256 * 1024)
+      const text = await responseText(response)
       return JSON.parse(text)
+    } catch (error) {
+      const diagnostic = connectionDiagnostic(error, { session: /^\/v1\/sessions\//.test(path), write: method !== "GET", timeout: timedOut,
+        cancelled: this.controller.signal.aborted || signal?.aborted })
+      // Leave the native status/code available for exact-session checks. Only the
+      // allowlisted connection code is exposed by MCP, never the fetch message.
+      throw Object.assign(error, { connectionCode: diagnostic.code })
     } finally {
       clearTimeout(timer)
       this.controller.signal.removeEventListener("abort", abort)
@@ -137,8 +154,8 @@ export class LiveControlClient {
   listQuestions(id) { return this.request(`/v1/sessions/${checkedSession(id)}/questions`) }
 
   answerQuestion({ sessionId, questionId, revision, answers, requestId, signal }) {
-    if (!/^[A-Za-z0-9_-]{8,128}$/.test(requestId) || !/^[a-f0-9]{64}$/.test(revision) ||
-        !Array.isArray(answers) || answers.length < 1 || answers.length > 16) throw new Error("Invalid question answer")
+    if (!/^[A-Za-z0-9_-]+$/.test(requestId) || !/^[a-f0-9]{64}$/.test(revision) ||
+        !Array.isArray(answers) || answers.length < 1) throw new Error("Invalid question answer")
     // No automatic POST retry. Reuse the exact requestId/payload on uncertainty.
     return this.request(`/v1/sessions/${checkedSession(sessionId)}/questions/${checkedSession(questionId)}/answers`, {
       method: "POST", body: { requestId, revision, answers }, signal,
@@ -146,9 +163,9 @@ export class LiveControlClient {
   }
 
   async sendInstruction({ sessionId, requestId, prompt, signal }) {
-    if (!/^[A-Za-z0-9_-]{8,128}$/.test(requestId)) throw new Error("Invalid request ID")
-    if (typeof prompt !== "string" || !prompt.trim() || prompt.length > 16000) {
-      throw new Error("Instruction must contain 1–16000 characters")
+    if (!/^[A-Za-z0-9_-]+$/.test(requestId)) throw new Error("Invalid request ID")
+    if (typeof prompt !== "string" || !prompt.trim()) {
+      throw new Error("Instruction must contain nonempty text")
     }
     const encodedSession = checkedSession(sessionId)
     // Capture the pre-command cursor before POST: a fast agent may finish before the first read.
@@ -182,9 +199,11 @@ export class LiveControlClient {
           this.floor = initial
           this.readCursor = initial
           this.task = this.runStream()
-        } catch {
+        } catch (error) {
           if (this.controller.signal.aborted) return
           this.status = "disconnected"
+          this.recordFailure(error)
+          this.nextRetryAt = Date.now() + this.reconnectMs
           this.task = (async () => { await this.delay(this.reconnectMs); await this.runStream() })()
         }
       })().finally(() => { this.starting = null })
@@ -194,16 +213,19 @@ export class LiveControlClient {
 
   async runStream() {
     while (!this.controller.signal.aborted) {
+      if (this.lastDisconnectedAt !== null) this.reconnectAttempts++
+      this.nextRetryAt = null
       this.status = "connecting"
       let reader
       let watchdog
       let resync = false
+      let timedOut = false
       const connection = new AbortController()
       const abort = () => connection.abort()
       this.controller.signal.addEventListener("abort", abort, { once: true })
       const armWatchdog = (ms = LIVE_STALE_MS) => {
         clearTimeout(watchdog)
-        watchdog = setTimeout(abort, ms)
+        watchdog = setTimeout(() => { timedOut = true; abort() }, ms)
       }
       armWatchdog(this.reconnectMs)
       try {
@@ -217,7 +239,8 @@ export class LiveControlClient {
           this.floor = initial
           this.readCursor = initial
         }
-        const response = await this.fetch(`${this.url}/v1/events?after=${encodeURIComponent(this.cursor)}`, {
+        const selected = this.sessionId === undefined ? "" : `&sessionID=${encodeURIComponent(this.sessionId)}`
+        const response = await this.fetch(`${this.url}/v1/events?after=${encodeURIComponent(this.cursor)}${selected}`, {
           redirect: "error", signal: connection.signal,
           headers: { Authorization: `Bearer ${this.token}`, Accept: "text/event-stream", ...this.projectHeaders },
         })
@@ -229,10 +252,14 @@ export class LiveControlClient {
           this.status = response.status === 401 || response.status === 403 ? "unauthorized" : "disconnected"
           this.notify()
           await response.body?.cancel().catch(() => {})
-          throw new Error("SSE connection unavailable")
+          throw Object.assign(new Error("SSE connection unavailable"), { status: response.status,
+            ...(response.ok ? { connectionCode: "invalid_bridge_response" } : {}) })
         }
         if (!response.body) throw new Error("SSE body missing")
         this.status = "connected"
+        this.successfulConnections++
+        this.lastConnectedAt = Date.now()
+        this.lastDiagnostic = null
         armWatchdog()
         this.notify()
         reader = response.body.getReader()
@@ -241,7 +268,10 @@ export class LiveControlClient {
         while (!this.controller.signal.aborted && !resync) {
           const item = await reader.read()
           if (item.done) {
-            if (!this.controller.signal.aborted) this.status = "disconnected"
+            if (!this.controller.signal.aborted) {
+              this.status = "disconnected"
+              this.recordFailure({ connectionCode: "connection_interrupted" })
+            }
             break
           }
           armWatchdog()
@@ -249,13 +279,14 @@ export class LiveControlClient {
           buffer = buffer.replace(/\r\n|\r(?!$)/g, "\n")
           let at
           while ((at = buffer.indexOf("\n\n")) !== -1) {
-            if (at > 64 * 1024) throw new Error("SSE frame exceeds limit")
             const frame = parseFrame(buffer.slice(0, at))
             buffer = buffer.slice(at + 2)
             if (!frame) continue
             if (frame.type === "backeer.gap") {
               if (!frame.value.cursor) throw new Error("SSE gap cursor missing")
-              this.gap = { reason: String(frame.value.reason), cursor: checkedCursor(frame.value.cursor) }
+              const reason = ["stream_restarted", "cursor_expired", "history_expired", "invalid_cursor"].includes(frame.value.reason)
+                ? frame.value.reason : "remote_replay_unavailable"
+              this.gap = { reason, cursor: checkedCursor(frame.value.cursor) }
               resync = true
               this.cursor = this.gap.cursor
               this.floor = this.cursor
@@ -282,16 +313,19 @@ export class LiveControlClient {
             }
             this.notify()
           }
-          if (buffer.length > 64 * 1024) throw new Error("SSE frame exceeds limit")
         }
-      } catch {
-        if (!this.controller.signal.aborted && this.status !== "unauthorized") this.status = "disconnected"
+      } catch (error) {
+        if (!this.controller.signal.aborted) {
+          if (this.status !== "unauthorized") this.status = "disconnected"
+          this.recordFailure(error, { timeout: timedOut })
+        }
       } finally {
         clearTimeout(watchdog)
         this.controller.signal.removeEventListener("abort", abort)
         await reader?.cancel().catch(() => {})
         reader?.releaseLock()
       }
+      if (!this.controller.signal.aborted) this.nextRetryAt = Date.now() + this.reconnectMs
       this.notify()
       if (!this.controller.signal.aborted) await this.delay(this.reconnectMs)
     }
@@ -310,11 +344,24 @@ export class LiveControlClient {
     })
   }
 
-  snapshot({ afterCursor = this.readCursor, sessionId, limit = 20, maxChars = 32000 } = {}) {
+  recordFailure(error, context) {
+    this.lastDisconnectedAt = Date.now()
+    this.lastDiagnostic = connectionDiagnostic(error, context)
+  }
+
+  connectionState() {
+    return { status: this.status, reconnectEveryMs: this.reconnectMs, reconnectAttempts: this.reconnectAttempts,
+      successfulConnections: this.successfulConnections, lastConnectedAt: this.lastConnectedAt,
+      lastDisconnectedAt: this.lastDisconnectedAt, nextRetryAt: this.nextRetryAt,
+      diagnostic: this.lastDiagnostic, bufferedEvents: this.events.length, cursor: this.cursor,
+      ...(this.gap ? { gap: this.gap } : {}) }
+  }
+
+  snapshot({ afterCursor = this.readCursor, sessionId, limit = Infinity, maxChars = Infinity } = {}) {
     checkedCursor(afterCursor)
     if (sessionId !== undefined) checkedSession(sessionId)
-    if (!Number.isInteger(limit) || limit < 1 || limit > 100 ||
-        !Number.isInteger(maxChars) || maxChars < 1024 || maxChars > 64000) throw new Error("Invalid read bounds")
+    if ((limit !== Infinity && (!Number.isSafeInteger(limit) || limit < 1)) ||
+        (maxChars !== Infinity && (!Number.isSafeInteger(maxChars) || maxChars < 1))) throw new Error("Invalid read bounds")
     let gap = this.gap
     let start = 0
     if (!gap && afterCursor !== this.floor) {
@@ -341,11 +388,12 @@ export class LiveControlClient {
       cursor = event.id
     }
     this.readCursor = cursor
-    return { events: result, cursor, connection: this.status, hasMore: index < this.events.length }
+    return { events: result, cursor, connection: this.status, hasMore: index < this.events.length,
+      transport: this.connectionState() }
   }
 
   async readEvents(options = {}, { waitMs = 0, signal } = {}) {
-    if (!Number.isInteger(waitMs) || waitMs < 0 || waitMs > 25000) throw new Error("Wait must be 0–25000ms")
+    if (waitMs !== Infinity && (!Number.isSafeInteger(waitMs) || waitMs < 0)) throw new Error("Wait must be a nonnegative safe integer or unlimited")
     await this.start(options.afterCursor)
     let result = this.snapshot(options)
     if (!waitMs || result.events.length || result.gap || result.hasMore || this.status === "unauthorized") return result
@@ -359,7 +407,7 @@ export class LiveControlClient {
           this.controller.signal.removeEventListener("abort", done)
           resolve()
         }
-        const timer = setTimeout(done, Math.max(0, deadline - Date.now()))
+        const timer = Number.isFinite(deadline) ? setTimeout(done, Math.min(2 ** 31 - 1, Math.max(0, deadline - Date.now()))) : undefined
         this.listeners.add(done)
         signal?.addEventListener("abort", done, { once: true })
         this.controller.signal.addEventListener("abort", done, { once: true })
@@ -374,6 +422,7 @@ export class LiveControlClient {
   async close() {
     this.controller.abort()
     this.status = "closed"
+    this.nextRetryAt = null
     this.notify()
     await this.starting
     await this.task
@@ -383,17 +432,14 @@ export class LiveControlClient {
   }
 }
 
-async function boundedText(response, limit) {
+async function responseText(response) {
   if (!response.body) throw new Error("Live-control response is empty")
   const reader = response.body.getReader()
   const chunks = []
-  let size = 0
   try {
     while (true) {
       const { done, value } = await reader.read()
       if (done) break
-      size += value.byteLength
-      if (size > limit) throw new Error("Live-control response exceeds limit")
       chunks.push(Buffer.from(value))
     }
     return Buffer.concat(chunks).toString("utf8")