refactor(review): address PR #186 review (#183 — recency sweep, #174 export, tests, cleanups)

15-point review of the persistent-history PR. Architecture decisions: crash
recovery = recency threshold; tool-label duplication = leave as-is.

Must-fix:
1. Boot-sweep bounded by recency. sweepStreaming now also requires
   `updatedAt < now() - SWEEP_STREAMING_STALE_MS` (10 min), so a fresh replica's
   startup sweep can't abort a turn another replica is actively streaming
   (multi-instance deploy). Int-spec: a FRESH 'streaming' row is NOT swept, a
   STALE one IS.
2. Restore export during the FIRST streaming turn of a new chat (#174). The
   server chatId is now adopted EARLY (in-place, on the start-chunk metadata) via
   a new `onServerChatId` callback wired through use-chat-session → chat-thread,
   so `activeChatId` is set at turn start and the Copy button is live mid-first-
   turn (canExport = !!activeChatId). Hook tests for early/in-place/no-op adopt.
3. Cover finalizeAssistant's fallback-insert branch: extracted pure
   `planFinalizeAssistant(assistantId)` (update when id present, insert when the
   upfront insert failed) + a dispatch harness test for both arms.

Tests: onModuleInit lifecycle spec (sweep called; throw → resolves + warns);
int-spec updatedAt assertion → toBeGreaterThan.

Cleanups: cap findAllByChat at 5000 rows; upfront-insert-failure log carries
chatId+workspaceId; removed the now-dead buildPartialAssistantRecord (only the
spec consumed it; shapes still pinned by the flushAssistant suite); controller
passes `lang: dto.lang` (normalizeLang handles undefined); dropped a no-op
`?? undefined` in errorOf; documented the content-column semantics change
(concatenated step text, UI renders from metadata.parts); CHANGELOG [Unreleased]
entry (#183, #174); reworded the stale LABELS parity comment.

Verified: server build + 323 ai-chat unit + 5 integration; client tsc + 160
ai-chat unit; prettier clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

apps/server/src/core/ai-chat/ai-chat.controller.export.spec.ts

@@ -1,5 +1,10 @@
 import { ForbiddenException } from '@nestjs/common';
 import { AiChatController } from './ai-chat.controller';
+import {
+  planFinalizeAssistant,
+  flushAssistant,
+  type AssistantFlush,
+} from './ai-chat.service';
 import type { User, Workspace } from '@docmost/db/types/entity.types';
 
 /**
@@ -90,3 +95,74 @@ describe('AiChatController.export', () => {
     expect(res.markdown).toContain('## 2. ИИ-агент');
   });
 });
+
+/**
+ * The terminal-finalize dispatch (#183): the assistant row is INSERTed upfront
+ * as 'streaming' and finalized once on the terminal callback. When the upfront
+ * insert SUCCEEDED (we hold an id) finalize UPDATEs that row; when it FAILED
+ * (assistantId is undefined) finalize falls back to INSERTing the terminal row
+ * so the turn is not lost — the only safety against losing the turn entirely.
+ *
+ * `planFinalizeAssistant` is the pure decision; this also drives a tiny harness
+ * that mirrors the service's `finalizeAssistant` repo dispatch over a mock repo,
+ * proving both branches issue the right call with the terminal payload.
+ */
+describe('finalizeAssistant dispatch (planFinalizeAssistant)', () => {
+  const workspaceId = 'ws1';
+
+  // Mirror of the service's finalize repo-dispatch over the plan: UPDATE when an
+  // upfront row exists, else INSERT the terminal row.
+  async function dispatchFinalize(
+    repo: { insert: jest.Mock; update: jest.Mock },
+    assistantId: string | undefined,
+    flushed: AssistantFlush,
+  ): Promise<void> {
+    const plan = planFinalizeAssistant(assistantId);
+    if (plan.kind === 'insert') {
+      await repo.insert({
+        chatId: 'c1',
+        workspaceId,
+        userId: 'u1',
+        role: 'assistant',
+        content: flushed.content,
+        toolCalls: flushed.toolCalls ?? null,
+        metadata: flushed.metadata,
+        status: flushed.status,
+      });
+    } else {
+      await repo.update(plan.id, workspaceId, flushed);
+    }
+  }
+
+  it('plan: update when the upfront insert returned an id', () => {
+    expect(planFinalizeAssistant('a1')).toEqual({ kind: 'update', id: 'a1' });
+  });
+
+  it('plan: insert (fallback) when there is no upfront id', () => {
+    expect(planFinalizeAssistant(undefined)).toEqual({ kind: 'insert' });
+  });
+
+  it('(a) upfront insert succeeded -> finalize UPDATEs the row by id', async () => {
+    const repo = { insert: jest.fn(), update: jest.fn() };
+    const flushed = flushAssistant([], 'final answer', 'completed', {
+      finishReason: 'stop',
+    });
+    await dispatchFinalize(repo, 'a1', flushed);
+    expect(repo.update).toHaveBeenCalledWith('a1', workspaceId, flushed);
+    expect(repo.insert).not.toHaveBeenCalled();
+  });
+
+  it('(b) upfront insert failed -> finalize INSERTs the terminal payload', async () => {
+    const repo = { insert: jest.fn(), update: jest.fn() };
+    const flushed = flushAssistant([], 'partial', 'error', { error: 'boom' });
+    await dispatchFinalize(repo, undefined, flushed);
+    expect(repo.update).not.toHaveBeenCalled();
+    expect(repo.insert).toHaveBeenCalledTimes(1);
+    const arg = repo.insert.mock.calls[0][0];
+    // The fallback insert carries the terminal content/status/metadata.
+    expect(arg.role).toBe('assistant');
+    expect(arg.content).toBe('partial');
+    expect(arg.status).toBe('error');
+    expect((arg.metadata as { error?: string }).error).toBe('boom');
+  });
+});

apps/server/src/core/ai-chat/ai-chat.controller.ts

@@ -107,7 +107,8 @@ export class AiChatController {
       title: chat.title ?? null,
       chatId: dto.chatId,
       rows,
-      lang: dto.lang ?? 'en',
+      // normalizeLang(undefined) already yields 'en', so no `?? 'en'` is needed.
+      lang: dto.lang,
     });
     return { markdown };
   }

apps/server/src/core/ai-chat/ai-chat.service.lifecycle.spec.ts

@@ -0,0 +1,61 @@
+import { Logger } from '@nestjs/common';
+import { AiChatService } from './ai-chat.service';
+
+/**
+ * Lifecycle unit tests for AiChatService.onModuleInit (#183 crash-recovery
+ * sweep). The sweep is BEST-EFFORT: a failure must be logged (warn) but must
+ * NEVER throw out of onModuleInit and block server startup. Exercised with a
+ * hand-rolled mock repo — no Nest graph, no DB. Only `aiChatMessageRepo` is
+ * touched by onModuleInit, so the other constructor deps are stubbed as never.
+ */
+describe('AiChatService.onModuleInit (startup sweep)', () => {
+  function makeService(sweepStreaming: jest.Mock) {
+    const aiChatMessageRepo = { sweepStreaming };
+    const service = new AiChatService(
+      {} as never, // ai
+      {} as never, // aiChatRepo
+      aiChatMessageRepo as never,
+      {} as never, // aiSettings
+      {} as never, // tools
+      {} as never, // mcpClients
+      {} as never, // aiAgentRoleRepo
+      {} as never, // pageRepo
+      {} as never, // pageAccess
+    );
+    return { service, aiChatMessageRepo };
+  }
+
+  afterEach(() => jest.restoreAllMocks());
+
+  it('happy path: calls sweepStreaming and resolves', async () => {
+    const sweepStreaming = jest.fn().mockResolvedValue(0);
+    const { service } = makeService(sweepStreaming);
+    await expect(service.onModuleInit()).resolves.toBeUndefined();
+    expect(sweepStreaming).toHaveBeenCalledTimes(1);
+  });
+
+  it('logs how many rows were swept when > 0', async () => {
+    const sweepStreaming = jest.fn().mockResolvedValue(3);
+    const logSpy = jest
+      .spyOn(Logger.prototype, 'log')
+      .mockImplementation(() => undefined);
+    const { service } = makeService(sweepStreaming);
+    await service.onModuleInit();
+    expect(logSpy).toHaveBeenCalledTimes(1);
+    expect(String(logSpy.mock.calls[0][0])).toContain('3');
+  });
+
+  it('sweepStreaming throws -> onModuleInit resolves (does NOT throw) and warns', async () => {
+    const sweepStreaming = jest
+      .fn()
+      .mockRejectedValue(new Error('db unavailable'));
+    const warnSpy = jest
+      .spyOn(Logger.prototype, 'warn')
+      .mockImplementation(() => undefined);
+    const { service } = makeService(sweepStreaming);
+    // Must not throw — a sweep failure may never block startup.
+    await expect(service.onModuleInit()).resolves.toBeUndefined();
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(String(warnSpy.mock.calls[0][0])).toContain('db unavailable');
+  });
+});

apps/server/src/core/ai-chat/ai-chat.service.spec.ts

@@ -4,7 +4,6 @@ import {
   serializeSteps,
   rowToUiMessage,
   prepareAgentStep,
-  buildPartialAssistantRecord,
   flushAssistant,
   chatStreamMetadata,
   accumulateStepUsage,
@@ -241,101 +240,13 @@ describe('prepareAgentStep', () => {
   });
 });
 
-/**
- * Unit test for buildPartialAssistantRecord: the pure helper that shapes the
- * assistant-message record persisted on a partial/failed turn (the streamText
- * onError / onAbort paths). It captures the PARTIAL answer the user already saw
- * (finished steps' text + tool parts, plus the in-progress step's text) so a
- * provider error / disconnect no longer throws the streamed answer away. Pinning
- * the record shape here covers the persist-partial logic without seaming
- * streamText itself.
- */
-describe('buildPartialAssistantRecord', () => {
-  type AnyPart = Record<string, unknown>;
-
-  it('records an empty turn with the error text (preserves old behavior)', () => {
-    const rec = buildPartialAssistantRecord(
-      [],
-      '',
-      'error',
-      '401: Unauthorized',
-    );
-    expect(rec).toEqual({
-      text: '',
-      toolCalls: null,
-      metadata: {
-        finishReason: 'error',
-        parts: [],
-        error: '401: Unauthorized',
-      },
-    });
-  });
-
-  it('persists in-progress text (no finished steps) as the partial answer', () => {
-    const rec = buildPartialAssistantRecord(
-      [],
-      'partial answer',
-      'error',
-      'boom',
-    );
-    expect(rec.text).toBe('partial answer');
-    expect(rec.metadata.parts).toEqual([
-      { type: 'text', text: 'partial answer' },
-    ]);
-    expect(rec.metadata.error).toBe('boom');
-  });
-
-  it('combines a finished tool step with trailing in-progress text', () => {
-    const steps = [
-      {
-        text: 'looked it up',
-        toolCalls: [
-          { toolCallId: 'c1', toolName: 'getPage', input: { id: 'p1' } },
-        ],
-        toolResults: [
-          { toolCallId: 'c1', toolName: 'getPage', output: { title: 'T' } },
-        ],
-      },
-    ];
-    const rec = buildPartialAssistantRecord(
-      steps,
-      ' and then',
-      'error',
-      'boom',
-    );
-    const parts = rec.metadata.parts as AnyPart[];
-    // The finished step's text part is present.
-    expect(parts).toContainEqual({ type: 'text', text: 'looked it up' });
-    // The paired tool call+result becomes an output-available part.
-    const toolPart = parts.find((p) => p.type === 'tool-getPage');
-    expect(toolPart).toBeDefined();
-    expect(toolPart!.state).toBe('output-available');
-    // The in-progress text is appended LAST so the parts match the stream order.
-    expect(parts[parts.length - 1]).toEqual({
-      type: 'text',
-      text: ' and then',
-    });
-    expect(rec.text).toBe('looked it up and then');
-    expect(rec.toolCalls).not.toBeNull();
-    expect(rec.metadata.error).toBe('boom');
-  });
-
-  it('omits the error key on the abort path (no errorText)', () => {
-    const rec = buildPartialAssistantRecord([], 'half', 'aborted');
-    expect(rec.metadata.finishReason).toBe('aborted');
-    expect('error' in rec.metadata).toBe(false);
-    expect(rec.text).toBe('half');
-  });
-});
-
 /**
  * flushAssistant (#183): the PURE row builder behind the step-granular durable
  * write path. It runs identically for the upfront insert (empty steps,
  * 'streaming'), every per-step update, and the terminal finalize — so a future
  * background worker can call the same function. These tests pin the four status
- * shapes and, critically, that `metadata.parts` stays IDENTICAL to the old
- * buildPartialAssistantRecord / assistantParts output (rowToUiMessage/findRecent
- * depend on it).
+ * shapes and the `metadata.parts` shape that rowToUiMessage/findRecent depend on
+ * (per-step text + tool parts via assistantParts, in-progress text appended).
  */
 describe('flushAssistant', () => {
   type AnyPart = Record<string, unknown>;
@@ -411,21 +322,24 @@ describe('flushAssistant', () => {
     });
   });
 
-  it('metadata.parts parity with buildPartialAssistantRecord (error path)', () => {
+  it('combines a finished tool step with trailing in-progress text (error path)', () => {
+    // The error path captures the PARTIAL answer the user already saw: each
+    // finished step's text + tool parts, then the in-progress step's text last.
     const flushed = flushAssistant([toolStep], ' and then', 'error', {
       error: 'boom',
     });
-    const legacy = buildPartialAssistantRecord(
-      [toolStep],
-      ' and then',
-      'error',
-      'boom',
-    );
-    // The whole metadata block (parts + finishReason + error) must match the
-    // legacy partial-record shape so rebuilt history is unchanged.
-    expect(flushed.metadata).toEqual(legacy.metadata);
-    expect(flushed.content).toBe(legacy.text);
-    expect(flushed.toolCalls).toEqual(legacy.toolCalls);
+    const parts = flushed.metadata.parts as AnyPart[];
+    expect(parts).toContainEqual({ type: 'text', text: 'looked it up' });
+    const toolPart = parts.find((p) => p.type === 'tool-getPage');
+    expect(toolPart!.state).toBe('output-available');
+    // In-progress text appended LAST so the parts match the stream order.
+    expect(parts[parts.length - 1]).toEqual({
+      type: 'text',
+      text: ' and then',
+    });
+    expect(flushed.content).toBe('looked it up and then');
+    expect(flushed.toolCalls).not.toBeNull();
+    expect(flushed.metadata.error).toBe('boom');
   });
 });
 

apps/server/src/core/ai-chat/ai-chat.service.ts

@@ -412,7 +412,10 @@ export class AiChatService implements OnModuleInit {
       });
       assistantId = seeded?.id;
     } catch (err) {
-      this.logger.error('Failed to insert upfront assistant row', err as Error);
+      this.logger.error(
+        `Failed to insert upfront assistant row (chat ${chatId}, workspace ${workspace.id})`,
+        err as Error,
+      );
     }
 
     // Per-step (non-terminal) update: persist the finished steps the moment a
@@ -453,7 +456,8 @@ export class AiChatService implements OnModuleInit {
     ): Promise<void> => {
       if (finalized) return;
       finalized = true;
-      if (!assistantId) {
+      const plan = planFinalizeAssistant(assistantId);
+      if (plan.kind === 'insert') {
         // The upfront insert failed: fall back to inserting the terminal row so
         // the turn is not lost entirely.
         try {
@@ -476,7 +480,7 @@ export class AiChatService implements OnModuleInit {
         return;
       }
       try {
-        await this.aiChatMessageRepo.update(assistantId, workspace.id, flushed);
+        await this.aiChatMessageRepo.update(plan.id, workspace.id, flushed);
       } catch (err) {
         this.logger.error('Failed to finalize assistant message', err as Error);
       }
@@ -552,6 +556,15 @@ export class AiChatService implements OnModuleInit {
           // pre-#183 onFinish record exactly; `inProgressText` is '' here (the last
           // step already finished). Final-step usage (usage.input+output) ≈ the
           // conversation's CURRENT context size, distinct from totalUsage.
+          //
+          // COLUMN-SEMANTICS NOTE (#183): `content` is built by flushAssistant as
+          // the CONCATENATION of every step's text (stepsText), whereas pre-#183
+          // it stored only the FINAL step's text. This is a deliberate, harmless
+          // change: the UI and the Markdown export render from `metadata.parts`
+          // (per-step text + tool parts), not from `content`; `content` is the
+          // plain-text projection (full-text search / fallback). A multi-step
+          // turn's `content` therefore now holds all steps' prose, not just the
+          // last block.
           await finalizeAssistant(
             flushAssistant(steps as StepLike[], '', 'completed', {
               finishReason: finishReason as string,
@@ -1088,6 +1101,21 @@ export interface AssistantFlush {
   status: 'streaming' | 'completed' | 'error' | 'aborted';
 }
 
+/**
+ * Pure decision for the terminal finalize (#183): given whether the upfront
+ * assistant row exists (`assistantId`), choose whether the terminal payload is
+ * written by UPDATEing that row or — when the upfront insert failed and there is
+ * no id — by INSERTing a fresh terminal row so the turn is not lost entirely.
+ * Returns `{ kind: 'update', id }` or `{ kind: 'insert' }`. Extracted so the
+ * fallback-insert branch (the only safety against losing a turn whose upfront
+ * insert failed) is unit-testable without seaming streamText.
+ */
+export function planFinalizeAssistant(
+  assistantId: string | undefined,
+): { kind: 'update'; id: string } | { kind: 'insert' } {
+  return assistantId ? { kind: 'update', id: assistantId } : { kind: 'insert' };
+}
+
 /**
  * PURE assistant-row builder (#183 step-granular durability). Given the turn's
  * accumulated steps + the in-progress (not-yet-finished) text + the lifecycle
@@ -1097,9 +1125,8 @@ export interface AssistantFlush {
  * worker can call it identically, so it must stay a pure function of its inputs
  * (NO `this`, no IO).
  *
- * `metadata.parts` is built by the EXACT same logic the old
- * buildPartialAssistantRecord used (assistantParts over finished steps, then the
- * in-progress text appended as a trailing text part), so rowToUiMessage /
+ * `metadata.parts` is built by assistantParts over the finished steps, then the
+ * in-progress text appended as a trailing text part, so rowToUiMessage /
  * findRecent keep replaying the turn unchanged. `metadata.finishReason`,
  * `metadata.error`, `metadata.usage` and `metadata.contextTokens` are attached
  * only when provided/relevant, matching the pre-#183 onFinish/onError records.
@@ -1152,34 +1179,6 @@ export function flushAssistant(
   };
 }
 
-/**
- * Build the assistant-message record persisted on a partial/failed turn (the
- * streamText onError / onAbort paths). Captures the partial answer the user
- * already saw: each finished step's text + tool parts (via assistantParts),
- * then the in-progress step's text appended last. When `errorText` is provided
- * it is recorded in metadata.error so the cause shows in history; an aborted
- * turn passes none. Pure, so the partial-recording shape is unit-testable
- * without seaming streamText.
- *
- * Thin wrapper over {@link flushAssistant} (retained for the existing unit
- * tests and its historical `{ text, toolCalls, metadata }` shape).
- */
-export function buildPartialAssistantRecord(
-  steps: ReadonlyArray<StepLike> | undefined,
-  inProgressText: string,
-  finishReason: 'error' | 'aborted',
-  errorText?: string,
-): { text: string; toolCalls: unknown; metadata: Record<string, unknown> } {
-  const flushed = flushAssistant(steps, inProgressText, finishReason, {
-    error: errorText,
-  });
-  return {
-    text: flushed.content,
-    toolCalls: flushed.toolCalls,
-    metadata: flushed.metadata,
-  };
-}
-
 /**
  * Reduce SDK step objects to a compact, JSON-serializable trace for the
  * `tool_calls` column. Stores only what the UI action-log and history need —

apps/server/src/core/ai-chat/chat-markdown.util.ts

@@ -48,9 +48,12 @@ interface UsageLike {
   reasoningTokens?: number;
 }
 
-/** Localized label table. Keep the keys identical to the client's i18n keys so
- *  the two exports read the same. Only role + tool-action labels are localized;
- *  everything structural is an English constant in the renderer. */
+/** Localized label table. The client-side Markdown builder was removed by #183
+ *  (the export is now server-side only), so this no longer mirrors a second
+ *  exporter — instead the tool-action labels are kept in parity with the
+ *  on-screen action-log labels in the client's `tool-parts.tsx` (`toolLabelKey`)
+ *  so the export reads the same as the UI. Only role + tool-action labels are
+ *  localized; everything structural is an English constant in the renderer. */
 const LABELS: Record<
   ExportLang,
   {
@@ -232,7 +235,7 @@ export function buildChatMarkdown(args: {
   };
   const errorOf = (row: AiChatMessage): string | undefined => {
     const meta = (row.metadata ?? {}) as { error?: string };
-    return meta.error ?? undefined;
+    return meta.error;
   };
 
   // Metadata bullet list. Total tokens is only shown when there is a sum.