@openchambery/web 1.18.4-beta.2 → 1.18.4-beta.20

package/server/lib/relay/tunnel-host.test.js

@@ -7,18 +7,17 @@
 // corrupted payload. This test must stay red until send serialization is fixed.
 // Production send path is intentionally not changed here.
 
-import { afterEach, describe, expect, it } from 'bun:test';
+import { describe, expect, it } from 'bun:test';
 
 import {
   MAX_TUNNEL_PAYLOAD_BYTES,
   TunnelFrameType,
   createFragmentAssembler,
-  decodeJsonPayload,
   decodeTunnelFrame,
   encodeJsonPayload,
   encodeTunnelFrame,
 } from './tunnel-codec.js';
-import { createTunnelHost, resolveTargetPort } from './tunnel-host.js';
+import { createTunnelHost } from './tunnel-host.js';
 
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder();
@@ -224,250 +223,3 @@ describe('createTunnelHost WS fragment ordering', () => {
     }
   });
 });
-
-const collectHttpExchange = async (outbound, streamId) => {
-  await waitFor(() => outbound.some((frame) => {
-    const decoded = decodeTunnelFrame(frame);
-    return decoded.streamId === streamId
-      && (decoded.frameType === TunnelFrameType.StreamEnd
-        || decoded.frameType === TunnelFrameType.StreamAbort);
-  }));
-  let status = null;
-  /** @type {Uint8Array[]} */
-  const bodyChunks = [];
-  for (const raw of outbound) {
-    const frame = decodeTunnelFrame(raw);
-    if (frame.streamId !== streamId) continue;
-    if (frame.frameType === TunnelFrameType.HttpResponse) {
-      status = decodeJsonPayload(frame.payload, (v) => v && typeof v.status === 'number').status;
-    } else if (frame.frameType === TunnelFrameType.HttpBody) {
-      bodyChunks.push(frame.payload);
-    }
-  }
-  let body = null;
-  if (bodyChunks.length > 0) {
-    const total = bodyChunks.reduce((n, c) => n + c.length, 0);
-    const merged = new Uint8Array(total);
-    let off = 0;
-    for (const c of bodyChunks) {
-      merged.set(c, off);
-      off += c.length;
-    }
-    body = JSON.parse(textDecoder.decode(merged));
-  }
-  return { status, body };
-};
-
-describe('createTunnelHost SSH target-port routing', () => {
-  /** @type {typeof globalThis.fetch | undefined} */
-  let originalFetch;
-
-  afterEach(() => {
-    if (originalFetch) {
-      globalThis.fetch = originalFetch;
-      originalFetch = undefined;
-    }
-  });
-
-  const installFetchProbe = () => {
-    /** @type {{ url: string, headers: Record<string, string> }[]} */
-    const calls = [];
-    originalFetch = globalThis.fetch;
-    globalThis.fetch = async (url, init) => {
-      calls.push({
-        url: String(url),
-        headers: { ...(init?.headers || {}) },
-      });
-      return new Response(JSON.stringify({ ok: true }), {
-        status: 200,
-        headers: { 'content-type': 'application/json' },
-      });
-    };
-    return calls;
-  };
-
-  it('dials the routing-table port when x-openchamber-target-port is allowed', async () => {
-    const fetchCalls = installFetchProbe();
-    /** @type {Uint8Array[]} */
-    const outbound = [];
-    const host = createTunnelHost({
-      connectionId: 'test-conn',
-      getLocalPort: () => 3000,
-      getSshRoutingTable: () => [{ id: 'ssh-1', localPort: 41234 }],
-      sendFrame: (frame) => { outbound.push(frame); },
-      getBufferedAmount: () => 0,
-    });
-
-    const streamId = 11;
-    await host.handleFrame(encodeTunnelFrame(
-      TunnelFrameType.HttpRequest,
-      streamId,
-      encodeJsonPayload({
-        method: 'GET',
-        path: '/health',
-        query: '',
-        headers: { 'x-openchamber-target-port': '41234', accept: 'application/json' },
-      }),
-    ));
-
-    const exchange = await collectHttpExchange(outbound, streamId);
-    expect(exchange.status).toBe(200);
-    expect(fetchCalls).toHaveLength(1);
-    expect(fetchCalls[0].url).toBe('http://127.0.0.1:41234/health');
-    host.close();
-  });
-
-  it('returns 503 and does not fall back when target-port is unknown', async () => {
-    const fetchCalls = installFetchProbe();
-    /** @type {Uint8Array[]} */
-    const outbound = [];
-    const host = createTunnelHost({
-      connectionId: 'test-conn',
-      getLocalPort: () => 3000,
-      getSshRoutingTable: () => [{ id: 'ssh-1', localPort: 41234 }],
-      sendFrame: (frame) => { outbound.push(frame); },
-      getBufferedAmount: () => 0,
-    });
-
-    const streamId = 12;
-    await host.handleFrame(encodeTunnelFrame(
-      TunnelFrameType.HttpRequest,
-      streamId,
-      encodeJsonPayload({
-        method: 'GET',
-        path: '/health',
-        query: '',
-        headers: { 'x-openchamber-target-port': '9999' },
-      }),
-    ));
-
-    const exchange = await collectHttpExchange(outbound, streamId);
-    expect(exchange.status).toBe(503);
-    expect(exchange.body?.error).toBe('ssh-host-unreachable');
-    expect(fetchCalls).toHaveLength(0);
-    host.close();
-  });
-
-  it('strips x-openchamber-target-port before forwarding to loopback', async () => {
-    const fetchCalls = installFetchProbe();
-    /** @type {Uint8Array[]} */
-    const outbound = [];
-    const host = createTunnelHost({
-      connectionId: 'test-conn',
-      getLocalPort: () => 3000,
-      getSshRoutingTable: () => [{ id: 'ssh-1', localPort: 41234 }],
-      sendFrame: (frame) => { outbound.push(frame); },
-      getBufferedAmount: () => 0,
-    });
-
-    const streamId = 13;
-    await host.handleFrame(encodeTunnelFrame(
-      TunnelFrameType.HttpRequest,
-      streamId,
-      encodeJsonPayload({
-        method: 'GET',
-        path: '/api/version',
-        query: '',
-        headers: {
-          'x-openchamber-target-port': '41234',
-          authorization: 'Bearer client-token',
-        },
-      }),
-    ));
-
-    await collectHttpExchange(outbound, streamId);
-    expect(fetchCalls).toHaveLength(1);
-    expect(fetchCalls[0].headers['x-openchamber-target-port']).toBeUndefined();
-    expect(fetchCalls[0].headers.authorization).toBe('Bearer client-token');
-    expect(fetchCalls[0].headers['x-openchamber-relay-connection']).toBe('test-conn');
-    host.close();
-  });
-
-  it('dials the default local port when target-port header is absent', async () => {
-    const fetchCalls = installFetchProbe();
-    /** @type {Uint8Array[]} */
-    const outbound = [];
-    const host = createTunnelHost({
-      connectionId: 'test-conn',
-      getLocalPort: () => 3000,
-      getSshRoutingTable: () => [{ id: 'ssh-1', localPort: 41234 }],
-      sendFrame: (frame) => { outbound.push(frame); },
-      getBufferedAmount: () => 0,
-    });
-
-    const streamId = 14;
-    await host.handleFrame(encodeTunnelFrame(
-      TunnelFrameType.HttpRequest,
-      streamId,
-      encodeJsonPayload({
-        method: 'GET',
-        path: '/health',
-        query: '',
-        headers: { accept: 'application/json' },
-      }),
-    ));
-
-    await collectHttpExchange(outbound, streamId);
-    expect(fetchCalls).toHaveLength(1);
-    expect(fetchCalls[0].url).toBe('http://127.0.0.1:3000/health');
-    host.close();
-  });
-
-  it('WS open dials routing-table port and aborts on miss without fallback', async () => {
-    FakeWebSocket.reset();
-    /** @type {Uint8Array[]} */
-    const outbound = [];
-    const host = createTunnelHost({
-      connectionId: 'test-conn',
-      getLocalPort: () => 3000,
-      getSshRoutingTable: () => [{ id: 'ssh-1', localPort: 41234 }],
-      sendFrame: (frame) => { outbound.push(frame); },
-      getBufferedAmount: () => 0,
-      createWebSocket: (url, protocols) => new FakeWebSocket(url, protocols),
-    });
-
-    await host.handleFrame(encodeTunnelFrame(
-      TunnelFrameType.WsOpen,
-      21,
-      encodeJsonPayload({
-        path: '/api/event/ws',
-        query: '',
-        headers: { 'x-openchamber-target-port': '41234' },
-      }),
-    ));
-    expect(FakeWebSocket.instances).toHaveLength(1);
-    expect(FakeWebSocket.instances[0].url).toBe('ws://127.0.0.1:41234/api/event/ws');
-
-    await host.handleFrame(encodeTunnelFrame(
-      TunnelFrameType.WsOpen,
-      22,
-      encodeJsonPayload({
-        path: '/api/event/ws',
-        query: '',
-        headers: { 'x-openchamber-target-port': '9999' },
-      }),
-    ));
-    // Miss must not open another socket (no fallback to 3000).
-    expect(FakeWebSocket.instances).toHaveLength(1);
-    await waitFor(() => outbound.some((frame) => {
-      const decoded = decodeTunnelFrame(frame);
-      return decoded.streamId === 22 && decoded.frameType === TunnelFrameType.StreamAbort;
-    }));
-    const abort = outbound
-      .map((frame) => decodeTunnelFrame(frame))
-      .find((frame) => frame.streamId === 22 && frame.frameType === TunnelFrameType.StreamAbort);
-    expect(decodeJsonPayload(abort.payload, () => true).reason).toBe('ssh-host-unreachable');
-    host.close();
-  });
-});
-
-describe('resolveTargetPort', () => {
-  it('returns default when header is absent and null on table miss', () => {
-    const table = () => [{ id: 'ssh-1', localPort: 41234 }];
-    expect(resolveTargetPort({}, 3000, table)).toBe(3000);
-    expect(resolveTargetPort({ 'x-openchamber-target-port': '41234' }, 3000, table)).toBe(41234);
-    expect(resolveTargetPort({ 'X-OpenChamber-Target-Port': '41234' }, 3000, table)).toBe(41234);
-    expect(resolveTargetPort({ 'x-openchamber-target-port': '9999' }, 3000, table)).toBeNull();
-    expect(resolveTargetPort({ 'x-openchamber-target-port': 'not-a-port' }, 3000, table)).toBeNull();
-  });
-});

package/server/lib/scheduled-tasks/DOCUMENTATION.md

@@ -31,7 +31,10 @@ Server-owned scheduled task runtime and routes for OpenChamber-only automation.
   - Global run history list endpoint
   - Project scheduled task CRUD endpoints
   - Manual run endpoint
-  - OpenChamber events SSE stream endpoint
+  - OpenChamber events SSE stream endpoint (`GET /api/openchamber/events`): 25s
+    heartbeat interval unchanged; half-open clients that stay paused across two
+    consecutive heartbeat cycles are destroyed and removed from the client set
+    (idempotent cleanup). SSE is best-effort; authoritative data is HTTP pull.
   - Returns persisted mutation results with `schedulerSynced`; a failed scheduler
     sync schedules one bounded retry while preserving the committed response
 

package/server/lib/scheduled-tasks/routes.js

@@ -321,6 +321,33 @@ export const registerScheduledTaskRoutes = (app, dependencies) => {
     const clients = getOpenChamberEventClients();
     clients.add(res);
 
+    let closed = false;
+    let heartbeatTimer = null;
+    // Half-open / stalled-drain eviction: destroy after this many consecutive
+    // heartbeat cycles while the socket remains paused (no drain). Interval
+    // itself is unchanged — only failure cleanup was added.
+    // SSE is best-effort; authoritative data is fetched over HTTP.
+    const maxPausedHeartbeatCycles = 2;
+
+    const cleanup = () => {
+      if (closed) {
+        return;
+      }
+      closed = true;
+      if (heartbeatTimer) {
+        clearInterval(heartbeatTimer);
+        heartbeatTimer = null;
+      }
+      clients.delete(res);
+      try {
+        if (!res.destroyed && !res.writableEnded) {
+          res.destroy();
+        }
+      } catch {
+        // ignore — destroy + delete must stay idempotent
+      }
+    };
+
     try {
       writeSseEvent(res, {
         type: 'openchamber:event-stream-ready',
@@ -329,25 +356,41 @@ export const registerScheduledTaskRoutes = (app, dependencies) => {
         },
       });
     } catch {
+      cleanup();
+      return;
     }
 
-    const heartbeat = setInterval(() => {
+    heartbeatTimer = setInterval(() => {
+      if (closed || res.writableEnded || res.destroyed) {
+        cleanup();
+        return;
+      }
+
       try {
-        writeSseEvent(res, {
+        const ok = writeSseEvent(res, {
           type: 'openchamber:heartbeat',
           properties: {
             timestamp: Date.now(),
           },
         });
+        if (ok === false || res.__ssePaused) {
+          const cycles = (res.__ssePausedHeartbeatCycles || 0) + 1;
+          res.__ssePausedHeartbeatCycles = cycles;
+          if (cycles >= maxPausedHeartbeatCycles) {
+            // Intentional half-open cleanup: TCP may still look open while the
+            // relay tunnel is dead and drain never fires. SSE is best-effort;
+            // authoritative data is fetched over HTTP.
+            cleanup();
+          }
+          return;
+        }
+        res.__ssePausedHeartbeatCycles = 0;
       } catch {
-        clearInterval(heartbeat);
-        clients.delete(res);
+        cleanup();
       }
     }, 25_000);
 
-    req.on('close', () => {
-      clearInterval(heartbeat);
-      clients.delete(res);
-    });
+    req.on('close', cleanup);
+    res.on('error', cleanup);
   });
 };

package/server/lib/session-assist/DOCUMENTATION.md

@@ -14,8 +14,10 @@ under `metadata.openchamber.assist`.
    `retry` status or a user `message.updated` clears it (the "1 minute of
    quiet" rule).
 3. On fire: fetch the session (skip sub-agent sessions with `parentID`),
-   take the LAST exchange only — the final assistant reply plus the user
-   message it answered (assistant `parentID` → user id) — and call
+   then build a trimmed excerpt via `buildAssistTranscript`: the LAST text
+   block of the last assistant message (earlier blocks, reasoning, and tool
+   output are excluded) plus the latest 3 real user messages (synthetic
+   hidden-instruction parts never count). The excerpt is sent to
    `generateSmallModelText` with the
    session's own provider/model taken from the last assistant message — so
    the utility call spends the same subscription as the conversation.

package/server/lib/session-assist/runtime.js

@@ -33,6 +33,8 @@ const isSessionRecapEnabled = () => {
 
 const IDLE_QUIET_MS = 60_000;
 const TRANSCRIPT_MESSAGE_LIMIT = 12;
+/** Latest real user messages fed to the recap prompt. */
+const TRANSCRIPT_USER_MESSAGE_LIMIT = 3;
 const TRANSCRIPT_PART_CHAR_LIMIT = 6_000;
 const RECAP_CHAR_LIMIT = 320;
 const FETCH_TIMEOUT_MS = 5_000;
@@ -92,13 +94,63 @@ const extractUserMessage = (payload) => {
   };
 };
 
-const messagePartsToText = (message) => {
+/** Real (non-synthetic) text parts of a message — hidden instructions excluded. */
+const realTextParts = (message) => {
   const parts = Array.isArray(message?.parts) ? message.parts : [];
   return parts
-    .map((part) => (part?.type === 'text' && typeof part.text === 'string' ? part.text : ''))
-    .filter(Boolean)
-    .join('\n')
-    .slice(0, TRANSCRIPT_PART_CHAR_LIMIT);
+    .filter((part) => part?.type === 'text'
+      && typeof part.text === 'string'
+      && part.text.trim().length > 0
+      && part.synthetic !== true)
+    .map((part) => part.text);
+};
+
+/** Body text of a message: only its LAST text block, char-clamped. */
+const lastMessageText = (message) => {
+  const texts = realTextParts(message);
+  return texts.length > 0 ? texts[texts.length - 1].slice(0, TRANSCRIPT_PART_CHAR_LIMIT) : '';
+};
+
+/**
+ * Build the recap transcript from a bounded recent-message window.
+ * - Assistant: only the LAST text block of the last assistant message —
+ *   earlier blocks, reasoning, and tool output are token waste for a
+ *   one-line recap.
+ * - User: the latest real user messages (default 3), chronological.
+ */
+export const buildAssistTranscript = (
+  messages,
+  { userLimit = TRANSCRIPT_USER_MESSAGE_LIMIT } = {},
+) => {
+  if (!Array.isArray(messages) || messages.length === 0) {
+    return { transcript: '', assistantInfo: null, userTexts: [], assistantText: '' };
+  }
+  let lastAssistant = null;
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    if (messages[i]?.info?.role === 'assistant') {
+      lastAssistant = messages[i];
+      break;
+    }
+  }
+  const lastAssistantInfo = lastAssistant?.info ?? null;
+  if (!lastAssistantInfo?.id) {
+    return { transcript: '', assistantInfo: null, userTexts: [], assistantText: '' };
+  }
+
+  const userTexts = [];
+  for (let i = messages.length - 1; i >= 0 && userTexts.length < userLimit; i -= 1) {
+    const message = messages[i];
+    if (message?.info?.role !== 'user') continue;
+    const text = lastMessageText(message);
+    if (!text) continue;
+    userTexts.unshift(text);
+  }
+  const assistantText = lastMessageText(lastAssistant);
+  const transcript = [
+    ...userTexts.map((text) => `User:\n${text}`),
+    assistantText ? `Assistant:\n${assistantText}` : '',
+  ].filter(Boolean).join('\n\n');
+  return { transcript, assistantInfo: lastAssistantInfo, userTexts, assistantText };
 };
 
 export const createSessionAssistRuntime = ({
@@ -169,36 +221,21 @@ export const createSessionAssistRuntime = ({
       return;
     }
 
-    let lastAssistant = null;
-    for (let i = messages.length - 1; i >= 0; i -= 1) {
-      const info = messages[i]?.info;
-      if (info?.role === 'assistant') {
-        lastAssistant = messages[i];
-        break;
-      }
-    }
-    const lastAssistantInfo = lastAssistant?.info;
+    // Trimmed extraction for a one-line recap: the last assistant text block
+    // plus the latest real user messages. Everything else (earlier blocks,
+    // reasoning, tool output, older turns) is token waste.
+    const { transcript, assistantInfo: lastAssistantInfo, userTexts, assistantText } = buildAssistTranscript(messages);
     if (!lastAssistantInfo?.id) return;
-
-    // Only the last exchange: the assistant reply plus the user message it
-    // answered (assistant info.parentID → user info.id). Everything else is
-    // token waste for a one-line recap.
-    const parentUserMessage = typeof lastAssistantInfo.parentID === 'string' && lastAssistantInfo.parentID
-      ? messages.find((message) => message?.info?.id === lastAssistantInfo.parentID && message?.info?.role === 'user')
-      : null;
-    const userText = parentUserMessage ? messagePartsToText(parentUserMessage) : '';
-    const assistantText = messagePartsToText(lastAssistant);
-    const transcript = [
-      userText ? `User:\n${userText}` : '',
-      assistantText ? `Assistant:\n${assistantText}` : '',
-    ].filter(Boolean).join('\n\n');
     if (!transcript) return;
 
     const { generateSmallModelText } = await getSmallModelService();
     // Instruct the language by example, not by description — account-side
     // personalization (e.g. the ChatGPT backend knowing the user's locale)
     // otherwise leaks a different language into the output.
-    const languageSample = (userText || assistantText).slice(0, 200).replace(/\s+/g, ' ').trim();
+    const languageSample = (userTexts[userTexts.length - 1] || assistantText)
+      .slice(0, 200)
+      .replace(/\s+/g, ' ')
+      .trim();
     let generated;
     try {
       generated = await generateSmallModelText({
@@ -206,7 +243,7 @@ export const createSessionAssistRuntime = ({
         // session's own provider unless the user explicitly picked a small
         // model (settings override / opencode config).
         restrictToPreferredProvider: true,
-        prompt: `The latest exchange in the conversation:\n\n${transcript}\n\nWrite recap in the SAME language as this sample from the conversation: "${languageSample}"`,
+        prompt: `The latest conversation excerpt:\n\n${transcript}\n\nWrite recap in the SAME language as this sample from the conversation: "${languageSample}"`,
         system: ASSIST_SYSTEM_PROMPT,
         directory,
         preferredProviderID: typeof lastAssistantInfo.providerID === 'string' ? lastAssistantInfo.providerID : undefined,
@@ -228,7 +265,7 @@ export const createSessionAssistRuntime = ({
     // no Cyrillic/CJK at all, the output must not either.
     const hasCyrillic = (text) => /[\u0400-\u04FF]/.test(text);
     const hasCjk = (text) => /[\u3040-\u30FF\u4E00-\u9FFF\uAC00-\uD7AF]/.test(text);
-    const inputText = `${userText}\n${assistantText}`;
+    const inputText = `${userTexts.join('\n')}\n${assistantText}`;
     const scriptMismatch = (text) => (hasCyrillic(text) && !hasCyrillic(inputText))
       || (hasCjk(text) && !hasCjk(inputText));
     if (recap && scriptMismatch(recap)) {

package/server/lib/session-assist/runtime.test.js

@@ -0,0 +1,114 @@
+import { describe, expect, test } from 'vitest';
+import { buildAssistTranscript } from './runtime.js';
+
+const textPart = (text, { synthetic = false } = {}) => ({
+  type: 'text',
+  text,
+  ...(synthetic ? { synthetic: true } : {}),
+});
+
+const userMessage = (id, parts) => ({ info: { id, role: 'user' }, parts });
+const assistantMessage = (id, parts) => ({ info: { id, role: 'assistant' }, parts });
+
+describe('buildAssistTranscript', () => {
+  test('assistant keeps only the LAST text block of the last assistant message', () => {
+    const result = buildAssistTranscript([
+      userMessage('u1', [textPart('first user message')]),
+      assistantMessage('a1', [textPart('old assistant reply')]),
+      userMessage('u2', [textPart('second user message')]),
+      assistantMessage('a2', [
+        textPart('intro before tools'),
+        { type: 'tool', tool: 'bash' },
+        textPart('final body text'),
+      ]),
+    ]);
+    expect(result.assistantInfo.id).toBe('a2');
+    expect(result.assistantText).toBe('final body text');
+    expect(result.transcript).toBe(
+      'User:\nfirst user message\n\nUser:\nsecond user message\n\nAssistant:\nfinal body text',
+    );
+  });
+
+  test('reasoning parts never enter the transcript', () => {
+    const result = buildAssistTranscript([
+      userMessage('u1', [textPart('请帮我看看')]),
+      assistantMessage('a1', [
+        { type: 'reasoning', text: 'thinking about the problem' },
+        textPart('最终答复'),
+      ]),
+    ]);
+    expect(result.transcript).toBe('User:\n请帮我看看\n\nAssistant:\n最终答复');
+    expect(result.transcript).not.toContain('thinking');
+  });
+
+  test('user side keeps only the latest 3 real user messages, chronologically', () => {
+    const result = buildAssistTranscript([
+      userMessage('u1', [textPart('question 1')]),
+      assistantMessage('a1', [textPart('answer 1')]),
+      userMessage('u2', [textPart('question 2')]),
+      assistantMessage('a2', [textPart('answer 2')]),
+      userMessage('u3', [textPart('question 3')]),
+      userMessage('u4', [textPart('question 4')]),
+      assistantMessage('a3', [textPart('answer 3')]),
+    ]);
+    expect(result.userTexts).toEqual(['question 2', 'question 3', 'question 4']);
+    expect(result.transcript).toBe(
+      'User:\nquestion 2\n\nUser:\nquestion 3\n\nUser:\nquestion 4\n\nAssistant:\nanswer 3',
+    );
+  });
+
+  test('synthetic-only user messages do not count toward the user window', () => {
+    const result = buildAssistTranscript([
+      userMessage('u1', [textPart('visible request')]),
+      userMessage('u2', [textPart('hidden instruction', { synthetic: true })]),
+      userMessage('u3', [textPart('real follow-up')]),
+      assistantMessage('a1', [textPart('reply body')]),
+    ]);
+    expect(result.userTexts).toEqual(['visible request', 'real follow-up']);
+    expect(result.transcript).not.toContain('hidden instruction');
+  });
+
+  test('synthetic instruction part on a real user message is dropped', () => {
+    const result = buildAssistTranscript([
+      userMessage('u1', [
+        textPart('visible request'),
+        textPart('/summary hidden instructions', { synthetic: true }),
+      ]),
+      assistantMessage('a1', [textPart('reply body')]),
+    ]);
+    expect(result.userTexts).toEqual(['visible request']);
+    expect(result.transcript).not.toContain('/summary hidden instructions');
+  });
+
+  test('fewer than 3 user messages keeps all of them', () => {
+    const result = buildAssistTranscript([
+      userMessage('u1', [textPart('only question')]),
+      assistantMessage('a1', [textPart('only answer')]),
+    ]);
+    expect(result.userTexts).toEqual(['only question']);
+    expect(result.transcript).toBe('User:\nonly question\n\nAssistant:\nonly answer');
+  });
+
+  test('no assistant message yields an empty transcript', () => {
+    const result = buildAssistTranscript([
+      userMessage('u1', [textPart('unanswered question')]),
+    ]);
+    expect(result.transcript).toBe('');
+    expect(result.assistantInfo).toBeNull();
+    expect(result.userTexts).toEqual([]);
+  });
+
+  test('assistant with no text parts still summarizes the user side', () => {
+    const result = buildAssistTranscript([
+      userMessage('u1', [textPart('question')]),
+      assistantMessage('a1', [{ type: 'tool', tool: 'bash' }]),
+    ]);
+    expect(result.assistantInfo.id).toBe('a1');
+    expect(result.transcript).toBe('User:\nquestion');
+  });
+
+  test('empty input yields an empty transcript', () => {
+    expect(buildAssistTranscript([]).transcript).toBe('');
+    expect(buildAssistTranscript(null).transcript).toBe('');
+  });
+});

package/server/lib/session-title/DOCUMENTATION.md

@@ -18,16 +18,21 @@ throttle (`TITLE_THROTTLE_MS`) when a refresh is armed.
    pattern as session-assist. Purely event-driven — dormant sessions never
    generate anything.
   2. Auto title refresh is intentionally sparse (title stability first). A newly
-    observed root `session.created` generates its first title immediately on the
-    first `session.status: idle`. A fork title (`(fork #n)`) waits for its first
-    newly-created user message; the matching assistant completion triggers an
-    immediate title refresh that bypasses inherited title metadata and throttle.
-    Ordinary later idle transitions do **not** arm another refresh. Any
-    `busy`/`retry` status or a fresh user `message.updated` still clears an
-    already-armed timer (so initial/fork timers cancel if the user keeps going).
-    A sidebar smart-title request sets `titleRefresh.requestedAt`; its
-    `session.updated` event arms the same flow immediately (forced / manual
-    refresh is unaffected by the background gate).
+     observed root `session.created` generates its first title immediately on the
+     first `session.status: idle`. A fork title (`(fork #n)`) waits for its first
+     newly-created user message; the matching assistant completion triggers an
+     immediate title refresh that bypasses inherited title metadata and throttle.
+     If the fork's `session.created` was lost (SSE reconnect gap, server or
+     OpenCode restart), the first newly-created user message lazily re-registers
+     the pending fork from the session read inside `recordUserActivity` (fork
+     title + message created after the fork + activity timestamp not yet past
+     the fork time), so the first-reply refresh still fires.
+     Ordinary later idle transitions do **not** arm another refresh. Any
+     `busy`/`retry` status or a fresh user `message.updated` still clears an
+     already-armed timer (so initial/fork timers cancel if the user keeps going).
+     A sidebar smart-title request sets `titleRefresh.requestedAt`; its
+     `session.updated` event arms the same flow immediately (forced / manual
+     refresh is unaffected by the background gate).
   3. On fire:
     - Skip when Settings → Chat → session title refresh is off.
     - Skip system-owned sessions whose metadata carries a non-empty