fix(ai-chat): «send now» во время detached-run — авторитетный серверный stop + ограниченный ретрай 409 (#396)

В автономном режиме «Interrupt and send now» во время живого detached-run делал
только локальный stop() (abort SSE), который сервер игнорирует (run живёт по
дизайну #184/#234), поэтому onFinish→flush новый POST упирался в гейт «один
активный run на чат» → 409 A_RUN_ALREADY_ACTIVE, новый turn не стартовал.
handleStop делает правильно (доп. onServerStop), sendNow — нет. Вариант A
(клиентский, горячий путь сервера не тронут):

- sendNow в автономном режиме дополнительно зовёт onServerStop(chatId) (или
  откладывает через stopPendingRef, если chatId ещё не усыновлён — как
  handleStop) и взводит one-shot supersedeRetryRef ДО stop();
- транспорт-fetch на supersede-отправке (и только на ней) ретраит РОВНО 409 с
  body.code===A_RUN_ALREADY_ACTIVE до 4 попыток с бэкоффом 150/300/600ms;
  onServerStop гарантирует осадку run → ретрай сходится. Обычная отправка (не
  взведён флаг) падает на 409 мгновенно. isRunAlreadyActive читает
  response.clone() → тело оригинала возвращается потребителю нетронутым.
  409 всегда до записи user-строки (pre-check/beginRun раньше insert) → повтор
  POST безопасен, дублей нет.

Внутренний цикл: 2 прохода. Ревью нашло CRITICAL: supersedeRetryRef застревал
взведённым, когда sendNow взвёл, но POST не ушёл (promoted head удалён →
flushNext() false; либо wasResumed-return) — следующая обычная отправка молча
ретраила настоящий 409. Починка: разоружать флаг симметрично остальным one-shot
(в ветке !flushNext() и в isStreaming-defuse-эффекте); транспорт read-and-clear
на входе каждой отправки. Мутационно: убрать disarm → strand-тест краснеет
(4 вызова вместо 1). Легаси-режим не тронут (регресс-гард).

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

.github/workflows/test.yml

@@ -1,13 +1,5 @@
 name: Test
 
-# NO `paths:` filter on purpose (issue #447). The tool-spec REGISTRY is split
-# across two packages that MUST stay in sync: the specs live in `packages/mcp`
-# but the parity/tier guard tests that read them live in the `apps/server` jest
-# suite. A PR touching only `packages/mcp/**` must therefore still run the SERVER
-# suite (and vice-versa), or an in-app wiring break slips through green and only
-# surfaces on develop after merge. The `test` job below runs BOTH suites via
-# `pnpm -r test` on every PR; the dedicated `mcp-server-parity` job makes that
-# cross-package gate explicit and fast. Do not add a `paths:` filter here.
 on:
   pull_request:
   workflow_call:
@@ -140,53 +132,3 @@ jobs:
       # isolated `docmost_test` DB and migrates it to latest.
       - name: Run server integration tests
         run: pnpm --filter server test:int
-
-  # Cross-package tool-spec parity gate (issue #447). The tool-spec registry lives
-  # in `packages/mcp` but its parity/tier guard tests live in the `apps/server`
-  # jest suite, so a PR touching ONLY one of the two packages must still run BOTH
-  # sides — otherwise an in-app wiring break (e.g. PR #434 drawio) passes the mcp
-  # suite green and only surfaces on develop after merge. The `test` job already
-  # runs everything via `pnpm -r test`; this job is a fast, explicitly-named guard
-  # that runs the mcp `node --test` suite AND the server tool-guard jest specs
-  # together, so the coupling is visible and can never be accidentally split by a
-  # path filter. No Postgres/Redis needed: these specs mock the DB/loader.
-  mcp-server-parity:
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Set up pnpm
-        uses: pnpm/action-setup@v4
-
-      - name: Set up Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: pnpm
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      # Shared deps first (build/ dirs are gitignored; see test.yml build order).
-      - name: Build editor-ext
-        run: pnpm --filter @docmost/editor-ext build
-
-      - name: Build prosemirror-markdown
-        run: pnpm --filter @docmost/prosemirror-markdown build
-
-      # Build the mcp package so build/ carries a FRESH REGISTRY_STAMP (#447): the
-      # build runs gen-registry-stamp.mjs before tsc, so a build/ vs src/ skew
-      # cannot slip into the tests that exercise the loader's stale-check.
-      - name: Build mcp (regenerates REGISTRY_STAMP)
-        run: pnpm --filter @docmost/mcp build
-
-      # mcp side: the standalone MCP server's own tool-spec / instructions guards.
-      - name: Run mcp tool-spec suite
-        run: pnpm --filter @docmost/mcp test
-
-      # server side: the parity + tier guards that read packages/mcp/src/tool-specs
-      # and assert the in-app AI-chat wiring matches it.
-      - name: Run server tool-spec guard specs
-        run: pnpm --filter server exec jest shared-tool-specs.contract tool-tiers ai-chat-tools.service --runInBand

.gitignore

@@ -19,11 +19,6 @@ packages/prosemirror-markdown/build/
 # markdown convention; the package is private and rebuilt at deploy.
 packages/mcp/build/
 
-# mcp REGISTRY_STAMP codegen output (issue #447). Regenerated into src/ by
-# scripts/gen-registry-stamp.mjs on every `build`/`pretest` (before tsc), so it
-# is a build artifact like build/ — never committed, always fresh.
-packages/mcp/src/registry-stamp.generated.ts
-
 # Logs
 logs
 *.log

AGENTS.md

@@ -248,22 +248,6 @@ pnpm collab:dev              # run the collaboration server process standalone (
 > that order). Reach for it whenever you run a consumer package's checks on their
 > own rather than through the full `pnpm build`.
 
-> **Editing an MCP tool spec requires a rebuild (issue #447).** The running
-> server loads the **compiled** `packages/mcp/build/` of `@docmost/mcp` (via the
-> runtime loader in `apps/server/src/core/ai-chat/tools/docmost-client.loader.ts`),
-> but the parity/tier guard tests read `packages/mcp/src/tool-specs.ts`. So if you
-> edit `tool-specs.ts` (any tool name, description, tier, catalog line, or input
-> schema) **without rebuilding**, `build/` and `src/` silently diverge — the tests
-> stay green while the server serves the OLD tools. To close that gap, the build
-> emits a `REGISTRY_STAMP` (a deterministic hash of the tool-specs content, via
-> `scripts/gen-registry-stamp.mjs` before `tsc`); on dev/test startup the loader
-> recomputes it from `src/` and **refuses to start with a "@docmost/mcp build is
-> stale …" error** on a mismatch (a pure no-op in prod, where only `build/` ships).
-> After editing tool specs, rebuild:
-> ```bash
-> pnpm --filter @docmost/mcp build     # or: pnpm --filter @docmost/mcp watch
-> ```
-
 **Lint** (per package — there is no root lint script):
 ```bash
 pnpm --filter server lint    # eslint --fix on server .ts

apps/client/src/features/ai-chat/components/chat-thread.test.tsx

@@ -28,7 +28,10 @@ const h = vi.hoisted(() => ({
         body: Record<string, unknown>;
       }) => { body: Record<string, unknown> };
       prepareReconnectToStreamRequest?: () => { api?: string };
-      fetch?: (input: unknown, init?: { method?: string }) => Promise<unknown>;
+      fetch?: (
+        input: unknown,
+        init?: { method?: string; body?: unknown },
+      ) => Promise<unknown>;
     },
   },
 }));
@@ -200,6 +203,244 @@ describe("ChatThread — send now (#198)", () => {
   });
 });
 
+// #396: in autonomous mode a live sendNow must additionally request the
+// AUTHORITATIVE server stop of the detached run (a local abort is only a client
+// disconnect the server ignores) and arm a bounded 409 retry so the re-POST
+// converges once the one-active-run slot frees. Legacy mode is unchanged.
+describe("ChatThread — send now server-stop + supersede retry (#396)", () => {
+  beforeEach(resetState);
+  afterEach(cleanup);
+
+  // A settled assistant tail => no mount resume (attemptResumeRef false), so the
+  // "Send now" button is visible for the NEW local streaming turn while
+  // autonomous runs are enabled.
+  const settledTail = () => [
+    row("u1", "user", undefined, "hi"),
+    row("a1", "assistant", "succeeded", "done"),
+  ];
+
+  it("autonomous: sendNow during a live stream calls onServerStop with the chat id", () => {
+    const { onServerStop } = renderThread({
+      autonomousRunsEnabled: true,
+      initialRows: settledTail(),
+    });
+    fireEvent.click(screen.getByTestId("queue-btn"));
+    fireEvent.click(screen.getByLabelText("Send now"));
+
+    expect(h.state.stop).toHaveBeenCalledTimes(1);
+    expect(onServerStop).toHaveBeenCalledWith("c1");
+  });
+
+  it("legacy (autonomous off): sendNow does NOT call onServerStop and does NOT retry the send", async () => {
+    const { onServerStop } = renderThread({
+      autonomousRunsEnabled: false,
+      initialRows: settledTail(),
+    });
+    fireEvent.click(screen.getByTestId("queue-btn"));
+    fireEvent.click(screen.getByLabelText("Send now"));
+    expect(onServerStop).not.toHaveBeenCalled();
+
+    // The supersede retry must NOT be armed: a POST that 409s is returned as-is
+    // (single fetch, no retry).
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValue(
+        new Response(JSON.stringify({ code: "A_RUN_ALREADY_ACTIVE" }), {
+          status: 409,
+        }),
+      );
+    vi.stubGlobal("fetch", fetchMock);
+    let res!: Response;
+    await act(async () => {
+      res = (await h.state.transport!.fetch!("http://x", {
+        method: "POST",
+        body: "{}",
+      })) as Response;
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(res.status).toBe(409);
+  });
+
+  it("armed supersede send retries 409 A_RUN_ALREADY_ACTIVE and succeeds once the slot frees", async () => {
+    renderThread({ autonomousRunsEnabled: true, initialRows: settledTail() });
+    // Arm the retry by performing a live sendNow (autonomous branch sets the ref).
+    fireEvent.click(screen.getByTestId("queue-btn"));
+    fireEvent.click(screen.getByLabelText("Send now"));
+
+    const fetchMock = vi
+      .fn()
+      // First POST: the old detached run still holds the slot -> 409.
+      .mockResolvedValueOnce(
+        new Response(JSON.stringify({ code: "A_RUN_ALREADY_ACTIVE" }), {
+          status: 409,
+        }),
+      )
+      // Retry: the server stop settled the old run -> 200.
+      .mockResolvedValueOnce(new Response("ok", { status: 200 }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    let res!: Response;
+    await act(async () => {
+      res = (await h.state.transport!.fetch!("http://x", {
+        method: "POST",
+        body: "{}",
+      })) as Response;
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(res.status).toBe(200);
+  });
+
+  it("supersede retry is one-shot: a later send (ref cleared) does NOT retry a 409", async () => {
+    renderThread({ autonomousRunsEnabled: true, initialRows: settledTail() });
+    fireEvent.click(screen.getByTestId("queue-btn"));
+    fireEvent.click(screen.getByLabelText("Send now")); // arms the one-shot
+
+    // First armed send: immediately succeeds, consuming the arm.
+    let fetchMock = vi
+      .fn()
+      .mockResolvedValue(new Response("ok", { status: 200 }));
+    vi.stubGlobal("fetch", fetchMock);
+    await act(async () => {
+      await h.state.transport!.fetch!("http://x", {
+        method: "POST",
+        body: "{}",
+      });
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // A subsequent send is NOT armed -> a 409 is returned as-is (no retry).
+    fetchMock = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ code: "A_RUN_ALREADY_ACTIVE" }), {
+        status: 409,
+      }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    let res!: Response;
+    await act(async () => {
+      res = (await h.state.transport!.fetch!("http://x", {
+        method: "POST",
+        body: "{}",
+      })) as Response;
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(res.status).toBe(409);
+  });
+
+  it("supersede retry is bounded: exhaustion surfaces the 409 error", async () => {
+    renderThread({ autonomousRunsEnabled: true, initialRows: settledTail() });
+    fireEvent.click(screen.getByTestId("queue-btn"));
+    fireEvent.click(screen.getByLabelText("Send now"));
+
+    // Every attempt 409s -> after 4 attempts the last 409 surfaces.
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ code: "A_RUN_ALREADY_ACTIVE" }), {
+        status: 409,
+      }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    let res!: Response;
+    await act(async () => {
+      res = (await h.state.transport!.fetch!("http://x", {
+        method: "POST",
+        body: "{}",
+      })) as Response;
+    });
+    // 4 attempts total (1 immediate + 3 backoff retries), then give up.
+    expect(fetchMock).toHaveBeenCalledTimes(4);
+    expect(res.status).toBe(409);
+  });
+
+  it("armed supersede send does NOT retry a non-409 status", async () => {
+    renderThread({ autonomousRunsEnabled: true, initialRows: settledTail() });
+    fireEvent.click(screen.getByTestId("queue-btn"));
+    fireEvent.click(screen.getByLabelText("Send now"));
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValue(new Response("boom", { status: 500 }));
+    vi.stubGlobal("fetch", fetchMock);
+    let res!: Response;
+    await act(async () => {
+      res = (await h.state.transport!.fetch!("http://x", {
+        method: "POST",
+        body: "{}",
+      })) as Response;
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(res.status).toBe(500);
+  });
+
+  // Strand-path regression: sendNow arms the supersede retry, but if the promoted
+  // head is removed before the abort's onFinish lands, flushNext() sends nothing
+  // (returns false) and NO re-POST consumes the arm. The arm must be disarmed on
+  // that no-send branch so the NEXT unrelated NORMAL send does not inherit it and
+  // silently retry a genuine 409 (e.g. a legitimate two-tab conflict) 4x instead
+  // of surfacing it immediately.
+  it("strand-path: a stranded supersede arm (flushNext no-send) does NOT retry a later normal 409", async () => {
+    renderThread({ autonomousRunsEnabled: true, initialRows: settledTail() });
+    // Arm the retry via a live autonomous sendNow (promotes the head + arms).
+    fireEvent.click(screen.getByTestId("queue-btn"));
+    fireEvent.click(screen.getByLabelText("Send now"));
+
+    // Remove the promoted head BEFORE the abort lands, so flushNext() returns
+    // false (no POST) and the arm would strand without the disarm fix.
+    fireEvent.click(screen.getByLabelText("Remove queued message"));
+
+    // The abort's onFinish now takes the flushOnAbortRef branch, calls flushNext()
+    // which finds an empty queue and returns false -> the no-send disarm must run.
+    act(() => {
+      h.state.onFinish?.({
+        message: { id: "a1", role: "assistant", parts: [] },
+        isAbort: true,
+        isDisconnect: false,
+        isError: false,
+      });
+    });
+    // No re-POST was sent (nothing to flush).
+    expect(h.state.sendMessage).not.toHaveBeenCalled();
+
+    // A subsequent NORMAL send that 409s must be returned as-is (exactly 1 fetch):
+    // the stranded arm must NOT cause the genuine 409 to be retried.
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValue(
+        new Response(JSON.stringify({ code: "A_RUN_ALREADY_ACTIVE" }), {
+          status: 409,
+        }),
+      );
+    vi.stubGlobal("fetch", fetchMock);
+    let res!: Response;
+    await act(async () => {
+      res = (await h.state.transport!.fetch!("http://x", {
+        method: "POST",
+        body: "{}",
+      })) as Response;
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(res.status).toBe(409);
+  });
+
+  it("armed supersede send does NOT retry a 409 with a different (non-A_RUN_ALREADY_ACTIVE) body", async () => {
+    renderThread({ autonomousRunsEnabled: true, initialRows: settledTail() });
+    fireEvent.click(screen.getByTestId("queue-btn"));
+    fireEvent.click(screen.getByLabelText("Send now"));
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ code: "SOMETHING_ELSE" }), {
+        status: 409,
+      }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    let res!: Response;
+    await act(async () => {
+      res = (await h.state.transport!.fetch!("http://x", {
+        method: "POST",
+        body: "{}",
+      })) as Response;
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(res.status).toBe(409);
+  });
+});
+
 // #388: the editor selection is snapshotted at send time and nested inside
 // openPage on the wire. The getter is read live from a ref, so each send ships a
 // fresh snapshot.

apps/client/src/features/ai-chat/components/chat-thread.tsx

@@ -70,6 +70,36 @@ const RECONNECT_MAX_ATTEMPTS = 5;
 // Backoff before attempt N (1-based): 1s, 2s, 4s, 8s, 16s.
 const RECONNECT_BASE_DELAY_MS = 1000;
 
+// #396: bounded retry for the "Interrupt and send now" re-send when it races the
+// authoritative server stop of the just-superseded detached run. The re-POST can
+// arrive before the old run has released the one-active-run slot, so the server
+// returns 409 A_RUN_ALREADY_ACTIVE. The server stop guarantees the slot frees, so
+// a few short backoffs converge. 4 total attempts: attempt 1 fires immediately,
+// then these are the waits BEFORE attempts 2, 3 and 4 (150ms, 300ms, 600ms). If
+// all 4 attempts 409, the last 409 surfaces (the banner) — acceptable per #396.
+const SUPERSEDE_RETRY_DELAYS_MS = [150, 300, 600];
+// The server error code that means "another run is already active for this chat".
+const A_RUN_ALREADY_ACTIVE = "A_RUN_ALREADY_ACTIVE";
+
+/**
+ * #396: defensively decide whether a 409 response is the one-active-run gate
+ * rejection (code A_RUN_ALREADY_ACTIVE) vs. some other 409. Reads a CLONE so the
+ * original response body stays intact for the caller when it is returned as-is.
+ * Any parse failure or unexpected shape => false (do NOT retry).
+ */
+async function isRunAlreadyActive(response: Response): Promise<boolean> {
+  try {
+    const body = (await response.clone().json()) as unknown;
+    return (
+      typeof body === "object" &&
+      body !== null &&
+      (body as { code?: unknown }).code === A_RUN_ALREADY_ACTIVE
+    );
+  } catch {
+    return false;
+  }
+}
+
 /** The page the user is currently viewing, sent as chat context. */
 export interface OpenPageContext {
   id: string;
@@ -326,6 +356,26 @@ export default function ChatThread({
   const flushOnAbortRef = useRef(false);
   const interruptNextSendRef = useRef(false);
 
+  // #396: one-shot arm for the bounded 409 A_RUN_ALREADY_ACTIVE retry on the
+  // "Interrupt and send now" re-send in autonomous mode. sendNow triggers the
+  // authoritative server stop of the detached run, but that stop and the
+  // onFinish->flushNext re-POST race: the new POST can hit the one-active-run
+  // gate before the old detached run has settled, yielding a spurious 409. When
+  // this ref is armed, the transport's send path retries that 409 with a short
+  // bounded backoff (the server stop guarantees convergence). A normal send (ref
+  // not armed) must STILL fail a 409 instantly (e.g. a genuine two-tab conflict).
+  //
+  // INVARIANT: sendNow arms this only to be consumed by the ONE re-POST that
+  // flushNext fires from onFinish. But that re-POST does not always happen (the
+  // promoted head may be gone, the finish may be a resumed turn, or the arm may
+  // race a stale finish). To keep the arm strictly one-shot it is disarmed on
+  // EVERY path where the paired interrupt one-shots (flushOnAbortRef /
+  // interruptNextSendRef) are cleared without a POST: the transport POST branch
+  // consumes it (read-and-clear), the onFinish `!flushNext()` no-send branch
+  // clears it, and the isStreaming-defuse effect clears it symmetrically. So it
+  // can never leak into a later, unrelated send and retry that send's genuine 409.
+  const supersedeRetryRef = useRef(false);
+
   // #234 F5: the user pressed Stop while streaming a BRAND-NEW chat whose server
   // chat id has not been adopted yet (the `start` chunk carrying it hadn't landed
   // when Stop was pressed). A local SSE abort alone does NOT stop the DETACHED
@@ -382,7 +432,43 @@ export default function ChatThread({
           }`,
         }),
         fetch: async (input: RequestInfo | URL, init: RequestInit = {}) => {
-          if ((init.method ?? "GET") !== "GET") return fetch(input, init); // send path untouched
+          if ((init.method ?? "GET") !== "GET") {
+            // Send path (POST). #396: read-and-clear the one-shot supersede arm
+            // here so it is strictly scoped to THIS send. When unarmed, behave
+            // exactly as before — a single fetch, a 409 surfaces instantly (a
+            // genuine two-tab conflict must NOT be retried).
+            const supersede = supersedeRetryRef.current;
+            supersedeRetryRef.current = false;
+            if (!supersede) return fetch(input, init);
+            // Buffer a ReadableStream body once so each retry can replay it.
+            // DefaultChatTransport sends the body as a JSON STRING (replayable as
+            // is), but guard defensively in case a future SDK streams it.
+            let sendInit = init;
+            if (init.body instanceof ReadableStream) {
+              const buffered = await new Response(init.body).arrayBuffer();
+              sendInit = { ...init, body: buffered };
+            }
+            // Bounded retry: attempt 1 fires immediately, then wait between
+            // attempts per SUPERSEDE_RETRY_DELAYS_MS. Retry ONLY on a real
+            // 409 A_RUN_ALREADY_ACTIVE; any other status/body is returned as-is.
+            for (let attempt = 0; ; attempt++) {
+              const response = await fetch(input, sendInit);
+              if (
+                response.status !== 409 ||
+                attempt >= SUPERSEDE_RETRY_DELAYS_MS.length ||
+                !(await isRunAlreadyActive(response))
+              ) {
+                return response;
+              }
+              // The old detached run has not released the one-active-run slot
+              // yet; the server stop we requested guarantees it will, so back off
+              // and re-POST (the 409 fired before the user message was persisted,
+              // so re-POSTing is safe — no duplicate rows).
+              await new Promise((r) =>
+                setTimeout(r, SUPERSEDE_RETRY_DELAYS_MS[attempt]),
+              );
+            }
+          }
           // Reconnect GET: the SDK passes no AbortSignal, so wire our own controller
           // for observer Stop / unmount abort.
           const controller = new AbortController();
@@ -562,9 +648,14 @@ export default function ChatThread({
         setStopNotice(null);
         // If the promoted head vanished (e.g. the user removed it before the
         // abort landed) flushNext sends nothing — clear the one-shot interrupt
-        // tag so it can't leak onto the next unrelated send. On a real send the
-        // tag is consumed by prepareSendMessagesRequest and stays untouched.
-        if (!flushNext()) interruptNextSendRef.current = false;
+        // tag AND the #396 supersede arm so neither can leak onto the next
+        // unrelated send (no re-POST will consume the arm here). On a real send
+        // the tag is consumed by prepareSendMessagesRequest and the arm by the
+        // transport POST branch, so both stay untouched then.
+        if (!flushNext()) {
+          interruptNextSendRef.current = false;
+          supersedeRetryRef.current = false;
+        }
         return;
       }
       if (isAbort || isDisconnect || isError) return;
@@ -873,6 +964,30 @@ export default function ChatThread({
         setQueue(promoteToHead(queuedRef.current, id));
         flushOnAbortRef.current = true;
         interruptNextSendRef.current = true;
+        // #396: in autonomous mode the turn is a DETACHED run — a local stop()
+        // is only a client disconnect the server ignores, so the run keeps going.
+        // The onFinish->flushNext re-POST would then hit the one-active-run gate
+        // and get a spurious 409 A_RUN_ALREADY_ACTIVE. Mirror handleStop: request
+        // the AUTHORITATIVE server stop so the detached run settles, and arm the
+        // one-shot bounded 409 retry BEFORE stop() so the re-send converges once
+        // the slot frees. Read chatId live from chatIdRef (adopted at the `start`
+        // chunk). If it is not known yet (brand-new chat, first moment of its
+        // first turn), defer the server stop via stopPendingRef exactly as
+        // handleStop does — the onServerChatId adoption effect fires it once the
+        // id lands; the retry stays armed so the re-send still converges then.
+        if (autonomousRunsEnabled) {
+          supersedeRetryRef.current = true; // arm the bounded 409 retry
+          if (chatIdRef.current) {
+            onServerStop?.(chatIdRef.current);
+          } else {
+            // Same #234-F5 sub-window limitation documented in handleStop: if the
+            // local abort below cancels the reader before the `start` chunk lands,
+            // the adoption effect never runs and the deferred stop never fires. Not
+            // a regression; at minimum we don't strand refs (the isStreaming effect
+            // defuses stopPendingRef on the next turn start).
+            stopPendingRef.current = true;
+          }
+        }
         stop(); // -> onFinish({ isAbort: true }) flushes the promoted head
       } else {
         // Nothing to interrupt: just send it now (no interrupt note).
@@ -884,7 +999,7 @@ export default function ChatThread({
         sendMessageRef.current?.({ text: msg.text });
       }
     },
-    [setQueue, stop, setResumedTurnPair],
+    [setQueue, stop, setResumedTurnPair, autonomousRunsEnabled, onServerStop],
   );
 
   // Stop the current turn. ALWAYS abort the local SSE (`stop()`) so the composer
@@ -944,6 +1059,13 @@ export default function ChatThread({
       setStopNotice(null);
       flushOnAbortRef.current = false;
       interruptNextSendRef.current = false;
+      // #396: symmetric with the other one-shot interrupt flags — defuse a stale
+      // supersede arm that was set but whose expected re-POST never fired (the
+      // turn finished in the same tick as the click, or the promoted head was
+      // gone), so it can never leak into this (or a later) turn's send and retry
+      // that send's genuine 409. A legit arm is consumed by the transport POST
+      // branch before this new turn streams, so this does not clobber it.
+      supersedeRetryRef.current = false;
       // #234 F5: a new turn is starting — drop any pending deferred-stop from a
       // previous turn that never adopted an id, so it can never fire against this
       // (or a later) unrelated turn's run. A deferred stop for the CURRENT turn is

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

@@ -1,17 +1,6 @@
 import { AiChatToolsService } from './ai-chat-tools.service';
 import * as loader from './docmost-client.loader';
 import type { DocmostClientLike } from './docmost-client.loader';
-
-// Test-double type for the loopback client. `DocmostClientLike` is now DERIVED
-// from the real `DocmostClient` (issue #446), so its method RETURN types are the
-// concrete client shapes. These stubs deliberately return minimal recording
-// shapes (e.g. `{ ok: true }`), which no longer satisfy those concrete returns —
-// so the doubles are typed with the same method NAMES but loose async returns.
-// Each is still cast to `DocmostClientLike` at the (return-erased) mock site, so
-// the positional-call type-safety on the PRODUCTION client is unaffected.
-type FakeDocmostClient = Partial<
-  Record<keyof DocmostClientLike, (...args: any[]) => Promise<any>>
->;
 // The real zod-agnostic shared tool-spec registry. It has no runtime deps, so
 // importing the TS source directly keeps these mocks honest: the service builds
 // the shared tools from exactly the specs the package ships, not a hand-stub.
@@ -42,7 +31,7 @@ describe('AiChatToolsService deletePage guardrail (H4)', () => {
 
   // Minimal fake DocmostClient: only the write methods the tools touch need to
   // exist; deletePage records its args. No network, no ESM import.
-  const fakeClient: FakeDocmostClient = {
+  const fakeClient: Partial<DocmostClientLike> = {
     deletePage: (...args: unknown[]) => {
       deletePageCalls.push(args);
       return Promise.resolve({ success: true });
@@ -171,7 +160,7 @@ describe('AiChatToolsService deletePage guardrail (H4)', () => {
 describe('AiChatToolsService expanded toolset guardrails', () => {
   // No client method is invoked here — every assertion is on tool presence /
   // input schema — so an empty fake client is sufficient.
-  const fakeClient: FakeDocmostClient = {};
+  const fakeClient: Partial<DocmostClientLike> = {};
 
   const tokenServiceStub = {
     generateAccessToken: jest.fn().mockResolvedValue('access-token'),
@@ -276,7 +265,7 @@ describe('AiChatToolsService node-arg JSON-string coercion', () => {
   const insertNodeCalls: unknown[][] = [];
   const updatePageJsonCalls: unknown[][] = [];
 
-  const fakeClient: FakeDocmostClient = {
+  const fakeClient: Partial<DocmostClientLike> = {
     patchNode: (...args: unknown[]) => {
       patchNodeCalls.push(args);
       return Promise.resolve({ ok: true });
@@ -450,7 +439,7 @@ describe('AiChatToolsService node-arg JSON-string coercion', () => {
  * getOutline) are exercised here end-to-end through forUser().
  */
 describe('AiChatToolsService model-friendly input validation (#190)', () => {
-  const fakeClient: FakeDocmostClient = {};
+  const fakeClient: Partial<DocmostClientLike> = {};
   const tokenServiceStub = {
     generateAccessToken: jest.fn().mockResolvedValue('access-token'),
     generateCollabToken: jest.fn().mockResolvedValue('collab-token'),
@@ -568,7 +557,7 @@ describe('AiChatToolsService #294 changed execute wirings', () => {
     tableDeleteRow: [],
     tableUpdateCell: [],
   };
-  const fakeClient: FakeDocmostClient = {
+  const fakeClient: Partial<DocmostClientLike> = {
     movePage: (...args: unknown[]) => {
       calls.movePage.push(args);
       return Promise.resolve({ success: true });
@@ -677,7 +666,7 @@ describe('AiChatToolsService #410 footnote + image tools', () => {
     insertImage: [],
     replaceImage: [],
   };
-  const fakeClient: FakeDocmostClient = {
+  const fakeClient: Partial<DocmostClientLike> = {
     insertFootnote: (...args: unknown[]) => {
       calls.insertFootnote.push(args);
       return Promise.resolve({ success: true, footnoteId: 'fn1', reused: false });

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

@@ -26,100 +26,6 @@ import {
   type ToolCatalogEntry,
 } from './tool-tiers';
 
-/**
- * Compile-time contract (issue #446): the in-app tool `execute` closures below
- * call the loopback `DocmostClient` POSITIONALLY (e.g.
- * `client.drawioGet(pageId, node, format ?? 'xml')`). Those closures receive an
- * AI-SDK-erased (`any`) input, so a positional call inside them is NOT checked
- * against the real signature — a parameter reorder/type-change in
- * `packages/mcp/src/client.ts` would otherwise reach production as a runtime
- * "wrong argument" tool failure with zero compile signal (the restored #294
- * debt). This never-called function reproduces every positional call with
- * correctly-typed placeholder arguments against the DERIVED `DocmostClientLike`
- * (a `Pick` of the real `DocmostClient`), so any such reorder/rename becomes a
- * SERVER COMPILE ERROR here. It emits nothing (types only) and is never invoked;
- * keep each call in lockstep with the matching `execute` body below.
- */
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-function __assertClientCallContract(client: DocmostClientLike): void {
-  // Placeholders standing in for the AI-SDK-erased execute inputs. Their types
-  // are deliberately concrete so the positional calls are checked end-to-end.
-  const s = '' as string;
-  const n = 0 as number;
-  const node: unknown = null;
-  const edits: Array<{ find: string; replace: string; replaceAll?: boolean }> =
-    [];
-  const cells: string[] = [];
-  const align = undefined as 'left' | 'center' | 'right' | undefined;
-
-  // --- read ---
-  void client.search(s, undefined, n);
-  void client.getPage(s);
-  void client.getPageRaw(s);
-  void client.getWorkspace();
-  void client.getSpaces();
-  void client.listPages(s, n, true);
-  void client.listSidebarPages(s, s);
-  void client.getOutline(s);
-  void client.getPageJson(s);
-  void client.getNode(s, s);
-  void client.searchInPage(s, s, {
-    regex: true,
-    caseSensitive: true,
-    limit: n,
-  });
-  void client.getTable(s, s);
-  void client.listComments(s, true);
-  void client.getComment(s);
-  void client.checkNewComments(s, s, s);
-  void client.listShares();
-  void client.listPageHistory(s, s);
-  void client.getPageHistory(s);
-  void client.diffPageVersions(s, s, s);
-  void client.exportPageMarkdown(s);
-  // --- write (page) ---
-  void client.createPage(s, s, s, s);
-  void client.updatePage(s, s, s);
-  void client.renamePage(s, s);
-  void client.movePage(s, s, s);
-  void client.deletePage(s);
-  void client.editPageText(s, edits);
-  void client.patchNode(s, s, node);
-  void client.insertNode(s, node, {
-    position: 'append',
-    anchorNodeId: s,
-    anchorText: s,
-  });
-  void client.deleteNode(s, s);
-  void client.updatePageJson(s, node, s);
-  void client.tableInsertRow(s, s, cells, n);
-  void client.tableDeleteRow(s, s, n);
-  void client.tableUpdateCell(s, s, n, n, s);
-  void client.copyPageContent(s, s);
-  void client.importPageMarkdown(s, s);
-  void client.sharePage(s, true);
-  void client.unsharePage(s);
-  void client.restorePageVersion(s);
-  void client.transformPage(s, s, { dryRun: true });
-  void client.stashPage(s);
-  // --- write (image / footnote), in-app since #410 ---
-  void client.insertFootnote(s, s, s);
-  void client.insertImage(s, s, {
-    align,
-    alt: s,
-    replaceText: s,
-    afterText: s,
-  });
-  void client.replaceImage(s, s, s, { align, alt: s });
-  // --- draw.io diagrams (#423) ---
-  void client.drawioGet(s, s, 'xml');
-  void client.drawioCreate(s, { position: 'append', anchorNodeId: s }, s, s);
-  void client.drawioUpdate(s, s, s, s);
-  // --- write (comment) ---
-  void client.createComment(s, s, 'inline', s, s, s);
-  void client.resolveComment(s, true);
-}
-
 /**
  * Per-user, per-request adapter that exposes Docmost READ operations to the
  * agent as AI SDK tools (STAGE A = read only).

apps/server/src/core/ai-chat/tools/comment-signal-inapp.spec.ts

@@ -7,16 +7,6 @@ import type {
   DocmostClientLike,
   CommentSignalTrackerLike,
 } from './docmost-client.loader';
-
-// Test-double type for the loopback client. `DocmostClientLike` is now DERIVED
-// from the real `DocmostClient` (issue #446), so its method RETURN types are the
-// concrete client shapes. These probe stubs deliberately return minimal shapes
-// (e.g. `getPageRaw` yielding only `{ title }`), so the doubles use the same
-// method NAMES but loose async returns; each is cast to `DocmostClientLike` at
-// the (return-erased) mock site, leaving production positional-call safety intact.
-type FakeDocmostClient = Partial<
-  Record<keyof DocmostClientLike, (...args: any[]) => Promise<any>>
->;
 import { SHARED_TOOL_SPECS } from '../../../../../../packages/mcp/src/tool-specs';
 // The REAL shared tracker factory, imported from source (same cross-boundary
 // approach the tool-specs spec uses) so the in-app wiring is exercised against
@@ -278,7 +268,7 @@ describe('AiChatToolsService forUser + comment signal (real tracker)', () => {
   // seeded at forUser time).
   const future = new Date(Date.now() + 3_600_000).toISOString();
 
-  function buildService(fakeClient: FakeDocmostClient) {
+  function buildService(fakeClient: Partial<DocmostClientLike>) {
     jest.spyOn(loader, 'loadDocmostMcp').mockResolvedValue({
       DocmostClient: function () {
         return fakeClient as DocmostClientLike;
@@ -327,7 +317,7 @@ describe('AiChatToolsService forUser + comment signal (real tracker)', () => {
   afterEach(() => jest.restoreAllMocks());
 
   it('emits the signal (model-only) on a non-comment tool when a new comment exists', async () => {
-    const fakeClient: FakeDocmostClient = {
+    const fakeClient: Partial<DocmostClientLike> = {
       getPage: async () => ({
         data: { title: 'Иранские языки', content: 'body' },
         success: true,
@@ -352,7 +342,7 @@ describe('AiChatToolsService forUser + comment signal (real tracker)', () => {
   });
 
   it('does NOT add the signal to the listComments tool itself (tautological)', async () => {
-    const fakeClient: FakeDocmostClient = {
+    const fakeClient: Partial<DocmostClientLike> = {
       listComments: async () => ({
         items: [{ createdAt: future }],
         resolvedThreadsHidden: 0,
@@ -366,7 +356,7 @@ describe('AiChatToolsService forUser + comment signal (real tracker)', () => {
   });
 
   it('no new comments => tool output is byte-identical AND the model sees no signal', async () => {
-    const fakeClient: FakeDocmostClient = {
+    const fakeClient: Partial<DocmostClientLike> = {
       getPage: async () => ({
         data: { title: 'T', content: 'body' },
         success: true,
@@ -382,7 +372,7 @@ describe('AiChatToolsService forUser + comment signal (real tracker)', () => {
   });
 
   it('injection-safety: a malicious page title cannot forge a second signal', async () => {
-    const fakeClient: FakeDocmostClient = {
+    const fakeClient: Partial<DocmostClientLike> = {
       getPage: async () => ({
         data: { title: 'body-title', content: 'body' },
         success: true,

apps/server/src/core/ai-chat/tools/docmost-client.loader.spec.ts

@@ -1,173 +0,0 @@
-import { createHash } from 'node:crypto';
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { computeSrcRegistryStamp } from './docmost-client.loader';
-
-// The exact message the loader throws on a build/src skew (issue #447). Kept as a
-// literal here so a reworded prod message reddens this test (the message is a
-// developer-facing contract: it tells them how to fix it).
-const STALE_BUILD_MESSAGE =
-  '@docmost/mcp build is stale (tool-specs changed since last build) — run: pnpm --filter @docmost/mcp build';
-
-// Replica of the loader's inline stale-check predicate + throw from
-// `loadDocmostMcp`. That guard is not independently exported (it lives inside the
-// dynamic-import IIFE, wired to a fixed `require.resolve('@docmost/mcp')`), so we
-// exercise the exact same three-condition logic against a stamp produced by the
-// REAL `computeSrcRegistryStamp`. This documents and locks the throw/no-throw
-// behaviour; if the prod predicate changes, this replica must change with it.
-function assertStaleGuard(
-  srcStamp: string | null,
-  registryStamp: string | undefined,
-): void {
-  if (
-    srcStamp !== null &&
-    typeof registryStamp === 'string' &&
-    srcStamp !== registryStamp
-  ) {
-    throw new Error(STALE_BUILD_MESSAGE);
-  }
-}
-
-// Build a throwaway `<pkg>/build/index.js` + optional `<pkg>/src/tool-specs.ts`
-// layout so `computeSrcRegistryStamp(<pkg>/build/index.js)` resolves src the same
-// way the loader does (dirname(dirname(entry))/src/tool-specs.ts).
-function makeFakePackage(toolSpecsSource: string | null): {
-  entry: string;
-  cleanup: () => void;
-} {
-  const root = mkdtempSync(join(tmpdir(), 'mcp-stamp-'));
-  const buildDir = join(root, 'build');
-  mkdirSync(buildDir, { recursive: true });
-  const entry = join(buildDir, 'index.js');
-  writeFileSync(entry, '// fake @docmost/mcp build entry\n', 'utf8');
-  if (toolSpecsSource !== null) {
-    const srcDir = join(root, 'src');
-    mkdirSync(srcDir, { recursive: true });
-    writeFileSync(join(srcDir, 'tool-specs.ts'), toolSpecsSource, 'utf8');
-  }
-  return { entry, cleanup: () => rmSync(root, { recursive: true, force: true }) };
-}
-
-describe('computeSrcRegistryStamp (#447 stale-build guard)', () => {
-  it('returns null when src/tool-specs.ts is absent (prod no-op path)', () => {
-    // A prod image ships only build/, no src/ — the guard must be a silent no-op.
-    const { entry, cleanup } = makeFakePackage(null);
-    try {
-      expect(computeSrcRegistryStamp(entry)).toBeNull();
-    } finally {
-      cleanup();
-    }
-  });
-
-  it('returns null for a bogus package entry (swallowed error path)', () => {
-    // A resolution/read hiccup must NEVER break startup — it resolves to null.
-    expect(
-      computeSrcRegistryStamp('/no/such/pkg/build/index.js'),
-    ).toBeNull();
-  });
-
-  it('computes a 64-char sha256 hex when src/tool-specs.ts exists', () => {
-    const { entry, cleanup } = makeFakePackage('export const specs = 1;\n');
-    try {
-      const stamp = computeSrcRegistryStamp(entry);
-      expect(stamp).toMatch(/^[0-9a-f]{64}$/);
-    } finally {
-      cleanup();
-    }
-  });
-
-  it('normalizes CRLF->LF and strips a single trailing newline', () => {
-    // A CRLF+trailing-newline variant of the same content hashes identically to
-    // the bare-LF form — the guard must not fire on a checkout-style difference.
-    const bare = makeFakePackage('alpha\nbeta');
-    const crlfTrailing = makeFakePackage('alpha\r\nbeta\r\n');
-    try {
-      expect(computeSrcRegistryStamp(crlfTrailing.entry)).toBe(
-        computeSrcRegistryStamp(bare.entry),
-      );
-    } finally {
-      bare.cleanup();
-      crlfTrailing.cleanup();
-    }
-  });
-
-  // CROSS-IMPL EQUALITY (covers reviewer suggestion 2). The SAME fixed input and
-  // EXPECTED hash are asserted in the mcp-side node test
-  // (packages/mcp/test/unit/registry-stamp.test.mjs) against the codegen's
-  // `computeRegistryStamp`. Asserting the SAME pair here against the loader's
-  // `computeSrcRegistryStamp` proves both implementations normalize+hash
-  // identically; a divergence in EITHER side reddens one of the two tests.
-  it('matches the documented cross-impl hash for a fixed input', () => {
-    const FIXED_INPUT = 'line1\r\nline2\n';
-    const EXPECTED =
-      '683376e290829b482c2655745caffa7a1dccfa10afaa62dac2b42dd6c68d0f83';
-    const { entry, cleanup } = makeFakePackage(FIXED_INPUT);
-    try {
-      expect(computeSrcRegistryStamp(entry)).toBe(EXPECTED);
-    } finally {
-      cleanup();
-    }
-  });
-
-  it('the documented EXPECTED is the normalize+sha256 of the fixed input', () => {
-    // Proves EXPECTED is not a magic constant but the documented computation.
-    const FIXED_INPUT = 'line1\r\nline2\n';
-    const normalized = FIXED_INPUT.replace(/\r\n/g, '\n').replace(/\n$/, '');
-    const expected = createHash('sha256')
-      .update(normalized, 'utf8')
-      .digest('hex');
-    const { entry, cleanup } = makeFakePackage(FIXED_INPUT);
-    try {
-      expect(computeSrcRegistryStamp(entry)).toBe(expected);
-    } finally {
-      cleanup();
-    }
-  });
-});
-
-describe('loadDocmostMcp stale-check predicate (#447)', () => {
-  it('THROWS the exact stale message when src stamp != built REGISTRY_STAMP', () => {
-    const { entry, cleanup } = makeFakePackage('export const specs = 1;\n');
-    try {
-      const srcStamp = computeSrcRegistryStamp(entry);
-      expect(srcStamp).not.toBeNull();
-      // Simulate a stale build: build/ carries a DIFFERENT stamp than src.
-      expect(() => assertStaleGuard(srcStamp, 'a'.repeat(64))).toThrow(
-        STALE_BUILD_MESSAGE,
-      );
-    } finally {
-      cleanup();
-    }
-  });
-
-  it('does NOT throw when src stamp equals the built REGISTRY_STAMP', () => {
-    const { entry, cleanup } = makeFakePackage('export const specs = 1;\n');
-    try {
-      const srcStamp = computeSrcRegistryStamp(entry);
-      // Fresh build: build/ stamp == src stamp -> guard is a no-op.
-      expect(() => assertStaleGuard(srcStamp, srcStamp as string)).not.toThrow();
-    } finally {
-      cleanup();
-    }
-  });
-
-  it('does NOT throw when src is absent (prod: srcStamp === null)', () => {
-    // Even against a present-but-mismatched REGISTRY_STAMP, a null src stamp
-    // (prod image with build/ only) must skip the check entirely.
-    expect(() => assertStaleGuard(null, 'a'.repeat(64))).not.toThrow();
-  });
-
-  it('does NOT throw when REGISTRY_STAMP is absent (pre-#447 build)', () => {
-    // An older @docmost/mcp build has no REGISTRY_STAMP export; the guard must be
-    // a no-op so an out-of-date build never wrongly blocks startup.
-    const { entry, cleanup } = makeFakePackage('export const specs = 1;\n');
-    try {
-      const srcStamp = computeSrcRegistryStamp(entry);
-      expect(() => assertStaleGuard(srcStamp, undefined)).not.toThrow();
-    } finally {
-      cleanup();
-    }
-  });
-});

apps/server/src/core/ai-chat/tools/docmost-client.loader.ts

@@ -1,93 +1,264 @@
-import { createHash } from 'node:crypto';
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import type { DocmostClient, SharedToolSpec } from '@docmost/mcp';
-
-// Re-export SharedToolSpec so downstream server modules keep a single import
-// path (they import it from this loader). The shape is DERIVED from the package
-// entry, not re-declared here — see the import above (issue #446).
-export type { SharedToolSpec } from '@docmost/mcp';
 
 /**
- * The exact set of `DocmostClient` methods the per-user in-app tool adapter
- * consumes. This is the AUTHORITATIVE list of the client surface the server
- * depends on; the adapter calls these methods POSITIONALLY, so this set is what
- * the derived type below type-checks against the real class (issue #446).
+ * Minimal structural type for the `DocmostClient` class we consume from the
+ * ESM-only `@docmost/mcp` package. We only need the constructor + the read/write
+ * methods used by the per-user tool adapter; the full client surface lives in
+ * `packages/mcp/src/client.ts`. Signatures here mirror that file exactly.
+ *
+ * DRIFT GUARD: the method NAMES below are runtime-checked against the real
+ * `DocmostClient` by `packages/mcp/test/unit/client-host-contract.test.mjs`
+ * (which can import the ESM class directly). If you rename/remove a method here
+ * or in client.ts, that test fails — so a stale mirror cannot silently ship a
+ * runtime "x is not a function" into an agent tool call. Keep the two in sync.
+ *
+ * STAGED PLAN — full derivation `DocmostClientLike = <real DocmostClient type>`
+ * (issue #193, layer 3) is intentionally NOT done; it stays a hand-mirror for
+ * now because of two verified blockers across the ESM(mcp)/CJS(server) boundary:
+ *   1. `@docmost/mcp` emits NO declaration files (its tsconfig has no
+ *      `declaration`, package.json has no `types`/types-export) and the server
+ *      tsconfig has no path mapping for it — the server only loads it via the
+ *      runtime `import()` trick below, so there is no type to import today.
+ *   2. The real client methods have inferred, CONCRETE return types; the in-app
+ *      tool adapter reads results through loose `Record<string,unknown>` returns
+ *      + `as` casts (e.g. `(result?.data ?? {}) as { title?: string }`).
+ *      Deriving the exact type would make those casts non-overlapping ("may be a
+ *      mistake") and break the build, and `Partial<DocmostClientLike>` test stubs
+ *      would have to satisfy the full concrete surface.
+ * To do it safely later (incrementally): (a) turn on `declaration: true` in
+ * packages/mcp/tsconfig.json + add a `types` export condition and commit the
+ * emitted `.d.ts`; (b) `import type { DocmostClient } from '@docmost/mcp'` here
+ * and replace this interface with a `Pick<DocmostClient, ...>` of the consumed
+ * methods; (c) audit every `as` cast in ai-chat-tools.service.ts against the now
+ * concrete return types (double-cast through `unknown` only where genuinely
+ * needed); (d) keep the runtime guard test as a belt-and-braces check. Until
+ * then the guard test above is the cheap, behaviour-neutral protection.
  */
-type DocmostClientMethod =
+export interface DocmostClientLike {
   // --- read ---
-  | 'search'
-  | 'getPage'
-  | 'getPageRaw'
-  | 'getWorkspace'
-  | 'getSpaces'
-  | 'listPages'
-  | 'listSidebarPages'
-  | 'getOutline'
-  | 'getPageJson'
-  | 'getNode'
-  | 'searchInPage'
-  | 'getTable'
-  | 'listComments'
-  | 'getComment'
-  | 'checkNewComments'
-  | 'listShares'
-  | 'listPageHistory'
-  | 'getPageHistory'
-  | 'diffPageVersions'
-  | 'exportPageMarkdown'
+  search(
+    query: string,
+    spaceId?: string,
+    limit?: number,
+  ): Promise<{ items: unknown[]; success: boolean }>;
+  getPage(
+    pageId: string,
+  ): Promise<{ data: Record<string, unknown>; success: boolean }>;
+  // Light raw page info (`/pages/info`): title + slugId + ProseMirror content,
+  // WITHOUT the Markdown render / subpage expansion getPage does. Used by the
+  // comment-signal probe to read just the page title on a hit.
+  getPageRaw(pageId: string): Promise<Record<string, unknown> | null>;
+  getWorkspace(): Promise<{ data: Record<string, unknown>; success: boolean }>;
+  getSpaces(): Promise<unknown[]>;
+  listPages(
+    spaceId?: string,
+    limit?: number,
+    tree?: boolean,
+  ): Promise<unknown[]>;
+  listSidebarPages(spaceId: string, pageId?: string): Promise<unknown[]>;
+  getOutline(pageId: string): Promise<Record<string, unknown>>;
+  getPageJson(pageId: string): Promise<Record<string, unknown>>;
+  getNode(pageId: string, nodeId: string): Promise<Record<string, unknown>>;
+  searchInPage(
+    pageId: string,
+    query: string,
+    opts?: { regex?: boolean; caseSensitive?: boolean; limit?: number },
+  ): Promise<Record<string, unknown>>;
+  getTable(pageId: string, tableRef: string): Promise<Record<string, unknown>>;
+  // Returns `{ items, resolvedThreadsHidden }`. DEFAULT (includeResolved unset/
+  // false) hides resolved threads wholesale; pass true for the full feed.
+  listComments(
+    pageId: string,
+    includeResolved?: boolean,
+  ): Promise<{ items: unknown[]; resolvedThreadsHidden: number }>;
+  getComment(
+    commentId: string,
+  ): Promise<{ data: Record<string, unknown>; success: boolean }>;
+  checkNewComments(
+    spaceId: string,
+    since: string,
+    parentPageId?: string,
+  ): Promise<unknown>;
+  listShares(): Promise<unknown[]>;
+  listPageHistory(
+    pageId: string,
+    cursor?: string,
+  ): Promise<{ items: unknown[]; nextCursor: string | null }>;
+  getPageHistory(historyId: string): Promise<Record<string, unknown>>;
+  diffPageVersions(
+    pageId: string,
+    from?: string,
+    to?: string,
+  ): Promise<Record<string, unknown>>;
+  exportPageMarkdown(pageId: string): Promise<string>;
   // --- write (page) ---
-  | 'createPage'
-  | 'updatePage'
-  | 'renamePage'
-  | 'movePage'
-  | 'deletePage'
-  | 'editPageText'
-  | 'patchNode'
-  | 'insertNode'
-  | 'deleteNode'
-  | 'updatePageJson'
-  | 'tableInsertRow'
-  | 'tableDeleteRow'
-  | 'tableUpdateCell'
-  | 'copyPageContent'
-  | 'importPageMarkdown'
-  | 'sharePage'
-  | 'unsharePage'
-  | 'restorePageVersion'
-  | 'transformPage'
-  | 'stashPage'
-  // --- write (image / footnote), in-app since #410 ---
-  | 'insertImage'
-  | 'replaceImage'
-  | 'insertFootnote'
+  createPage(
+    title: string,
+    content: string,
+    spaceId: string,
+    parentPageId?: string,
+  ): Promise<{ data: Record<string, unknown>; success: boolean }>;
+  // Markdown content update via the collab path (carries provenance via the
+  // collab-token provider). Optionally also updates the title.
+  updatePage(
+    pageId: string,
+    content: string,
+    title?: string,
+  ): Promise<Record<string, unknown>>;
+  // Title-only rename via REST.
+  renamePage(
+    pageId: string,
+    title: string,
+  ): Promise<Record<string, unknown>>;
+  // Move via REST. parentPageId null => move to space root.
+  movePage(
+    pageId: string,
+    parentPageId: string | null,
+    position?: string,
+  ): Promise<unknown>;
+  // SOFT delete only (POST /pages/delete with { pageId }). NEVER permanent.
+  deletePage(pageId: string): Promise<unknown>;
+  editPageText(
+    pageId: string,
+    edits: Array<{ find: string; replace: string; replaceAll?: boolean }>,
+  ): Promise<Record<string, unknown>>;
+  patchNode(
+    pageId: string,
+    nodeId: string,
+    node: unknown,
+  ): Promise<Record<string, unknown>>;
+  insertNode(
+    pageId: string,
+    node: unknown,
+    opts: {
+      position: 'before' | 'after' | 'append';
+      anchorNodeId?: string;
+      anchorText?: string;
+    },
+  ): Promise<Record<string, unknown>>;
+  deleteNode(
+    pageId: string,
+    nodeId: string,
+  ): Promise<Record<string, unknown>>;
+  updatePageJson(
+    pageId: string,
+    doc?: unknown,
+    title?: string,
+  ): Promise<Record<string, unknown>>;
+  // Attach an author-inline footnote after the first occurrence of anchorText;
+  // numbering + the footnotes list are derived server-side.
+  insertFootnote(
+    pageId: string,
+    anchorText: string,
+    text: string,
+  ): Promise<Record<string, unknown>>;
+  // Download a web image and insert it into the page (append, or replace/after a
+  // text anchor). `url` is the image http(s) URL.
+  insertImage(
+    pageId: string,
+    url: string,
+    opts?: {
+      align?: 'left' | 'center' | 'right';
+      alt?: string;
+      replaceText?: string;
+      afterText?: string;
+    },
+  ): Promise<Record<string, unknown>>;
+  // Swap an existing image (by its attachmentId) for a new one fetched from a web
+  // URL, repointing every reference in the live document.
+  replaceImage(
+    pageId: string,
+    oldAttachmentId: string,
+    url: string,
+    opts?: { align?: 'left' | 'center' | 'right'; alt?: string },
+  ): Promise<Record<string, unknown>>;
   // --- draw.io diagrams (#423, stage 1) ---
-  | 'drawioGet'
-  | 'drawioCreate'
-  | 'drawioUpdate'
+  // Read a diagram as decoded mxGraph XML (default) or the raw .drawio.svg.
+  // meta.hash is the optimistic-lock key drawioUpdate expects as baseHash.
+  drawioGet(
+    pageId: string,
+    node: string,
+    format?: 'xml' | 'svg',
+  ): Promise<Record<string, unknown>>;
+  // Lint mxGraph XML, build the .drawio.svg attachment and insert a drawio node.
+  drawioCreate(
+    pageId: string,
+    where: {
+      position: 'before' | 'after' | 'append';
+      anchorNodeId?: string;
+      anchorText?: string;
+    },
+    xml: string,
+    title?: string,
+  ): Promise<Record<string, unknown>>;
+  // Optimistic-locked full replacement of a diagram (baseHash from drawioGet).
+  drawioUpdate(
+    pageId: string,
+    node: string,
+    xml: string,
+    baseHash: string,
+  ): Promise<Record<string, unknown>>;
+  tableInsertRow(
+    pageId: string,
+    tableRef: string,
+    cells: string[],
+    index?: number,
+  ): Promise<Record<string, unknown>>;
+  tableDeleteRow(
+    pageId: string,
+    tableRef: string,
+    index: number,
+  ): Promise<Record<string, unknown>>;
+  tableUpdateCell(
+    pageId: string,
+    tableRef: string,
+    row: number,
+    col: number,
+    text: string,
+  ): Promise<Record<string, unknown>>;
+  copyPageContent(
+    sourcePageId: string,
+    targetPageId: string,
+  ): Promise<Record<string, unknown>>;
+  importPageMarkdown(
+    pageId: string,
+    fullMarkdown: string,
+  ): Promise<Record<string, unknown>>;
+  sharePage(
+    pageId: string,
+    searchIndexing?: boolean,
+  ): Promise<Record<string, unknown>>;
+  unsharePage(pageId: string): Promise<Record<string, unknown>>;
+  restorePageVersion(historyId: string): Promise<Record<string, unknown>>;
+  // The opts type declares deleteComments? to match the real client signature,
+  // but the agent tool NEVER sets it (comment deletion stays unreachable).
+  transformPage(
+    pageId: string,
+    transformJs: string,
+    opts?: { dryRun?: boolean; deleteComments?: boolean },
+  ): Promise<Record<string, unknown>>;
   // --- write (comment) ---
-  | 'createComment'
-  | 'resolveComment';
-
-/**
- * The client surface the per-user tool adapter consumes, DERIVED from the real
- * `DocmostClient` type in `@docmost/mcp` (issue #446, restored #294 debt). This
- * replaces the former hand-mirror of ~45 method signatures.
- *
- * `import type` (above) is fully ERASED at compile time, so nothing is actually
- * imported from the ESM-only package at runtime — the server still loads the
- * class through the dynamic `import()` trick in `loadDocmostMcp` below; this is
- * purely a compile-time type. Deriving via `Pick` means a parameter reorder or a
- * type change to any of these methods in `client.ts` now becomes a SERVER
- * COMPILE ERROR at the positional call sites in ai-chat-tools.service.ts,
- * instead of a silent runtime "wrong argument" failure inside an agent tool.
- *
- * This made the old name-only drift-guard test
- * (packages/mcp/test/unit/client-host-contract.test.mjs) redundant — tsc now
- * enforces both names AND signatures — so that test was removed.
- */
-export type DocmostClientLike = Pick<DocmostClient, DocmostClientMethod>;
+  createComment(
+    pageId: string,
+    content: string,
+    type?: 'page' | 'inline',
+    selection?: string,
+    parentCommentId?: string,
+    suggestedText?: string,
+  ): Promise<{ data: Record<string, unknown>; success: boolean }>;
+  resolveComment(
+    commentId: string,
+    resolved: boolean,
+  ): Promise<Record<string, unknown>>;
+  // Serialize a page + mirror its internal images into the blob sandbox; returns
+  // ONLY a short anonymous URL (the body never enters the model context).
+  stashPage(pageId: string): Promise<{
+    uri: string;
+    sha256: string;
+    size: number;
+    images: { mirrored: number; failed: number };
+  }>;
+}
 
 export type DocmostClientConfig = {
   apiUrl: string;
@@ -109,7 +280,32 @@ export type DocmostClientConfig = {
 };
 
 export interface DocmostClientCtor {
-  new (config: DocmostClientConfig): DocmostClient;
+  new (config: DocmostClientConfig): DocmostClientLike;
+}
+
+/**
+ * Local hand-mirror of the `SharedToolSpec` shape exported from
+ * `@docmost/mcp` (packages/mcp/src/tool-specs.ts). Same approach as
+ * `DocmostClientLike`: we do not import the ESM package's types directly across
+ * the CJS/ESM boundary. The registry itself has no runtime deps, but keeping the
+ * type local avoids coupling the server build to the package's type surface.
+ *
+ * `buildShape` is intentionally zod-agnostic: it returns a plain ZodRawShape
+ * built with whatever zod namespace the caller passes (the server passes its own
+ * zod v4; the MCP package passes its zod v3). See the registry module comment.
+ */
+export interface SharedToolSpec {
+  mcpName: string;
+  inAppKey: string;
+  description: string;
+  // Deferred-tool metadata (#332). Optional in this mirror so an older/stale
+  // @docmost/mcp build (pre-#332) still type-checks; the in-app catalog builder
+  // reads them defensively. The external /mcp server ignores both fields.
+  tier?: 'core' | 'deferred';
+  catalogLine?: string;
+  // Loose `z` on purpose: the registry is zod-agnostic so the server can pass
+  // its own zod (v4) and the MCP package its own (v3) into the same builder.
+  buildShape?: (z: any) => Record<string, unknown>;
 }
 
 /**
@@ -148,50 +344,6 @@ interface DocmostMcpModule {
   // loader in unit tests. The in-app layer treats an absent factory as "signal
   // disabled" — a pure no-op that leaves tool results byte-identical.
   createCommentSignalTracker?: CommentSignalTrackerFactory;
-  // Optional (#447): a deterministic hash of the tool-specs registry content,
-  // generated into build/ by the package's build. Absent on a pre-#447 build (or
-  // the mocked loader in unit tests) — the stale-check below is a NO-OP when it
-  // is missing, so an older build never wrongly fails startup.
-  REGISTRY_STAMP?: string;
-}
-
-/**
- * Recompute the REGISTRY_STAMP (#447) from the @docmost/mcp source tree, if it is
- * present. Returns the stamp string, or `null` when the source is absent (a prod
- * image ships only build/, no src/). MUST stay byte-for-byte identical to
- * packages/mcp/scripts/gen-registry-stamp.mjs's `computeRegistryStamp` so the
- * build-time and src-time hashes agree: same input file (src/tool-specs.ts), same
- * normalization (CRLF -> LF, strip a single trailing newline), same sha256.
- *
- * DEV vs PROD detection is by FILE EXISTENCE, not NODE_ENV: we resolve the
- * package's own directory from `require.resolve('@docmost/mcp')` (which points at
- * build/index.js) and look for ../src/tool-specs.ts next to it. In a dev/test
- * worktree that file exists; in a prod image (build/ only, src/ stripped) it does
- * not, so this returns null and the caller skips the check. Any error (ENOENT, a
- * bad resolve) is swallowed to null — the stale-check must NEVER break startup.
- *
- * Exported for unit testing (docmost-client.loader.spec.ts): the export keyword
- * is behaviourally a no-op — the module-internal caller `loadDocmostMcp` is
- * unaffected. The test drives the null (no-src) path and asserts this
- * normalize+sha256 stays identical to the codegen's `computeRegistryStamp`.
- */
-export function computeSrcRegistryStamp(packageEntry: string): string | null {
-  try {
-    // packageEntry is <pkg>/build/index.js; the source lives at <pkg>/src/.
-    const toolSpecsPath = join(
-      dirname(dirname(packageEntry)),
-      'src',
-      'tool-specs.ts',
-    );
-    if (!existsSync(toolSpecsPath)) return null; // prod: no src tree -> skip.
-    const source = readFileSync(toolSpecsPath, 'utf8');
-    const normalized = source.replace(/\r\n/g, '\n').replace(/\n$/, '');
-    return createHash('sha256').update(normalized, 'utf8').digest('hex');
-  } catch {
-    // Never let a resolution/read hiccup break server startup — treat as "no
-    // src available" and skip the check (identical to the prod no-op path).
-    return null;
-  }
 }
 
 // TS with module:commonjs downlevels a literal `import()` to `require()`, which
@@ -223,23 +375,6 @@ export async function loadDocmostMcp(): Promise<{
       const mod = (await esmImport(
         pathToFileURL(entry).href,
       )) as DocmostMcpModule;
-      // #447 stale-build guard (dev/test only). The server loads the COMPILED
-      // build/ of @docmost/mcp, but the parity/tier guard tests read src/. If a
-      // tool spec is edited in src without rebuilding the package, build/ and src/
-      // silently diverge and the running server serves the OLD tools. Here we
-      // recompute the stamp from src/tool-specs.ts and compare it to the stamp
-      // baked into build/. In PROD the src tree is absent (image ships build/
-      // only), so computeSrcRegistryStamp returns null and this is a pure no-op.
-      const srcStamp = computeSrcRegistryStamp(entry);
-      if (
-        srcStamp !== null &&
-        typeof mod.REGISTRY_STAMP === 'string' &&
-        srcStamp !== mod.REGISTRY_STAMP
-      ) {
-        throw new Error(
-          '@docmost/mcp build is stale (tool-specs changed since last build) — run: pnpm --filter @docmost/mcp build',
-        );
-      }
       return mod;
     })().catch((err) => {
       // Do not cache a rejected import — allow the next call to retry.

packages/mcp/package.json

@@ -5,26 +5,18 @@
   "private": true,
   "type": "module",
   "main": "./build/index.js",
-  "types": "./build/index.d.ts",
   "exports": {
-    ".": {
-      "types": "./build/index.d.ts",
-      "default": "./build/index.js"
-    },
-    "./http": {
-      "types": "./build/http.d.ts",
-      "default": "./build/http.js"
-    }
+    ".": "./build/index.js",
+    "./http": "./build/http.js"
   },
   "bin": {
     "docmost-mcp": "./build/stdio.js"
   },
   "scripts": {
-    "gen:stamp": "node scripts/gen-registry-stamp.mjs",
-    "build": "node scripts/gen-registry-stamp.mjs && tsc",
+    "build": "tsc",
     "start": "node build/stdio.js",
-    "watch": "node scripts/gen-registry-stamp.mjs && tsc --watch",
-    "pretest": "node scripts/gen-registry-stamp.mjs && tsc",
+    "watch": "tsc --watch",
+    "pretest": "tsc",
     "test": "node --test \"test/unit/*.test.mjs\" \"test/mock/*.test.mjs\"",
     "test:unit": "node --test \"test/unit/*.test.mjs\"",
     "test:mock": "node --test \"test/mock/*.test.mjs\"",

packages/mcp/scripts/gen-registry-stamp.mjs

@@ -1,67 +0,0 @@
-// Codegen: emit src/registry-stamp.generated.ts with a REGISTRY_STAMP hash of
-// the tool-specs REGISTRY CONTENT, so a build/ vs src/ skew (issue #447) is
-// detectable at runtime.
-//
-// WHY hash the raw source text (not extracted structured data):
-// SHARED_TOOL_SPECS carries `buildShape` functions (the input SCHEMAS) which are
-// NOT serializable. The input schema is exactly one of the things that MUST stay
-// in sync between build/ and src/, so we cannot drop it from the hash. Rather
-// than probe zod with a fragile shim to reconstruct the schema shape, we hash the
-// STABLE, deterministic source TEXT of tool-specs.ts. That text fully captures
-// every field that must stay in sync — mcpName, inAppKey, description, tier,
-// catalogLine AND the buildShape bodies (input schemas) — with zero probing
-// fragility. Any edit to a spec (a renamed tool, a reworded description, a
-// changed schema field) changes the text and therefore the stamp.
-//
-// DETERMINISM: the hash is computed over the file bytes with line endings
-// normalized to LF and a single trailing newline stripped, so a CRLF checkout or
-// an editor's trailing-newline habit cannot make build/ and src/ disagree. No
-// Date.now / randomness. The loader's dev-only stale-check (docmost-client.loader.ts)
-// re-runs THIS SAME normalization + sha256 over src/tool-specs.ts and compares to
-// the built REGISTRY_STAMP; the two must compute identically.
-//
-// This script runs from the `build` and `pretest` npm scripts BEFORE tsc, so
-// build/ always carries a stamp derived from the tool-specs.ts that was compiled.
-
-import { createHash } from 'node:crypto';
-import { readFileSync, writeFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const SRC_DIR = join(__dirname, '..', 'src');
-const TOOL_SPECS_PATH = join(SRC_DIR, 'tool-specs.ts');
-const OUT_PATH = join(SRC_DIR, 'registry-stamp.generated.ts');
-
-/**
- * Deterministic stamp of the tool-specs registry content. Kept as a plain
- * function (exported) so the algorithm has a single home; the loader duplicates
- * only the tiny normalize+sha256 steps because it lives in the CJS server build
- * and cannot import this ESM script. If you change the normalization here, mirror
- * it in apps/server/src/core/ai-chat/tools/docmost-client.loader.ts.
- */
-export function computeRegistryStamp(toolSpecsSource) {
-  const normalized = toolSpecsSource.replace(/\r\n/g, '\n').replace(/\n$/, '');
-  return createHash('sha256').update(normalized, 'utf8').digest('hex');
-}
-
-function main() {
-  const source = readFileSync(TOOL_SPECS_PATH, 'utf8');
-  const stamp = computeRegistryStamp(source);
-  const out =
-    '// AUTO-GENERATED by scripts/gen-registry-stamp.mjs — DO NOT EDIT BY HAND.\n' +
-    '// A deterministic hash of src/tool-specs.ts content (tool names, descriptions,\n' +
-    '// tiers, catalog lines and input schemas). Regenerated on every build/pretest\n' +
-    '// so build/ always matches the compiled src. The in-app loader recomputes this\n' +
-    '// from src and refuses to run on a mismatch (issue #447). This file is\n' +
-    '// gitignored and produced by the build — see .gitignore.\n' +
-    `export const REGISTRY_STAMP = ${JSON.stringify(stamp)};\n`;
-  writeFileSync(OUT_PATH, out, 'utf8');
-  // eslint-disable-next-line no-console
-  console.log(`gen-registry-stamp: wrote ${OUT_PATH} (${stamp.slice(0, 12)}…)`);
-}
-
-// Only run when invoked directly (not when imported for computeRegistryStamp).
-if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
-  main();
-}

packages/mcp/src/index.ts

@@ -29,14 +29,6 @@ export { destroyAllSessions } from "./lib/collab-session.js";
 export { SHARED_TOOL_SPECS } from "./tool-specs.js";
 export type { SharedToolSpec } from "./tool-specs.js";
 
-// Re-export the build-time REGISTRY_STAMP (issue #447): a deterministic hash of
-// the tool-specs registry content, generated into src/registry-stamp.generated.ts
-// by scripts/gen-registry-stamp.mjs BEFORE tsc, so it lands in build/. The in-app
-// loader recomputes the same hash from src/tool-specs.ts (dev/test only) and
-// refuses to run on a mismatch, catching a build/ vs src/ skew (a spec edited in
-// src without rebuilding the package the server actually loads from build/).
-export { REGISTRY_STAMP } from "./registry-stamp.generated.js";
-
 // Re-export the shared "new comments: N" signal helper (#417) so the in-app
 // layer reads the SAME watermark/debounce/injection-safe line builder off the
 // loaded module (same pattern as SHARED_TOOL_SPECS). Both surfaces then differ

packages/mcp/test/unit/client-host-contract.test.mjs

@@ -0,0 +1,224 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+import { DocmostClient } from "../../build/index.js";
+
+// Drift guard for the THIRD hand-written layer of the AI tool set (issue #193,
+// layer 3): the in-app server hand-mirrors the DocmostClient method signatures
+// it consumes as the `DocmostClientLike` interface in
+// apps/server/src/core/ai-chat/tools/docmost-client.loader.ts ("Signatures here
+// mirror that file exactly"). That mirror lives across the ESM(mcp)/CJS(server)
+// boundary and the package ships NO .d.ts, so the server typecheck cannot verify
+// the names against the real class — a rename/removal in client.ts would surface
+// only as a runtime "x is not a function" inside an agent tool call.
+//
+// SCOPE: this guard checks the method-NAME set only, not signatures. It pins the
+// contract from the mcp side (ESM, where the real class is directly importable):
+// every method the embedding host depends on MUST exist as a function on a real
+// DocmostClient instance. If you rename/remove a client method, this fails here
+// AND you must update DocmostClientLike to match. It does NOT verify parameter or
+// return-type parity — signature drift between the hand-mirror and client.ts can
+// still ship silently; full signature/type parity is the deferred staged-plan
+// item below.
+//
+// Keep the HOST_CONTRACT_METHODS NAME list aligned with the method NAMES declared
+// in the server's DocmostClientLike interface (the in-app per-user tool adapter
+// only — it is a SUBSET of the DocmostClient surface — covers only what the in-app adapter
+// consumes; the standalone MCP transport (packages/mcp/src/index.ts) calls additional
+// client methods (deleteComment/updateComment) that this guard does NOT track — the
+// MCP transport's own typecheck covers those. insertImage/replaceImage/insertFootnote
+// were MCP-only but are now in-app-consumed too (#410), so they ARE tracked below. Full type-derivation
+// of DocmostClientLike from this class is deferred (see the staged plan in
+// docmost-client.loader.ts): the package emits no declarations and the real
+// (inferred, concrete) return types conflict with the host's loose
+// `Record<string,unknown>` + `as`-cast result handling.
+const HOST_CONTRACT_METHODS = [
+  // read
+  "search",
+  "getPage",
+  "getPageRaw",
+  "getWorkspace",
+  "getSpaces",
+  "listPages",
+  "listSidebarPages",
+  "getOutline",
+  "getPageJson",
+  "getNode",
+  "searchInPage",
+  "getTable",
+  "listComments",
+  "getComment",
+  "checkNewComments",
+  "listShares",
+  "listPageHistory",
+  "getPageHistory",
+  "diffPageVersions",
+  "exportPageMarkdown",
+  // write (page)
+  "createPage",
+  "updatePage",
+  "renamePage",
+  "movePage",
+  "deletePage",
+  "editPageText",
+  "patchNode",
+  "insertNode",
+  "deleteNode",
+  "updatePageJson",
+  "tableInsertRow",
+  "tableDeleteRow",
+  "tableUpdateCell",
+  "copyPageContent",
+  "importPageMarkdown",
+  "sharePage",
+  "unsharePage",
+  "restorePageVersion",
+  "transformPage",
+  "stashPage",
+  // write (image / footnote) — MCP-only until #410 promoted them to in-app tools
+  "insertImage",
+  "replaceImage",
+  "insertFootnote",
+  // draw.io diagrams (#423, stage 1) — read + create + optimistic-locked update
+  "drawioGet",
+  "drawioCreate",
+  "drawioUpdate",
+  // write (comment)
+  "createComment",
+  "resolveComment",
+];
+
+test("DocmostClient implements every method the in-app DocmostClientLike mirror declares", () => {
+  // The constructor is side-effect-free (no network/login on construction): it
+  // only stores config and creates an axios instance, so it is safe to build a
+  // throwaway instance here with a dummy token provider.
+  const client = new DocmostClient({
+    apiUrl: "http://127.0.0.1:1/api",
+    getToken: async () => "test-token",
+  });
+
+  const missing = HOST_CONTRACT_METHODS.filter(
+    (name) => typeof client[name] !== "function",
+  );
+
+  assert.deepEqual(
+    missing,
+    [],
+    `DocmostClient is missing host-contract method(s): ${missing.join(", ")}. ` +
+      `Update packages/mcp/src/client.ts and/or the server's DocmostClientLike ` +
+      `interface (apps/server/src/core/ai-chat/tools/docmost-client.loader.ts) ` +
+      `so the hand-mirrored method NAMES stay aligned (this guards names only, ` +
+      `not signatures).`,
+  );
+});
+
+test("HOST_CONTRACT_METHODS has no duplicates", () => {
+  assert.equal(
+    new Set(HOST_CONTRACT_METHODS).size,
+    HOST_CONTRACT_METHODS.length,
+  );
+});
+
+// Parse the method names declared in the server's `DocmostClientLike` interface
+// body. We read the .ts source as plain text (no TS compiler dep, and the file
+// lives in the CJS server tree across the ESM boundary): scan from the
+// `export interface DocmostClientLike {` line to its closing brace at column 0,
+// matching member-signature lines like `  methodName(`. Nested param-object
+// braces (`opts: { ... }`) are indented, so only the interface's own closing
+// `}` (column 0) ends the scan.
+function parseDocmostClientLikeMethods() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  // packages/mcp/test/unit -> repo root is four levels up.
+  const loaderPath = resolve(
+    here,
+    "../../../../apps/server/src/core/ai-chat/tools/docmost-client.loader.ts",
+  );
+  let source;
+  try {
+    source = readFileSync(loaderPath, "utf8");
+  } catch (err) {
+    if (err && err.code === "ENOENT") {
+      throw new Error(
+        `Expected monorepo layout; server tree at ${loaderPath} not found. ` +
+          `This drift-guard reads the server's DocmostClientLike interface via a ` +
+          `fixed relative path and must run from inside the monorepo checkout.`,
+      );
+    }
+    throw err;
+  }
+  const lines = source.split(/\r?\n/);
+
+  const startIdx = lines.findIndex((l) =>
+    /^export interface DocmostClientLike\s*\{/.test(l),
+  );
+  assert.notEqual(
+    startIdx,
+    -1,
+    `Could not find "export interface DocmostClientLike {" in ${loaderPath}. ` +
+      `If the interface was renamed/moved, update this drift-guard test.`,
+  );
+
+  const methods = [];
+  let closed = false;
+  // Track whether we are inside a `/* ... */` block comment. Inner lines of a
+  // block comment need NOT start with `*`, so a `name(` line inside one would be
+  // falsely parsed as an interface method without this. (`//` line comments can
+  // never match the method regex below since they start with `/`.)
+  let inBlockComment = false;
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (inBlockComment) {
+      // Stay in the block until we see its closing `*/`.
+      if (line.includes("*/")) inBlockComment = false;
+      continue;
+    }
+    // Enter a block comment only when it opens without closing on the same line;
+    // a self-contained `/* ... */` on one line cannot precede a method name we
+    // care about (such lines start with `/`, so the method regex won't match).
+    if (line.includes("/*") && !line.includes("*/")) {
+      inBlockComment = true;
+      continue;
+    }
+    if (/^\}/.test(line)) {
+      closed = true;
+      break;
+    }
+    // Method-name match: a TS identifier (letters/digits/`_`/`$`, not starting
+    // with a digit) optionally followed by a generic clause (`method<T>(`), then
+    // the opening paren of the signature.
+    const m = /^\s*([A-Za-z_$][A-Za-z0-9_$]*)\s*(?:<[^>]*>)?\(/.exec(line);
+    if (m) methods.push(m[1]);
+  }
+  assert.ok(
+    closed,
+    `Did not find the closing brace of DocmostClientLike in ${loaderPath}.`,
+  );
+  assert.ok(
+    methods.length > 0,
+    `Parsed zero methods from DocmostClientLike in ${loaderPath} — the parser ` +
+      `is likely out of date with the interface formatting.`,
+  );
+  return methods;
+}
+
+// The point of the guard is to protect the DocmostClientLike mirror <-> client.ts
+// link, but HOST_CONTRACT_METHODS is itself a HAND-COPY of that interface kept in
+// sync manually. The list<->interface link must be tested too: a method consumed
+// by the adapter and added to DocmostClientLike but forgotten here (or removed
+// from the interface but left here) would otherwise escape both the server
+// typecheck (pkg emits no .d.ts) and the first test above (name not in the list).
+// Assert the two agree BOTH ways.
+test("HOST_CONTRACT_METHODS exactly mirrors the server's DocmostClientLike interface", () => {
+  const interfaceMethods = parseDocmostClientLikeMethods();
+  assert.deepEqual(
+    [...HOST_CONTRACT_METHODS].sort(),
+    [...interfaceMethods].sort(),
+    `HOST_CONTRACT_METHODS has drifted from the DocmostClientLike interface in ` +
+      `apps/server/src/core/ai-chat/tools/docmost-client.loader.ts. Add/remove ` +
+      `method names in HOST_CONTRACT_METHODS so it lists EXACTLY the methods ` +
+      `declared in that interface (both directions are checked).`,
+  );
+});

packages/mcp/test/unit/registry-stamp.test.mjs

@@ -1,101 +0,0 @@
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { createHash } from "node:crypto";
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
-
-import { computeRegistryStamp } from "../../scripts/gen-registry-stamp.mjs";
-import { REGISTRY_STAMP } from "../../build/index.js";
-
-// Guard tests for the build/src-skew stamp (issue #447). The codegen script
-// exports `computeRegistryStamp(sourceText)` — a sha256 over normalized source
-// text (CRLF->LF, single trailing newline stripped). The in-app loader
-// (apps/server/.../docmost-client.loader.ts) DUPLICATES that normalize+sha256 to
-// recompute the stamp from src and refuse a stale build. These tests pin the
-// algorithm's behaviour AND assert the built stamp matches the current src, so a
-// stale generated file OR a normalize divergence reddens.
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const TOOL_SPECS_PATH = join(__dirname, "..", "..", "src", "tool-specs.ts");
-
-test("computeRegistryStamp is deterministic: same input -> same hash", () => {
-  const input = "export const X = 1;\nexport const Y = 2;\n";
-  assert.equal(computeRegistryStamp(input), computeRegistryStamp(input));
-});
-
-test("computeRegistryStamp returns a 64-char lowercase hex sha256", () => {
-  const stamp = computeRegistryStamp("anything");
-  assert.match(stamp, /^[0-9a-f]{64}$/);
-});
-
-test("normalizes CRLF vs LF: the same content hashes equal", () => {
-  const lf = "line1\nline2\nline3";
-  const crlf = "line1\r\nline2\r\nline3";
-  assert.equal(computeRegistryStamp(crlf), computeRegistryStamp(lf));
-});
-
-test("normalizes a trailing newline: with/without a final \\n hashes equal", () => {
-  const noTrailing = "alpha\nbeta";
-  const trailing = "alpha\nbeta\n";
-  assert.equal(computeRegistryStamp(trailing), computeRegistryStamp(noTrailing));
-});
-
-test("a CRLF checkout WITH a trailing CRLF still hashes equal to bare LF", () => {
-  // A worst-case Windows checkout: CRLF line endings + a trailing CRLF. Both the
-  // \r\n->\n replace and the trailing-newline strip must apply for parity.
-  const bare = "alpha\nbeta";
-  const crlfTrailing = "alpha\r\nbeta\r\n";
-  assert.equal(
-    computeRegistryStamp(crlfTrailing),
-    computeRegistryStamp(bare),
-  );
-});
-
-test("a real content change hashes differently", () => {
-  const before = "export const description = 'search a page';\n";
-  const after = "export const description = 'search a PAGE';\n";
-  assert.notEqual(computeRegistryStamp(before), computeRegistryStamp(after));
-});
-
-// Only a SINGLE trailing newline is stripped — a second blank line is content and
-// must change the hash. This pins the exact `/\n$/` semantics the loader mirrors.
-test("only ONE trailing newline is stripped (two differ from one)", () => {
-  assert.notEqual(
-    computeRegistryStamp("x\n"),
-    computeRegistryStamp("x\n\n"),
-  );
-});
-
-// Cross-impl equality against a fixed, documented input. The SAME literal input
-// and expected hash are asserted in the server-side jest test
-// (docmost-client.loader.spec.ts). If either side's normalize+sha256 ever
-// diverges, one of the two tests reddens. Input exercises BOTH normalize steps.
-test("fixed-input hash matches the documented cross-impl value", () => {
-  const FIXED_INPUT = "line1\r\nline2\n";
-  const EXPECTED =
-    "683376e290829b482c2655745caffa7a1dccfa10afaa62dac2b42dd6c68d0f83";
-  assert.equal(computeRegistryStamp(FIXED_INPUT), EXPECTED);
-});
-
-// DESYNC GUARD (covers reviewer suggestion 2). Recompute the stamp from the
-// actual src/tool-specs.ts and assert it equals the REGISTRY_STAMP baked into the
-// freshly-built build/index.js. This reddens if the generated file is stale OR if
-// the codegen normalize ever diverges from what produced the built stamp.
-test("built REGISTRY_STAMP equals the stamp recomputed from src/tool-specs.ts", () => {
-  const source = readFileSync(TOOL_SPECS_PATH, "utf8");
-  assert.equal(computeRegistryStamp(source), REGISTRY_STAMP);
-});
-
-// Sanity: the fixed-input helper computes the SAME way the codegen does, proving
-// the EXPECTED constant above is not an arbitrary magic value but the documented
-// normalize+sha256 of FIXED_INPUT. Belt-and-braces so a bad EXPECTED can't hide a
-// real regression.
-test("the documented EXPECTED constant is the normalize+sha256 of FIXED_INPUT", () => {
-  const FIXED_INPUT = "line1\r\nline2\n";
-  const normalized = FIXED_INPUT.replace(/\r\n/g, "\n").replace(/\n$/, "");
-  const expected = createHash("sha256")
-    .update(normalized, "utf8")
-    .digest("hex");
-  assert.equal(computeRegistryStamp(FIXED_INPUT), expected);
-});

packages/mcp/tsconfig.json

@@ -5,8 +5,6 @@
     "moduleResolution": "Node16",
     "outDir": "./build",
     "rootDir": "./src",
-    "declaration": true,
-    "declarationMap": true,
     "strict": true,
     "esModuleInterop": true,
     "skipLibCheck": true,