Add persistent agent messaging and shared chat bubbles

Connect Sybil to the Pi root conversation with authenticated REST and WebSocket
APIs, persistent read state, and a dedicated agent tab. Keep optimistic messages
stable through delivery and retries, and animate arrivals without losing the
reader's scroll position.

Share bubble styling with regular chats and remove the obsolete admission sender.
Reject malformed upstream receipts and WebSocket upgrade requests, with regression
coverage and updated API documentation.

Validated with 51 web tests, 44 server tests, both production builds, desktop/mobile
bubble comparisons, and 11 browser animation and scrolling checks.

server/README.md

@@ -106,3 +106,26 @@ When `chatId` is provided to completion endpoints, you can send full conversatio
 - User accounts + per-device API keys
 - Postgres support + migrations for prod
 - Attachments + embeddings + semantic search
+
+## Persistent Pi Agent
+
+Configure the backend with:
+
+```dotenv
+PI_AGENT_BASE_URL=http://pi-durable:8788
+PI_AGENT_API_KEY=<the Pi service's PI_API_KEY>
+```
+
+The base URL defaults to `http://pi-durable:8788` and has no `/v1` suffix. In Docker,
+attach Sybil's **server** container and Pi to the shared `agents` network so that
+`pi-durable` resolves privately. Supply the key through a private server environment
+file; it is never a `VITE_*` variable or browser setting. Keep the existing Sybil
+`ADMIN_TOKEN` authentication for clients.
+
+The Agent tab uses `/v1/agent`, `/v1/agent/messages`, and `/v1/agent/ws` to proxy the
+same persistent Pi root conversation across devices. Pi remains the source of
+truth for messages and background replies. Sybil stores only the shared,
+monotonically increasing read cursor in SQLite through `/v1/agent/read-state`;
+its migration is applied automatically at startup. The bundled nginx configuration
+forwards WebSocket upgrades. See `docs/api/rest.md` and
+`docs/api/streaming-chat.md` at the repository root for the client contracts.

server/package-lock.json

@@ -22,10 +22,12 @@
         "openai": "^6.16.0",
         "pino-pretty": "^13.1.3",
         "prisma": "^6.6.0",
+        "ws": "8.22.0",
         "zod": "^4.3.6"
       },
       "devDependencies": {
         "@types/node": "^25.0.10",
+        "@types/ws": "8.18.1",
         "tsx": "^4.21.0",
         "typescript": "^5.9.3"
       }
@@ -876,6 +878,16 @@
         "undici-types": "~7.16.0"
       }
     },
+    "node_modules/@types/ws": {
+      "version": "8.18.1",
+      "resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.18.1.tgz",
+      "integrity": "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
     "node_modules/abstract-logging": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/abstract-logging/-/abstract-logging-2.0.1.tgz",
@@ -2241,6 +2253,27 @@
       "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
       "license": "ISC"
     },
+    "node_modules/ws": {
+      "version": "8.22.0",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.22.0.tgz",
+      "integrity": "sha512-Ydggc987+RO0AnWtZ/7Wq9FtNvcrL1b/RO0ud9mWjUPgDrsAAwQSF51sm2hm1XofbU/4jkpGEsLFsZZxU+1DOg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10.0.0"
+      },
+      "peerDependencies": {
+        "bufferutil": "^4.0.1",
+        "utf-8-validate": ">=5.0.2"
+      },
+      "peerDependenciesMeta": {
+        "bufferutil": {
+          "optional": true
+        },
+        "utf-8-validate": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/yaml": {
       "version": "2.8.2",
       "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.2.tgz",

server/package.json

@@ -31,10 +31,12 @@
     "openai": "^6.16.0",
     "pino-pretty": "^13.1.3",
     "prisma": "^6.6.0",
+    "ws": "8.22.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",
+    "@types/ws": "8.18.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   }

server/prisma/migrations/20261014000000_add_agent_read_state/migration.sql

@@ -0,0 +1,5 @@
+CREATE TABLE "AgentReadState" (
+  "id" TEXT NOT NULL PRIMARY KEY,
+  "cursor" TEXT NOT NULL DEFAULT '0',
+  "updatedAt" DATETIME NOT NULL
+);

server/prisma/schema.prisma

@@ -215,3 +215,11 @@ model ProjectItem {
   @@index([chatId])
   @@index([searchId])
 }
+
+// Shared personal read position for the external persistent Pi room.
+// Messages remain in Pi's durable transcript, not duplicated in Sybil Chat.
+model AgentReadState {
+  id        String @id
+  cursor    String @default("0")
+  updatedAt DateTime @updatedAt
+}

server/src/agent.ts

@@ -0,0 +1,171 @@
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import type { FastifyInstance } from 'fastify';
+import { WebSocket, WebSocketServer } from 'ws';
+import { z } from 'zod';
+import { requireAdmin } from './auth.js';
+import { prisma } from './db.js';
+import { env } from './env.js';
+
+const Cursor = z.string().regex(/^\d{1,16}$/).refine(value => Number.isSafeInteger(Number(value)), 'Invalid cursor')
+  .transform(value => String(Number(value)));
+const PageQuery = z.object({ after: Cursor.optional(), before: Cursor.optional(), limit: z.coerce.number().int().min(1).max(200).optional() })
+  .refine(value => !(value.after && value.before), 'Use after or before, not both');
+const MessageBody = z.object({ content: z.string().min(1).max(40_000).refine(value => value.trim().length > 0, 'content is required'), requestId: z.string().min(1).max(256) });
+const ReadBody = z.object({ cursor: Cursor });
+const AuthFrame = z.object({ type: z.literal('auth'), token: z.string().nullable().optional(), after: Cursor.optional() });
+const SubscribeFrame = z.object({ type: z.literal('subscribe'), after: Cursor.optional() });
+const SubmissionReceipt = z.object({ id: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+  status: z.enum(['queued', 'placed', 'done', 'unanswered']), messageId: z.string() });
+
+type AgentOptions = { baseUrl?: string; apiKey?: string };
+const parse = <T>(schema: z.ZodType<T>, value: unknown): T => {
+  const result = schema.safeParse(value);
+  if (!result.success) throw Object.assign(new Error(result.error.issues.map(issue => issue.message).join('; ')), { statusCode: 400 });
+  return result.data;
+};
+
+async function readState() {
+  const value = await prisma.agentReadState.findUnique({ where: { id: 'root' } });
+  return { cursor: value?.cursor || '0', updatedAt: value?.updatedAt.toISOString() || null };
+}
+
+/** Pi owns the conversation; Sybil stores only its shared personal read cursor. */
+export async function registerAgentRoutes(app: FastifyInstance, options: AgentOptions = {}) {
+  const baseUrl = options.baseUrl || env.PI_AGENT_BASE_URL;
+  const apiKey = options.apiKey ?? env.PI_AGENT_API_KEY;
+  const proxyJson = async (path: string, method = 'GET', body?: unknown) => {
+    if (!apiKey) throw app.httpErrors.serviceUnavailable('Pi agent is not configured');
+    let response: Response;
+    try {
+      response = await fetch(new URL(path, baseUrl), { method,
+        headers: { Authorization: `Bearer ${apiKey}`, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: AbortSignal.timeout(15_000),
+      });
+    } catch { throw app.httpErrors.badGateway('Pi agent is unavailable'); }
+    let data: unknown;
+    try { data = await response.json(); }
+    catch { throw app.httpErrors.badGateway('Pi agent returned invalid JSON'); }
+    return { status: response.status, data };
+  };
+
+  app.get('/v1/agent', async (req, reply) => {
+    reply.header('Cache-Control', 'no-store');
+    requireAdmin(req);
+    const result = await proxyJson('/api/conversations/root');
+    reply.code(result.status);
+    if (result.status !== 200) return result.data;
+    return { ...result.data as object, websocket: '/v1/agent/ws' };
+  });
+  app.get('/v1/agent/messages', async (req, reply) => {
+    reply.header('Cache-Control', 'no-store');
+    requireAdmin(req);
+    const query = parse(PageQuery, req.query);
+    const params = new URLSearchParams();
+    for (const [name, value] of Object.entries(query)) if (value !== undefined) params.set(name, String(value));
+    const result = await proxyJson(`/api/conversations/root/messages?${params}`);
+    reply.code(result.status);
+    return result.data;
+  });
+  app.post('/v1/agent/messages', { bodyLimit: 256 * 1024 }, async (req, reply) => {
+    reply.header('Cache-Control', 'no-store');
+    requireAdmin(req);
+    const body = parse(MessageBody, req.body);
+    const result = await proxyJson('/api/conversations/root/messages', 'POST', { ...body, channel: 'sybil', whenBusy: 'followUp', wait: false });
+    if (result.status >= 200 && result.status < 300) {
+      const receipt = SubmissionReceipt.safeParse(result.data);
+      if (!receipt.success || receipt.data.messageId !== `inbound:sybil:${body.requestId}`) {
+        throw app.httpErrors.badGateway('Pi agent returned an invalid message receipt');
+      }
+    }
+    reply.code(result.status);
+    return result.data;
+  });
+  app.get('/v1/agent/read-state', async (req, reply) => {
+    reply.header('Cache-Control', 'no-store');
+    requireAdmin(req);
+    return readState();
+  });
+  app.put('/v1/agent/read-state', async (req, reply) => {
+    reply.header('Cache-Control', 'no-store');
+    requireAdmin(req);
+    const { cursor } = parse(ReadBody, req.body);
+    // One SQLite statement makes concurrent tabs monotonic. Never write an older
+    // cursor over one saved by another connection between a read and an update.
+    await prisma.$executeRaw`INSERT INTO "AgentReadState" ("id", "cursor", "updatedAt") VALUES ('root', ${cursor}, CURRENT_TIMESTAMP)
+      ON CONFLICT("id") DO UPDATE SET
+        "cursor" = CASE WHEN CAST(excluded."cursor" AS INTEGER) > CAST("AgentReadState"."cursor" AS INTEGER) THEN excluded."cursor" ELSE "AgentReadState"."cursor" END,
+        "updatedAt" = CASE WHEN CAST(excluded."cursor" AS INTEGER) > CAST("AgentReadState"."cursor" AS INTEGER) THEN CURRENT_TIMESTAMP ELSE "AgentReadState"."updatedAt" END`;
+    return readState();
+  });
+
+  attachAgentSocket(app, baseUrl, apiKey);
+}
+
+function attachAgentSocket(app: FastifyInstance, baseUrl: string, apiKey?: string) {
+  const sockets = new WebSocketServer({ noServer: true, maxPayload: 16 * 1024 });
+  const cleanup = new Set<() => void>();
+  const upgrade = (request: IncomingMessage, socket: Duplex, head: Buffer) => {
+    let url: URL;
+    try { url = new URL(request.url || '/', 'http://localhost'); }
+    catch { socket.end('HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n'); return; }
+    if (url.pathname !== '/v1/agent/ws') { socket.end('HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n'); return; }
+    // Credentials must never enter URLs and access logs.
+    if (url.search) { socket.end('HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n'); return; }
+    sockets.handleUpgrade(request, socket, head, browser => {
+      let upstream: WebSocket | undefined;
+      let authenticated = false, disposed = false, alive = true;
+      const send = (value: unknown) => {
+        if (browser.readyState !== WebSocket.OPEN) return;
+        if (browser.bufferedAmount > 2 * 1024 * 1024) { browser.close(1013, 'Slow consumer; reconnect with cursor'); return; }
+        browser.send(typeof value === 'string' ? value : JSON.stringify(value));
+      };
+      const authTimeout = setTimeout(() => browser.close(4401, 'Authentication required'), 5000);
+      const heartbeat = setInterval(() => { if (!alive) browser.terminate(); else { alive = false; browser.ping(); } }, 25_000);
+      browser.on('pong', () => { alive = true; });
+      const dispose = () => {
+        if (disposed) return;
+        disposed = true; clearTimeout(authTimeout); clearInterval(heartbeat); cleanup.delete(dispose);
+        upstream?.terminate(); browser.terminate();
+      };
+      cleanup.add(dispose);
+      browser.on('close', dispose); browser.on('error', dispose);
+      browser.on('message', (raw, isBinary) => {
+        try {
+          if (isBinary) throw new Error('JSON text frames are required');
+          const frame = JSON.parse(raw.toString());
+          if (!authenticated) {
+            const auth = parse(AuthFrame, frame);
+            if (env.ADMIN_TOKEN && auth.token !== env.ADMIN_TOKEN) { browser.close(4401, 'Invalid token'); return; }
+            if (!apiKey) { browser.close(4503, 'Pi agent is not configured'); return; }
+            authenticated = true; clearTimeout(authTimeout);
+            const target = new URL('/api/ws', baseUrl); target.protocol = target.protocol === 'https:' ? 'wss:' : 'ws:';
+            upstream = new WebSocket(target, { headers: { Authorization: `Bearer ${apiKey}` }, handshakeTimeout: 10_000, maxPayload: 16 * 1024 * 1024 });
+            upstream.on('open', () => upstream!.send(JSON.stringify({ type: 'subscribe', ...(auth.after === undefined ? {} : { after: auth.after }) })));
+            upstream.on('message', (data, binary) => {
+              if (binary) { browser.close(1011, 'Invalid Pi frame'); return; }
+              send(data.toString());
+            });
+            upstream.on('close', () => { if (!disposed) browser.close(1012, 'Pi agent disconnected; reconnect with cursor'); });
+            upstream.on('error', () => { send({ type: 'error', error: 'Pi agent is unavailable' }); browser.close(1011, 'Pi agent is unavailable'); });
+            return;
+          }
+          if (frame.type === 'ping') { send({ type: 'pong' }); return; }
+          const subscribe = parse(SubscribeFrame, frame);
+          if (upstream?.readyState !== WebSocket.OPEN) { send({ type: 'error', error: 'Pi agent is still connecting' }); return; }
+          upstream.send(JSON.stringify(subscribe));
+        } catch (error) {
+          if (!authenticated) browser.close(4400, 'Invalid authentication frame');
+          else send({ type: 'error', error: error instanceof Error ? error.message : 'Invalid frame' });
+        }
+      });
+    });
+  };
+  app.server.on('upgrade', upgrade);
+  app.addHook('preClose', async () => {
+    app.server.off('upgrade', upgrade);
+    for (const stop of cleanup) stop();
+    for (const client of sockets.clients) client.terminate();
+    sockets.close();
+  });
+}

server/src/env.ts

@@ -70,6 +70,8 @@ const EnvSchema = z.object({
   HERMES_AGENT_API_BASE_URL: HermesAgentApiBaseUrlSchema,
   HERMES_AGENT_API_KEY: OptionalTrimmedStringSchema,
   HERMES_AGENT_MODEL: OptionalTrimmedStringSchema,
+  PI_AGENT_BASE_URL: z.string().url().default("http://pi-durable:8788"),
+  PI_AGENT_API_KEY: OptionalTrimmedStringSchema,
   EXA_API_KEY: z.string().optional(),
   BRAVE_SEARCH_API_KEY: OptionalTrimmedStringSchema,
 

server/src/index.ts

@@ -6,6 +6,7 @@ import sensible from "@fastify/sensible";
 import { env } from "./env.js";
 import { ensureDatabaseReady } from "./db-init.js";
 import { startModelCatalogRefreshLoop, warmModelCatalog } from "./llm/model-catalog.js";
+import { registerAgentRoutes } from "./agent.js";
 import { registerRoutes } from "./routes.js";
 
 const app = Fastify({
@@ -26,7 +27,7 @@ const stopModelCatalogRefreshLoop = startModelCatalogRefreshLoop(app.log);
 await app.register(cors, {
   origin: true,
   credentials: true,
-  methods: ["GET", "HEAD", "POST", "DELETE", "OPTIONS"],
+  methods: ["GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS"],
 });
 
 await app.register(swagger, {
@@ -86,6 +87,7 @@ app.addHook("onClose", async () => {
 });
 
 await registerRoutes(app);
+await registerAgentRoutes(app);
 
 await app.listen({ port: env.PORT, host: env.HOST });
 app.log.info(`listening on http://${env.HOST}:${env.PORT}`);

server/tests/agent.test.ts

@@ -0,0 +1,184 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { once } from 'node:events';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { createConnection } from 'node:net';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+import Fastify from 'fastify';
+import sensible from '@fastify/sensible';
+import { WebSocket, WebSocketServer } from 'ws';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const directory = mkdtempSync(join(tmpdir(), 'sybil-agent-'));
+process.env.DATABASE_URL = `file:${join(directory, 'agent.db')}`;
+process.env.ADMIN_TOKEN = 'sybil-test-token-0123456789';
+execFileSync(process.execPath, [join(root, 'node_modules/prisma/build/index.js'), 'migrate', 'deploy'], {
+  cwd: root, env: { ...process.env, PRISMA_HIDE_UPDATE_MESSAGE: '1' }, stdio: 'pipe',
+});
+const [{ registerAgentRoutes }, { prisma }, { env }] = await Promise.all([
+  import('../src/agent.js'), import('../src/db.js'), import('../src/env.js'),
+]);
+const auth = { authorization: `Bearer ${process.env.ADMIN_TOKEN}` };
+const privateKey = 'pi-private-key-for-test';
+const requests: { method?: string; url?: string; body: any }[] = [];
+const accepted = new Map<string, number>();
+let upstreamReply: { status: number; body: string } | undefined;
+let connections = 0;
+const subscriptions: any[] = [];
+const upstream = createServer(async (req, res) => {
+  assert.equal(req.headers.authorization, `Bearer ${privateKey}`);
+  const chunks = [];
+  for await (const chunk of req) chunks.push(chunk);
+  const body = chunks.length ? JSON.parse(Buffer.concat(chunks).toString()) : null;
+  requests.push({ method: req.method, url: req.url, body });
+  res.setHeader('Content-Type', 'application/json');
+  if (upstreamReply) { res.statusCode = upstreamReply.status; res.end(upstreamReply.body); return; }
+  if (req.method === 'POST') {
+    const id = accepted.get(body.requestId) || accepted.size + 1; accepted.set(body.requestId, id);
+    res.statusCode = 202; res.end(JSON.stringify({ id, status: 'queued', messageId: `inbound:sybil:${body.requestId}` }));
+  } else if (req.url?.includes('/messages')) {
+    res.end(JSON.stringify({ conversationId: '1', messages: [{ id: 'outbound:43', role: 'assistant', content: 'Later result' }], cursor: '43', beforeCursor: '43', hasMore: false }));
+  } else res.end(JSON.stringify({ id: '1', type: 'persistent-agent', title: 'Pi', websocket: '/api/ws', protocol: 'pi-room.v1', activity: { thinking: true } }));
+});
+const sourceSockets = new WebSocketServer({ noServer: true });
+upstream.on('upgrade', (req, socket, head) => {
+  assert.equal(req.headers.authorization, `Bearer ${privateKey}`);
+  assert.equal(req.url, '/api/ws');
+  connections++;
+  sourceSockets.handleUpgrade(req, socket, head, ws => {
+    ws.on('message', raw => {
+      const frame = JSON.parse(raw.toString()); subscriptions.push(frame);
+      ws.send(JSON.stringify({ type: 'ready', protocol: 'pi-room.v1', conversationId: '1' }));
+      ws.send(JSON.stringify({ type: 'messages', conversationId: '1', messages: [{ id: 'outbound:43', role: 'assistant', content: 'Later result' }], cursor: '43', hasMore: false }));
+      ws.send(JSON.stringify({ type: 'activity', conversationId: '1', activity: { thinking: true, responding: true } }));
+    });
+  });
+});
+upstream.listen(0, '127.0.0.1'); await once(upstream, 'listening');
+const upstreamAddress = upstream.address() as { port: number };
+const app = Fastify({ logger: false }); await app.register(sensible);
+await registerAgentRoutes(app, { baseUrl: `http://127.0.0.1:${upstreamAddress.port}`, apiKey: privateKey });
+await app.listen({ port: 0, host: '127.0.0.1' });
+const address = app.server.address() as { port: number };
+const wsUrl = `ws://127.0.0.1:${address.port}/v1/agent/ws`;
+
+test.after(async () => {
+  await app.close();
+  for (const socket of sourceSockets.clients) socket.terminate();
+  sourceSockets.close();
+  await new Promise<void>(resolve => upstream.close(() => resolve()));
+  await prisma.$disconnect();
+  rmSync(directory, { recursive: true, force: true });
+});
+
+async function eventually(check: () => boolean) {
+  for (let i = 0; i < 100; i++) { if (check()) return; await new Promise(resolve => setTimeout(resolve, 10)); }
+  assert.fail('Expected condition was not reached');
+}
+
+test('REST authenticates, proxies the shared room, and retains stable message IDs without revealing Pi credentials', async () => {
+  assert.equal((await app.inject({ url: '/v1/agent' })).statusCode, 401);
+  const descriptor = await app.inject({ url: '/v1/agent', headers: auth });
+  assert.equal(descriptor.statusCode, 200);
+  assert.equal(descriptor.json().websocket, '/v1/agent/ws');
+  assert.ok(!descriptor.body.includes(privateKey));
+  const page = await app.inject({ url: '/v1/agent/messages?after=42&limit=20', headers: auth });
+  assert.equal(page.json().messages[0].role, 'assistant');
+  assert.match(requests.at(-1)!.url!, /after=42&limit=20/);
+  const input = { content: '  Keep watching\n', requestId: 'same-client-message' };
+  const first = await app.inject({ method: 'POST', url: '/v1/agent/messages', headers: auth, payload: input });
+  const second = await app.inject({ method: 'POST', url: '/v1/agent/messages', headers: auth, payload: input });
+  assert.equal(first.statusCode, 202); assert.deepEqual(first.json(), second.json());
+  assert.deepEqual(requests.at(-1)!.body, { ...input, channel: 'sybil', whenBusy: 'followUp', wait: false });
+  assert.equal((await prisma.chat.count()), 0, 'Pi messages are not copied into ordinary Sybil chats');
+  assert.equal((await app.inject({ url: '/v1/agent/messages?after=2&before=3', headers: auth })).statusCode, 400);
+  assert.equal((await app.inject({ method: 'POST', url: '/v1/agent/messages', headers: auth, payload: { content: 'Hello' } })).statusCode, 400);
+});
+
+test('the read cursor stays monotonic under concurrent tabs and survives reconnecting to SQLite', async () => {
+  const initial = await app.inject({ url: '/v1/agent/read-state', headers: auth });
+  assert.equal(initial.json().cursor, '0');
+  assert.equal(initial.headers['cache-control'], 'no-store');
+  await Promise.all(['900', '4', '100', '12'].map(cursor => app.inject({ method: 'PUT', url: '/v1/agent/read-state', headers: auth, payload: { cursor } })));
+  assert.equal((await app.inject({ url: '/v1/agent/read-state', headers: auth })).json().cursor, '900');
+  await prisma.$disconnect();
+  assert.equal((await app.inject({ method: 'PUT', url: '/v1/agent/read-state', headers: auth, payload: { cursor: '5' } })).json().cursor, '900');
+  assert.equal((await app.inject({ method: 'PUT', url: '/v1/agent/read-state', headers: auth, payload: { cursor: '-1' } })).statusCode, 400);
+});
+
+test('malformed upstream JSON and unconfirmed message receipts return 502, preserving safe retries', async () => {
+  const payload = { content: 'One durable message', requestId: 'invalid-receipt-retry' };
+  try {
+    upstreamReply = { status: 200, body: '{truncated' };
+    for (const url of ['/v1/agent', '/v1/agent/messages']) {
+      const response = await app.inject({ url, headers: auth });
+      assert.equal(response.statusCode, 502);
+      assert.equal(response.headers['cache-control'], 'no-store');
+    }
+    for (const body of ['{truncated', '{}', 'null', JSON.stringify({ id: 1, status: 'queued', messageId: 'wrong-message' }),
+      JSON.stringify({ id: 1, status: 'unknown', messageId: `inbound:sybil:${payload.requestId}` })]) {
+      upstreamReply = { status: 202, body };
+      const response = await app.inject({ method: 'POST', url: '/v1/agent/messages', headers: auth, payload });
+      assert.equal(response.statusCode, 502, body);
+      assert.equal(response.headers['cache-control'], 'no-store');
+    }
+  } finally { upstreamReply = undefined; }
+  const retry = await app.inject({ method: 'POST', url: '/v1/agent/messages', headers: auth, payload });
+  assert.equal(retry.statusCode, 202);
+  assert.equal(retry.json().messageId, `inbound:sybil:${payload.requestId}`);
+});
+
+test('malformed and unmatched upgrade targets close without crashing or opening Pi connections', async () => {
+  const before = connections;
+  const requestUpgrade = (target: string): Promise<string> => new Promise((resolve, reject) => {
+    let response = '';
+    const socket = createConnection({ host: '127.0.0.1', port: address.port }, () => {
+      socket.write(`GET ${target} HTTP/1.1\r\nHost: localhost\r\nConnection: Upgrade\r\nUpgrade: websocket\r\nSec-WebSocket-Version: 13\r\nSec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n\r\n`);
+    });
+    socket.setTimeout(1000, () => socket.destroy(new Error('Upgrade rejection did not close the socket')));
+    socket.on('data', chunk => { response += chunk.toString(); });
+    socket.on('error', reject);
+    socket.on('end', () => { socket.destroy(); resolve(response); });
+  });
+  assert.match(await requestUpgrade('http://['), /^HTTP\/1\.1 400 /);
+  assert.match(await requestUpgrade('/v1/not-an-agent/ws'), /^HTTP\/1\.1 404 /);
+  assert.match(await requestUpgrade('/v1/agent/ws?token=forbidden'), /^HTTP\/1\.1 400 /);
+  assert.equal(connections, before);
+  assert.equal((await app.inject({ url: '/v1/agent', headers: auth })).statusCode, 200);
+});
+
+test('WebSocket first-frame authentication gates the private connection and forwards resumable native frames', async () => {
+  const before = connections;
+  const denied = new WebSocket(wsUrl); await once(denied, 'open');
+  denied.send(JSON.stringify({ type: 'auth', token: 'wrong' }));
+  const [code] = await once(denied, 'close');
+  assert.equal(code, 4401); assert.equal(connections, before);
+  const browser = new WebSocket(wsUrl);
+  const frames: any[] = []; browser.on('message', raw => frames.push(JSON.parse(raw.toString())));
+  await once(browser, 'open'); browser.send(JSON.stringify({ type: 'auth', token: env.ADMIN_TOKEN, after: '42' }));
+  await eventually(() => frames.some(frame => frame.type === 'activity'));
+  assert.deepEqual(subscriptions.at(-1), { type: 'subscribe', after: '42' });
+  assert.deepEqual(frames.map(frame => frame.type), ['ready', 'messages', 'activity']);
+  assert.equal(frames[1].messages[0].content, 'Later result');
+  assert.equal(frames[2].activity.thinking, true);
+  assert.ok(!JSON.stringify(frames).includes(privateKey));
+  browser.send(JSON.stringify({ type: 'subscribe', after: '43' }));
+  await eventually(() => subscriptions.at(-1)?.after === '43');
+  browser.close(); await once(browser, 'close');
+  await eventually(() => sourceSockets.clients.size === 0);
+});
+
+test('open-mode WebSocket authentication accepts null and still keeps the Pi token server-side', async () => {
+  const saved = env.ADMIN_TOKEN; env.ADMIN_TOKEN = undefined;
+  try {
+    const browser = new WebSocket(wsUrl); const frames: any[] = [];
+    browser.on('message', raw => frames.push(JSON.parse(raw.toString())));
+    await once(browser, 'open'); browser.send(JSON.stringify({ type: 'auth', token: null, after: '0' }));
+    await eventually(() => frames.some(frame => frame.type === 'ready'));
+    browser.close(); await once(browser, 'close');
+  } finally { env.ADMIN_TOKEN = saved; }
+});