refactor(review): address PR #185 review (lease leak, tests, changelog, jsonb seam)

8-point multi-aspect review of the batch PR; security/regressions were clean.

1. Lease leak: the #180 reorder moved `toolsFor` (which leases external MCP
   clients, refCount+1) ahead of buildSystemPrompt + forUser, but the only
   release (closeExternalClients) was bound to the streamText callbacks. A throw
   in between leaked the lease (refCount stuck, undici sockets held until
   restart). Define closeExternalClients right after the lease and wrap
   buildSystemPrompt+forUser in try/catch that closes-then-rethrows.
2. Cover the patch_node/delete_node dup-id refusal (#159 #6): extract the guard
   into a pure `assertUnambiguousMatch` (node-ops) and unit-test 0/1/>1.
3. Regress the body-before-title order (#159 #10): mock-HTTP test (collab fails
   fast against a server with no WS upgrade) asserts /pages/update (title) is
   NEVER posted when the body write fails — for updatePage AND updatePageJson.
4. CHANGELOG [Unreleased]: #180, #168 (Added); #163 (Fixed).
5. Add the missing en-US i18n keys (Back to references / {{label}}).
6. Drop the duplicate content/empty/blank cases in ai-chat.prompt.spec.ts (they
   repeat the buildMcpToolingBlock unit tests); keep only sandwich placement +
   both-safety-copies.
7. CI Postgres pg16 -> pg18 (match docker-compose).
8. jsonb decode seam: shared `parseJsonbValue(value, guard)` in database/utils.ts
   holds the legacy double-encoding self-heal in one place; parseToolAllowlist /
   parseModelConfig keep only a type-guard.

Verified: server build + 124 unit + 15 integration; mcp 311; prettier clean.

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

apps/client/public/locales/en-US/translation.json

@@ -1078,6 +1078,8 @@
   "Undo": "Undo",
   "Redo": "Redo",
   "Backlinks": "Backlinks",
+  "Back to references": "Back to references",
+  "Back to reference {{label}}": "Back to reference {{label}}",
   "Last updated by": "Last updated by",
   "Last updated": "Last updated",
   "Stats": "Stats",

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

@@ -174,47 +174,10 @@ describe('buildSystemPrompt mcp tooling guidance', () => {
   const workspace = { name: 'Acme' } as unknown as Workspace;
   const SAFETY_MARKER = 'Operating rules (always in effect)';
 
-  it('renders the server name, tool prefix and text when guidance is present', () => {
-    const prompt = buildSystemPrompt({
-      workspace,
-      mcpInstructions: [
-        {
-          serverName: 'Tavily',
-          toolPrefix: 'tavily',
-          instructions: 'Use tavily_search for fresh web facts; cite sources.',
-        },
-      ],
-    });
-    expect(prompt).toContain('<mcp_tooling');
-    expect(prompt).toContain('Tavily');
-    // The header names the namespace prefix as `<prefix>_*`.
-    expect(prompt).toContain('tavily_*');
-    expect(prompt).toContain(
-      'Use tavily_search for fresh web facts; cite sources.',
-    );
-  });
-
-  it('renders nothing for an empty list', () => {
-    const prompt = buildSystemPrompt({ workspace, mcpInstructions: [] });
-    expect(prompt).not.toContain('<mcp_tooling');
-  });
-
-  it('renders nothing for an undefined list', () => {
-    const prompt = buildSystemPrompt({ workspace });
-    expect(prompt).not.toContain('<mcp_tooling');
-  });
-
-  it('renders nothing when every entry has blank text', () => {
-    const prompt = buildSystemPrompt({
-      workspace,
-      mcpInstructions: [
-        { serverName: 'A', toolPrefix: 'a', instructions: '   ' },
-        { serverName: 'B', toolPrefix: 'b', instructions: '' },
-      ],
-    });
-    expect(prompt).not.toContain('<mcp_tooling');
-  });
-
+  // The block's CONTENT and its empty/undefined/all-blank handling are covered by
+  // the buildMcpToolingBlock unit tests below; here we only pin the INTEGRATION
+  // invariants that are unique to buildSystemPrompt: sandwich placement and that
+  // both safety copies survive.
   it('places the block inside the safety sandwich, after context, before the trailing SAFETY', () => {
     const prompt = buildSystemPrompt({
       workspace,

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

@@ -332,38 +332,14 @@ export class AiChatService {
       );
     }
 
-    const system = buildSystemPrompt({
-      workspace,
-      adminPrompt: resolved?.systemPrompt,
-      // The role (pre-resolved by the controller) REPLACES the persona layer;
-      // the safety framework is still appended by buildSystemPrompt.
-      roleInstructions: role?.instructions,
-      // Server-validated open page (authoritative title), not the client value.
-      openedPage: openPageContext,
-      // Guidance only for servers that connected and yielded ≥1 callable tool.
-      mcpInstructions: external.instructions,
-    });
-
-    // Pass the resolved chatId so the write tools can mint provenance tokens
-    // (access + collab) carrying { actor:'agent', aiChatId: chatId }, making
-    // agent REST/collab writes attributable and non-spoofable (§6.5/§6.6).
-    const docmostTools = await this.tools.forUser(
-      user,
-      sessionId,
-      workspace.id,
-      chatId,
-      // Same server-validated open page used by the system prompt above; exposed
-      // to the model via getCurrentPage so page identity (and the AUTHORITATIVE
-      // title) survives prompt mangling and client title spoofing (#159).
-      openPageContext,
-    );
-
-    const tools = { ...external.tools, ...docmostTools };
-
     // Close every external client EXACTLY ONCE across the turn's terminal
     // callbacks (onFinish/onError/onAbort all fire at most once collectively,
-    // but guard anyway). Close errors are swallowed so they never break the
-    // response.
+    // but guard anyway). DEFINED HERE — before the prompt/toolset are built — so
+    // that if buildSystemPrompt or forUser throws AFTER the external lease was
+    // taken (toolsFor above), the lease is still released. Otherwise its refCount
+    // stays >= 1 forever and the external undici sockets leak until restart
+    // (#180 reorder moved toolsFor ahead of these; #185 review). Close errors are
+    // swallowed so they never break the response.
     let clientsClosed = false;
     const closeExternalClients = async (): Promise<void> => {
       if (clientsClosed) return;
@@ -381,6 +357,44 @@ export class AiChatService {
       );
     };
 
+    // Build the system prompt + Docmost toolset. If either throws after the
+    // external MCP lease was taken above, release the lease before rethrowing so
+    // the leased transports are not leaked (#185 review).
+    let system: string;
+    let docmostTools: Awaited<ReturnType<AiChatToolsService['forUser']>>;
+    try {
+      system = buildSystemPrompt({
+        workspace,
+        adminPrompt: resolved?.systemPrompt,
+        // The role (pre-resolved by the controller) REPLACES the persona layer;
+        // the safety framework is still appended by buildSystemPrompt.
+        roleInstructions: role?.instructions,
+        // Server-validated open page (authoritative title), not the client value.
+        openedPage: openPageContext,
+        // Guidance only for servers that connected and yielded ≥1 callable tool.
+        mcpInstructions: external.instructions,
+      });
+
+      // Pass the resolved chatId so the write tools can mint provenance tokens
+      // (access + collab) carrying { actor:'agent', aiChatId: chatId }, making
+      // agent REST/collab writes attributable and non-spoofable (§6.5/§6.6).
+      docmostTools = await this.tools.forUser(
+        user,
+        sessionId,
+        workspace.id,
+        chatId,
+        // Same server-validated open page used by the system prompt above;
+        // exposed to the model via getCurrentPage so page identity (and the
+        // AUTHORITATIVE title) survives prompt mangling / client title spoofing.
+        openPageContext,
+      );
+    } catch (err) {
+      await closeExternalClients();
+      throw err;
+    }
+
+    const tools = { ...external.tools, ...docmostTools };
+
     // Persist the assistant message. Used by onFinish (full result) and the
     // abort/error paths (partial result). Guarded so we persist at most once.
     let persisted = false;

apps/server/src/database/repos/ai-agent-roles/ai-agent-roles.repo.ts

@@ -1,7 +1,7 @@
 import { Injectable } from '@nestjs/common';
 import { InjectKysely } from 'nestjs-kysely';
 import { KyselyDB, KyselyTransaction } from '../../types/kysely.types';
-import { dbOrTx, jsonbBind } from '../../utils';
+import { dbOrTx, jsonbBind, parseJsonbValue } from '../../utils';
 import { AiAgentRole } from '@docmost/db/types/entity.types';
 
 /** The jsonb shape persisted in `model_config` (loosely typed for the column). */
@@ -183,17 +183,13 @@ export class AiAgentRoleRepo {
 export function parseModelConfig(
   value: unknown,
 ): Record<string, unknown> | null {
-  let v: unknown = value;
-  if (typeof v === 'string') {
-    try {
-      v = JSON.parse(v); // legacy double-encoded read
-    } catch {
-      return null;
-    }
-  }
-  return v !== null && typeof v === 'object' && !Array.isArray(v)
-    ? (v as Record<string, unknown>)
-    : null;
+  // Shape guard only; the legacy double-encoding self-heal lives in
+  // parseJsonbValue (database/utils.ts).
+  return parseJsonbValue(
+    value,
+    (v): v is Record<string, unknown> =>
+      v !== null && typeof v === 'object' && !Array.isArray(v),
+  );
 }
 
 /** Normalize a DB row so `modelConfig` is always an object or null. The cast

apps/server/src/database/repos/ai-chat/ai-mcp-server.repo.ts

@@ -1,7 +1,7 @@
 import { Injectable, Logger } from '@nestjs/common';
 import { InjectKysely } from 'nestjs-kysely';
 import { KyselyDB, KyselyTransaction } from '../../types/kysely.types';
-import { dbOrTx, jsonbBind } from '../../utils';
+import { dbOrTx, jsonbBind, parseJsonbValue } from '../../utils';
 import { AiMcpServer } from '@docmost/db/types/entity.types';
 
 const logger = new Logger('AiMcpServerRepo');
@@ -161,17 +161,13 @@ export function blankToNull(value: string | null | undefined): string | null {
  * array with a non-string element all become null (unrestricted).
  */
 export function parseToolAllowlist(value: unknown): string[] | null {
-  let v: unknown = value;
-  if (typeof v === 'string') {
-    try {
-      v = JSON.parse(v); // legacy double-encoded read
-    } catch {
-      return null;
-    }
-  }
-  return Array.isArray(v) && v.every((x) => typeof x === 'string')
-    ? (v as string[])
-    : null;
+  // Shape guard only; the legacy double-encoding self-heal lives in
+  // parseJsonbValue (database/utils.ts).
+  return parseJsonbValue(
+    value,
+    (v): v is string[] =>
+      Array.isArray(v) && v.every((x) => typeof x === 'string'),
+  );
 }
 
 /**

apps/server/src/database/utils.ts

@@ -64,3 +64,29 @@ export function jsonbBind<T>(
   }
   return sql<T>`${JSON.stringify(value)}::text::jsonb`;
 }
+
+/**
+ * READ-side counterpart to {@link jsonbBind}: tolerantly decode a jsonb value
+ * read back from the DB and validate its shape with `guard`. THE single place
+ * the legacy double-encoding self-heal lives, so repos keep only a type-guard.
+ *
+ * A row written by the old `::jsonb` bind round-trips as a JSON STRING (see the
+ * quirk in jsonbBind), so the driver hands back e.g. `'["a"]'` / `'{"k":1}'`
+ * rather than the structure. This parses such a string once, then applies the
+ * caller's `guard`. Returns `null` for null / an unparseable string / a value
+ * the guard rejects (so a corrupt or wrong-shaped value degrades to "unset").
+ */
+export function parseJsonbValue<T>(
+  value: unknown,
+  guard: (v: unknown) => v is T,
+): T | null {
+  let v: unknown = value;
+  if (typeof v === 'string') {
+    try {
+      v = JSON.parse(v); // legacy double-encoded read
+    } catch {
+      return null;
+    }
+  }
+  return guard(v) ? v : null;
+}