From 5c04da4c69557ee2a5d8e5c6d9df229fa327d84b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=BC=A0=E5=BC=BA?= <zhangqiang@furtherref.com>
Date: Mon, 18 May 2026 23:03:52 -0400
Subject: [PATCH 1/4] fix(mention): canonicalize @mention labels server-side
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The mention markdown `[@Label](mention://type/UUID)` has two parts: the
visible label and the routable UUID. Mention routing reads only the UUID,
but the rendered comment shows only the label, so a label that disagrees
with its UUID silently misroutes — the UI shows "@A" while agent B is
triggered and replies. This already happened in the squad coordination
flow (a leader's delegation paired one roster row's label with another
row's UUID).

Defend against it at write time, in the place every comment passes
through: on `CreateComment` / `UpdateComment` and the agent task-
completion comment path, rewrite each mention's label to the current
name of the entity its UUID resolves to.

- Agent / squad: if the UUID resolves in the workspace, replace the
  label with the entity's current name. If it doesn't resolve, keep the
  mention markdown as-is — `ParseMentions` will still find no live
  trigger target, and the existing top-level "mention only others"
  trigger-suppression keeps working.
- Member: resolve via `GetMemberByUserAndWorkspace`, not `GetUser` —
  the latter is workspace-unscoped and would leak the name of any
  user in the system. If the user is not a member of this workspace,
  strip the mention entirely.
- When canonicalization changes a label, log a warning with the
  original label, resolved entity name, and UUID. This gives a
  searchable signal for the prompt/UI bug that produced the mismatch
  in the first place.

Care taken in the regex layer:
- Issue-identifier expansion (`MUL-123` → markdown link) previously
  re-scanned inside mention labels, so an agent named "MUL-117 reviewer"
  would have its label rewritten into nested markdown. Split skip-region
  detection into `findSkipRegions` (code fences / inline code, shared
  with canonicalization) and `expandSkipRegions` (also covers existing
  link spans, used by issue expansion).
- Canonical labels are markdown-escaped before being spliced back in,
  so a name containing `]` or `\` can't break the surrounding link.
---
 server/cmd/multica/cmd_issue.go              |   6 +-
 server/internal/handler/comment.go           |  44 +++
 server/internal/mention/canonicalize.go      | 198 ++++++++++++
 server/internal/mention/canonicalize_test.go | 299 +++++++++++++++++++
 server/internal/mention/expand.go            |  37 ++-
 server/internal/mention/expand_test.go       |  29 ++
 server/internal/service/task.go              |   7 +
 server/internal/util/mention.go              | 132 +++++++-
 server/internal/util/mention_test.go         |  49 +++
 9 files changed, 787 insertions(+), 14 deletions(-)
 create mode 100644 server/internal/mention/canonicalize.go
 create mode 100644 server/internal/mention/canonicalize_test.go

diff --git a/server/cmd/multica/cmd_issue.go b/server/cmd/multica/cmd_issue.go
index fc72c04b3f..6f7752f1f1 100644
--- a/server/cmd/multica/cmd_issue.go
+++ b/server/cmd/multica/cmd_issue.go
@@ -1640,10 +1640,10 @@ func resolveAssignee(ctx context.Context, client *cli.APIClient, name string, ki
 
 func normalizeAssigneeLookupInput(raw string) string {
 	input := strings.TrimSpace(raw)
-	if m := util.MentionRe.FindStringSubmatch(input); len(m) == 4 && m[0] == input {
-		switch m[2] {
+	if matches := util.FindMentionMatches(input); len(matches) == 1 && matches[0].Start == 0 && matches[0].End == len(input) {
+		switch matches[0].Type {
 		case "member", "agent", "squad":
-			return m[3]
+			return matches[0].ID
 		}
 	}
 	input = strings.TrimLeftFunc(input, func(r rune) bool {
diff --git a/server/internal/handler/comment.go b/server/internal/handler/comment.go
index 1626a2ed4a..2a280fe3b7 100644
--- a/server/internal/handler/comment.go
+++ b/server/internal/handler/comment.go
@@ -6,6 +6,7 @@ import (
 	"log/slog"
 	"net/http"
 	"strconv"
+	"strings"
 	"time"
 
 	"github.com/go-chi/chi/v5"
@@ -506,6 +507,15 @@ func (h *Handler) CreateComment(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 
+	// Canonicalize agent/member/squad mention labels so the visible label
+	// always matches the entity the UUID actually resolves to. Without this,
+	// an author (typically an LLM) can post a comment whose mention link
+	// says "[@A](mention://agent/<B-uuid>)" — the UI renders @A but the
+	// routing layer triggers B, so the wrong agent picks up the task while
+	// humans see the right name. Done before ExpandIssueIdentifiers so the
+	// issue-identifier pass operates on already-cleaned content.
+	req.Content = mention.CanonicalizeMentions(r.Context(), h.Queries, issue.WorkspaceID, req.Content)
+
 	// Expand bare issue identifiers (e.g. MUL-117) into mention links.
 	req.Content = mention.ExpandIssueIdentifiers(r.Context(), h.Queries, issue.WorkspaceID, req.Content)
 
@@ -735,6 +745,7 @@ func (h *Handler) enqueueMentionedAgentTasks(ctx context.Context, issue db.Issue
 			if err != nil {
 				continue
 			}
+			logMentionLabelMismatch(m, squad.Name, "squad", issue.ID, comment.ID)
 			leaderID := squad.LeaderID
 			// Prevent self-trigger only when the agent's last activity on this
 			// issue was itself a leader task. An agent that holds both the
@@ -790,6 +801,7 @@ func (h *Handler) enqueueMentionedAgentTasks(ctx context.Context, issue db.Issue
 		if err != nil || !agent.RuntimeID.Valid || agent.ArchivedAt.Valid {
 			continue
 		}
+		logMentionLabelMismatch(m, agent.Name, "agent", issue.ID, comment.ID)
 		// Private-agent gate (member→private requires allowed_principals;
 		// agent→agent always passes).
 		if !h.canAccessPrivateAgent(ctx, agent, authorType, authorID, wsID) {
@@ -811,6 +823,33 @@ func (h *Handler) enqueueMentionedAgentTasks(ctx context.Context, issue db.Issue
 	}
 }
 
+// logMentionLabelMismatch emits a warning when the visible mention label
+// disagrees with the resolved entity's canonical name. Observability for
+// the canonicalization defense in mention.CanonicalizeMentions — after that
+// pass ran on write, this warn should be effectively silent in steady state.
+// A non-zero rate means: historical rows that predate canonicalization, or
+// some write path that bypasses it (e.g. a future endpoint that forgets to
+// call CanonicalizeMentions).
+func logMentionLabelMismatch(m util.Mention, canonicalName, kind string, issueID, commentID pgtype.UUID) {
+	if m.Label == "" || canonicalName == "" {
+		return
+	}
+	// Editor escapes `[` and `]` in labels for grammar; undo that for the
+	// equality check so a legitimately-bracketed name doesn't false-positive.
+	unescaped := strings.ReplaceAll(strings.ReplaceAll(m.Label, `\[`, `[`), `\]`, `]`)
+	if unescaped == canonicalName {
+		return
+	}
+	slog.Warn("mention label / UUID mismatch",
+		"kind", kind,
+		"id", m.ID,
+		"label", m.Label,
+		"resolved_name", canonicalName,
+		"issue_id", uuidToString(issueID),
+		"comment_id", uuidToString(commentID),
+	)
+}
+
 func (h *Handler) UpdateComment(w http.ResponseWriter, r *http.Request) {
 	commentId := chi.URLParam(r, "commentId")
 
@@ -871,6 +910,11 @@ func (h *Handler) UpdateComment(w http.ResponseWriter, r *http.Request) {
 
 	// NOTE: See CreateComment — Markdown is sanitized at render/edit time, not here.
 
+	// Canonicalize mention labels on edit too: an author editing their own
+	// comment can introduce the same label/UUID mismatch addressed in
+	// CreateComment, so we run the same defense before persisting.
+	req.Content = mention.CanonicalizeMentions(r.Context(), h.Queries, wsUUID, req.Content)
+
 	comment, err := h.Queries.UpdateComment(r.Context(), db.UpdateCommentParams{
 		ID:      commentUUID,
 		Content: req.Content,
diff --git a/server/internal/mention/canonicalize.go b/server/internal/mention/canonicalize.go
new file mode 100644
index 0000000000..dfebbe017c
--- /dev/null
+++ b/server/internal/mention/canonicalize.go
@@ -0,0 +1,198 @@
+package mention
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/jackc/pgx/v5/pgtype"
+	"github.com/multica-ai/multica/server/internal/util"
+	db "github.com/multica-ai/multica/server/pkg/db/generated"
+)
+
+// NameResolver looks up the canonical display name for an entity referenced
+// by a mention link. Implemented by *db.Queries in production.
+//
+// Note on member lookups: GetUser is workspace-unscoped (the user table has
+// no workspace_id). For member mentions, callers must gate the user lookup
+// behind GetMemberByUserAndWorkspace — otherwise a `mention://member/<id>`
+// for a globally-valid user who is not a workspace member would canonicalize
+// to that outsider's name, leaking the name and leaving the link in place
+// for downstream routing-style checks.
+type NameResolver interface {
+	GetAgentInWorkspace(ctx context.Context, arg db.GetAgentInWorkspaceParams) (db.Agent, error)
+	GetSquadInWorkspace(ctx context.Context, arg db.GetSquadInWorkspaceParams) (db.Squad, error)
+	GetMemberByUserAndWorkspace(ctx context.Context, arg db.GetMemberByUserAndWorkspaceParams) (db.Member, error)
+	GetUser(ctx context.Context, id pgtype.UUID) (db.User, error)
+}
+
+// lookupOutcome carries the decision lookupCanonicalName reached for a
+// single mention. The three states distinguish "rewrite to canonical name"
+// from "leave the link alone" from "demote to plain text" — collapsing the
+// last two into a single boolean failure breaks the trigger-suppression
+// invariant in commentMentionsOthersButNotAssignee, which relies on author
+// intent surviving canonicalization for agent/squad mentions.
+type lookupOutcome int
+
+const (
+	// lookupResolved means the UUID resolves and the label should be rewritten.
+	lookupResolved lookupOutcome = iota
+	// lookupKeepAsIs means the UUID does not resolve, but the mention link
+	// should be preserved verbatim. Used for agent and squad mentions whose
+	// UUID is unknown / cross-workspace / deleted — the label was authored
+	// by whoever wrote the comment (not derived from a DB lookup), so there
+	// is no name-leak risk, and preserving the link keeps the author's
+	// routing intent visible to downstream gates.
+	lookupKeepAsIs
+	// lookupStrip means the link must be demoted to plain `@<label>` text.
+	// Reserved for member mentions whose UUID belongs to a user who is NOT
+	// a member of this workspace — canonicalizing via the global GetUser
+	// would leak the outsider's real display name into a workspace they
+	// have no membership in.
+	lookupStrip
+)
+
+// CanonicalizeMentions rewrites every agent/member/squad mention in `content`
+// so the visible label matches the actual entity name stored in the database.
+// Defends against the failure mode in which an author (typically an LLM)
+// writes `[@A](mention://agent/<B-uuid>)` — the UI renders "@A" but the
+// routing layer triggers B. After this pass, the label and the UUID's
+// resolved entity always agree, eliminating that silent mismatch.
+//
+// Behaviour:
+//   - agent / member / squad mention whose UUID resolves in this workspace:
+//     label replaced with the entity's current `name` (with `[` and `]`
+//     escaped to keep the link grammar intact).
+//   - agent / squad mention whose UUID does NOT resolve (deleted,
+//     cross-workspace, fake): mention link left in place. The label is
+//     author-controlled so there is no name-leak risk, and downstream gates
+//     (enqueueMentionedAgentTasks, commentMentionsOthersButNotAssignee)
+//     correctly interpret the unresolved mention without further help.
+//   - member mention whose UUID is NOT a workspace member: mention link is
+//     stripped down to plain `@<original-label>` text. GetUser is global,
+//     so leaving the link would let a follow-up canonicalize-on-edit leak
+//     the outsider's display name; demote it to text so the link cannot be
+//     re-resolved and the routing-style mention disappears.
+//   - `issue` and `all` mentions: left untouched. Issue mention labels are
+//     resolved at render time via IssueMentionLink; `all` is a literal.
+//   - Mentions inside inline code or fenced code blocks: left untouched
+//     (shared with ExpandIssueIdentifiers via findSkipRegions).
+func CanonicalizeMentions(ctx context.Context, resolver NameResolver, workspaceID pgtype.UUID, content string) string {
+	if content == "" {
+		return content
+	}
+	matches := util.FindMentionMatches(content)
+	if len(matches) == 0 {
+		return content
+	}
+	skipRegions := findSkipRegions(content)
+
+	type replacement struct {
+		start, end int
+		text       string
+	}
+	var replacements []replacement
+
+	for _, m := range matches {
+		fullStart, fullEnd := m.Start, m.End
+		if inSkipRegion(fullStart, skipRegions) {
+			continue
+		}
+		label := m.Label
+		mentionType := m.Type
+		idStr := m.ID
+
+		if mentionType != "agent" && mentionType != "member" && mentionType != "squad" {
+			continue
+		}
+
+		canonical, outcome := lookupCanonicalName(ctx, resolver, workspaceID, mentionType, idStr)
+		switch outcome {
+		case lookupResolved:
+			escapedCanonical := escapeMentionLabel(canonical)
+			if escapedCanonical == label {
+				continue
+			}
+			replacements = append(replacements, replacement{
+				start: fullStart,
+				end:   fullEnd,
+				text:  fmt.Sprintf("[@%s](mention://%s/%s)", escapedCanonical, mentionType, idStr),
+			})
+		case lookupStrip:
+			replacements = append(replacements, replacement{
+				start: fullStart,
+				end:   fullEnd,
+				text:  "@" + label,
+			})
+		case lookupKeepAsIs:
+			// no-op
+		}
+	}
+
+	if len(replacements) == 0 {
+		return content
+	}
+	result := content
+	for i := len(replacements) - 1; i >= 0; i-- {
+		r := replacements[i]
+		result = result[:r.start] + r.text + result[r.end:]
+	}
+	return result
+}
+
+func lookupCanonicalName(ctx context.Context, r NameResolver, workspaceID pgtype.UUID, mentionType, idStr string) (string, lookupOutcome) {
+	id, err := util.ParseUUID(idStr)
+	if err != nil {
+		if mentionType == "member" {
+			return "", lookupStrip
+		}
+		// Malformed agent/squad UUID — keep the authored link in place. We
+		// never reach the DB for this row, so there is no name to leak;
+		// leaving the literal markdown lets downstream gates preserve the
+		// author's routing intent.
+		return "", lookupKeepAsIs
+	}
+	switch mentionType {
+	case "agent":
+		ag, err := r.GetAgentInWorkspace(ctx, db.GetAgentInWorkspaceParams{ID: id, WorkspaceID: workspaceID})
+		if err != nil {
+			return "", lookupKeepAsIs
+		}
+		return ag.Name, lookupResolved
+	case "squad":
+		sq, err := r.GetSquadInWorkspace(ctx, db.GetSquadInWorkspaceParams{ID: id, WorkspaceID: workspaceID})
+		if err != nil {
+			return "", lookupKeepAsIs
+		}
+		return sq.Name, lookupResolved
+	case "member":
+		// Gate on workspace membership first — GetUser is global. Without
+		// this gate a `mention://member/<user-id>` for any valid user
+		// would canonicalize to that user's name regardless of which
+		// workspace the comment lives in. Non-members are stripped (not
+		// kept-as-is) so a subsequent canonicalize-on-edit cannot resolve
+		// the link via GetUser and leak the name.
+		if _, err := r.GetMemberByUserAndWorkspace(ctx, db.GetMemberByUserAndWorkspaceParams{
+			UserID:      id,
+			WorkspaceID: workspaceID,
+		}); err != nil {
+			return "", lookupStrip
+		}
+		u, err := r.GetUser(ctx, id)
+		if err != nil {
+			return "", lookupStrip
+		}
+		return u.Name, lookupResolved
+	}
+	return "", lookupKeepAsIs
+}
+
+// escapeMentionLabel mirrors the editor's mention-extension escaping
+// (packages/views/editor/extensions/mention-extension.ts): only `[` and `]`
+// are escaped so the bracket structure of the resulting markdown link
+// survives names that contain them (e.g. "David[TF]").
+func escapeMentionLabel(s string) string {
+	s = strings.ReplaceAll(s, "[", "\\[")
+	s = strings.ReplaceAll(s, "]", "\\]")
+	return s
+}
diff --git a/server/internal/mention/canonicalize_test.go b/server/internal/mention/canonicalize_test.go
new file mode 100644
index 0000000000..218a2b71c2
--- /dev/null
+++ b/server/internal/mention/canonicalize_test.go
@@ -0,0 +1,299 @@
+package mention
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"testing"
+
+	"github.com/jackc/pgx/v5/pgtype"
+	db "github.com/multica-ai/multica/server/pkg/db/generated"
+)
+
+// nameResolverMock implements NameResolver for testing. Entries are keyed by
+// the canonical UUID string (uuidToString output) of the entity.
+type nameResolverMock struct {
+	workspaceID pgtype.UUID
+	agents      map[string]string // uuid string → agent.Name
+	squads      map[string]string // uuid string → squad.Name
+	users       map[string]string // uuid string → user.Name (global, like the SQL)
+	// memberUserIDs is the set of user UUIDs that are members of
+	// workspaceID. Member canonicalization must be gated by this — a
+	// globally-valid user who is not a workspace member must NOT leak
+	// their name into a comment, and must not survive as a routable
+	// member mention.
+	memberUserIDs map[string]struct{}
+}
+
+func (m *nameResolverMock) GetAgentInWorkspace(_ context.Context, arg db.GetAgentInWorkspaceParams) (db.Agent, error) {
+	if uuidToString(arg.WorkspaceID) != uuidToString(m.workspaceID) {
+		return db.Agent{}, fmt.Errorf("wrong workspace")
+	}
+	name, ok := m.agents[uuidToString(arg.ID)]
+	if !ok {
+		return db.Agent{}, fmt.Errorf("agent not found")
+	}
+	return db.Agent{ID: arg.ID, WorkspaceID: arg.WorkspaceID, Name: name}, nil
+}
+
+func (m *nameResolverMock) GetSquadInWorkspace(_ context.Context, arg db.GetSquadInWorkspaceParams) (db.Squad, error) {
+	if uuidToString(arg.WorkspaceID) != uuidToString(m.workspaceID) {
+		return db.Squad{}, fmt.Errorf("wrong workspace")
+	}
+	name, ok := m.squads[uuidToString(arg.ID)]
+	if !ok {
+		return db.Squad{}, fmt.Errorf("squad not found")
+	}
+	return db.Squad{ID: arg.ID, WorkspaceID: arg.WorkspaceID, Name: name}, nil
+}
+
+func (m *nameResolverMock) GetUser(_ context.Context, id pgtype.UUID) (db.User, error) {
+	name, ok := m.users[uuidToString(id)]
+	if !ok {
+		return db.User{}, fmt.Errorf("user not found")
+	}
+	return db.User{ID: id, Name: name}, nil
+}
+
+func (m *nameResolverMock) GetMemberByUserAndWorkspace(_ context.Context, arg db.GetMemberByUserAndWorkspaceParams) (db.Member, error) {
+	if uuidToString(arg.WorkspaceID) != uuidToString(m.workspaceID) {
+		return db.Member{}, fmt.Errorf("wrong workspace")
+	}
+	if _, ok := m.memberUserIDs[uuidToString(arg.UserID)]; !ok {
+		return db.Member{}, fmt.Errorf("not a member")
+	}
+	return db.Member{UserID: arg.UserID, WorkspaceID: arg.WorkspaceID}, nil
+}
+
+func TestCanonicalizeMentions(t *testing.T) {
+	ctx := context.Background()
+	ws := makeUUID("ws1")
+
+	agentRealID := makeUUID("agent-real")
+	agentRealUUID := uuidToString(agentRealID)
+	agentBracketID := makeUUID("agent-brkts")
+	agentBracketUUID := uuidToString(agentBracketID)
+	agentIssueBracketID := makeUUID("agent-issue")
+	agentIssueBracketUUID := uuidToString(agentIssueBracketID)
+	agentMissingID := makeUUID("agent-gone-")
+	agentMissingUUID := uuidToString(agentMissingID)
+
+	squadID := makeUUID("squad-real-")
+	squadUUID := uuidToString(squadID)
+
+	userID := makeUUID("user-real--")
+	userUUID := uuidToString(userID)
+
+	resolver := &nameResolverMock{
+		workspaceID: ws,
+		agents: map[string]string{
+			agentRealUUID:         "RealAgent",
+			agentBracketUUID:      "David[TF]",
+			agentIssueBracketUUID: "MUL-117[TF]",
+		},
+		squads: map[string]string{
+			squadUUID: "RealSquad",
+		},
+		users: map[string]string{
+			userUUID: "Alice",
+		},
+		memberUserIDs: map[string]struct{}{
+			userUUID: {},
+		},
+	}
+
+	tests := []struct {
+		name  string
+		input string
+		want  string
+	}{
+		{
+			name:  "agent mention with matching label is unchanged",
+			input: "[@RealAgent](mention://agent/" + agentRealUUID + ")",
+			want:  "[@RealAgent](mention://agent/" + agentRealUUID + ")",
+		},
+		{
+			name:  "agent mention with mismatched label is rewritten to real name",
+			input: "[@FakeName](mention://agent/" + agentRealUUID + ")",
+			want:  "[@RealAgent](mention://agent/" + agentRealUUID + ")",
+		},
+		{
+			name:  "ordinary markdown link before agent mention is preserved",
+			input: "See [docs](https://x) and [@FakeName](mention://agent/" + agentRealUUID + ")",
+			want:  "See [docs](https://x) and [@RealAgent](mention://agent/" + agentRealUUID + ")",
+		},
+		{
+			// Agent mentions with an unresolvable UUID are LEFT IN PLACE so
+			// downstream signals that depend on author intent — most notably
+			// commentMentionsOthersButNotAssignee, which suppresses the
+			// on_comment trigger when the comment is aimed at someone other
+			// than the assignee — continue to see the mention. The mention
+			// link is harmless: enqueueMentionedAgentTasks separately gates
+			// on GetAgentInWorkspace and skips it, and the readonly renderer
+			// falls back to the markdown label when the UUID isn't cached.
+			name:  "agent mention with unresolvable uuid is left unchanged",
+			input: "hi [@Ghost](mention://agent/" + agentMissingUUID + ") there",
+			want:  "hi [@Ghost](mention://agent/" + agentMissingUUID + ") there",
+		},
+		{
+			name:  "squad mention is canonicalized",
+			input: "[@WrongSquadName](mention://squad/" + squadUUID + ")",
+			want:  "[@RealSquad](mention://squad/" + squadUUID + ")",
+		},
+		{
+			name:  "member mention is canonicalized",
+			input: "[@WrongUser](mention://member/" + userUUID + ")",
+			want:  "[@Alice](mention://member/" + userUUID + ")",
+		},
+		{
+			name:  "member mention with malformed uuid is stripped",
+			input: "[@BadMember](mention://member/aaaaaaaa)",
+			want:  "@BadMember",
+		},
+		{
+			name:  "all mention is untouched",
+			input: "[@all](mention://all/all)",
+			want:  "[@all](mention://all/all)",
+		},
+		{
+			name:  "issue mention is untouched",
+			input: "[MUL-1](mention://issue/" + agentRealUUID + ")",
+			want:  "[MUL-1](mention://issue/" + agentRealUUID + ")",
+		},
+		{
+			name:  "mention inside inline code is untouched",
+			input: "use `[@Wrong](mention://agent/" + agentRealUUID + ")` to delegate",
+			want:  "use `[@Wrong](mention://agent/" + agentRealUUID + ")` to delegate",
+		},
+		{
+			name:  "mention inside fenced code is untouched",
+			input: "```\n[@Wrong](mention://agent/" + agentRealUUID + ")\n```",
+			want:  "```\n[@Wrong](mention://agent/" + agentRealUUID + ")\n```",
+		},
+		{
+			name: "multiple mentions are all canonicalized",
+			input: "[@FakeA](mention://agent/" + agentRealUUID + ") cc [@FakeB](mention://member/" + userUUID +
+				") and squad [@FakeC](mention://squad/" + squadUUID + ")",
+			want: "[@RealAgent](mention://agent/" + agentRealUUID + ") cc [@Alice](mention://member/" + userUUID +
+				") and squad [@RealSquad](mention://squad/" + squadUUID + ")",
+		},
+		{
+			name:  "name containing brackets is escaped on rewrite",
+			input: "[@WrongLabel](mention://agent/" + agentBracketUUID + ")",
+			want:  "[@David\\[TF\\]](mention://agent/" + agentBracketUUID + ")",
+		},
+		{
+			name:  "matching label containing raw brackets is escaped",
+			input: "[@David[TF]](mention://agent/" + agentBracketUUID + ")",
+			want:  "[@David\\[TF\\]](mention://agent/" + agentBracketUUID + ")",
+		},
+		{
+			name:  "matching label containing issue key and raw brackets is escaped",
+			input: "[@MUL-117[TF]](mention://agent/" + agentIssueBracketUUID + ")",
+			want:  "[@MUL-117\\[TF\\]](mention://agent/" + agentIssueBracketUUID + ")",
+		},
+		{
+			name:  "empty content is empty",
+			input: "",
+			want:  "",
+		},
+		{
+			name:  "no mentions is no-op",
+			input: "Just plain text without mentions.",
+			want:  "Just plain text without mentions.",
+		},
+		{
+			name: "mix of canonicalized and unresolvable mentions",
+			input: "[@FakeReal](mention://agent/" + agentRealUUID + ") and [@FakeGone](mention://agent/" +
+				agentMissingUUID + ")",
+			want: "[@RealAgent](mention://agent/" + agentRealUUID + ") and [@FakeGone](mention://agent/" +
+				agentMissingUUID + ")",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := CanonicalizeMentions(ctx, resolver, ws, tt.input)
+			if got != tt.want {
+				t.Errorf("CanonicalizeMentions() =\n  %q\nwant:\n  %q", got, tt.want)
+			}
+		})
+	}
+}
+
+// TestCanonicalizeMentions_NonMemberUserStripped pins the membership gate
+// for member mentions. A `mention://member/<user-id>` whose UUID belongs to
+// a globally-valid user who is NOT a member of this workspace must be
+// stripped to plain text — never canonicalized — so non-members' display
+// names cannot leak into a workspace's comments and the mention cannot
+// continue to act as a routing target for downstream gates that compare
+// mention IDs to participants.
+func TestCanonicalizeMentions_NonMemberUserStripped(t *testing.T) {
+	ctx := context.Background()
+	ws := makeUUID("ws-A-------")
+
+	memberID := makeUUID("user-in-A--")
+	memberUUID := uuidToString(memberID)
+
+	outsiderID := makeUUID("user-other-")
+	outsiderUUID := uuidToString(outsiderID)
+
+	resolver := &nameResolverMock{
+		workspaceID: ws,
+		users: map[string]string{
+			memberUUID:   "AliceInside",
+			outsiderUUID: "EveOutside", // globally valid, but not a workspace member
+		},
+		memberUserIDs: map[string]struct{}{
+			memberUUID: {}, // only AliceInside is a member
+		},
+	}
+
+	in := "hi [@Anything](mention://member/" + outsiderUUID + ") and [@Stale](mention://member/" + memberUUID + ")"
+	want := "hi @Anything and [@AliceInside](mention://member/" + memberUUID + ")"
+
+	got := CanonicalizeMentions(ctx, resolver, ws, in)
+	if got != want {
+		t.Errorf("non-member mention must strip while member mention canonicalizes:\n got:  %q\n want: %q", got, want)
+	}
+	if strings.Contains(got, "EveOutside") {
+		t.Errorf("non-member display name leaked into output: %q", got)
+	}
+}
+
+// TestCanonicalizeMentions_CrossWorkspaceAgentLeftAsIs pins that an agent
+// mention whose UUID does not resolve in this workspace is LEFT IN PLACE
+// rather than rewritten or stripped:
+//   - There is no name-leak risk for agents the way there is for members:
+//     the label here was authored by whoever wrote the comment (commonly an
+//     LLM), not derived from a cross-workspace agent.name lookup. The
+//     workspace-scoped GetAgentInWorkspace already prevents any DB-sourced
+//     rewrite for an outsider agent.
+//   - Stripping the link would erase author intent and break
+//     commentMentionsOthersButNotAssignee — a fake-UUID mention that the
+//     author wrote to direct the comment elsewhere would silently stop
+//     suppressing the assignee's on_comment trigger.
+//   - enqueueMentionedAgentTasks separately gates on GetAgentInWorkspace
+//     and refuses to dispatch, so the link does not actually route anywhere.
+func TestCanonicalizeMentions_CrossWorkspaceAgentLeftAsIs(t *testing.T) {
+	ctx := context.Background()
+	wsA := makeUUID("ws-A-------")
+	wsB := makeUUID("ws-B-------")
+
+	agentB := makeUUID("agent-in-B-")
+	agentBUUID := uuidToString(agentB)
+
+	// Resolver scoped to wsB only. Lookups against wsA fail by design.
+	resolver := &nameResolverMock{
+		workspaceID: wsB,
+		agents:      map[string]string{agentBUUID: "AgentInB"},
+	}
+
+	input := "ping [@AgentInB](mention://agent/" + agentBUUID + ")"
+	want := "ping [@AgentInB](mention://agent/" + agentBUUID + ")"
+
+	got := CanonicalizeMentions(ctx, resolver, wsA, input)
+	if got != want {
+		t.Errorf("cross-workspace agent should be left unchanged:\n got:  %q\n want: %q", got, want)
+	}
+}
diff --git a/server/internal/mention/expand.go b/server/internal/mention/expand.go
index 1c9d932915..a8848410e7 100644
--- a/server/internal/mention/expand.go
+++ b/server/internal/mention/expand.go
@@ -51,8 +51,13 @@ func ExpandIssueIdentifiers(ctx context.Context, resolver Resolver, workspaceID
 	// The prefix is escaped in case it contains regex-special characters.
 	pattern := regexp.MustCompile(`(?:^|(?:\W))` + `(` + regexp.QuoteMeta(prefix) + `-(\d+))` + `(?:\W|$)`)
 
-	// First, identify regions to skip: fenced code blocks and inline code.
-	skipRegions := findSkipRegions(content)
+	// First, identify regions to skip: code blocks plus existing markdown
+	// link spans. The link-span coverage matters when an entity name
+	// (canonicalized into a mention label) contains the workspace issue
+	// prefix — without it, an agent named "MUL-117 reviewer" would get a
+	// nested issue link wrapped around its label and the outer mention
+	// would no longer parse.
+	skipRegions := expandSkipRegions(content)
 
 	// Find all matches and process from right to left (to preserve offsets).
 	allMatches := pattern.FindAllStringSubmatchIndex(content, -1)
@@ -128,8 +133,10 @@ type skipRegion struct {
 	start, end int
 }
 
-// findSkipRegions identifies fenced code blocks (```) and inline code (`)
-// regions in the content.
+// findSkipRegions identifies code regions in the content that should not be
+// touched: fenced code blocks and inline code. Shared with
+// CanonicalizeMentions, which must operate on every mention link outside of
+// code — so the link-span guard belongs to expandSkipRegions, not here.
 func findSkipRegions(content string) []skipRegion {
 	var regions []skipRegion
 
@@ -148,6 +155,28 @@ func findSkipRegions(content string) []skipRegion {
 	return regions
 }
 
+// linkSpanRe matches an entire `[label](url)` markdown link so
+// ExpandIssueIdentifiers can skip identifiers anywhere inside the label or
+// URL — not just immediately adjacent to `[` or `](`. The label pattern
+// allows the editor's `\[` / `\]` escaping for names like "David[TF]" and
+// stops at the first unescaped `]`. The URL pattern stops at the first `)`,
+// matching the mention URLs we generate (UUIDs never contain `)`) without
+// greedily swallowing body text.
+var linkSpanRe = regexp.MustCompile(`\[(?:[^\[\]\n\\]|\\.)*\]\([^)\n]*\)`)
+
+// expandSkipRegions returns the union of code regions plus `[...](...)`
+// link spans. ExpandIssueIdentifiers uses this so that an identifier
+// embedded inside a mention link's label (e.g. an agent name like
+// "MUL-117 reviewer") does not get nested into a second mention link,
+// which would break the outer link's parse and silently drop routing.
+func expandSkipRegions(content string) []skipRegion {
+	regions := findSkipRegions(content)
+	for _, loc := range linkSpanRe.FindAllStringIndex(content, -1) {
+		regions = append(regions, skipRegion{loc[0], loc[1]})
+	}
+	return regions
+}
+
 // inSkipRegion checks if a position falls within any skip region.
 func inSkipRegion(pos int, regions []skipRegion) bool {
 	for _, r := range regions {
diff --git a/server/internal/mention/expand_test.go b/server/internal/mention/expand_test.go
index 0fa3d1b7bf..6581e20656 100644
--- a/server/internal/mention/expand_test.go
+++ b/server/internal/mention/expand_test.go
@@ -106,6 +106,35 @@ func TestExpandIssueIdentifiers(t *testing.T) {
 			input: "(MUL-117)",
 			want:  "([MUL-117](mention://issue/" + uuidToString(issueID) + "))",
 		},
+		{
+			// An agent / member / squad named with the workspace's issue
+			// prefix embedded in the middle (e.g. "MUL-117 reviewer") would
+			// otherwise get a nested issue link wrapped around the label
+			// after CanonicalizeMentions, breaking the outer mention link.
+			// The link-aware skip region must cover the label, not just the
+			// chars immediately adjacent to `[` and `](`.
+			name:  "issue key inside mention link label is not expanded",
+			input: "ping [@MUL-117 reviewer](mention://agent/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa)",
+			want:  "ping [@MUL-117 reviewer](mention://agent/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa)",
+		},
+		{
+			// Same guarantee when the same identifier ALSO appears in body
+			// text: the body occurrence still expands, only the label
+			// occurrence is preserved.
+			name: "issue key inside mention label is preserved while body identifier expands",
+			input: "ping [@MUL-117 reviewer](mention://agent/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa) " +
+				"about MUL-117",
+			want: "ping [@MUL-117 reviewer](mention://agent/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa) " +
+				"about [MUL-117](mention://issue/" + uuidToString(issueID) + ")",
+		},
+		{
+			// Labels can contain escaped square brackets (the editor emits
+			// `\[` / `\]` for names like "David[TF]"). The skip region must
+			// extend to the real closing `]`, not the escaped one inside.
+			name:  "issue key inside mention label with escaped brackets is not expanded",
+			input: `[@David\[MUL-117\]](mention://agent/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa)`,
+			want:  `[@David\[MUL-117\]](mention://agent/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa)`,
+		},
 	}
 
 	for _, tt := range tests {
diff --git a/server/internal/service/task.go b/server/internal/service/task.go
index 55241ae6a7..f1850ea89c 100644
--- a/server/internal/service/task.go
+++ b/server/internal/service/task.go
@@ -1798,6 +1798,13 @@ func (s *TaskService) createAgentComment(ctx context.Context, issueID, agentID p
 			}
 		}
 	}
+	// Canonicalize agent/member/squad mention labels so the visible label
+	// matches the UUID's resolved entity. The HTTP-handler CreateComment
+	// path runs the same pass; agent task result / failure comments must
+	// share it or LLM-authored output containing
+	// `[@A](mention://agent/<B-uuid>)` would persist the same label/UUID
+	// mismatch this defense exists to prevent.
+	content = mention.CanonicalizeMentions(ctx, s.Queries, issue.WorkspaceID, content)
 	// Expand bare issue identifiers (e.g. MUL-117) into mention links.
 	content = mention.ExpandIssueIdentifiers(ctx, s.Queries, issue.WorkspaceID, content)
 	comment, err := s.Queries.CreateComment(ctx, db.CreateCommentParams{
diff --git a/server/internal/util/mention.go b/server/internal/util/mention.go
index f969f2fa3f..5d7dd43b9a 100644
--- a/server/internal/util/mention.go
+++ b/server/internal/util/mention.go
@@ -1,37 +1,155 @@
 package util
 
-import "regexp"
+import (
+	"regexp"
+	"strings"
+)
 
 // Mention represents a parsed @mention from markdown content.
 type Mention struct {
 	Type string // "member", "agent", "issue", or "all"
 	ID   string // user_id, agent_id, issue_id, or "all"
+	// Label is the visible text inside the markdown `[ ]` brackets, with
+	// the optional leading `@` stripped. Routing always uses ID, but the
+	// label is retained for dispatch-time observability — comparing it
+	// against the resolved entity's canonical name surfaces label/UUID
+	// mismatch (the failure mode that motivated mention.CanonicalizeMentions).
+	Label string
 }
 
 // MentionRe matches [@Label](mention://type/id) or [Label](mention://issue/id) in markdown.
 // The @ prefix is optional to support issue mentions which use [MUL-123](mention://issue/...).
 // Uses .+? (non-greedy) instead of [^\]]* so labels containing square brackets
-// (e.g. "David[TF]") are matched correctly — the ](mention:// anchor is specific
-// enough to prevent over-matching.
+// (e.g. "David[TF]") are matched correctly. Use FindMentionMatches for
+// scanning arbitrary Markdown content; this regex is kept for exact single
+// mention parsing in CLI input normalization.
 var MentionRe = regexp.MustCompile(`\[@?(.+?)\]\(mention://(member|agent|squad|issue|all)/([0-9a-fA-F-]+|all)\)`)
 
+// MentionMatch represents one parsed mention with byte offsets into the
+// original markdown content.
+type MentionMatch struct {
+	Start      int
+	End        int
+	LabelStart int
+	LabelEnd   int
+	Mention
+}
+
 // IsMentionAll returns true if the mention is an @all mention.
 func (m Mention) IsMentionAll() bool {
 	return m.Type == "all"
 }
 
+// FindMentionMatches extracts mention links from Markdown without crossing
+// ordinary Markdown links. Regex alone is too blunt here: a line like
+// `[docs](https://x) and [@Bot](mention://agent/...)` must not be treated as
+// one giant mention whose label starts at `docs`.
+func FindMentionMatches(content string) []MentionMatch {
+	var result []MentionMatch
+	for start := 0; start < len(content); start++ {
+		if content[start] != '[' {
+			continue
+		}
+		match, ok := scanMentionAt(content, start)
+		if !ok {
+			continue
+		}
+		result = append(result, match)
+		start = match.End - 1
+	}
+	return result
+}
+
+func scanMentionAt(content string, start int) (MentionMatch, bool) {
+	for close := start + 1; close < len(content); close++ {
+		switch content[close] {
+		case '\n':
+			return MentionMatch{}, false
+		case '\\':
+			if close+1 < len(content) {
+				close++
+			}
+		case ']':
+			if close+1 >= len(content) || content[close+1] != '(' {
+				continue
+			}
+			if !strings.HasPrefix(content[close+2:], "mention://") {
+				return MentionMatch{}, false
+			}
+			return parseMentionAt(content, start, close)
+		}
+	}
+	return MentionMatch{}, false
+}
+
+func parseMentionAt(content string, start, close int) (MentionMatch, bool) {
+	targetStart := close + len("](mention://")
+	targetEnd := targetStart
+	for targetEnd < len(content) && content[targetEnd] != ')' && content[targetEnd] != '\n' {
+		targetEnd++
+	}
+	if targetEnd >= len(content) || content[targetEnd] != ')' {
+		return MentionMatch{}, false
+	}
+	target := content[targetStart:targetEnd]
+	mentionType, id, ok := strings.Cut(target, "/")
+	if !ok || !isMentionType(mentionType) || !isMentionID(id) {
+		return MentionMatch{}, false
+	}
+
+	labelStart := start + 1
+	if labelStart < close && content[labelStart] == '@' {
+		labelStart++
+	}
+	return MentionMatch{
+		Start:      start,
+		End:        targetEnd + 1,
+		LabelStart: labelStart,
+		LabelEnd:   close,
+		Mention: Mention{
+			Type:  mentionType,
+			ID:    id,
+			Label: content[labelStart:close],
+		},
+	}, true
+}
+
+func isMentionType(mentionType string) bool {
+	switch mentionType {
+	case "member", "agent", "squad", "issue", "all":
+		return true
+	default:
+		return false
+	}
+}
+
+func isMentionID(id string) bool {
+	if id == "all" {
+		return true
+	}
+	if id == "" {
+		return false
+	}
+	for _, r := range id {
+		if (r >= '0' && r <= '9') || (r >= 'a' && r <= 'f') || (r >= 'A' && r <= 'F') || r == '-' {
+			continue
+		}
+		return false
+	}
+	return true
+}
+
 // ParseMentions extracts deduplicated mentions from markdown content.
 func ParseMentions(content string) []Mention {
-	matches := MentionRe.FindAllStringSubmatch(content, -1)
 	seen := make(map[string]bool)
 	var result []Mention
-	for _, m := range matches {
-		key := m[2] + ":" + m[3]
+	for _, m := range FindMentionMatches(content) {
+		key := m.Type + ":" + m.ID
 		if seen[key] {
 			continue
 		}
 		seen[key] = true
-		result = append(result, Mention{Type: m[2], ID: m[3]})
+		result = append(result, m.Mention)
 	}
 	return result
 }
diff --git a/server/internal/util/mention_test.go b/server/internal/util/mention_test.go
index 49957e2226..4ba04a7f07 100644
--- a/server/internal/util/mention_test.go
+++ b/server/internal/util/mention_test.go
@@ -80,6 +80,55 @@ func TestParseMentions(t *testing.T) {
 	}
 }
 
+// TestParseMentions_PopulatesLabel pins that the visible markdown label
+// (the text inside the `[ ]`, without the optional leading @) is preserved
+// on the returned Mention. Dispatch-time logging compares this against the
+// resolved entity's canonical name to flag label/UUID mismatch.
+func TestParseMentions_PopulatesLabel(t *testing.T) {
+	tests := []struct {
+		name      string
+		content   string
+		wantLabel string
+	}{
+		{
+			name:      "agent mention without @",
+			content:   "[Bare](mention://agent/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa)",
+			wantLabel: "Bare",
+		},
+		{
+			name:      "agent mention with @",
+			content:   "[@Alice](mention://agent/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa)",
+			wantLabel: "Alice",
+		},
+		{
+			name:      "ordinary markdown link before mention on same line is not part of label",
+			content:   "See [docs](https://x) and [@Bot](mention://agent/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa)",
+			wantLabel: "Bot",
+		},
+		{
+			name:      "issue mention",
+			content:   "[MUL-7](mention://issue/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa)",
+			wantLabel: "MUL-7",
+		},
+		{
+			name:      "all mention",
+			content:   "[@all](mention://all/all)",
+			wantLabel: "all",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := ParseMentions(tt.content)
+			if len(got) != 1 {
+				t.Fatalf("expected 1 mention, got %d: %+v", len(got), got)
+			}
+			if got[0].Label != tt.wantLabel {
+				t.Errorf("Label = %q, want %q", got[0].Label, tt.wantLabel)
+			}
+		})
+	}
+}
+
 func TestHasMentionAll(t *testing.T) {
 	tests := []struct {
 		name     string

From 31b89cb92a4254bb721c4ce3eccbbcbe0def10ba Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=BC=A0=E5=BC=BA?= <zhangqiang@furtherref.com>
Date: Mon, 18 May 2026 23:28:58 -0400
Subject: [PATCH 2/4] fix(mention): bail when [ at scan start opens plain
 bracketed text

scanMentionAt's "continue on ] not followed by (" branch existed to
support labels with balanced inner brackets like [@David[TF]](...),
but the same branch fired when the ] belonged to a plain bracketed
phrase (e.g. [this]) with no inner [. The scanner kept walking past
whitespace and the next [ until it anchored on an unrelated real
mention's ](mention://...), producing a match whose span covered the
unrelated text in between.

In CanonicalizeMentions that span was replaced wholesale, silently
deleting user content: "check [this] out [@Bot](mention://...) please"
was persisted as "check [@Bot](mention://...) please".

Track unescaped [ depth opened after the leading [ at start. A ] at
depth > 0 is treated as closing an inner [ (the [@David[TF]] case
still parses). A ] at depth 0 not followed by ( now bails out
instead of continuing the scan, so the outer FindMentionMatches loop
advances past the plain bracketed text and finds the real mention
intact.

Regression tests cover both ParseMentions (positions invisible there,
so the existing test is a no-op safety pin) and CanonicalizeMentions
(where the data-loss actually shows up).
---
 server/internal/mention/canonicalize_test.go | 11 +++++++++++
 server/internal/util/mention.go              | 19 ++++++++++++++++++-
 server/internal/util/mention_test.go         | 11 +++++++++++
 3 files changed, 40 insertions(+), 1 deletion(-)

diff --git a/server/internal/mention/canonicalize_test.go b/server/internal/mention/canonicalize_test.go
index 218a2b71c2..10e01e3920 100644
--- a/server/internal/mention/canonicalize_test.go
+++ b/server/internal/mention/canonicalize_test.go
@@ -122,6 +122,16 @@ func TestCanonicalizeMentions(t *testing.T) {
 			input: "See [docs](https://x) and [@FakeName](mention://agent/" + agentRealUUID + ")",
 			want:  "See [docs](https://x) and [@RealAgent](mention://agent/" + agentRealUUID + ")",
 		},
+		{
+			// Regression: a bare bracketed phrase like "[this]" before a real
+			// mention used to make the scanner merge both into one fake match
+			// (label "this] out [@FakeName"), so canonicalize replaced the
+			// whole span and "[this] out " was silently deleted from the
+			// persisted comment.
+			name:  "plain bracketed text before agent mention is preserved",
+			input: "check [this] out [@FakeName](mention://agent/" + agentRealUUID + ") please",
+			want:  "check [this] out [@RealAgent](mention://agent/" + agentRealUUID + ") please",
+		},
 		{
 			// Agent mentions with an unresolvable UUID are LEFT IN PLACE so
 			// downstream signals that depend on author intent — most notably
@@ -297,3 +307,4 @@ func TestCanonicalizeMentions_CrossWorkspaceAgentLeftAsIs(t *testing.T) {
 		t.Errorf("cross-workspace agent should be left unchanged:\n got:  %q\n want: %q", got, want)
 	}
 }
+
diff --git a/server/internal/util/mention.go b/server/internal/util/mention.go
index 5d7dd43b9a..221090b7a1 100644
--- a/server/internal/util/mention.go
+++ b/server/internal/util/mention.go
@@ -61,6 +61,17 @@ func FindMentionMatches(content string) []MentionMatch {
 }
 
 func scanMentionAt(content string, start int) (MentionMatch, bool) {
+	// depth tracks unescaped `[` opened AFTER the leading `[` at start, so that
+	// labels containing balanced inner brackets (e.g. "David[TF]") still parse.
+	// A `]` at depth > 0 is treated as closing an inner `[` and the scan
+	// continues. A `]` at depth 0 that is not immediately followed by `(`
+	// means this `[` opened plain bracketed text (e.g. "[note]"), NOT a
+	// mention label — bail out so the outer loop can advance and look for
+	// the next candidate. Without this guard the scanner would walk across
+	// whitespace and a subsequent real mention's `[`, fabricating a match
+	// whose span includes the unrelated bracketed text and causing
+	// CanonicalizeMentions to delete that text on replacement.
+	depth := 0
 	for close := start + 1; close < len(content); close++ {
 		switch content[close] {
 		case '\n':
@@ -69,10 +80,16 @@ func scanMentionAt(content string, start int) (MentionMatch, bool) {
 			if close+1 < len(content) {
 				close++
 			}
+		case '[':
+			depth++
 		case ']':
-			if close+1 >= len(content) || content[close+1] != '(' {
+			if depth > 0 {
+				depth--
 				continue
 			}
+			if close+1 >= len(content) || content[close+1] != '(' {
+				return MentionMatch{}, false
+			}
 			if !strings.HasPrefix(content[close+2:], "mention://") {
 				return MentionMatch{}, false
 			}
diff --git a/server/internal/util/mention_test.go b/server/internal/util/mention_test.go
index 4ba04a7f07..c8cf55b907 100644
--- a/server/internal/util/mention_test.go
+++ b/server/internal/util/mention_test.go
@@ -63,6 +63,17 @@ func TestParseMentions(t *testing.T) {
 			content: `[@David\[TF\]](mention://agent/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa) hi`,
 			want:    []Mention{{Type: "agent", ID: "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"}},
 		},
+		{
+			// Regression: a bare bracketed phrase like "[this]" used to make the
+			// scanner walk past whitespace and the next `[` and merge the two
+			// into one fake match (label "this] out [@Bot"), with End pointing
+			// past the real mention. In CanonicalizeMentions that span gets
+			// replaced wholesale, silently deleting "[this] out " from the
+			// persisted comment.
+			name:    "plain bracketed text before mention on same line",
+			content: "check [this] out [@Bot](mention://agent/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa) please",
+			want:    []Mention{{Type: "agent", ID: "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"}},
+		},
 	}
 
 	for _, tt := range tests {

From 8d1cc4f31c8eba7647a42c5d65918839ee1d9b08 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=BC=A0=E5=BC=BA?= <zhangqiang@furtherref.com>
Date: Tue, 19 May 2026 04:00:06 -0400
Subject: [PATCH 3/4] fix(mention): harden label escape/parse round-trip across
 producers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Tighten the backend label round-trip surface so the canonicalize defense
holds against malformed input and pathological names:

- scanMentionAt: keep strict depth-tracking with anchor only at depth 0.
  An earlier attempt to anchor on `](mention://` at depth > 0 (to support
  unescaped unpaired brackets in labels) created a new data-loss path for
  bracketed prefixes like `note [draft [@Bob](mention://...)` — the outer
  `[draft ` text would get swallowed into the match. Producer-side escape
  is the right place to handle bracket-bearing names.
- parseMentionAt: reject empty labels after stripping the optional `@`.
  Without this, `[](mention://all/all)` or `[@](mention://all/all)` route
  as @all — an invisible markdown link could silently broadcast to the
  whole workspace.
- Add util.EscapeMentionLabel / util.UnescapeMentionLabel as the single
  source of truth for the escape contract. `\` is escaped FIRST so a name
  like `foo\[bar` emits `foo\\\[bar` (not `foo\\[bar`, which the scanner
  would consume as `\\` + raw `[`). Inverse unescapes brackets BEFORE
  collapsing `\\` so a legitimate `\[` pair is not split.
- squad_briefing.formatMention now routes the name through
  EscapeMentionLabel before splicing into markdown.
- mention.CanonicalizeMentions drops its local escapeMentionLabel and uses
  the shared util helper.
- handler.logMentionLabelMismatch uses UnescapeMentionLabel for the
  equality check so a legitimately bracket- or backslash-bearing canonical
  name doesn't false-positive the warning.

Test coverage: empty-label and bare-@ rejection (parse + canonicalize);
non-@ bracketed prefix before mention preserved (no data loss);
unescaped unpaired bracket inside label passes through deterministically
(no character deletion); escape↔unescape inverse contract; full producer→
parser round-trip for plain / bracket / backslash / mixed names.
---
 server/internal/handler/comment.go           |   9 +-
 server/internal/handler/squad_briefing.go    |   8 +-
 server/internal/mention/canonicalize.go      |  12 +-
 server/internal/mention/canonicalize_test.go |  47 ++++++
 server/internal/util/mention.go              |  63 ++++++--
 server/internal/util/mention_test.go         | 146 +++++++++++++++++++
 6 files changed, 256 insertions(+), 29 deletions(-)

diff --git a/server/internal/handler/comment.go b/server/internal/handler/comment.go
index 2a280fe3b7..f6b50dea45 100644
--- a/server/internal/handler/comment.go
+++ b/server/internal/handler/comment.go
@@ -6,7 +6,6 @@ import (
 	"log/slog"
 	"net/http"
 	"strconv"
-	"strings"
 	"time"
 
 	"github.com/go-chi/chi/v5"
@@ -834,10 +833,10 @@ func logMentionLabelMismatch(m util.Mention, canonicalName, kind string, issueID
 	if m.Label == "" || canonicalName == "" {
 		return
 	}
-	// Editor escapes `[` and `]` in labels for grammar; undo that for the
-	// equality check so a legitimately-bracketed name doesn't false-positive.
-	unescaped := strings.ReplaceAll(strings.ReplaceAll(m.Label, `\[`, `[`), `\]`, `]`)
-	if unescaped == canonicalName {
+	// Producers escape `\`, `[`, `]` in labels for grammar; undo that for the
+	// equality check so a legitimately bracketed or backslash-bearing name
+	// doesn't false-positive.
+	if util.UnescapeMentionLabel(m.Label) == canonicalName {
 		return
 	}
 	slog.Warn("mention label / UUID mismatch",
diff --git a/server/internal/handler/squad_briefing.go b/server/internal/handler/squad_briefing.go
index 4c899dfaac..e77ec9c8df 100644
--- a/server/internal/handler/squad_briefing.go
+++ b/server/internal/handler/squad_briefing.go
@@ -213,8 +213,10 @@ func formatRosterRow(name, kind, role, mention string) string {
 }
 
 // formatMention emits a mention markdown string that round-trips through
-// util.ParseMentions. The label is the human display name; the link target
-// uses the mention:// scheme with the entity type and UUID.
+// util.ParseMentions. The label is the human display name (with `[`/`]`
+// escaped so names containing brackets — e.g. "David[TF]" or "Alice [QA"
+// — don't make the resulting markdown ambiguous to the scanner); the link
+// target uses the mention:// scheme with the entity type and UUID.
 func formatMention(name, mentionType, id string) string {
-	return "[@" + name + "](mention://" + mentionType + "/" + id + ")"
+	return "[@" + util.EscapeMentionLabel(name) + "](mention://" + mentionType + "/" + id + ")"
 }
diff --git a/server/internal/mention/canonicalize.go b/server/internal/mention/canonicalize.go
index dfebbe017c..f8f9818afc 100644
--- a/server/internal/mention/canonicalize.go
+++ b/server/internal/mention/canonicalize.go
@@ -3,7 +3,6 @@ package mention
 import (
 	"context"
 	"fmt"
-	"strings"
 
 	"github.com/jackc/pgx/v5/pgtype"
 	"github.com/multica-ai/multica/server/internal/util"
@@ -109,7 +108,7 @@ func CanonicalizeMentions(ctx context.Context, resolver NameResolver, workspaceI
 		canonical, outcome := lookupCanonicalName(ctx, resolver, workspaceID, mentionType, idStr)
 		switch outcome {
 		case lookupResolved:
-			escapedCanonical := escapeMentionLabel(canonical)
+			escapedCanonical := util.EscapeMentionLabel(canonical)
 			if escapedCanonical == label {
 				continue
 			}
@@ -187,12 +186,3 @@ func lookupCanonicalName(ctx context.Context, r NameResolver, workspaceID pgtype
 	return "", lookupKeepAsIs
 }
 
-// escapeMentionLabel mirrors the editor's mention-extension escaping
-// (packages/views/editor/extensions/mention-extension.ts): only `[` and `]`
-// are escaped so the bracket structure of the resulting markdown link
-// survives names that contain them (e.g. "David[TF]").
-func escapeMentionLabel(s string) string {
-	s = strings.ReplaceAll(s, "[", "\\[")
-	s = strings.ReplaceAll(s, "]", "\\]")
-	return s
-}
diff --git a/server/internal/mention/canonicalize_test.go b/server/internal/mention/canonicalize_test.go
index 10e01e3920..508ac21497 100644
--- a/server/internal/mention/canonicalize_test.go
+++ b/server/internal/mention/canonicalize_test.go
@@ -75,6 +75,8 @@ func TestCanonicalizeMentions(t *testing.T) {
 	agentBracketUUID := uuidToString(agentBracketID)
 	agentIssueBracketID := makeUUID("agent-issue")
 	agentIssueBracketUUID := uuidToString(agentIssueBracketID)
+	agentUnpairedID := makeUUID("agent-unpar")
+	agentUnpairedUUID := uuidToString(agentUnpairedID)
 	agentMissingID := makeUUID("agent-gone-")
 	agentMissingUUID := uuidToString(agentMissingID)
 
@@ -90,6 +92,7 @@ func TestCanonicalizeMentions(t *testing.T) {
 			agentRealUUID:         "RealAgent",
 			agentBracketUUID:      "David[TF]",
 			agentIssueBracketUUID: "MUL-117[TF]",
+			agentUnpairedUUID:     "Alice [QA",
 		},
 		squads: map[string]string{
 			squadUUID: "RealSquad",
@@ -132,6 +135,50 @@ func TestCanonicalizeMentions(t *testing.T) {
 			input: "check [this] out [@FakeName](mention://agent/" + agentRealUUID + ") please",
 			want:  "check [this] out [@RealAgent](mention://agent/" + agentRealUUID + ") please",
 		},
+		{
+			// Producer-side escape contract: every backend producer of mention
+			// markdown (squad_briefing.formatMention, this canonicalize on
+			// rewrite) routes the name through util.EscapeMentionLabel. For
+			// an agent named "Alice [QA" the well-formed input from those
+			// producers is `[@Alice \[QA](mention://...)`; canonicalize
+			// compares the captured label against the escaped canonical and
+			// leaves it untouched.
+			name:  "agent name with escaped unpaired bracket round-trips canonical",
+			input: "hi [@Alice \\[QA](mention://agent/" + agentUnpairedUUID + ") there",
+			want:  "hi [@Alice \\[QA](mention://agent/" + agentUnpairedUUID + ") there",
+		},
+		{
+			// If an LLM bypasses the producer escape contract and writes a
+			// raw `[` inside a mention label, the markdown is ambiguous —
+			// the strict scanner finds the inner `[QA](mention://...)` as a
+			// valid link (markdown semantics: the outer `[@Alice ` is a
+			// dangling unclosed bracket = literal text). Canonicalize then
+			// rewrites the inner label to the escaped canonical, leaving
+			// the outer `[@Alice ` as visible text. Not pretty, but
+			// deterministic and no characters are deleted.
+			name:  "unescaped unpaired bracket inside label canonicalizes the inner link",
+			input: "hi [@Alice [QA](mention://agent/" + agentUnpairedUUID + ") there",
+			want:  "hi [@Alice [@Alice \\[QA](mention://agent/" + agentUnpairedUUID + ") there",
+		},
+		{
+			// Regression for the scanner anchor heuristic: a non-@ bracketed
+			// prefix before a real mention must not be swallowed by the
+			// span. Without the heuristic, canonicalize would replace the
+			// `[draft ` prefix along with the mention and emit
+			// `note [@RealAgent](...)`, deleting user text.
+			name:  "non-@ bracketed prefix before mention is preserved by canonicalize",
+			input: "note [draft [@FakeBob](mention://agent/" + agentRealUUID + ") tail",
+			want:  "note [draft [@RealAgent](mention://agent/" + agentRealUUID + ") tail",
+		},
+		{
+			// `[](mention://all/all)` is invisible markdown that the old
+			// regex rejected (label was `.+?`). After the scanner rewrite
+			// it slipped through and routed as @all. Now stripped — the
+			// invisible link is left as plain text.
+			name:  "empty-label all mention is stripped",
+			input: "hi [](mention://all/all) there",
+			want:  "hi [](mention://all/all) there",
+		},
 		{
 			// Agent mentions with an unresolvable UUID are LEFT IN PLACE so
 			// downstream signals that depend on author intent — most notably
diff --git a/server/internal/util/mention.go b/server/internal/util/mention.go
index 221090b7a1..c2786d74f1 100644
--- a/server/internal/util/mention.go
+++ b/server/internal/util/mention.go
@@ -61,16 +61,20 @@ func FindMentionMatches(content string) []MentionMatch {
 }
 
 func scanMentionAt(content string, start int) (MentionMatch, bool) {
-	// depth tracks unescaped `[` opened AFTER the leading `[` at start, so that
-	// labels containing balanced inner brackets (e.g. "David[TF]") still parse.
-	// A `]` at depth > 0 is treated as closing an inner `[` and the scan
-	// continues. A `]` at depth 0 that is not immediately followed by `(`
-	// means this `[` opened plain bracketed text (e.g. "[note]"), NOT a
-	// mention label — bail out so the outer loop can advance and look for
-	// the next candidate. Without this guard the scanner would walk across
-	// whitespace and a subsequent real mention's `[`, fabricating a match
-	// whose span includes the unrelated bracketed text and causing
-	// CanonicalizeMentions to delete that text on replacement.
+	// depth tracks unescaped `[` opened AFTER the leading `[` at start, so
+	// labels with balanced inner brackets like "David[TF]" or non-mention
+	// links inside a label still parse. A `]` at depth > 0 is treated as
+	// closing an inner `[` and the scan continues. A `]` at depth 0 that is
+	// not the mention terminator means this `[` opened plain bracketed text
+	// (e.g. "[note]") or a non-mention link, NOT a mention label — bail so
+	// the outer loop can advance and look for the next candidate.
+	//
+	// Names that contain a raw, unpaired `[` or `]` must be escaped by the
+	// producer (squad_briefing.formatMention, the frontend mention-extension,
+	// canonicalize) so the resulting markdown round-trips through this
+	// scanner. Trying to recognise unescaped unpaired brackets in the parser
+	// is ambiguous with bracketed text preceding a real mention and leads to
+	// data loss in CanonicalizeMentions — keep the parser strict.
 	depth := 0
 	for close := start + 1; close < len(content); close++ {
 		switch content[close] {
@@ -118,6 +122,12 @@ func parseMentionAt(content string, start, close int) (MentionMatch, bool) {
 	if labelStart < close && content[labelStart] == '@' {
 		labelStart++
 	}
+	// Reject empty labels (`[](...)` or `[@](...)`). The previous regex
+	// required `.+?`; without this guard an invisible markdown link would
+	// route as e.g. `@all` and silently broadcast.
+	if labelStart >= close {
+		return MentionMatch{}, false
+	}
 	return MentionMatch{
 		Start:      start,
 		End:        targetEnd + 1,
@@ -180,3 +190,36 @@ func HasMentionAll(mentions []Mention) bool {
 	}
 	return false
 }
+
+// EscapeMentionLabel escapes `\`, `[` and `]` in a name so the resulting
+// `[@<name>](mention://...)` markdown round-trips through FindMentionMatches
+// and CanonicalizeMentions. Every backend producer of mention markdown
+// (squad_briefing.formatMention, mention.CanonicalizeMentions on rewrite)
+// must funnel labels through this before splicing into a markdown link.
+//
+// `\` is escaped FIRST because the subsequent `[`/`]` replacements introduce
+// new backslashes. Without the leading step, a name like `foo\[bar` would
+// emit `foo\\[bar` — the scanner would consume the first `\` as escaping the
+// second `\`, then see `[` as raw structure and fail to round-trip. Order
+// matters here.
+func EscapeMentionLabel(s string) string {
+	s = strings.ReplaceAll(s, "\\", "\\\\")
+	s = strings.ReplaceAll(s, "[", "\\[")
+	s = strings.ReplaceAll(s, "]", "\\]")
+	return s
+}
+
+// UnescapeMentionLabel reverses EscapeMentionLabel: turns `\[`, `\]` and `\\`
+// back into the literal `[`, `]`, `\`. Apply this when comparing a parsed
+// MentionMatch.Label (which still carries the producer's escapes) against an
+// in-memory canonical name, or when stripping mention markdown to plain text.
+//
+// Brackets are unescaped BEFORE the `\\` step — reversing the producer in
+// reverse order. If `\\` ran first, it would consume the leading backslash
+// of a legitimate `\[` pair, leaving a raw `[` in the output.
+func UnescapeMentionLabel(s string) string {
+	s = strings.ReplaceAll(s, "\\[", "[")
+	s = strings.ReplaceAll(s, "\\]", "]")
+	s = strings.ReplaceAll(s, "\\\\", "\\")
+	return s
+}
diff --git a/server/internal/util/mention_test.go b/server/internal/util/mention_test.go
index c8cf55b907..416918e5ea 100644
--- a/server/internal/util/mention_test.go
+++ b/server/internal/util/mention_test.go
@@ -74,6 +74,30 @@ func TestParseMentions(t *testing.T) {
 			content: "check [this] out [@Bot](mention://agent/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa) please",
 			want:    []Mention{{Type: "agent", ID: "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"}},
 		},
+		{
+			// Empty markdown label `[](mention://all/all)` is invisible. The
+			// previous regex required at least one label character (`.+?`);
+			// the scanner rewrite let it through and routed it as @all.
+			// Reject so an invisible link can't @-mention everyone.
+			name:    "empty label is not a mention",
+			content: "hi [](mention://all/all) there",
+			want:    nil,
+		},
+		{
+			// Regression: an unrelated bracketed phrase like "[draft" before a
+			// real mention must not absorb the prefix into the match. Only
+			// labels starting with `@` may anchor on the mention terminator
+			// while still inside nested brackets — a non-@ outer `[` like
+			// `[draft` indicates plain text, not a mention label.
+			name:    "non-@ bracketed prefix before agent mention is parsed independently",
+			content: "note [draft [@Bob](mention://agent/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa) tail",
+			want:    []Mention{{Type: "agent", ID: "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"}},
+		},
+		{
+			name:    "bare @ label is not a mention",
+			content: "[@](mention://all/all) hi",
+			want:    nil,
+		},
 	}
 
 	for _, tt := range tests {
@@ -126,6 +150,24 @@ func TestParseMentions_PopulatesLabel(t *testing.T) {
 			content:   "[@all](mention://all/all)",
 			wantLabel: "all",
 		},
+		{
+			// Producer-side escape contract: a name containing a literal `[`
+			// must be emitted as `\[` so the markdown round-trips. The label
+			// captured here keeps the literal `\` from the escape — callers
+			// that compare it against an in-memory name must escape that name
+			// the same way (see util.EscapeMentionLabel).
+			name:      "label with escaped left bracket round-trips",
+			content:   `[@Alice \[QA](mention://agent/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa)`,
+			wantLabel: `Alice \[QA`,
+		},
+		{
+			// Regression: an unrelated bracketed prefix like "[draft" must
+			// NOT absorb itself into the label of the following real mention.
+			// Only the label of `[@Bob](...)` should be captured.
+			name:      "non-@ bracketed prefix before agent mention does not absorb prefix",
+			content:   "note [draft [@Bob](mention://agent/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa)",
+			wantLabel: "Bob",
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
@@ -140,6 +182,110 @@ func TestParseMentions_PopulatesLabel(t *testing.T) {
 	}
 }
 
+func TestEscapeMentionLabel(t *testing.T) {
+	tests := []struct {
+		in   string
+		want string
+	}{
+		{"", ""},
+		{"plain", "plain"},
+		{"David[TF]", `David\[TF\]`},
+		{"Alice [QA", `Alice \[QA`},
+		{"trailing ]", `trailing \]`},
+		{"MUL-117[TF]", `MUL-117\[TF\]`},
+		// Literal `\` in the name MUST be escaped first; otherwise the
+		// scanner consumes the user's `\` as escaping the `\` we add for
+		// `[`, then sees the `[` as raw structure and breaks the round-trip.
+		{`foo\bar`, `foo\\bar`},
+		{`pre\[post`, `pre\\\[post`},
+	}
+	for _, tt := range tests {
+		t.Run(tt.in, func(t *testing.T) {
+			if got := EscapeMentionLabel(tt.in); got != tt.want {
+				t.Errorf("EscapeMentionLabel(%q) = %q, want %q", tt.in, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestUnescapeMentionLabel(t *testing.T) {
+	tests := []struct {
+		in   string
+		want string
+	}{
+		{"", ""},
+		{"plain", "plain"},
+		{`David\[TF\]`, "David[TF]"},
+		{`Alice \[QA`, "Alice [QA"},
+		{`foo\\bar`, `foo\bar`},
+		{`foo\\\[bar`, `foo\[bar`},
+	}
+	for _, tt := range tests {
+		t.Run(tt.in, func(t *testing.T) {
+			if got := UnescapeMentionLabel(tt.in); got != tt.want {
+				t.Errorf("UnescapeMentionLabel(%q) = %q, want %q", tt.in, got, tt.want)
+			}
+		})
+	}
+}
+
+// TestUnescapeMentionLabel_InverseOfEscape pins that escape→unescape is the
+// identity function. Any name that goes through the producer-side escape
+// and comes back through the consumer-side unescape MUST round-trip.
+func TestUnescapeMentionLabel_InverseOfEscape(t *testing.T) {
+	names := []string{
+		"",
+		"plain",
+		"David[TF]",
+		"Alice [QA",
+		"trailing ]",
+		`foo\bar`,
+		`pre\[post`,
+		`\start`,
+		`mixed [a]\b`,
+	}
+	for _, name := range names {
+		t.Run(name, func(t *testing.T) {
+			if got := UnescapeMentionLabel(EscapeMentionLabel(name)); got != name {
+				t.Errorf("escape→unescape of %q yielded %q", name, got)
+			}
+		})
+	}
+}
+
+// TestEscapeMentionLabel_RoundTrip is the contract test that ties the
+// producer (EscapeMentionLabel) to the consumer (FindMentionMatches). Any
+// name passing through escape MUST produce markdown that parses back as a
+// single mention with the same ID.
+func TestEscapeMentionLabel_RoundTrip(t *testing.T) {
+	uuid := "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
+	names := []string{
+		"plain",
+		"David[TF]",
+		"Alice [QA",
+		"trailing ]",
+		`foo\bar`,
+		`pre\[post`,
+		`\start`,
+		`mixed [a]\b`,
+	}
+	for _, name := range names {
+		t.Run(name, func(t *testing.T) {
+			md := "[@" + EscapeMentionLabel(name) + "](mention://agent/" + uuid + ")"
+			matches := FindMentionMatches(md)
+			if len(matches) != 1 {
+				t.Fatalf("FindMentionMatches(%q) returned %d matches, want 1", md, len(matches))
+			}
+			if matches[0].ID != uuid {
+				t.Errorf("mention ID = %q, want %q", matches[0].ID, uuid)
+			}
+			if matches[0].Start != 0 || matches[0].End != len(md) {
+				t.Errorf("match span = [%d,%d), want [0,%d)", matches[0].Start, matches[0].End, len(md))
+			}
+		})
+	}
+}
+
 func TestHasMentionAll(t *testing.T) {
 	tests := []struct {
 		name     string

From e2efefeca848603d387b7aa4d0f90457f3ead072 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=BC=A0=E5=BC=BA?= <zhangqiang@furtherref.com>
Date: Tue, 19 May 2026 04:00:20 -0400
Subject: [PATCH 4/4] fix(editor): align mention label escape/unescape with
 backend contract
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Mirror the backend's util.EscapeMentionLabel / UnescapeMentionLabel
contract in the two frontend consumers so labels round-trip through the
editor and trigger-summary path without losing or gaining backslashes:

- mention-extension renderMarkdown (safeLabel): escape `\` FIRST, then
  `[` and `]`. Order matters — without leading `\` escape, a name like
  `foo\[bar` emits `foo\\[bar`, which the scanner consumes as `\\` + raw
  `[` and fails to round-trip.
- mention-extension tokenize: unescape `\[`, `\]`, then `\\` (reverse of
  the producer). Also mirror util.parseMentionAt's empty-label guard —
  `[@](mention://all/all)` backtracks into the label group (label = `@`),
  and without rejection here the editor would tokenize it, then
  renderMarkdown would emit `[@@](mention://all/all)`, slipping past the
  backend's non-empty check and routing as @all on save.
- strip-mention-markdown: same unescape order so trigger summaries for a
  name like `Ops\Bot` no longer show an extra backslash.

Regression tests pin: label with literal `\`; label with `\` adjacent to
`[` (4-char-into-7-source-char round-trip); `[](...)` and `[@](...)`
rejected by the tokenizer.
---
 .../extensions/mention-extension.test.ts      | 41 +++++++++++++++++++
 .../editor/extensions/mention-extension.ts    | 30 +++++++++++---
 .../utils/strip-mention-markdown.test.ts      | 14 +++++++
 .../issues/utils/strip-mention-markdown.ts    | 10 ++++-
 4 files changed, 88 insertions(+), 7 deletions(-)

diff --git a/packages/views/editor/extensions/mention-extension.test.ts b/packages/views/editor/extensions/mention-extension.test.ts
index 15542752c2..60d0e69de2 100644
--- a/packages/views/editor/extensions/mention-extension.test.ts
+++ b/packages/views/editor/extensions/mention-extension.test.ts
@@ -81,4 +81,45 @@ describe("mention tokenizer", () => {
     expect(token!.attributes.label).toBe("MUL-123");
     expect(token!.attributes.type).toBe("issue");
   });
+
+  it("round-trips a label containing a literal backslash", () => {
+    // renderMarkdown must escape the literal backslash so the scanner
+    // doesn't eat the next char; tokenizer unescapes after brackets.
+    const md = renderMarkdown({
+      attrs: { id: "ops-1", label: "Ops\\Bot", type: "agent" },
+    });
+    expect(md).toBe("[@Ops\\\\Bot](mention://agent/ops-1)");
+
+    const token = tokenize(md);
+    expect(token).toBeDefined();
+    expect(token!.attributes.label).toBe("Ops\\Bot");
+  });
+
+  it("rejects an empty mention label", () => {
+    // `[](mention://all/all)` is invisible markdown — the regex's `+`
+    // already requires one char, so the start search returns -1.
+    expect(startFn("[](mention://all/all)")).toBe(-1);
+  });
+
+  it("rejects a bare-@ mention label", () => {
+    // `[@](mention://all/all)` matches via regex backtracking (`@?` → empty,
+    // label captures `@`). Tokenize must reject it so a re-render doesn't
+    // emit `[@@](...)` and slip past the backend's non-empty guard.
+    const token = tokenize("[@](mention://all/all)");
+    expect(token).toBeUndefined();
+  });
+
+  it("round-trips a label with a backslash adjacent to a bracket", () => {
+    // `\[` in the name means literal `\` then literal `[` — order of
+    // escapes matters (backslash first) so the producer emits
+    // `\\\[`, which the consumer unescapes back to `\[`.
+    const md = renderMarkdown({
+      attrs: { id: "x", label: "foo\\[bar", type: "agent" },
+    });
+    expect(md).toBe("[@foo\\\\\\[bar](mention://agent/x)");
+
+    const token = tokenize(md);
+    expect(token).toBeDefined();
+    expect(token!.attributes.label).toBe("foo\\[bar");
+  });
 });
diff --git a/packages/views/editor/extensions/mention-extension.ts b/packages/views/editor/extensions/mention-extension.ts
index 380b0be930..eabb1f8cbb 100644
--- a/packages/views/editor/extensions/mention-extension.ts
+++ b/packages/views/editor/extensions/mention-extension.ts
@@ -52,8 +52,22 @@ export const BaseMentionExtension = Mention.extend({
         /^\[@?((?:\\.|[^\]])+)\]\(mention:\/\/(\w+)\/([^)]+)\)/,
       );
       if (!match) return undefined;
-      // Unescape backslash-escaped brackets that renderMarkdown may produce.
-      const rawLabel = match[1]?.replace(/\\\[/g, "[").replace(/\\\]/g, "]");
+      // Unescape backslash sequences produced by renderMarkdown / the Go
+      // backend's util.EscapeMentionLabel. `\\` must be unescaped LAST so
+      // it doesn't eat a backslash that's part of a `\[` / `\]` pair.
+      const rawLabel = match[1]
+        ?.replace(/\\\[/g, "[")
+        .replace(/\\\]/g, "]")
+        .replace(/\\\\/g, "\\");
+      // Mirror util.parseMentionAt's empty-label guard: a `[@](...)` payload
+      // backtracks into the label group (regex `@?` matches empty, `@`
+      // becomes the single captured char). Without this check tokenize would
+      // accept it, renderMarkdown would emit `[@@](...)`, and the backend's
+      // non-empty check would no longer reject it — a back door to @all.
+      const labelAfterAt = rawLabel?.startsWith("@")
+        ? rawLabel.slice(1)
+        : rawLabel;
+      if (!labelAfterAt) return undefined;
       return {
         type: "mention",
         raw: match[0],
@@ -67,9 +81,15 @@ export const BaseMentionExtension = Mention.extend({
   renderMarkdown: (node: any) => {
     const { id, label, type = "member" } = node.attrs || {};
     const prefix = type === "issue" ? "" : "@";
-    // Escape square brackets in the label so the markdown link syntax
-    // is not broken when the name contains [ or ] (e.g. "David[TF]").
-    const safeLabel = (label ?? id).replace(/\[/g, "\\[").replace(/\]/g, "\\]");
+    // Escape `\`, `[`, `]` in the label so the markdown link syntax is not
+    // broken when the name contains them (e.g. "David[TF]" or "Ops\Bot").
+    // Mirrors the backend's util.EscapeMentionLabel — `\` must be escaped
+    // FIRST so a name like `foo\[bar` produces `foo\\\[bar`, not `foo\\[bar`
+    // (which the scanner would consume as `\\` + raw `[`).
+    const safeLabel = (label ?? id)
+      .replace(/\\/g, "\\\\")
+      .replace(/\[/g, "\\[")
+      .replace(/\]/g, "\\]");
     return `[${prefix}${safeLabel}](mention://${type}/${id})`;
   },
 });
diff --git a/packages/views/issues/utils/strip-mention-markdown.test.ts b/packages/views/issues/utils/strip-mention-markdown.test.ts
index a393ada8d7..4971e35b14 100644
--- a/packages/views/issues/utils/strip-mention-markdown.test.ts
+++ b/packages/views/issues/utils/strip-mention-markdown.test.ts
@@ -26,6 +26,20 @@ describe("stripMentionMarkdown", () => {
     ).toBe("@David[TF]");
   });
 
+  it("handles escaped backslash in names", () => {
+    expect(
+      stripMentionMarkdown("[@Ops\\\\Bot](mention://agent/id-1)"),
+    ).toBe("@Ops\\Bot");
+  });
+
+  it("handles backslash adjacent to bracket in names", () => {
+    // Name "foo\[bar" → producer emits `[@foo\\\[bar](...)`. Strip
+    // unescapes brackets first, then the remaining `\\` becomes `\`.
+    expect(
+      stripMentionMarkdown("[@foo\\\\\\[bar](mention://agent/id-2)"),
+    ).toBe("@foo\\[bar");
+  });
+
   it("handles multiple mentions in one string", () => {
     expect(
       stripMentionMarkdown(
diff --git a/packages/views/issues/utils/strip-mention-markdown.ts b/packages/views/issues/utils/strip-mention-markdown.ts
index c5da0cc1f4..b5236f8167 100644
--- a/packages/views/issues/utils/strip-mention-markdown.ts
+++ b/packages/views/issues/utils/strip-mention-markdown.ts
@@ -4,17 +4,23 @@
  * Handles:
  * - Simple mentions: `[@Name](mention://agent/id)` → `@Name`
  * - Escaped brackets in names: `[@David\[TF\]](mention://agent/id)` → `@David[TF]`
+ * - Escaped backslash in names: `[@Ops\\Bot](mention://agent/id)` → `@Ops\Bot`
  * - Issue mentions (no @): `[MUL-123](mention://issue/id)` → `MUL-123`
  * - Does NOT touch regular markdown links: `[docs](https://...)` stays unchanged
  * - Does NOT touch backslash-escaped mentions: `\[@Name](mention://...)` stays unchanged
  *
- * The regex mirrors the tokenizer in mention-extension.ts.
+ * The regex + unescape mirrors the tokenizer in mention-extension.ts and the
+ * Go-side util.UnescapeMentionLabel. Brackets are unescaped BEFORE `\\` so
+ * a legitimate `\[` pair isn't broken by collapsing the leading `\`.
  */
 export function stripMentionMarkdown(text: string): string {
   return text.replace(
     /(?<![\\])\[(@?)((?:\\.|[^\]])+)\]\(mention:\/\/\w+\/[^)]+\)/g,
     (_, prefix: string, rawLabel: string) => {
-      const label = rawLabel.replace(/\\\[/g, "[").replace(/\\\]/g, "]");
+      const label = rawLabel
+        .replace(/\\\[/g, "[")
+        .replace(/\\\]/g, "]")
+        .replace(/\\\\/g, "\\");
       return `${prefix}${label}`;
     },
   );