@polderlabs/bizar 4.4.13 → 4.5.0

package/bizar-dash/tests/chat-session-create.test.mjs

@@ -0,0 +1,391 @@
+/**
+ * tests/chat-session-create.test.mjs — v4.2.5
+ *
+ * Tests the session-mutation endpoints on the opencode-sessions router:
+ *
+ *   POST   /api/opencode-sessions/new
+ *   PATCH  /api/opencode-sessions/:id
+ *   DELETE /api/opencode-sessions/:id
+ *
+ * Strategy: stand up a fake opencode serve child on a random port,
+ * point readServeInfo() at it by writing a tmp serve.json to
+ * ~/.cache/bizar/serve.json. The fake serves:
+ *
+ *   POST   /api/session?directory=...   → returns { data: { id, ... } }
+ *   PATCH  /api/session/:id?directory=. → echoes the body as { id }
+ *   DELETE /api/session/:id?directory=. → returns 200 or 404
+ *
+ * For "plugin offline" tests we move serve.json aside, then restore.
+ */
+
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync,
+  writeFileSync,
+  rmSync,
+  existsSync,
+  copyFileSync,
+  unlinkSync,
+  readFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createServer } from 'node:http';
+import express from 'express';
+
+import { createOpencodeSessionsRouter } from '../src/server/routes/opencode-sessions.mjs';
+
+// ── fake upstream (opencode serve child) ──────────────────────────────────
+
+let upstreamServer, upstreamPort;
+const upstream = {
+  createHits: [],
+  patchHits: [],
+  deleteHits: [],
+  nextCreateStatus: 200,
+  nextCreateId: null,
+  // Behavior knobs tests can flip:
+  failNextCreate: false,
+};
+
+function startUpstream() {
+  return new Promise((resolve) => {
+    upstreamServer = createServer((req, res) => {
+      const url = new URL(req.url, 'http://127.0.0.1');
+
+      // CREATE: POST /api/session?directory=...
+      if (
+        url.pathname === '/api/session' &&
+        req.method === 'POST'
+      ) {
+        let body = '';
+        req.on('data', (c) => {
+          body += c;
+        });
+        req.on('end', () => {
+          let parsed;
+          try { parsed = JSON.parse(body); } catch { parsed = {}; }
+          upstream.createHits.push({ url: req.url, body: parsed });
+          if (upstream.failNextCreate) {
+            upstream.failNextCreate = false;
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'fake-upstream-failure' }));
+            return;
+          }
+          res.writeHead(upstream.nextCreateStatus, {
+            'Content-Type': 'application/json',
+          });
+          const id =
+            upstream.nextCreateId ||
+            `sess-new-${upstream.createHits.length}`;
+          upstream.nextCreateId = null;
+          res.end(JSON.stringify({ data: { id, title: parsed.title, agent: parsed.agent } }));
+        });
+        return;
+      }
+
+      // RENAME: PATCH /api/session/:id?directory=...
+      const patchM = url.pathname.match(/^\/api\/session\/([^/]+)$/);
+      if (patchM && req.method === 'PATCH') {
+        let body = '';
+        req.on('data', (c) => {
+          body += c;
+        });
+        req.on('end', () => {
+          let parsed;
+          try { parsed = JSON.parse(body); } catch { parsed = {}; }
+          upstream.patchHits.push({ id: patchM[1], url: req.url, body: parsed });
+          if (patchM[1] === 'sess-missing') {
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'not found' }));
+            return;
+          }
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ id: patchM[1], title: parsed.title }));
+        });
+        return;
+      }
+
+      // DELETE: DELETE /api/session/:id?directory=...
+      const deleteM = url.pathname.match(/^\/api\/session\/([^/]+)$/);
+      if (deleteM && req.method === 'DELETE') {
+        upstream.deleteHits.push({ id: deleteM[1], url: req.url });
+        if (deleteM[1] === 'sess-gone') {
+          res.writeHead(404, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'gone' }));
+          return;
+        }
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ id: deleteM[1] }));
+        return;
+      }
+
+      res.writeHead(404);
+      res.end('not found');
+    });
+    upstreamServer.listen(0, '127.0.0.1', () => {
+      upstreamPort = upstreamServer.address().port;
+      resolve();
+    });
+  });
+}
+
+async function startDashboard() {
+  const app = express();
+  app.use(express.json({ limit: '2mb' }));
+  app.use('/api', createOpencodeSessionsRouter());
+  dashboardServer = createServer(app);
+  await new Promise((r) => dashboardServer.listen(0, '127.0.0.1', r));
+  dashboardBaseUrl = `http://127.0.0.1:${dashboardServer.address().port}`;
+}
+
+let dashboardServer, dashboardBaseUrl, tmpDir;
+let SERVE_JSON_PATH;
+let originalServeJson;
+
+before(async () => {
+  SERVE_JSON_PATH = `${tmpdir()}/bizar-test-serve-create-${process.pid}-${Date.now()}.json`;
+  process.env.BIZAR_SERVE_JSON_PATH = SERVE_JSON_PATH;
+  await startUpstream();
+  await startDashboard();
+  tmpDir = mkdtempSync(join(tmpdir(), 'opencode-sessions-create-'));
+  if (existsSync(SERVE_JSON_PATH)) {
+    originalServeJson = readFileSync(SERVE_JSON_PATH, 'utf8');
+  }
+});
+
+after(async () => {
+  if (originalServeJson !== undefined) {
+    writeFileSync(SERVE_JSON_PATH, originalServeJson, 'utf8');
+  } else if (existsSync(SERVE_JSON_PATH)) {
+    rmSync(SERVE_JSON_PATH);
+  }
+  if (dashboardServer) await new Promise((r) => dashboardServer.close(r));
+  if (upstreamServer) await new Promise((r) => upstreamServer.close(r));
+  if (tmpDir) rmSync(tmpDir, { recursive: true, force: true });
+  delete process.env.BIZAR_SERVE_JSON_PATH;
+});
+
+beforeEach(() => {
+  upstream.createHits = [];
+  upstream.patchHits = [];
+  upstream.deleteHits = [];
+  upstream.nextCreateStatus = 200;
+  upstream.nextCreateId = null;
+  upstream.failNextCreate = false;
+});
+
+function writeServeJson(worktree = '/tmp/new-session-worktree') {
+  writeFileSync(
+    SERVE_JSON_PATH,
+    JSON.stringify({
+      port: upstreamPort,
+      password: 'test-pw',
+      worktree,
+      pid: 99999,
+      startedAt: Date.now(),
+    }),
+    'utf8',
+  );
+}
+
+/** Move serve.json aside so readServeInfo() returns null.
+ *  Uses copy + unlink because rename across filesystems (e.g.
+ *  /home/* → /tmp/*) throws EXDEV on Linux. */
+function moveServeJsonAside() {
+  if (!existsSync(SERVE_JSON_PATH)) return;
+  const tmp = join(tmpDir, `serve-aside-${Date.now()}-${process.pid}.json`);
+  copyFileSync(SERVE_JSON_PATH, tmp);
+  unlinkSync(SERVE_JSON_PATH);
+}
+
+// ── tests ─────────────────────────────────────────────────────────────────
+
+test('POST /api/opencode-sessions/new returns 201 with id+title+agent on happy path', async () => {
+  writeServeJson();
+  upstream.nextCreateId = 'sess-fresh-1';
+  const r = await fetch(`${dashboardBaseUrl}/api/opencode-sessions/new`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ title: 'Hello world', agent: 'odin' }),
+  });
+  assert.equal(r.status, 201);
+  const body = await r.json();
+  assert.equal(body.id, 'sess-fresh-1');
+  assert.equal(body.title, 'Hello world');
+  assert.equal(body.agent, 'odin');
+  assert.ok(typeof body.directory === 'string' && body.directory.length > 0);
+  assert.ok(typeof body.createdAt === 'number' && body.createdAt > 0);
+  assert.equal(upstream.createHits.length, 1);
+  assert.equal(upstream.createHits[0].body.title, 'Hello world');
+  assert.equal(upstream.createHits[0].body.agent, 'odin');
+});
+
+test('POST /api/opencode-sessions/new returns 400 when body is missing', async () => {
+  writeServeJson();
+  const r = await fetch(`${dashboardBaseUrl}/api/opencode-sessions/new`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+  });
+  assert.equal(r.status, 400);
+  const body = await r.json();
+  assert.match(body.message, /agent.*required/i);
+});
+
+test('POST /api/opencode-sessions/new returns 400 when agent missing', async () => {
+  writeServeJson();
+  const r = await fetch(`${dashboardBaseUrl}/api/opencode-sessions/new`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ title: 'no-agent' }),
+  });
+  assert.equal(r.status, 400);
+});
+
+test('POST /api/opencode-sessions/new returns 400 when agent is invalid', async () => {
+  writeServeJson();
+  const r = await fetch(`${dashboardBaseUrl}/api/opencode-sessions/new`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ agent: 'has space and !' }),
+  });
+  assert.equal(r.status, 400);
+});
+
+test('POST /api/opencode-sessions/new returns 502 when upstream 500s', async () => {
+  writeServeJson();
+  upstream.failNextCreate = true;
+  const r = await fetch(`${dashboardBaseUrl}/api/opencode-sessions/new`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ agent: 'odin' }),
+  });
+  assert.equal(r.status, 502);
+  const body = await r.json();
+  assert.equal(body.error, 'opencode_error');
+  assert.ok(body.message.length > 0);
+});
+
+test('POST /api/opencode-sessions/new returns 503 plugin_offline when no serve.json', async () => {
+  moveServeJsonAside();
+  try {
+    const r = await fetch(`${dashboardBaseUrl}/api/opencode-sessions/new`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ agent: 'odin' }),
+    });
+    assert.equal(r.status, 503);
+    assert.equal((await r.json()).error, 'plugin_offline');
+  } finally {
+    if (originalServeJson !== undefined)
+      writeFileSync(SERVE_JSON_PATH, originalServeJson, 'utf8');
+    else writeServeJson('/tmp/session-worktree');
+  }
+});
+
+test('POST /api/opencode-sessions/new defaults title to "Chat: <agent>"', async () => {
+  writeServeJson();
+  upstream.nextCreateId = 'sess-defaulted-1';
+  const r = await fetch(`${dashboardBaseUrl}/api/opencode-sessions/new`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ agent: 'tyr' }),
+  });
+  assert.equal(r.status, 201);
+  const body = await r.json();
+  assert.equal(body.title, 'Chat: tyr');
+  assert.equal(upstream.createHits[0].body.title, 'Chat: tyr');
+});
+
+test('PATCH /api/opencode-sessions/:id renames the session (200)', async () => {
+  writeServeJson();
+  const r = await fetch(
+    `${dashboardBaseUrl}/api/opencode-sessions/sess-1`,
+    {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title: 'New title' }),
+    },
+  );
+  assert.equal(r.status, 200);
+  const body = await r.json();
+  assert.equal(body.id, 'sess-1');
+  assert.equal(body.title, 'New title');
+  assert.equal(upstream.patchHits.length, 1);
+  assert.equal(upstream.patchHits[0].body.title, 'New title');
+});
+
+test('PATCH /api/opencode-sessions/:id returns 400 when title missing', async () => {
+  writeServeJson();
+  const r = await fetch(
+    `${dashboardBaseUrl}/api/opencode-sessions/sess-1`,
+    {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+    },
+  );
+  assert.equal(r.status, 400);
+});
+
+test('PATCH /api/opencode-sessions/:id returns 400 when title is empty', async () => {
+  writeServeJson();
+  const r = await fetch(
+    `${dashboardBaseUrl}/api/opencode-sessions/sess-1`,
+    {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title: '   ' }),
+    },
+  );
+  assert.equal(r.status, 400);
+});
+
+test('PATCH /api/opencode-sessions/:id returns 404 when upstream 404s', async () => {
+  writeServeJson();
+  const r = await fetch(
+    `${dashboardBaseUrl}/api/opencode-sessions/sess-missing`,
+    {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title: 'whatever' }),
+    },
+  );
+  assert.equal(r.status, 404);
+});
+
+test('DELETE /api/opencode-sessions/:id returns 200 with { deleted: true }', async () => {
+  writeServeJson();
+  const r = await fetch(
+    `${dashboardBaseUrl}/api/opencode-sessions/sess-1`,
+    { method: 'DELETE' },
+  );
+  assert.equal(r.status, 200);
+  const body = await r.json();
+  assert.deepEqual(body, { id: 'sess-1', deleted: true });
+  assert.equal(upstream.deleteHits.length, 1);
+});
+
+test('DELETE /api/opencode-sessions/:id is idempotent (returns 200 even when upstream 404s)', async () => {
+  // Idempotent semantics: a "session already gone" response is the
+  // desired terminal state — we don't surface that to the client as
+  // an error.
+  writeServeJson();
+  const r = await fetch(
+    `${dashboardBaseUrl}/api/opencode-sessions/sess-gone`,
+    { method: 'DELETE' },
+  );
+  assert.equal(r.status, 200);
+  const body = await r.json();
+  assert.deepEqual(body, { id: 'sess-gone', deleted: true });
+});
+
+test('DELETE /api/opencode-sessions/:id returns 400 when id is invalid', async () => {
+  writeServeJson();
+  const r = await fetch(
+    `${dashboardBaseUrl}/api/opencode-sessions/has space`,
+    { method: 'DELETE' },
+  );
+  assert.equal(r.status, 400);
+});

package/bizar-dash/tests/chat-session-stream.test.mjs

@@ -0,0 +1,308 @@
+/**
+ * tests/chat-session-stream.test.mjs — v4.2.5
+ *
+ * End-to-end tests for the opencode SSE streaming endpoints. The
+ * opencode-session-detail router proxies the upstream
+ * `/event?directory=...` stream and forwards one canonical
+ * envelope per upstream event, filtered by `sessionID`.
+ *
+ * Tests cover three guarantees:
+ *
+ *   1. `message.updated` events for the right session are forwarded,
+ *      and events for other sessions are dropped.
+ *   2. Sync envelopes (the v2 wire format) are unwrapped: the inner
+ *      `syncEvent.type` with version suffix (`.<n>`) becomes the
+ *      canonical event name on the dashboard-side SSE stream.
+ *   3. The proxy emits a heartbeat (`: keepalive`) within the
+ *      configured SSE_HEARTBEAT_MS (default 25s — we set it to 250ms
+ *      via env override so the test runs in well under a second).
+ *
+ * Strategy: stand up a fake opencode serve child on a random port,
+ * point readServeInfo() at it. The fake emits three events then
+ * holds the connection open long enough for the heartbeat to land.
+ */
+
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync,
+  writeFileSync,
+  rmSync,
+  existsSync,
+  copyFileSync,
+  unlinkSync,
+  readFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createServer } from 'node:http';
+import express from 'express';
+
+import { createOpencodeSessionDetailRouter } from '../src/server/routes/opencode-session-detail.mjs';
+
+// ── fake upstream ─────────────────────────────────────────────────────────
+
+let upstreamServer, upstreamPort;
+const upstream = {
+  streamChunks: [],
+  /** When non-null, hold the SSE connection open this many ms before
+   *  ending it. The heartbeat test uses this. */
+  holdMs: 0,
+};
+
+function startUpstream() {
+  return new Promise((resolve) => {
+    upstreamServer = createServer((req, res) => {
+      const url = new URL(req.url, 'http://127.0.0.1');
+      if (url.pathname === '/event') {
+        res.writeHead(200, {
+          'Content-Type': 'text/event-stream',
+          'Cache-Control': 'no-cache',
+          Connection: 'keep-alive',
+        });
+        for (const c of upstream.streamChunks) res.write(c);
+        const hold = upstream.holdMs;
+        setTimeout(() => res.end(), hold);
+        return;
+      }
+      res.writeHead(404);
+      res.end('not found');
+    });
+    upstreamServer.listen(0, '127.0.0.1', () => {
+      upstreamPort = upstreamServer.address().port;
+      resolve();
+    });
+  });
+}
+
+async function startDashboard() {
+  const app = express();
+  app.use(express.json({ limit: '2mb' }));
+  app.use('/api', createOpencodeSessionDetailRouter());
+  dashboardServer = createServer(app);
+  await new Promise((r) => dashboardServer.listen(0, '127.0.0.1', r));
+  dashboardBaseUrl = `http://127.0.0.1:${dashboardServer.address().port}`;
+}
+
+let dashboardServer, dashboardBaseUrl, tmpDir;
+let SERVE_JSON_PATH;
+let originalServeJson;
+
+before(async () => {
+  // Shrink the SSE heartbeat from 25s → 250ms so the heartbeat test
+  // actually exercises the path within the test runner's timeout.
+  process.env.BIZAR_SSE_HEARTBEAT_MS = '250';
+  // Use a per-PID isolated serve.json path so multiple test files
+  // don't contaminate each other.
+  SERVE_JSON_PATH = `${tmpdir()}/bizar-test-serve-stream-${process.pid}-${Date.now()}.json`;
+  process.env.BIZAR_SERVE_JSON_PATH = SERVE_JSON_PATH;
+  await startUpstream();
+  await startDashboard();
+  tmpDir = mkdtempSync(join(tmpdir(), 'opencode-stream-'));
+  if (existsSync(SERVE_JSON_PATH)) {
+    originalServeJson = readFileSync(SERVE_JSON_PATH, 'utf8');
+  }
+});
+
+after(async () => {
+  if (originalServeJson !== undefined) {
+    writeFileSync(SERVE_JSON_PATH, originalServeJson, 'utf8');
+  } else if (existsSync(SERVE_JSON_PATH)) {
+    rmSync(SERVE_JSON_PATH);
+  }
+  if (dashboardServer) await new Promise((r) => dashboardServer.close(r));
+  if (upstreamServer) await new Promise((r) => upstreamServer.close(r));
+  if (tmpDir) rmSync(tmpDir, { recursive: true, force: true });
+  delete process.env.BIZAR_SSE_HEARTBEAT_MS;
+  delete process.env.BIZAR_SERVE_JSON_PATH;
+});
+
+beforeEach(() => {
+  upstream.streamChunks = [];
+  upstream.holdMs = 0;
+});
+
+function writeServeJson() {
+  writeFileSync(
+    SERVE_JSON_PATH,
+    JSON.stringify({
+      port: upstreamPort,
+      password: 'test-pw',
+      worktree: '/tmp/stream-worktree',
+      pid: 99999,
+      startedAt: Date.now(),
+    }),
+    'utf8',
+  );
+}
+
+function moveServeJsonAside() {
+  if (!existsSync(SERVE_JSON_PATH)) return;
+  const tmp = join(tmpDir, `serve-aside-${Date.now()}-${process.pid}.json`);
+  copyFileSync(SERVE_JSON_PATH, tmp);
+  unlinkSync(SERVE_JSON_PATH);
+}
+
+function parseSseStream(text) {
+  const out = [];
+  let event = null, dataLines = [];
+  for (const line of text.split(/\r?\n/)) {
+    if (line === '') {
+      if (event !== null || dataLines.length > 0) {
+        out.push({ event, data: dataLines.join('\n') });
+      }
+      event = null; dataLines = [];
+      continue;
+    }
+    if (line.startsWith(':')) continue;
+    const colon = line.indexOf(':');
+    if (colon < 0) continue;
+    const field = line.slice(0, colon);
+    let value = line.slice(colon + 1);
+    if (value.startsWith(' ')) value = value.slice(1);
+    if (field === 'event') event = value;
+    else if (field === 'data') dataLines.push(value);
+  }
+  return out;
+}
+
+// ── tests ─────────────────────────────────────────────────────────────────
+
+test('SSE forwards message.updated for the requested session, drops others', async () => {
+  writeServeJson();
+  upstream.streamChunks = [
+    // Direct envelope (older wire format). properties.sessionID.
+    'event: message.updated\ndata: {"type":"message.updated","properties":{"sessionID":"our-id","messageID":"m1"}}\n\n',
+    // Wrong session: must be filtered.
+    'event: message.updated\ndata: {"type":"message.updated","properties":{"sessionID":"OTHER-id","messageID":"m9"}}\n\n',
+    // Sync envelope (newer wire format).
+    'event: sync\ndata: {"type":"sync","syncEvent":{"type":"message.updated.1","data":{"sessionID":"our-id","messageID":"m3"}}}\n\n',
+  ];
+  const res = await fetch(
+    `${dashboardBaseUrl}/api/opencode-sessions/our-id/stream`,
+  );
+  assert.equal(res.status, 200);
+  assert.match(res.headers.get('content-type'), /text\/event-stream/);
+  assert.match(res.headers.get('cache-control'), /no-cache/);
+  assert.equal(res.headers.get('x-accel-buffering'), 'no');
+
+  const events = parseSseStream(await res.text());
+  // 1: message.updated (our-id)
+  // 2: message.updated from sync envelope (our-id)
+  // The OTHER-id message.updated is dropped.
+  assert.equal(events.length, 2);
+  assert.equal(events[0].event, 'message.updated');
+  const d0 = JSON.parse(events[0].data);
+  assert.equal(d0.sessionID, 'our-id');
+  assert.equal(d0.messageID, 'm1');
+  assert.equal(events[1].event, 'message.updated');
+  const d1 = JSON.parse(events[1].data);
+  assert.equal(d1.sessionID, 'our-id');
+  assert.equal(d1.messageID, 'm3');
+});
+
+test('SSE unwraps sync envelopes and strips the version suffix from the event name', async () => {
+  writeServeJson();
+  upstream.streamChunks = [
+    'event: sync\ndata: {"type":"sync","syncEvent":{"type":"session.idle.1","data":{"sessionID":"our-id"}}}\n\n',
+  ];
+  const res = await fetch(
+    `${dashboardBaseUrl}/api/opencode-sessions/our-id/stream`,
+  );
+  assert.equal(res.status, 200);
+  const events = parseSseStream(await res.text());
+  assert.equal(events.length, 1);
+  assert.equal(events[0].event, 'session.idle');
+  const d = JSON.parse(events[0].data);
+  assert.equal(d.sessionID, 'our-id');
+});
+
+test('SSE does NOT emit redundant chat:delta / chat:status aliases (only canonical events)', async () => {
+  // v4.2.5 fix: prior version emitted chat:delta/chat:status aliases
+  // in ADDITION to the canonical event, causing downstream listeners
+  // to see each idle/delta event twice. The proxy now emits one
+  // canonical envelope per upstream event — no aliases.
+  writeServeJson();
+  upstream.streamChunks = [
+    'event: message.part.updated\ndata: {"type":"message.part.updated.1","properties":{"sessionID":"our-id","messageID":"m1","part":{"type":"text","text":"hello"}}}\n\n',
+    'event: sync\ndata: {"type":"sync","syncEvent":{"type":"session.idle.1","data":{"sessionID":"our-id"}}}\n\n',
+  ];
+  const res = await fetch(
+    `${dashboardBaseUrl}/api/opencode-sessions/our-id/stream`,
+  );
+  const events = parseSseStream(await res.text());
+  // Only 2 events expected — one part.updated and one session.idle.
+  // We do NOT want chat:delta or chat:status emitted here.
+  assert.equal(events.length, 2);
+  const evNames = events.map((e) => e.event);
+  assert.ok(evNames.includes('message.part.updated'));
+  assert.ok(evNames.includes('session.idle'));
+  assert.equal(evNames.filter((n) => n === 'chat:status').length, 0);
+  assert.equal(evNames.filter((n) => n === 'chat:delta').length, 0);
+});
+
+test('SSE emits a heartbeat (": keepalive") within BIZAR_SSE_HEARTBEAT_MS', async () => {
+  // Override forces a 250ms heartbeat (set in `before`). We hold
+  // the upstream connection open for 600ms so the heartbeat fires
+  // at least once after the initial chunks land.
+  writeServeJson();
+  upstream.holdMs = 600;
+  upstream.streamChunks = [
+    'event: message.updated\ndata: {"type":"message.updated","properties":{"sessionID":"our-id","messageID":"m1"}}\n\n',
+  ];
+  const t0 = Date.now();
+  const res = await fetch(
+    `${dashboardBaseUrl}/api/opencode-sessions/our-id/stream`,
+  );
+  const text = await res.text();
+  const elapsed = Date.now() - t0;
+  // Body should be at least one blank line-separated chunk containing
+  // a `: keepalive` heartbeat comment. We assert the raw body has
+  // `: keepalive` somewhere and the total wait was longer than the
+  // heartbeat interval (250ms).
+  assert.ok(
+    text.includes(': keepalive'),
+    `expected ": keepalive" in body — got: ${text.slice(0, 500)}`,
+  );
+  assert.ok(elapsed >= 250, `expected >= 250ms elapsed, got ${elapsed}ms`);
+});
+
+test('SSE returns the response in <50ms when upstream immediately errors (plugin offline)', async () => {
+  // Move serve.json aside so the proxy sees `plugin_offline`.
+  moveServeJsonAside();
+  try {
+    const t0 = Date.now();
+    const res = await fetch(
+      `${dashboardBaseUrl}/api/opencode-sessions/our-id/stream`,
+    );
+    const elapsed = Date.now() - t0;
+    assert.equal(res.status, 200);
+    assert.match(res.headers.get('content-type'), /text\/event-stream/);
+    const text = await res.text();
+    assert.ok(text.includes('plugin_offline'));
+    assert.ok(elapsed < 200, `expected < 200ms, got ${elapsed}ms`);
+  } finally {
+    if (originalServeJson !== undefined) {
+      writeFileSync(SERVE_JSON_PATH, originalServeJson, 'utf8');
+    } else {
+      writeServeJson();
+    }
+  }
+});
+
+test('SSE handles whitespace-only session id gracefully (no 500 crash)', async () => {
+  writeServeJson();
+  // Whitespace session id: server resolves `decodeURIComponent('%20')`
+  // to a single space, which is non-empty; the proxy tries to filter
+  // events and never matches → empty stream, but never 5xx.
+  const res = await fetch(
+    `${dashboardBaseUrl}/api/opencode-sessions/%20/stream`,
+  );
+  // The handler may return 200 (empty stream) or 503 (directory
+  // unknown because the worktree doesn't contain ` ` session).
+  // Critically it must NOT 5xx or return undefined.
+  assert.ok(
+    res.status === 200 || res.status === 503,
+    `unexpected ${res.status} for whitespace session id`,
+  );
+});