docs: отразить ключ error в заглавной секции reading-ai-logs (устранить противоречие)

Ревью #426: секция «How tool calls are stored — READ THIS» всё ещё утверждала,
что единственные ключи элемента — toolName/input/output и «нет error», хотя этот
же PR добавляет error и подробно описывает его ниже. Заглавный абзац приведён в
соответствие: error — возможный ключ для брошенных ошибок на строках после #407;
подсчёт инвокаций и пайринг учитывают error как парный результат.

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

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

@@ -148,6 +148,53 @@ describe('assistantParts', () => {
     expect(toolPart).not.toHaveProperty('output');
   });
 
+  it('replays the REAL error text for a THROWN tool (tool-error part)', () => {
+    const steps = [
+      {
+        text: '',
+        toolCalls: [
+          { toolCallId: 'c7', toolName: 'editPageText', input: { id: 'p1' } },
+        ],
+        // A thrown tool is a `tool-error` content part; toolResults holds only
+        // successes and stays empty for this call.
+        toolResults: [],
+        content: [
+          {
+            type: 'tool-error',
+            toolCallId: 'c7',
+            toolName: 'editPageText',
+            input: { id: 'p1' },
+            error: new Error('page is locked'),
+          },
+        ],
+      },
+    ];
+    const parts = assistantParts(steps, '') as AnyPart[];
+    const toolPart = parts.find((p) => p.type === 'tool-editPageText');
+    expect(toolPart).toBeDefined();
+    expect(toolPart!.state).toBe('output-error');
+    // The REAL error is replayed, NOT the 'Tool call did not complete.' placeholder.
+    expect(toolPart!.errorText).toBe('page is locked');
+    expect(toolPart).not.toHaveProperty('output');
+  });
+
+  it('keeps the placeholder ONLY for a call with neither result nor tool-error', () => {
+    const steps = [
+      {
+        text: '',
+        toolCalls: [
+          { toolCallId: 'c8', toolName: 'insertNode', input: { node: {} } },
+        ],
+        toolResults: [],
+        content: [], // aborted mid-step: no result AND no tool-error
+      },
+    ];
+    const parts = assistantParts(steps, '') as AnyPart[];
+    const toolPart = parts.find((p) => p.type === 'tool-insertNode');
+    expect(toolPart!.state).toBe('output-error');
+    expect(toolPart!.errorText).toBe('Tool call did not complete.');
+  });
+
   it('skips malformed tool-calls (missing toolName or toolCallId)', () => {
     const steps = [
       {
@@ -195,6 +242,45 @@ describe('serializeSteps', () => {
     expect(trace[0]).toEqual({ toolName: 'getPage', input: { id: 'p1' } });
     expect(trace[1]).toEqual({ toolName: 'getPage', output: { title: 'T' } });
   });
+
+  it('records a THROWN tool failure (tool-error part) with its error message', () => {
+    const trace = serializeSteps([
+      {
+        toolCalls: [{ toolName: 'editPageText', input: { id: 'p1' } }],
+        toolResults: [],
+        content: [
+          {
+            type: 'tool-error',
+            toolName: 'editPageText',
+            error: new Error('page is locked'),
+          },
+        ],
+      },
+    ]) as Array<Record<string, unknown>>;
+    // The call element is followed by a paired error element (mirroring how a
+    // successful result is appended), so the failure survives in the trace.
+    expect(trace).toHaveLength(2);
+    expect(trace[0]).toEqual({ toolName: 'editPageText', input: { id: 'p1' } });
+    expect(trace[1]).toEqual({
+      toolName: 'editPageText',
+      error: 'page is locked',
+    });
+  });
+
+  it('truncates a very long tool-error message to the tool-output limit', () => {
+    const long = 'x'.repeat(5000);
+    const trace = serializeSteps([
+      {
+        toolCalls: [{ toolName: 'editPageText', input: {} }],
+        toolResults: [],
+        content: [{ type: 'tool-error', toolName: 'editPageText', error: long }],
+      },
+    ]) as Array<Record<string, unknown>>;
+    const errorText = trace[1].error as string;
+    // Truncated (not the full 5000 chars) and carries the omission marker.
+    expect(errorText.length).toBeLessThan(long.length);
+    expect(errorText).toContain('chars omitted');
+  });
 });
 
 describe('rowToUiMessage', () => {

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

@@ -1637,6 +1637,17 @@ type StepLike = {
     toolName?: string;
     output?: unknown;
   }>;
+  // ai@6.0.134: a tool that THREW surfaces as a `tool-error` content part
+  // ({ type:'tool-error', toolCallId, toolName, input, error }), NOT as a
+  // `toolResults` entry (which holds only successes). Read from here so failed
+  // calls are persisted with their real error instead of being dropped.
+  content?: ReadonlyArray<{
+    type?: string;
+    toolCallId?: string;
+    toolName?: string;
+    input?: unknown;
+    error?: unknown;
+  }>;
 };
 
 /**
@@ -1739,6 +1750,26 @@ function compactValue(value: unknown, depth: number): unknown {
   return value;
 }
 
+/**
+ * Extract a bounded string message from a `tool-error` part's `error` field for
+ * persistence and history replay. The field may be an `Error`, a string, or an
+ * arbitrary object, so pull a message robustly. The result is passed through
+ * `compactValue` so a very long error honors the SAME truncation limits the file
+ * already applies to tool outputs (no new limit is introduced here).
+ */
+function normalizeToolError(error: unknown): string {
+  const message =
+    error instanceof Error
+      ? error.message
+      : typeof error === 'string'
+        ? error
+        : error != null &&
+            typeof (error as { message?: unknown }).message === 'string'
+          ? (error as { message: string }).message
+          : String(error);
+  return compactValue(message, 0) as string;
+}
+
 /**
  * Rebuild the FULL UIMessage `parts` for an assistant turn from the SDK steps,
  * so multi-turn history replays prior tool-calls/results to the model (not just
@@ -1771,6 +1802,14 @@ export function assistantParts(
     for (const r of step.toolResults ?? []) {
       if (r.toolCallId) resultsById.set(r.toolCallId, r.output);
     }
+    // Index this step's THROWN tool failures (ai@6 `tool-error` content parts)
+    // by tool call id, so a call that failed replays with its real error text.
+    const errorsById = new Map<string, unknown>();
+    for (const part of step.content ?? []) {
+      if (part.type === 'tool-error' && part.toolCallId) {
+        errorsById.set(part.toolCallId, part.error);
+      }
+    }
     for (const call of step.toolCalls ?? []) {
       if (!call.toolName || !call.toolCallId) continue;
       const hasResult = resultsById.has(call.toolCallId);
@@ -1783,9 +1822,21 @@ export function assistantParts(
           input: call.input,
           output: compactToolOutput(resultsById.get(call.toolCallId)),
         });
+      } else if (errorsById.has(call.toolCallId)) {
+        // The tool THREW: replay the REAL error so the model on the next turn
+        // knows WHY the call failed (and does not blindly repeat it). An
+        // output-error round-trips through convertToModelMessages as a balanced
+        // tool-call + tool-result, keeping the rebuilt history valid.
+        parts.push({
+          type: `tool-${call.toolName}`,
+          toolCallId: call.toolCallId,
+          state: 'output-error',
+          input: call.input,
+          errorText: normalizeToolError(errorsById.get(call.toolCallId)),
+        });
       } else {
-        // No paired result (e.g. aborted mid-step). Persisting a bare
-        // tool-call (input-available) would replay as an unpaired call and
+        // No paired result AND no tool-error (e.g. aborted mid-step). Persisting
+        // a bare tool-call (input-available) would replay as an unpaired call and
         // throw MissingToolResultsError on the next turn (convertToModelMessages
         // emits no tool-result for it). Emit a SYNTHETIC paired result instead:
         // an output-error round-trips through convertToModelMessages as a
@@ -2021,10 +2072,19 @@ export function serializeSteps(
   steps: ReadonlyArray<{
     toolCalls?: ReadonlyArray<{ toolName?: string; input?: unknown }>;
     toolResults?: ReadonlyArray<{ toolName?: string; output?: unknown }>;
+    content?: ReadonlyArray<{
+      type?: string;
+      toolName?: string;
+      error?: unknown;
+    }>;
   }>,
 ): unknown {
-  const calls: Array<{ toolName?: string; input?: unknown; output?: unknown }> =
-    [];
+  const calls: Array<{
+    toolName?: string;
+    input?: unknown;
+    output?: unknown;
+    error?: string;
+  }> = [];
   for (const step of steps ?? []) {
     for (const call of step.toolCalls ?? []) {
       calls.push({ toolName: call.toolName, input: call.input });
@@ -2032,6 +2092,18 @@ export function serializeSteps(
     for (const r of step.toolResults ?? []) {
       calls.push({ toolName: r.toolName, output: compactToolOutput(r.output) });
     }
+    // ai@6 surfaces a THROWN tool failure as a `tool-error` content part, NOT as
+    // a `toolResults` entry. Record it as its own paired element (mirroring how a
+    // successful result is appended) so the failure and its reason survive in the
+    // trace instead of leaving an orphaned call with no result.
+    for (const part of step.content ?? []) {
+      if (part.type === 'tool-error') {
+        calls.push({
+          toolName: part.toolName,
+          error: normalizeToolError(part.error),
+        });
+      }
+    }
   }
   return calls.length > 0 ? calls : null;
 }

docs/reading-ai-logs.md

@@ -13,12 +13,14 @@ Read the **Gotchas** section before you trust any error count.
 - Agent chats live in Postgres, DB `docmost`, tables `ai_chat_*`.
 - Each tool invocation is stored as **two** array elements (a `tool-call` part and
   a `tool-result` part), so naive counting double-counts.
-- **A tool that *throws* writes no result part at all.** Its error text is nowhere
-  in the DB — not in `tool_calls`, `content`, or `metadata`. It is shown live in
-  the UI only. So `isError` / `success=false` scans under-report by design.
-- To find where agents fail you need **three** sources: (1) soft-failure markers in
-  `tool_calls`, (2) the orphan-gap proxy for thrown errors, (3) server logs / the
-  live UI for the actual error text.
+- **A tool that *throws* writes no result part.** Since the #407 fix its error is
+  persisted as a dedicated `{toolName, error}` element in `tool_calls` (queryable +
+  replayed to the model). **Rows written before #407 still drop it** — the error is
+  nowhere in the DB and shows only in the live UI. So `isError` / `success=false`
+  scans under-report by design, and pre-#407 thrown errors are invisible.
+- To find where agents fail: (1) soft-failure markers in `tool_calls`, (2) the new
+  `error` field for thrown errors (new rows) / the orphan-gap proxy (old rows),
+  (3) server logs / the live UI for full stack traces beyond the truncated message.
 
 ## Where the data lives
 
@@ -61,13 +63,17 @@ index 0: { "toolName": "getPage",  "input":  { "pageId": "…" } }   ← tool-ca
 index 1: { "toolName": "getPage",  "output": { … } }                ← tool-result (has output, NO input)
 ```
 
-The **only** keys that ever appear on an element are `toolName`, `input`, `output`.
-There is no `state`, no `errorText`, no `type`. Consequences:
+The keys that appear on an element are `toolName`, `input`, `output`, and — for a
+**thrown** failure on rows written after the #407 fix — `error` (the tool's error
+message; see the "Hard failures" section below). There is no `state`, no `errorText`,
+no `type`. On pre-#407 rows a thrown failure has NO paired result element at all
+(silent orphan). Consequences:
 
-1. **Real invocation count = elements that have `output`.** Counting every element
-   double-counts (you get ~2× and a spurious "~50% of every tool has no output").
-2. **Pairing:** a successful call = a `tool-call` part followed by its `tool-result`
-   part. Both carry `toolName`, so you can group by tool on either.
+1. **Real invocation count = elements that have `output` or `error`.** Counting every
+   element double-counts (you get ~2× and a spurious "~50% of every tool has no output").
+2. **Pairing:** a call = a `tool-call` part followed by its result part. A success
+   carries `output`; a thrown failure (post-#407) carries `error` instead. Both carry
+   `toolName`, so you can group by tool on either.
 
 ## The two classes of failure (and which the DB can see)
 
@@ -85,25 +91,37 @@ These are visible in the `tool-result` `output`. The marker differs per tool:
 Note `editPageText` returns `failed: []` on success — filtering on the *presence*
 of the key gives false positives; filter on **non-empty**.
 
-### 2. Hard failures — tool THREW → NOT PERSISTED ❌ (the trap)
+### 2. Hard failures — tool THREW → NOW PERSISTED ✅ (since the #407 fix)
 
 When a tool throws (the classic one is `patchNode` / `insertNode` / `tableUpdateCell`
 → `Failed to encode document to Yjs (fromJSON): Unknown node type: undefined`), the
-runtime writes **no `tool-result` part**. The orphaned `tool-call` part stays, but
-the error text is **nowhere in the DB**. It is streamed to the UI live and (until
-rotation) to server logs — that is it.
+runtime still writes **no `tool-result` part** — the failure is an ai@6 `tool-error`
+content part instead. **Since the #407 fix, that error is persisted**: `serializeSteps`
+appends a dedicated element `{toolName, error: "<message>"}` right after the failed
+call, mirroring how a successful `{toolName, output}` element is appended. So a thrown
+error now leaves a queryable `error` field carrying its (truncated) reason, and the
+same real text is replayed to the model on the next turn (an `output-error` part with
+the real `errorText`, no longer the `'Tool call did not complete.'` placeholder).
 
-So any query like `count(*) FILTER (WHERE output.success = false)` will happily
-return **0** for `patchNode` even when the chat is visibly full of red failures.
-That is survivorship bias, not reliability.
+**Cutover caveat — old rows keep the old blind shape.** Rows written **before** this
+change have the two-part shape (`call` + `output` only) and simply **drop** thrown
+errors, leaving a silent **orphan** (a `call` with no `output` *and* no `error`). Rows
+written **after** the fix additionally carry the `error` element. So:
 
-The only DB-side proxy for a thrown error is an **orphan**: a `tool-call` part with
-no matching `tool-result`. Caveat: orphans also appear when a run is **aborted**
-mid-flight (server restart), so a high-volume tool (`createComment`, `searchInPage`,
-`Search_web_search`) shows orphans from aborts, not from real errors. Treat the
-orphan gap as an *upper bound* on hard errors, and cross-check the tool: a gap on a
-structural editor (`patchNode`, `insertNode`, `updatePageJson`, `transformPage`) is
-almost certainly a thrown Yjs-encode error; a gap on `createComment` is mostly aborts.
+- **New rows:** query the `error` field directly (see the hard-error query below) — no
+  orphan heuristic needed for thrown failures.
+- **Old rows (pre-#407):** the only DB-side proxy is still an **orphan**: a `tool-call`
+  part with no matching `tool-result` *and* no `error`. Orphans also appear when a run
+  is **aborted** mid-flight (server restart), so a high-volume tool (`createComment`,
+  `searchInPage`, `Search_web_search`) shows orphans from aborts, not real errors on
+  old rows. Treat the orphan gap as an *upper bound*, and cross-check the tool: a gap on
+  a structural editor (`patchNode`, `insertNode`, `updatePageJson`, `transformPage`) is
+  almost certainly a thrown Yjs-encode error; a gap on `createComment` is mostly aborts.
+
+A note on the aborted-call fallback: a call with **neither** a result **nor** a
+`tool-error` (genuinely interrupted mid-step) still replays with the
+`'Tool call did not complete.'` placeholder and persists as an orphan — that path is
+unchanged, and is distinct from a real thrown error, which now carries `error`.
 
 ### 3. Run-level failures → `ai_chat_runs`
 
@@ -164,14 +182,28 @@ WHERE jsonb_typeof(o->'failed') = 'array'
 GROUP BY 1 ORDER BY 2 DESC;
 ```
 
-**Hard-error proxy — orphan gap per tool, WITH a spread column** (call parts minus
-result parts, plus how many distinct chats the gap is spread across):
+**Hard errors — persisted `error` field per tool (NEW rows, since #407)** — thrown
+tool failures now carry their real reason, so query them directly:
+
+```sql
+SELECT elem->>'toolName' AS tool, count(*) AS thrown_errors,
+       min(elem->>'error') AS sample_error
+FROM ai_chat_messages m, jsonb_array_elements(m.tool_calls) elem
+WHERE jsonb_typeof(m.tool_calls) = 'array' AND elem ? 'error'
+GROUP BY 1 ORDER BY 2 DESC;
+```
+
+**Hard-error proxy for OLD rows (pre-#407) — orphan gap per tool, WITH a spread column**
+(call parts minus result parts, plus how many distinct chats the gap is spread across).
+This covers rows written before thrown errors were persisted; on new rows a thrown
+failure now has its own `error` element (use the query above) and an orphan means only
+a genuinely aborted mid-step call:
 
 ```sql
 WITH parts AS (
   SELECT m.chat_id, elem->>'toolName' AS tool,
          (elem ? 'input' AND NOT (elem ? 'output')) AS is_call,
-         (elem ? 'output')                          AS is_result
+         (elem ? 'output' OR elem ? 'error')        AS is_result
   FROM ai_chat_messages m, jsonb_array_elements(m.tool_calls) elem
   WHERE jsonb_typeof(m.tool_calls) = 'array' AND m.role = 'assistant'
 ),
@@ -188,8 +220,12 @@ HAVING sum(gap) FILTER (WHERE gap > 0) > 0
 ORDER BY missing_results DESC;
 ```
 
-**`missing_results` mixes thrown errors AND aborted/interrupted runs — you cannot
-split them from `output` alone** (a positional "what follows the orphan" heuristic
+The `is_result` predicate counts an `error` element as a paired result too, so on new
+rows a persisted thrown error no longer inflates the orphan gap; a remaining gap is an
+aborted/interrupted call.
+
+**On OLD rows, `missing_results` mixes thrown errors AND aborted/interrupted runs — you
+cannot split them from `output` alone** (a positional "what follows the orphan" heuristic
 breaks on parallel tool batches, which persist as `call,call,…,result,result`). Use
 `chats_spread` to disambiguate:
 
@@ -244,18 +280,20 @@ docker compose -p gitmost logs -f --tail=100 # whole stack
 ```
 
 Logging is `json-file`, `max-size=10m max-file=5` → ~50 MB retained, then rotated,
-and **wiped on container recreate**. So thrown-tool error text is only reliably
-caught **in real time** (or in the live chat UI, which renders the failed part with
-its message). There is no durable, queryable store of hard tool errors today — if you
-need one, that is a feature to add (persist `output-error` parts, or emit a
-`tool_calls_total{tool,status}` metric to VictoriaMetrics).
+and **wiped on container recreate**. Since the #407 fix, thrown-tool error text is
+**persisted in the `error` field** of `tool_calls` (see the hard-error query above), so
+you no longer depend on live logs for it. Logs/live UI remain useful for **pre-#407
+rows** (whose thrown errors were dropped) and for full stack traces beyond the
+truncated stored message. A per-tool `tool_calls_total{tool,status}` metric to
+VictoriaMetrics is still a possible future add for aggregate dashboards.
 
 ## Gotchas checklist
 
-- [ ] Counting every `tool_calls` element → **2× overcount**. Count elements with `output`.
-- [ ] `isError` / `success=false` ≈ 0 does **not** mean "no errors" — thrown errors aren't persisted.
+- [ ] Counting every `tool_calls` element → **overcount**. Count `output` elements; add `error` elements for thrown failures (new rows), but don't count both as invocations.
+- [ ] `isError` / `success=false` ≈ 0 does **not** mean "no errors" — thrown errors are a separate `error` element (new rows) or dropped entirely (pre-#407 rows).
+- [ ] Thrown errors persist only on rows written **after the #407 fix** — pre-#407 rows still drop them (orphan only). Mind the cutover when trending over time.
 - [ ] `editPageText.failed` is `[]` on success — test for **non-empty**, not presence.
-- [ ] Orphan gap mixes thrown errors **and** aborted runs — split by tool before concluding.
+- [ ] Orphan gap on OLD rows mixes thrown errors **and** aborted runs — split by tool. On NEW rows a thrown error is its own `error` element, so a gap ≈ aborted call.
 - [ ] `aborted` runs = server restarts, `failed` runs = provider overload — not agent mistakes.
 - [ ] Never dump a raw `tool_calls` cell — it can be hundreds of KB.
 - [ ] Logs are ephemeral (≤50 MB, wiped on recreate) — grab hard-error text live.

packages/mcp/src/client.ts

@@ -40,7 +40,6 @@ import {
   deleteNodeById,
   assertUnambiguousMatch,
   insertNodeRelative,
-  blockPlainText,
   buildOutline,
   getNodeByRef,
   readTable,
@@ -60,12 +59,10 @@ import { getCollabToken, performLogin } from "./lib/auth-utils.js";
 import { diffDocs, summarizeChange } from "./lib/diff.js";
 import {
   applyAnchorInDoc,
+  canAnchorInDoc,
   countAnchorMatches,
   getAnchoredText,
-  resolveAnchorSelection,
-  normalizeForMatch,
 } from "./lib/comment-anchor.js";
-import { closestBlockHint } from "./lib/text-normalize.js";
 import {
   blockText,
   walk,
@@ -2477,64 +2474,6 @@ export class DocmostClient {
     };
   }
 
-  /** Plain text of each TOP-LEVEL block of `doc`, for anchor-failure hints. */
-  private topLevelBlockTexts(doc: any): string[] {
-    const content = doc && Array.isArray(doc.content) ? doc.content : [];
-    return content
-      .map((b: any) => blockPlainText(b))
-      .filter((t: string) => t.length > 0);
-  }
-
-  /**
-   * True when per-block anchoring failed but the (normalized) selection DOES
-   * appear in the blocks' joined plain text — i.e. it straddles a block
-   * boundary. Blocks are joined with a newline (collapsed to one space by
-   * normalizeForMatch) so a selection whose parts are separated by a paragraph
-   * break still matches. Callers only reach here after single-block anchoring
-   * (incl. the markdown-strip fallback) has already failed.
-   */
-  private selectionSpansMultipleBlocks(
-    blockTexts: string[],
-    selection: string,
-  ): boolean {
-    const normSel = normalizeForMatch(selection).norm.trim();
-    if (normSel.length === 0) return false;
-    const joined = normalizeForMatch(blockTexts.join("\n")).norm;
-    return joined.indexOf(normSel) !== -1;
-  }
-
-  /**
-   * Build the actionable error for a create_comment anchor MISS, porting
-   * edit_page_text's self-correction affordances: an explicit "spans multiple
-   * blocks" message when the selection straddles a block boundary, otherwise a
-   * "closest block text" hint quoting the block that holds the selection's
-   * longest token. `live` switches the wording between the pre-check (reading the
-   * persisted page) and the post-create live-anchor failure (which rolls back).
-   */
-  private anchorNotFoundError(
-    doc: any,
-    selection: string,
-    live: boolean,
-  ): Error {
-    const blockTexts = this.topLevelBlockTexts(doc);
-    const rolled = live ? " The comment was rolled back." : "";
-    if (this.selectionSpansMultipleBlocks(blockTexts, selection)) {
-      return new Error(
-        "create_comment: the selection spans multiple blocks; anchor on a " +
-          "contiguous fragment within a SINGLE paragraph/block (<=250 chars)." +
-          rolled,
-      );
-    }
-    const where = live ? "in the live document" : "in the page";
-    return new Error(
-      `create_comment: could not find the selection text ${where} to anchor ` +
-        "the comment. Provide the EXACT contiguous text from a single " +
-        "paragraph/block (<=250 chars)." +
-        closestBlockHint(blockTexts, selection) +
-        rolled,
-    );
-  }
-
   /**
    * Create an inline comment anchored to its `selection` text, or a reply.
    *
@@ -2596,10 +2535,6 @@ export class DocmostClient {
     // Captured in the pre-check below (which already reads the page) and used as
     // payload.selection. Ordinary comments keep sending the raw agent selection.
     let anchoredSelection: string | null = null;
-    // Set when the anchor matched only after stripping markdown from the
-    // selection (the strip fallback); surfaced as a soft warning like
-    // edit_page_text does, so a stale-markdown selection is flagged.
-    let anchorNormalized = false;
 
     // For a top-level comment, fail BEFORE creating anything when the selection
     // is not present in the persisted document — this avoids leaving an orphan
@@ -2615,7 +2550,10 @@ export class DocmostClient {
           // rejected BEFORE creating the comment.
           const matches = countAnchorMatches(page.content, selection);
           if (matches === 0) {
-            throw this.anchorNotFoundError(page.content, selection, false);
+            throw new Error(
+              "create_comment: could not find the selection text in the page to anchor the comment. " +
+                "Provide the EXACT contiguous text from a single paragraph/block (<=250 chars).",
+            );
           }
           if (matches >= 2) {
             throw new Error(
@@ -2629,27 +2567,18 @@ export class DocmostClient {
           // null despite countAnchorMatches===1 (shouldn't happen), fall back to
           // the raw agent selection below rather than crash.
           anchoredSelection = getAnchoredText(page.content, selection);
-          anchorNormalized = resolveAnchorSelection(
-            page.content,
-            selection,
-          ).normalized;
-        } else {
-          const resolved = resolveAnchorSelection(page.content, selection);
-          if (!resolved.found) {
-            throw this.anchorNotFoundError(page.content, selection, false);
-          }
-          anchorNormalized = resolved.normalized;
+        } else if (!canAnchorInDoc(page.content, selection)) {
+          throw new Error(
+            "create_comment: could not find the selection text in the page to anchor the comment. " +
+              "Provide the EXACT contiguous text from a single paragraph/block (<=250 chars).",
+          );
         }
       } catch (e) {
-        // Rethrow our own "not found"/"ambiguous"/"spans multiple blocks" errors;
-        // swallow read/network errors so the live anchor step can still try (and
-        // enforce) anchoring.
+        // Rethrow our own "not found"/"ambiguous" errors; swallow read/network
+        // errors so the live anchor step can still try (and enforce) anchoring.
         if (
           e instanceof Error &&
           (e.message.startsWith("create_comment: could not find the selection") ||
-            e.message.startsWith(
-              "create_comment: the selection spans multiple blocks",
-            ) ||
             e.message.startsWith(
               "create_comment: the suggestion's selection is ambiguous",
             ))
@@ -2721,10 +2650,6 @@ export class DocmostClient {
     // Set inside the transform when a suggestion's live anchor is ambiguous
     // (>=2 occurrences), so the rollback path can surface the right error.
     let ambiguousInLiveDoc = false;
-    // Captured inside the transform on a not-found abort, so the rollback path
-    // can surface the closest-block / spans-multiple-blocks hint built from the
-    // LIVE document (the pre-check page is not in scope there).
-    let liveNotFoundError: Error | null = null;
     try {
       const collabToken = await this.getCollabTokenWithReauth();
       // Open the collab doc by the canonical UUID, never the slugId (#260). The
@@ -2752,13 +2677,6 @@ export class DocmostClient {
             const liveCount = countAnchorMatches(doc, selection as string);
             if (liveCount !== 1) {
               ambiguousInLiveDoc = liveCount >= 2;
-              if (liveCount === 0) {
-                liveNotFoundError = this.anchorNotFoundError(
-                  doc,
-                  selection as string,
-                  true,
-                );
-              }
               return null;
             }
           }
@@ -2768,11 +2686,6 @@ export class DocmostClient {
           }
           // Selection text not found in the LIVE document: abort the write. The
           // rollback + throw below turns this into a hard error.
-          liveNotFoundError = this.anchorNotFoundError(
-            doc,
-            selection as string,
-            true,
-          );
           return null;
         },
       );
@@ -2789,28 +2702,13 @@ export class DocmostClient {
       // suggestion, was ambiguous) in the live document. Roll back the comment
       // and surface a hard error.
       await this.safeDeleteComment(newCommentId);
-      if (ambiguousInLiveDoc) {
-        throw new Error(
-          "create_comment: the suggestion's selection is ambiguous in the live document (multiple occurrences); the comment was rolled back. Expand the selection with surrounding context so it is unique.",
-        );
-      }
-      throw (
-        liveNotFoundError ??
-        new Error(
-          "create_comment: failed to anchor the comment (selection not found in the live document); the comment was rolled back",
-        )
+      throw new Error(
+        ambiguousInLiveDoc
+          ? "create_comment: the suggestion's selection is ambiguous in the live document (multiple occurrences); the comment was rolled back. Expand the selection with surrounding context so it is unique."
+          : "create_comment: failed to anchor the comment (selection not found in the live document); the comment was rolled back",
       );
     }
 
-    // Soft warning (like edit_page_text): the selection only matched after
-    // stripping markdown, so the caller likely quoted a styled fragment.
-    if (anchorNormalized) {
-      result.warning =
-        "The selection matched only after stripping markdown syntax; the comment " +
-        "was anchored on the document's plain text. Copy the selection verbatim " +
-        "from get_page / search_in_page output to avoid this.";
-    }
-
     result.anchored = true;
     return result;
   }

packages/mcp/src/lib/comment-anchor.ts

@@ -17,23 +17,8 @@
  * comparing and match across maximal runs of consecutive text nodes within a
  * single block, while mapping every normalized character back to its raw index
  * so the mark lands on the exact original characters.
- *
- * MARKDOWN-STRIP FALLBACK: when the agent copies a selection that still carries
- * inline markdown (`**bold**`, `` `code` ``, `[t](u)`), the raw locator will not
- * match the document's plain text. Exactly like edit_page_text's json-edit
- * fallback, we first try the verbatim selection and, ONLY if it anchors nowhere
- * in the whole document, retry with `stripInlineMarkdown` applied. `canAnchorInDoc`,
- * `getAnchoredText` and `applyAnchorInDoc` share this decision via
- * `resolveAnchorSelection`. `countAnchorMatches` keeps its OWN parallel exact-wins
- * implementation (it needs a raw match COUNT, not a single resolved locator), kept
- * deliberately in sync with `resolveAnchorSelection`: raw match ⇒ use raw, else fall
- * back to the stripped count. All four therefore agree on which locator matched —
- * the suggestion-uniqueness gate depends on count and can/get never disagreeing, so
- * these two exact-wins implementations MUST stay in sync if either is changed.
  */
 
-import { stripInlineMarkdown } from "./text-normalize.js";
-
 /** Typographic double-quote variants mapped to ASCII `"`. */
 const DOUBLE_QUOTES = "«»„“”‟〝〞＂";
 /** Typographic single-quote/apostrophe variants mapped to ASCII `'`. */
@@ -229,17 +214,15 @@ function reconstructRawText(blockContent: any[], match: AnchorMatch): string {
  * un-appliable (spurious 409).
  */
 export function getAnchoredText(doc: any, selection: string): string | null {
-  const { selection: effective, found } = resolveAnchorSelection(doc, selection);
-  if (!found) return null;
   const visit = (node: any, depth: number): string | null => {
     if (depth > MAX_DEPTH || !node || typeof node !== "object") return null;
     if (!Array.isArray(node.content)) return null;
-    const match = findAnchorInBlock(node.content, effective);
+    const match = findAnchorInBlock(node.content, selection);
     if (match) return reconstructRawText(node.content, match);
     for (const child of node.content) {
       if (child && typeof child === "object" && Array.isArray(child.content)) {
-        const foundText = visit(child, depth + 1);
-        if (foundText !== null) return foundText;
+        const found = visit(child, depth + 1);
+        if (found !== null) return found;
       }
     }
     return null;
@@ -248,11 +231,12 @@ export function getAnchoredText(doc: any, selection: string): string | null {
 }
 
 /**
- * RAW (no markdown-strip fallback) depth-first check that `selection` anchors
- * somewhere in `doc`. This is the primitive `resolveAnchorSelection` builds on;
- * public callers should use `canAnchorInDoc`, which adds the strip fallback.
+ * Depth-first, document-order check for whether `selection` can be anchored
+ * anywhere in `doc`. At each node with an array `content`, first try to match
+ * within that node's own content, then recurse into children that themselves
+ * have a `content` array.
  */
-function rawCanAnchorInDoc(doc: any, selection: string): boolean {
+export function canAnchorInDoc(doc: any, selection: string): boolean {
   const visit = (node: any, depth: number): boolean => {
     if (depth > MAX_DEPTH || !node || typeof node !== "object") return false;
     if (!Array.isArray(node.content)) return false;
@@ -267,43 +251,6 @@ function rawCanAnchorInDoc(doc: any, selection: string): boolean {
   return visit(doc, 0);
 }
 
-/**
- * Decide the locator that ACTUALLY anchors `selection` in `doc`, applying the
- * markdown-strip fallback once (so every public entry point agrees):
- *  - EXACT WINS: if the verbatim selection anchors anywhere, use it as-is.
- *  - FALLBACK: only if the verbatim selection anchors nowhere, and the
- *    markdown-stripped form differs and DOES anchor, use the stripped form and
- *    flag `normalized` so callers can surface a soft warning.
- *  - otherwise `found` is false and `selection` is returned unchanged.
- *
- * The stripped form is used ONLY to LOCATE the anchor; getAnchoredText still
- * reconstructs and stores the RAW document substring, so the strip never leaks
- * into what gets persisted.
- */
-export function resolveAnchorSelection(
-  doc: any,
-  selection: string,
-): { selection: string; found: boolean; normalized: boolean } {
-  if (rawCanAnchorInDoc(doc, selection)) {
-    return { selection, found: true, normalized: false };
-  }
-  const stripped = stripInlineMarkdown(selection);
-  if (stripped !== selection && rawCanAnchorInDoc(doc, stripped)) {
-    return { selection: stripped, found: true, normalized: true };
-  }
-  return { selection, found: false, normalized: false };
-}
-
-/**
- * Depth-first, document-order check for whether `selection` can be anchored
- * anywhere in `doc` (with the markdown-strip fallback). At each node with an
- * array `content`, first try to match within that node's own content, then
- * recurse into children that themselves have a `content` array.
- */
-export function canAnchorInDoc(doc: any, selection: string): boolean {
-  return resolveAnchorSelection(doc, selection).found;
-}
-
 /**
  * Split the matched text nodes and splice the comment mark across the range.
  * `blockContent` is mutated IN PLACE. `match.startChild..endChild` are all text
@@ -368,7 +315,7 @@ function spliceCommentMark(
  * not use this. (Note: counts OCCURRENCES, not just matching blocks, so two
  * occurrences inside one block are correctly reported as 2.)
  */
-function rawCountAnchorMatches(doc: any, selection: string): number {
+export function countAnchorMatches(doc: any, selection: string): number {
   const normSel = normalizeForMatch(selection).norm.trim();
   if (normSel.length === 0) return 0;
 
@@ -422,25 +369,6 @@ function rawCountAnchorMatches(doc: any, selection: string): number {
   return total;
 }
 
-/**
- * Uniqueness gate for suggestions, with the SAME markdown-strip fallback as the
- * other entry points so count never disagrees with can/get/apply. EXACT WINS: if
- * the verbatim selection occurs at all, return its raw occurrence count (so a
- * selection that is unique raw stays unique — the fallback never runs and cannot
- * introduce a spurious second match). Only when the verbatim selection is absent
- * do we count occurrences of the markdown-stripped form.
- */
-export function countAnchorMatches(doc: any, selection: string): number {
-  const raw = rawCountAnchorMatches(doc, selection);
-  if (raw > 0) return raw;
-  const stripped = stripInlineMarkdown(selection);
-  if (stripped !== selection) {
-    const strippedCount = rawCountAnchorMatches(doc, stripped);
-    if (strippedCount > 0) return strippedCount;
-  }
-  return 0;
-}
-
 /**
  * Depth-first (same order as canAnchorInDoc) over `doc`; on the FIRST block
  * whose content matches `selection`, splice the comment mark across the matched
@@ -452,12 +380,10 @@ export function applyAnchorInDoc(
   selection: string,
   commentId: string,
 ): boolean {
-  const { selection: effective, found } = resolveAnchorSelection(doc, selection);
-  if (!found) return false;
   const visit = (node: any, depth: number): boolean => {
     if (depth > MAX_DEPTH || !node || typeof node !== "object") return false;
     if (!Array.isArray(node.content)) return false;
-    const match = findAnchorInBlock(node.content, effective);
+    const match = findAnchorInBlock(node.content, selection);
     if (match) {
       spliceCommentMark(node.content, match, commentId);
       return true;

packages/mcp/src/lib/json-edit.ts

@@ -12,11 +12,7 @@
  * re-import for small wording fixes.
  */
 
-import {
-  stripInlineMarkdown,
-  stripBalancedWrappers,
-  closestBlockHint,
-} from "./text-normalize.js";
+import { stripInlineMarkdown, stripBalancedWrappers } from "./text-normalize.js";
 
 export interface TextEdit {
   find: string;
@@ -385,9 +381,29 @@ export function applyTextEdits(
       } else {
         // Append a bounded "closest text" hint: find the FIRST block that
         // contains the longest whitespace-delimited token (>= 3 chars) of the
-        // (stripped, then raw) locator, and quote that block's plain text. Shared
-        // with create_comment via closestBlockHint so both give the same hint.
-        reason = "text not found in the document." + closestBlockHint(blockPlain, edit.find);
+        // (stripped, then raw) locator, and quote that block's plain text.
+        reason = "text not found in the document.";
+        const tokenSource = stripped.length > 0 ? stripped : edit.find;
+        const longestToken = tokenSource
+          .split(/\s+/)
+          .filter((t) => t.length >= 3)
+          .sort((a, b) => b.length - a.length)[0];
+        if (longestToken) {
+          const hitBlock = blockPlain.find((plain) =>
+            plain.includes(longestToken),
+          );
+          if (hitBlock) {
+            // Truncate by code point (spread iterates by code point) so a
+            // surrogate pair is never split; append the ellipsis only when the
+            // text was actually longer than the limit.
+            const points = [...hitBlock];
+            const snippet =
+              points.length > 120
+                ? points.slice(0, 120).join("") + "…"
+                : hitBlock;
+            reason += ` Closest block text: "${snippet}".`;
+          }
+        }
       }
       failed.push({ find: edit.find, reason });
       continue;

packages/mcp/src/lib/text-normalize.ts

@@ -114,37 +114,3 @@ export function stripInlineMarkdown(s: string): string {
 
   return out;
 }
-
-/**
- * Build a bounded "closest text" hint for an anchor/find MISS, shared by
- * edit_page_text (json-edit) and create_comment (client) so both surface the
- * same self-correction affordance.
- *
- * Take the longest whitespace-delimited token (>= 3 chars) of the locator
- * (markdown-stripped first, so `**bold**` contributes `bold`), find the FIRST
- * of `blockTexts` that contains it, and return ` Closest block text: "…".` with
- * the block quoted (truncated to 120 code points + ellipsis). Returns "" when
- * no token qualifies or no block contains it, so the caller can append it
- * unconditionally.
- */
-export function closestBlockHint(
-  blockTexts: string[],
-  locator: string,
-): string {
-  if (typeof locator !== "string" || locator.length === 0) return "";
-  const stripped = stripInlineMarkdown(locator);
-  const tokenSource = stripped.length > 0 ? stripped : locator;
-  const longestToken = tokenSource
-    .split(/\s+/)
-    .filter((t) => t.length >= 3)
-    .sort((a, b) => b.length - a.length)[0];
-  if (!longestToken) return "";
-  const hitBlock = blockTexts.find((plain) => plain.includes(longestToken));
-  if (!hitBlock) return "";
-  // Truncate by code point (spread iterates by code point) so a surrogate pair
-  // is never split; append the ellipsis only when the text was actually longer.
-  const points = [...hitBlock];
-  const snippet =
-    points.length > 120 ? points.slice(0, 120).join("") + "…" : hitBlock;
-  return ` Closest block text: "${snippet}".`;
-}

packages/mcp/src/tool-specs.ts

@@ -771,13 +771,9 @@ export const SHARED_TOOL_SPECS = {
       'The comment is anchored inline to the given exact `selection` text ' +
       '(which gets highlighted); page-level comments are NOT supported. A ' +
       'new top-level comment REQUIRES a `selection`. Replies inherit the ' +
-      "parent's anchor and take no selection. Always COPY the `selection` " +
-      'VERBATIM from get_page / search_in_page output — do NOT quote it from ' +
-      'memory (stale-memory quoting is the top cause of anchor misses). If the ' +
-      'call fails with a "selection not found" error, the error quotes the ' +
-      "closest block text (or says the selection spans multiple blocks); retry " +
-      "with a corrected EXACT selection copied verbatim from a single " +
-      'paragraph/block. You may also attach a ' +
+      "parent's anchor and take no selection. If the call fails with a " +
+      '"selection not found" error, retry with a corrected EXACT selection ' +
+      'copied verbatim from a single paragraph/block. You may also attach a ' +
       '`suggestedText` proposing a replacement for the `selection` (a human ' +
       'applies it from the UI); when set, the `selection` must occur exactly ' +
       'once in the page. Reversible via the comment UI.',

packages/mcp/test/mock/create-comment.test.mjs

@@ -548,94 +548,3 @@ test("suggestedText: the stored selection is the doc's RAW typographic substring
   );
   assert.equal(createPayload.suggestedText, "goodbye");
 });
-
-// -----------------------------------------------------------------------------
-// 8) #408: a not-found selection error QUOTES the closest block text so the
-//    model can self-correct instead of blind-retrying.
-// -----------------------------------------------------------------------------
-test("a not-found selection error includes a 'Closest block text' hint", async () => {
-  let createCalls = 0;
-  const { baseURL } = await spawn(async (req, res) => {
-    await readBody(req);
-    if (req.url === "/api/auth/login") {
-      sendJson(res, 200, { success: true }, {
-        "Set-Cookie": "authToken=t; Path=/; HttpOnly",
-      });
-      return;
-    }
-    if (req.url === "/api/pages/info") {
-      sendJson(res, 200, {
-        data: {
-          id: "page-1",
-          content: {
-            type: "doc",
-            content: [
-              { type: "paragraph", content: [{ type: "text", text: "The quick brown fox jumps" }] },
-            ],
-          },
-        },
-      });
-      return;
-    }
-    if (req.url === "/api/comments/create") {
-      createCalls++;
-      sendJson(res, 200, { data: { id: "should-not-happen" } });
-      return;
-    }
-    sendJson(res, 404, { message: "not found" });
-  });
-
-  const client = new DocmostClient(baseURL, "user@example.com", "pw");
-  await assert.rejects(
-    () => client.createComment("page-1", "body", "inline", "quick brown cat"),
-    /Closest block text: "The quick brown fox jumps"/,
-    "a not-found selection must quote the closest block text",
-  );
-  assert.equal(createCalls, 0, "/comments/create must NOT be called on a miss");
-});
-
-// -----------------------------------------------------------------------------
-// 9) #408: a selection that straddles two blocks gets the explicit
-//    "spans multiple blocks" message instead of a bare not-found.
-// -----------------------------------------------------------------------------
-test("a selection spanning multiple blocks gets the explicit spans-multiple-blocks message", async () => {
-  let createCalls = 0;
-  const { baseURL } = await spawn(async (req, res) => {
-    await readBody(req);
-    if (req.url === "/api/auth/login") {
-      sendJson(res, 200, { success: true }, {
-        "Set-Cookie": "authToken=t; Path=/; HttpOnly",
-      });
-      return;
-    }
-    if (req.url === "/api/pages/info") {
-      sendJson(res, 200, {
-        data: {
-          id: "page-1",
-          content: {
-            type: "doc",
-            content: [
-              { type: "paragraph", content: [{ type: "text", text: "the quick brown" }] },
-              { type: "paragraph", content: [{ type: "text", text: "fox jumps over" }] },
-            ],
-          },
-        },
-      });
-      return;
-    }
-    if (req.url === "/api/comments/create") {
-      createCalls++;
-      sendJson(res, 200, { data: { id: "should-not-happen" } });
-      return;
-    }
-    sendJson(res, 404, { message: "not found" });
-  });
-
-  const client = new DocmostClient(baseURL, "user@example.com", "pw");
-  await assert.rejects(
-    () => client.createComment("page-1", "body", "inline", "brown fox"),
-    /spans multiple blocks/,
-    "a cross-block selection must report the spans-multiple-blocks hint",
-  );
-  assert.equal(createCalls, 0, "/comments/create must NOT be called on a miss");
-});

packages/mcp/test/unit/comment-anchor.test.mjs

@@ -8,7 +8,6 @@ import {
   applyAnchorInDoc,
   countAnchorMatches,
   getAnchoredText,
-  resolveAnchorSelection,
 } from "../../build/lib/comment-anchor.js";
 
 const COMMENT_ID = "cmt-123";
@@ -309,70 +308,3 @@ test("getAnchoredText returns null when the selection does not anchor", () => {
   const doc = paragraphDoc([{ type: "text", text: "hello world" }]);
   assert.equal(getAnchoredText(doc, "not present"), null);
 });
-
-// ---------------------------------------------------------------------------
-// #408 MARKDOWN-STRIP FALLBACK. A selection copied with inline markdown still
-// carries `**`/`` ` ``/`[t](u)` markers the plain document text lacks. When the
-// verbatim selection anchors nowhere, all four entry points retry with the
-// markdown stripped — consistently, so the suggestion-uniqueness gate stays
-// coherent — while what gets STORED remains the raw document substring.
-// ---------------------------------------------------------------------------
-test("a markdown-styled selection anchors against plain doc text via the strip fallback", () => {
-  const doc = paragraphDoc([{ type: "text", text: "a bold word here" }]);
-  // The agent quoted "**bold** word" from a styled view; the doc is plain text.
-  const sel = "**bold** word";
-  const resolved = resolveAnchorSelection(doc, sel);
-  assert.equal(resolved.found, true, "strip fallback finds the anchor");
-  assert.equal(resolved.normalized, true, "reports the soft-warning flag");
-  assert.equal(canAnchorInDoc(doc, sel), true);
-  assert.equal(countAnchorMatches(doc, sel), 1);
-
-  const ok = applyAnchorInDoc(doc, sel, COMMENT_ID);
-  assert.equal(ok, true);
-  const marked = doc.content[0].content.filter((p) => commentMark(p));
-  assert.equal(marked.map((m) => m.text).join(""), "bold word",
-    "the mark lands on the plain-text span");
-});
-
-test("getAnchoredText stores the RAW doc substring even when matched via the strip fallback", () => {
-  // Doc uses a smart apostrophe; the agent typed ASCII + markdown emphasis.
-  const doc = paragraphDoc([{ type: "text", text: "it’s bold now" }]);
-  const stored = getAnchoredText(doc, "it's **bold**");
-  assert.equal(stored, "it’s bold",
-    "stored selection is the raw document text, not the stripped/ASCII locator");
-});
-
-test("the strip fallback does not flip a raw-unique selection to ambiguous", () => {
-  // "config" appears twice, but the raw phrase "config value" appears once.
-  const doc = {
-    type: "doc",
-    content: [
-      { type: "paragraph", content: [{ type: "text", text: "the config value here" }] },
-      { type: "paragraph", content: [{ type: "text", text: "another config here" }] },
-    ],
-  };
-  // Raw phrase is unique -> exactly 1, and no strip happens (nothing to strip).
-  assert.equal(countAnchorMatches(doc, "config value"), 1);
-  assert.equal(resolveAnchorSelection(doc, "config value").normalized, false);
-});
-
-test("EXACT WINS: a raw match short-circuits the strip fallback (count reflects raw)", () => {
-  // A literal "**" run exists raw once; its stripped form would also appear.
-  const doc = paragraphDoc([{ type: "text", text: "use **stars** and stars" }]);
-  // Raw "**stars**" occurs once -> count 1 from the verbatim locator; the
-  // fallback (which would find two "stars") never runs.
-  assert.equal(countAnchorMatches(doc, "**stars**"), 1);
-  assert.equal(resolveAnchorSelection(doc, "**stars**").normalized, false);
-});
-
-test("a markdown selection whose stripped form is ambiguous is counted as ambiguous", () => {
-  const doc = {
-    type: "doc",
-    content: [
-      { type: "paragraph", content: [{ type: "text", text: "first config here" }] },
-      { type: "paragraph", content: [{ type: "text", text: "second config here" }] },
-    ],
-  };
-  // Verbatim "**config**" matches nothing; stripped "config" matches twice.
-  assert.equal(countAnchorMatches(doc, "**config**"), 2);
-});