@polderlabs/bizar 5.0.2 → 5.2.0

package/bizar-dash/src/server/plugins/registry.mjs

@@ -31,7 +31,10 @@
  *   }
  */
 import { createHash } from 'node:crypto';
-import { createReadStream } from 'node:fs';
+import { createReadStream, readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as logger from '../logger.mjs';
 
 /**
  * Default registry URL. Override with `BIZAR_REGISTRY_URL` env var.
@@ -43,6 +46,68 @@ import { createReadStream } from 'node:fs';
 const DEFAULT_REGISTRY_URL =
   'https://raw.githubusercontent.com/DrB0rk/bizar-plugins/main/registry.json';
 
+/**
+ * Fallback registry URLs tried in order when the primary URL fails.
+ * BIZAR_REGISTRY_URL env var takes precedence over all if set.
+ */
+const FALLBACK_REGISTRY_URLS = [
+  'https://bizar-plugins.bork.deno.net/registry.json',
+];
+
+/**
+ * All registry URLs in priority order: explicit override (if any) first,
+ * then BIZAR_REGISTRY_URL, then defaults including fallbacks.
+ * @returns {string[]}
+ */
+function getRegistryUrls() {
+  const urls = [];
+  if (process.env.BIZAR_REGISTRY_URL && process.env.BIZAR_REGISTRY_URL.trim()) {
+    urls.push(process.env.BIZAR_REGISTRY_URL.trim());
+  }
+  urls.push(DEFAULT_REGISTRY_URL, ...FALLBACK_REGISTRY_URLS);
+  return urls;
+}
+
+/** Path to the on-disk registry cache. */
+function getCacheFilePath() {
+  const homedir = process.env.HOME || process.env.USERPROFILE || tmpdir();
+  const cacheDir = join(homedir, '.cache', 'bizar');
+  return join(cacheDir, 'registry.json');
+}
+
+/**
+ * Read the registry from the on-disk cache file.
+ * Returns null if the file doesn't exist or can't be parsed.
+ * @returns {Promise<RegistryShape | null>}
+ */
+export async function readRegistryCache() {
+  try {
+    const cachePath = getCacheFilePath();
+    if (!existsSync(cachePath)) return null;
+    const raw = readFileSync(cachePath, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the registry to the on-disk cache file.
+ * @param {RegistryShape} data
+ */
+export function writeRegistryCache(data) {
+  try {
+    const cachePath = getCacheFilePath();
+    const cacheDir = dirname(cachePath);
+    if (!existsSync(cacheDir)) {
+      mkdirSync(cacheDir, { recursive: true });
+    }
+    writeFileSync(cachePath, JSON.stringify(data, null, 2), 'utf8');
+  } catch (err) {
+    logger.warn('failed to write registry cache', { err: err.message });
+  }
+}
+
 /** How long a cached registry is considered fresh. */
 const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
 
@@ -156,65 +221,102 @@ export function validateRegistry(data) {
 /**
  * Fetch the registry, returning the validated parsed shape.
  *
+ * When no explicit URL is provided, iterates through all registry URLs
+ * (BIZAR_REGISTRY_URL env var > defaults > fallbacks) until one succeeds.
+ * On complete failure, falls back to the on-disk cache file.
+ *
  * Cache: in-memory for 1 hour per URL. A `force: true` option bypasses
  * the cache (used by the `update` CLI subcommand).
  *
  * @param {object} [opts]
- * @param {string} [opts.url]   override the URL (default: env/default)
+ * @param {string} [opts.url]   override the URL (uses all fallbacks if omitted)
  * @param {boolean} [opts.force] skip the cache
  * @param {typeof globalThis.fetch} [opts.fetch] fetch override (tests)
  * @returns {Promise<RegistryShape>}
  */
 export async function fetchRegistry({ url, force = false, fetch: fetchImpl } = {}) {
-  const resolvedUrl = getRegistryUrl(url);
   const now = Date.now();
-  if (
-    !force &&
-    _cache &&
-    _cache.url === resolvedUrl &&
-    now - _cache.fetchedAt < CACHE_TTL_MS
-  ) {
-    return _cache.data;
-  }
   const fetchFn = fetchImpl || globalThis.fetch;
   if (typeof fetchFn !== 'function') {
     throw new Error('fetch is not available in this runtime');
   }
-  let res;
-  try {
-    res = await fetchFn(resolvedUrl, {
-      headers: { 'User-Agent': 'bizar-registry-client/5.0' },
-    });
-  } catch (err) {
-    const wrap = new Error(
-      `registry fetch failed for ${resolvedUrl}: ${err.message}`,
-    );
-    wrap.code = 'registry_unreachable';
-    wrap.cause = err;
-    throw wrap;
+
+  // Determine which URLs to try: explicit url takes priority, otherwise use all
+  const urls = url ? [url] : getRegistryUrls();
+
+  // Check in-memory cache first (only valid for the first URL in the list)
+  if (!force && _cache && urls.includes(_cache.url)) {
+    if (now - _cache.fetchedAt < CACHE_TTL_MS) {
+      return _cache.data;
+    }
   }
-  if (!res.ok) {
-    const err = new Error(
-      `registry fetch returned ${res.status} ${res.statusText} from ${resolvedUrl}`,
-    );
-    err.code = 'registry_unreachable';
-    err.status = res.status;
-    throw err;
+
+  let lastError;
+  for (const registryUrl of urls) {
+    try {
+      const res = await fetchFn(registryUrl, {
+        headers: { 'User-Agent': 'bizar-registry-client/5.0' },
+      });
+      if (!res.ok) {
+        logger.warn('registry fetch failed, trying next', {
+          url: registryUrl,
+          status: res.status,
+          statusText: res.statusText,
+        });
+        lastError = new Error(
+          `registry fetch returned ${res.status} ${res.statusText} from ${registryUrl}`,
+        );
+        lastError.code = 'registry_unreachable';
+        lastError.status = res.status;
+        continue;
+      }
+      let json;
+      try {
+        json = await res.json();
+      } catch (err) {
+        logger.warn('registry fetch failed, trying next', {
+          url: registryUrl,
+          err: err.message,
+        });
+        lastError = new Error(
+          `registry at ${registryUrl} is not valid JSON: ${err.message}`,
+        );
+        lastError.code = 'invalid_registry';
+        lastError.cause = err;
+        continue;
+      }
+      const validated = validateRegistry(json);
+      _cache = { fetchedAt: now, url: registryUrl, data: validated };
+      writeRegistryCache(validated);
+      return validated;
+    } catch (err) {
+      logger.warn('registry fetch failed, trying next', {
+        url: registryUrl,
+        err: err.message,
+      });
+      lastError = err;
+    }
   }
-  let json;
-  try {
-    json = await res.json();
-  } catch (err) {
-    const wrap = new Error(
-      `registry at ${resolvedUrl} is not valid JSON: ${err.message}`,
-    );
-    wrap.code = 'invalid_registry';
-    wrap.cause = err;
-    throw wrap;
+
+  // All URLs failed — try the on-disk cache as last resort,
+  // but only when no explicit URL was provided (disk cache is not
+  // meaningful when the caller specified a particular endpoint).
+  if (!url) {
+    const cached = await readRegistryCache();
+    if (cached) {
+      logger.warn('all registry URLs failed, using disk cache');
+      _cache = { fetchedAt: now, url: urls[0], data: cached };
+      return cached;
+    }
   }
-  const validated = validateRegistry(json);
-  _cache = { fetchedAt: now, url: resolvedUrl, data: validated };
-  return validated;
+
+  // Nothing worked — throw the last error with a helpful message
+  const wrap = new Error(
+    `registry fetch failed for all URLs. Last error: ${lastError?.message}`,
+  );
+  wrap.code = 'registry_unreachable';
+  wrap.cause = lastError;
+  throw wrap;
 }
 
 /**

package/bizar-dash/src/server/routes/chat.mjs

@@ -24,7 +24,8 @@
 import { Router } from 'express';
 import { SpanStatusCode } from '@opentelemetry/api';
 import { warn as logWarn } from '../logger.mjs';
-import { tracer } from '../otel.mjs';
+import { tracer, withSpan, setCommonAttributes } from '../otel.mjs';
+import { recordTrace } from '../metrics.mjs';
 import {
   existsSync,
   mkdirSync,
@@ -382,15 +383,19 @@ export function createChatRouter({ state, broadcast }) {
     });
   }));
 
-  router.get('/chat/sessions', wrap(async (_req, res) => {
+  router.get('/chat/sessions', wrap(withSpan('chat.sessions.list', async (span, _req, res) => {
     const active = projectsStore.active();
+    setCommonAttributes(span, { userAgent: _req.headers?.['user-agent'] });
+    span.setAttribute('chat.has_active_project', active ? true : false);
     if (!active) {
       res.json({ sessions: [] });
+      recordTrace('chat.sessions.list', { has_active_project: false });
       return;
     }
     const dir = join(projectsStore.ensureProjectDir(active.id), 'sessions');
     if (!existsSync(dir)) {
       res.json({ sessions: [] });
+      recordTrace('chat.sessions.list', { has_active_project: true, sessions_dir_exists: false });
       return;
     }
     const sessions = readdirSync(dir)
@@ -400,13 +405,24 @@ export function createChatRouter({ state, broadcast }) {
         return { id: f.replace(/\.jsonl$/, ''), file: f, mtime: st.mtimeMs, size: st.size };
       });
     sessions.sort((a, b) => b.mtime - a.mtime);
+    span.setAttribute('chat.session_count', sessions.length);
     res.json({ sessions });
-  }));
+    recordTrace('chat.sessions.list', {
+      has_active_project: true,
+      session_count_bucket: sessions.length === 0 ? '0' : sessions.length < 10 ? '1-9' : '10+',
+    });
+  })));
 
-  router.post('/chat/sessions', wrap(async (req, res) => {
+  router.post('/chat/sessions', wrap(withSpan('chat.session.create', async (span, req, res) => {
     const active = projectsStore.active();
+    setCommonAttributes(span, {
+      ip: req.ip || req.socket?.remoteAddress,
+      userAgent: req.headers?.['user-agent'],
+    });
+    span.setAttribute('chat.has_active_project', active ? true : false);
     if (!active) {
       res.status(400).json({ error: 'no_active_project', message: 'No active project. Pick one in Overview first.' });
+      recordTrace('chat.session.create', { outcome: 'no_active_project' });
       return;
     }
     const requestedId = typeof req.body?.id === 'string' ? req.body.id.trim() : '';
@@ -419,6 +435,7 @@ export function createChatRouter({ state, broadcast }) {
     if (!existsSync(file)) {
       writeFileSync(file, '', 'utf8');
     }
+    span.setAttribute('chat.session_id', sessionId);
     state.appendActivity({ kind: 'chat.session.create', id: sessionId });
     broadcast({ type: 'chat:session:create', sessionId });
     res.status(201).json({
@@ -427,29 +444,39 @@ export function createChatRouter({ state, broadcast }) {
       mtime: Date.now(),
       size: 0,
     });
-  }));
+    recordTrace('chat.session.create', { outcome: 'created' });
+  })));
 
-  router.post('/chat/regenerate', wrap(async (req, res) => {
+  router.post('/chat/regenerate', wrap(withSpan('chat.regenerate', async (span, req, res) => {
     const { sessionId, messageId } = req.body || {};
+    setCommonAttributes(span, {
+      ip: req.ip || req.socket?.remoteAddress,
+      userAgent: req.headers?.['user-agent'],
+    });
     if (!messageId) {
       res.status(400).json({ error: 'bad_request', message: 'messageId is required' });
+      recordTrace('chat.regenerate', { outcome: 'missing_message_id' });
       return;
     }
     const active = projectsStore.active();
+    span.setAttribute('chat.has_active_project', active ? true : false);
     if (!active) {
       res.status(400).json({ error: 'no_active_project', message: 'no active project' });
+      recordTrace('chat.regenerate', { outcome: 'no_active_project' });
       return;
     }
     const dir = projectsStore.ensureProjectDir(active.id);
     const sessionsDir = join(dir, 'sessions');
     if (!existsSync(sessionsDir)) {
       res.status(404).json({ error: 'not_found', message: 'no sessions found' });
+      recordTrace('chat.regenerate', { outcome: 'no_sessions' });
       return;
     }
     const allFiles = readdirSync(sessionsDir).filter((f) => f.endsWith('.jsonl'));
     const targetFiles = sessionId ? allFiles.filter((f) => f === `${sessionId}.jsonl`) : allFiles;
     if (!targetFiles.length) {
       res.status(404).json({ error: 'not_found', message: 'session not found' });
+      recordTrace('chat.regenerate', { outcome: 'session_not_found' });
       return;
     }
     const full = join(sessionsDir, targetFiles[0]);
@@ -481,6 +508,7 @@ export function createChatRouter({ state, broadcast }) {
       }
     } catch (err) {
       res.status(500).json({ error: 'read_failed', message: err.message });
+      recordTrace('chat.regenerate', { outcome: 'read_failed' });
       return;
     }
     if (!lastUserMessage) {
@@ -503,6 +531,7 @@ export function createChatRouter({ state, broadcast }) {
     }
     if (!lastUserMessage) {
       res.status(404).json({ error: 'not_found', message: 'no user message found to regenerate' });
+      recordTrace('chat.regenerate', { outcome: 'no_user_message' });
       return;
     }
     const record = {
@@ -520,6 +549,8 @@ export function createChatRouter({ state, broadcast }) {
     } catch {
       /* best effort */
     }
+    span.setAttribute('chat.session_id', sessionId || '');
+    span.setAttribute('chat.regenerate_agent', record.agent || '');
     state.appendActivity({
       kind: 'chat.regenerate',
       agent: lastUserMessage.agent || null,
@@ -527,15 +558,21 @@ export function createChatRouter({ state, broadcast }) {
     });
     broadcast({ type: 'chat:regenerate', message: record });
     res.status(202).json({ accepted: true, regeneratedMessage: record });
-  }));
+    recordTrace('chat.regenerate', { outcome: 'regenerated' });
+  })));
 
-  router.post('/chat/audit', wrap(async (req, res) => {
+  router.post('/chat/audit', wrap(withSpan('chat.audit', async (span, req, res) => {
+    setCommonAttributes(span, {
+      ip: req.ip || req.socket?.remoteAddress,
+      userAgent: req.headers?.['user-agent'],
+    });
     res.json({
       ok: true,
       note: 'audit dispatched — see command.audit in config/opencode.json.template',
       audit: { status: 'queued' },
     });
-  }));
+    recordTrace('chat.audit', { outcome: 'queued' });
+  })));
 
   return router;
 }

package/bizar-dash/src/server/routes/opencode-session-detail.mjs

@@ -54,6 +54,8 @@ import {
   extractContentFromOpencodeMessage,
 } from '../serve-info.mjs';
 import { child as loggerChild } from '../logger.mjs';
+import { tracer, withSpan, setCommonAttributes } from '../otel.mjs';
+import { recordTrace } from '../metrics.mjs';
 import { wrap } from './_shared.mjs';
 
 /** Structured logger scoped to this route — emits `{module:'opencode-session-detail', ...}` on every line. */
@@ -112,28 +114,40 @@ export function createOpencodeSessionDetailRouter() {
   // Returns the message history for a session in the dashboard's
   // ChatMessage shape: { id, role, content, ts }.
   // ---------------------------------------------------------------------
-  router.get('/opencode-sessions/:id/messages', wrap(async (req, res) => {
+  router.get('/opencode-sessions/:id/messages', wrap(withSpan('opencode.session.messages', async (span, req, res) => {
     const sessionId = String(req.params?.id || '');
+    setCommonAttributes(span, {
+      ip: req.ip || req.socket?.remoteAddress,
+      userAgent: req.headers?.['user-agent'],
+    });
+    span.setAttribute('opencode.session_id', sessionId);
     if (!sessionId) {
-      return res.status(400).json({ error: 'bad_request', message: 'session id is required' });
+      res.status(400).json({ error: 'bad_request', message: 'session id is required' });
+      recordTrace('opencode.session.messages', { outcome: 'missing_session_id' });
+      return;
     }
     const info = readServeInfo();
     if (!info) {
-      return res.status(503).json({
+      res.status(503).json({
         error: 'plugin_offline',
         message: 'opencode plugin is not running',
         suggestion: 'Run `bizar doctor` for diagnostics, or start opencode with `opencode serve`',
       });
+      recordTrace('opencode.session.messages', { outcome: 'plugin_offline' });
+      return;
     }
     const directory = await resolveSessionDirectory(sessionId, info);
     if (!directory) {
-      return res.status(503).json({
+      res.status(503).json({
         error: 'directory_unknown',
         message:
           'Cannot determine the opencode session directory; ensure the opencode plugin is running with serve.json containing worktree.',
         suggestion: 'Create a new session or restart opencode serve.',
       });
+      recordTrace('opencode.session.messages', { outcome: 'directory_unknown' });
+      return;
     }
+    span.setAttribute('opencode.worktree', directory);
     const result = await listOpencodeMessages(info, sessionId, directory, LIST_MESSAGES_TIMEOUT_MS);
     if (!result?.ok) {
       const errMsg = result?.error || 'unknown error from opencode serve';
@@ -154,17 +168,23 @@ export function createOpencodeSessionDetailRouter() {
         cause,
         err: errMsg,
       });
-      return res.status(502).json({
+      span.setAttribute('opencode.error_cause', cause);
+      span.setAttribute('opencode.upstream_status', result?.status ?? 0);
+      res.status(502).json({
         error: 'opencode_error',
         message: errMsg,
         cause,
         status: result?.status ?? undefined,
         suggestion: 'Check that the opencode serve child is running. Try `bizar doctor` or restart the plugin.',
       });
+      recordTrace('opencode.session.messages', { outcome: 'opencode_error', cause });
+      return;
     }
     const messages = Array.isArray(result.messages) ? result.messages.map(toChatMessage) : [];
-    return res.json({ messages });
-  }));
+    span.setAttribute('opencode.message_count', messages.length);
+    res.json({ messages });
+    recordTrace('opencode.session.messages', { outcome: 'ok', message_count_bucket: messages.length === 0 ? '0' : messages.length < 50 ? '1-49' : '50+' });
+  })));
 
   // ---------------------------------------------------------------------
   // POST /opencode-sessions/:id/send
@@ -172,40 +192,59 @@ export function createOpencodeSessionDetailRouter() {
   // Body: { message: string, agent: string } — both required.
   // Returns { ok: true, messageId } or an error envelope.
   // ---------------------------------------------------------------------
-  router.post('/opencode-sessions/:id/send', wrap(async (req, res) => {
+  router.post('/opencode-sessions/:id/send', wrap(withSpan('opencode.session.send', async (span, req, res) => {
     const sessionId = String(req.params?.id || '');
+    setCommonAttributes(span, {
+      ip: req.ip || req.socket?.remoteAddress,
+      userAgent: req.headers?.['user-agent'],
+    });
+    span.setAttribute('opencode.session_id', sessionId);
     if (!sessionId) {
-      return res.status(400).json({ error: 'bad_request', message: 'session id is required' });
+      res.status(400).json({ error: 'bad_request', message: 'session id is required' });
+      recordTrace('opencode.session.send', { outcome: 'missing_session_id' });
+      return;
     }
     const body = req.body && typeof req.body === 'object' ? req.body : {};
     const message = typeof body.message === 'string' ? body.message.trim() : '';
     const agent = typeof body.agent === 'string' ? body.agent.trim() : '';
+    span.setAttribute('opencode.message_length', message.length);
+    if (agent) span.setAttribute('opencode.agent', agent);
     if (!message) {
-      return res.status(400).json({ error: 'bad_request', message: '`message` is required' });
+      res.status(400).json({ error: 'bad_request', message: '`message` is required' });
+      recordTrace('opencode.session.send', { outcome: 'missing_message' });
+      return;
     }
     if (!agent) {
-      return res.status(400).json({ error: 'bad_request', message: '`agent` is required' });
+      res.status(400).json({ error: 'bad_request', message: '`agent` is required' });
+      recordTrace('opencode.session.send', { outcome: 'missing_agent' });
+      return;
     }
     const info = readServeInfo();
     if (!info) {
-      return res.status(503).json({
+      res.status(503).json({
         error: 'plugin_offline',
         message: 'opencode plugin is not running',
         suggestion: 'Run `bizar doctor` for diagnostics, or start opencode with `opencode serve`',
       });
+      recordTrace('opencode.session.send', { outcome: 'plugin_offline' });
+      return;
     }
     const directory = await resolveSessionDirectory(sessionId, info);
     if (!directory) {
-      return res.status(503).json({
+      res.status(503).json({
         error: 'directory_unknown',
         message:
           'Cannot determine the opencode session directory; ensure the opencode plugin is running with serve.json containing worktree.',
         suggestion: 'Create a new session or restart opencode serve.',
       });
+      recordTrace('opencode.session.send', { outcome: 'directory_unknown' });
+      return;
     }
+    span.setAttribute('opencode.worktree', directory);
     // Synthesize a unique messageID so the client can correlate the
     // prompt with the SSE events that opencode emits for it.
     const messageID = `msg_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+    span.setAttribute('opencode.message_id', messageID);
     const result = await sendOpencodePrompt(
       info,
       { sessionId, agent, text: message, messageID },
@@ -227,16 +266,21 @@ export function createOpencodeSessionDetailRouter() {
         cause,
         err: errMsg,
       });
-      return res.status(502).json({
+      span.setAttribute('opencode.error_cause', cause);
+      res.status(502).json({
         error: 'opencode_error',
         message: errMsg,
         cause,
         status: result?.status ?? undefined,
         suggestion: 'Check that the opencode serve child is running. Try `bizar doctor` or restart the plugin.',
       });
+      recordTrace('opencode.session.send', { outcome: 'opencode_error', cause });
+      return;
     }
-    return res.json({ ok: true, messageId: result.messageId });
-  }));
+    span.setAttribute('opencode.ack_message_id', result.messageId || '');
+    res.json({ ok: true, messageId: result.messageId });
+    recordTrace('opencode.session.send', { outcome: 'ok' });
+  })));
 
   // ---------------------------------------------------------------------
   // GET /opencode-sessions/:id/stream  (SSE proxy)
@@ -253,10 +297,42 @@ export function createOpencodeSessionDetailRouter() {
   //     is ported to serve-info.mjs (`unwrapOpencodeSseEvent`).
   //   - We DO mirror the response shape used by `routes-v2/events.mjs`:
   //     `event: <type>\ndata: <json>\n\n`.
+  //   - v5.1.0 — span lifecycle is manual (`startSpan` + `span.end()`)
+  //     because the response is a long-lived stream. Using `withSpan`
+  //     would end the span the instant the handler returned, well
+  //     before the actual SSE close. We pin the same tracer for
+  //     consistency with the rest of this module.
   // ---------------------------------------------------------------------
   router.get('/opencode-sessions/:id/stream', (req, res) => {
     const sessionId = String(req.params?.id || '');
+    const span = tracer.startSpan('opencode.session.stream', {
+      attributes: {
+        'opencode.session_id': sessionId,
+        'http.client_ip': req.ip || req.socket?.remoteAddress || '',
+        'http.user_agent': (req.headers && req.headers['user-agent']) || '',
+      },
+    });
+    let spanEnded = false;
+    const endSpan = (extraAttrs) => {
+      if (spanEnded) return;
+      spanEnded = true;
+      try {
+        if (extraAttrs && typeof extraAttrs === 'object') {
+          for (const [k, v] of Object.entries(extraAttrs)) {
+            try { span.setAttribute(k, v); } catch { /* ignore */ }
+          }
+        }
+        span.setStatus({ code: 1 /* OK */ });
+        span.end();
+      } catch {
+        /* never throw from OTel helper */
+      }
+    };
     if (!sessionId) {
+      try {
+        span.setStatus({ code: 2 /* ERROR */, message: 'missing_session_id' });
+        span.end();
+      } catch { /* ignore */ }
       return res.status(400).json({ error: 'bad_request', message: 'session id is required' });
     }
     if (activeSubscribers >= MAX_SSE_SUBSCRIBERS) {
@@ -264,6 +340,12 @@ export function createOpencodeSessionDetailRouter() {
         error: 'too_many_subscribers',
         message: `SSE subscriber cap reached (${MAX_SSE_SUBSCRIBERS}); try again later.`,
       });
+      try {
+        span.setAttribute('opencode.stream.outcome', 'too_many_subscribers');
+        span.setStatus({ code: 2 /* ERROR */, message: 'too_many_subscribers' });
+        span.end();
+      } catch { /* ignore */ }
+      recordTrace('opencode.session.stream', { outcome: 'too_many_subscribers' });
       return;
     }
 
@@ -280,10 +362,13 @@ export function createOpencodeSessionDetailRouter() {
     if (!info) {
       res.write(`event: error\ndata: ${JSON.stringify({ error: 'plugin_offline' })}\n\n`);
       res.end();
+      endSpan({ 'opencode.stream.outcome': 'plugin_offline' });
+      recordTrace('opencode.session.stream', { outcome: 'plugin_offline' });
       return;
     }
 
     activeSubscribers += 1;
+    span.setAttribute('opencode.stream.active_subscribers', activeSubscribers);
 
     // Upstream fetch + line-buffered SSE parser. Aborted on client
     // disconnect or when the upstream closes.
@@ -300,6 +385,7 @@ export function createOpencodeSessionDetailRouter() {
       }
     }, getSseHeartbeatMs());
     let closed = false;
+    const startTs = Date.now();
     const cleanup = () => {
       if (closed) return;
       closed = true;
@@ -309,8 +395,21 @@ export function createOpencodeSessionDetailRouter() {
       if (!res.writableEnded) {
         try { res.end(); } catch { /* ignore */ }
       }
+      const lifetimeMs = Date.now() - startTs;
+      endSpan({
+        'opencode.stream.outcome': closedReason || 'closed',
+        'opencode.stream.lifetime_ms': lifetimeMs,
+      });
+      recordTrace('opencode.session.stream', {
+        outcome: closedReason || 'closed',
+        lifetime_bucket: lifetimeMs < 1_000 ? '<1s' : lifetimeMs < 60_000 ? '<60s' : '60s+',
+      });
     };
-    req.on('close', cleanup);
+    let closedReason = 'client_closed';
+    req.on('close', () => {
+      closedReason = 'client_closed';
+      cleanup();
+    });
 
     const upstreamUrl = `${info.baseUrl}/event?directory=${encodeURIComponent(info.worktree || '')}`;
     let upstream;
@@ -326,6 +425,7 @@ export function createOpencodeSessionDetailRouter() {
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       res.write(`event: error\ndata: ${JSON.stringify({ error: 'upstream_open_failed', message: msg })}\n\n`);
+      closedReason = 'upstream_open_failed';
       cleanup();
       return;
     }
@@ -338,10 +438,12 @@ export function createOpencodeSessionDetailRouter() {
             error: 'upstream_status',
             status: r.status,
           })}\n\n`);
+          closedReason = 'upstream_bad_status';
           cleanup();
           return;
         }
         await pumpSseStream(r.body, res, sessionId);
+        closedReason = 'upstream_eof';
       } catch (err) {
         if (controller.signal.aborted) return; // client disconnected, already cleaned up
         const msg = err instanceof Error ? err.message : String(err);
@@ -350,6 +452,7 @@ export function createOpencodeSessionDetailRouter() {
             res.write(`event: error\ndata: ${JSON.stringify({ error: 'upstream_read_error', message: msg })}\n\n`);
           } catch { /* ignore */ }
         }
+        closedReason = 'upstream_read_error';
       } finally {
         cleanup();
       }