From 61272bd14aff0fe775987facb09bb4e01ba6acf5 Mon Sep 17 00:00:00 2001
From: Taylor Ho <taylorkmho@gmail.com>
Date: Sun, 13 Sep 2026 06:18:53 -1000
Subject: [PATCH 1/7] feat(avatars): distinguish agents with svg squircles

Co-authored-by: Carl <acda9e433d19dcd0e6b6840f7f4b98f3a56f1fab98049d444c087019e6d36560@buzz.block.builderlab.xyz>
Signed-off-by: Taylor Ho <taylorkmho@gmail.com>
---
 src/bundled/agents/AgentsPage.tsx             |  8 +++++++-
 src/bundled/mentions/MentionCompletion.tsx    |  3 +++
 src/bundled/mentions/MentionPicker.tsx        |  5 +++++
 src/bundled/profiles/ProfilePanel.tsx         |  8 ++++++--
 src/features/agents/known.test.ts             | 14 +++++++++++++
 src/features/agents/known.ts                  | 15 ++++++++++++++
 src/features/agents/use-known.ts              | 20 +++++++++++++++++++
 src/features/messages/ChannelTimeline.tsx     |  4 ++++
 src/features/messages/MembershipRow.tsx       | 10 +++++++++-
 src/features/messages/MessageRow.test.tsx     | 17 ++++++++++++++++
 src/features/messages/MessageRow.tsx          |  8 ++++++++
 src/features/messages/Messages.module.css     |  6 ++++++
 src/features/messages/ThreadPanel.tsx         |  4 ++++
 src/features/relay/contracts.ts               |  2 ++
 src/features/relay/profile-details.test.ts    | 14 ++++++++++++-
 src/features/relay/profiles.ts                |  5 +++++
 src/shared/Avatar.tsx                         |  3 +++
 .../design-system/styles/components.css       |  6 ++++++
 src/shared/design-system/ui/Avatar.tsx        |  3 +++
 tests/browser/fixture.mjs                     |  1 +
 tests/browser/membership.spec.mjs             |  4 ++++
 21 files changed, 155 insertions(+), 5 deletions(-)
 create mode 100644 src/features/agents/known.test.ts
 create mode 100644 src/features/agents/known.ts
 create mode 100644 src/features/agents/use-known.ts

diff --git a/src/bundled/agents/AgentsPage.tsx b/src/bundled/agents/AgentsPage.tsx
index e79f342f..aef56a6d 100644
--- a/src/bundled/agents/AgentsPage.tsx
+++ b/src/bundled/agents/AgentsPage.tsx
@@ -196,7 +196,13 @@ function AgentCard({
   return (
     <article className="flex min-w-0 flex-col rounded-2xl border border-primary p-4">
       <div className="flex min-h-36 flex-1 items-center justify-center py-5">
-        <Avatar alt={name} fallback={name} src={picture ?? null} size="large" />
+        <Avatar
+          alt={name}
+          fallback={name}
+          src={picture ?? null}
+          size="large"
+          shape="squircle"
+        />
       </div>
       <h3 className="m-0 truncate text-body font-semibold" title={name}>
         {name}
diff --git a/src/bundled/mentions/MentionCompletion.tsx b/src/bundled/mentions/MentionCompletion.tsx
index 30d53b44..62fbc7d6 100644
--- a/src/bundled/mentions/MentionCompletion.tsx
+++ b/src/bundled/mentions/MentionCompletion.tsx
@@ -2,6 +2,7 @@ import { useEffect, useState, useSyncExternalStore } from "react";
 import type { ComposerCompletionProps } from "../../features/conversation/contracts";
 import type { RelaySession } from "../../features/relay/session";
 import { Avatar } from "../../shared/Avatar";
+import { useKnownAgentPubkeys } from "../../features/agents/use-known";
 import { matchesMentionQuery } from "./mention-query";
 
 // Demand bookkeeping only, not another profile cache. Missing names do not issue
@@ -23,6 +24,7 @@ export function MentionCompletion({
     session.profiles.snapshot,
     session.profiles.snapshot,
   );
+  const agentPubkeys = useKnownAgentPubkeys(session, profiles);
   const channel = list.channels.find((item) => item.id === channelId);
   const members = channel?.members ?? [];
   const memberKey = members.join(":");
@@ -82,6 +84,7 @@ export function MentionCompletion({
             name={recipient.name}
             src={session.media(profiles.get(recipient.pubkey)?.picture ?? "")}
             className="size-7 rounded-lg text-xs"
+            shape={agentPubkeys.has(recipient.pubkey) ? "squircle" : "circle"}
           />
         ),
         edit: { mention: recipient },
diff --git a/src/bundled/mentions/MentionPicker.tsx b/src/bundled/mentions/MentionPicker.tsx
index 90439f16..b520c143 100644
--- a/src/bundled/mentions/MentionPicker.tsx
+++ b/src/bundled/mentions/MentionPicker.tsx
@@ -1,4 +1,5 @@
 import { Avatar } from "../../shared/Avatar";
+import { useKnownAgentPubkeys } from "../../features/agents/use-known";
 import { AtSign } from "lucide-react";
 import {
   useEffect,
@@ -39,6 +40,7 @@ export function MentionPicker({
     session.profiles.snapshot,
     session.profiles.snapshot,
   );
+  const agentPubkeys = useKnownAgentPubkeys(session, profiles);
   const channel = list.channels.find((item) => item.id === channelId);
   const memberKey = channel?.members?.join(":") ?? "";
   useEffect(() => {
@@ -140,6 +142,9 @@ export function MentionPicker({
                     profiles.get(recipient.pubkey)?.picture ?? "",
                   )}
                   className="size-8 rounded-lg text-xs"
+                  shape={
+                    agentPubkeys.has(recipient.pubkey) ? "squircle" : "circle"
+                  }
                 />
                 <span className={styles.mentionLabel}>
                   <span>{recipient.name}</span>
diff --git a/src/bundled/profiles/ProfilePanel.tsx b/src/bundled/profiles/ProfilePanel.tsx
index 4259775a..cc9033c2 100644
--- a/src/bundled/profiles/ProfilePanel.tsx
+++ b/src/bundled/profiles/ProfilePanel.tsx
@@ -7,6 +7,7 @@ import {
 } from "react";
 import { IconCopy } from "@tabler/icons-react";
 import { Avatar } from "../../shared/design-system/ui/Avatar";
+import { useKnownAgentPubkeys } from "../../features/agents/use-known";
 import { Button } from "../../shared/design-system/ui/Button";
 import { activityTarget } from "../../features/agents/activity-target";
 import type { PanelProps } from "../../features/panels/service";
@@ -49,11 +50,12 @@ function ProfileDetails({
     () => selectProfiles(session.profiles, [pubkey]),
     [session.profiles, pubkey],
   );
-  const profile = useSyncExternalStore(
+  const profiles = useSyncExternalStore(
     selection.subscribe,
     selection.snapshot,
     selection.snapshot,
-  ).get(pubkey);
+  );
+  const profile = profiles.get(pubkey);
   const [status, setStatus] = useState<"loading" | "ready" | "error">(
     "loading",
   );
@@ -80,6 +82,7 @@ function ProfileDetails({
       active = false;
     };
   }, [session, pubkey, attempt]);
+  const agentPubkeys = useKnownAgentPubkeys(session, profiles);
   const npub = profileTarget(pubkey)?.slice(6) ?? pubkey;
   const name = profile?.name ?? "Unknown profile";
   const activity = activityTarget(pubkey, context?.channelId);
@@ -99,6 +102,7 @@ function ProfileDetails({
           alt={`${name} avatar`}
           fallback={profile?.name ?? "?"}
           size="large"
+          shape={agentPubkeys.has(pubkey) ? "squircle" : "circle"}
         />
         <h2 className="text-heading">{name}</h2>
       </div>
diff --git a/src/features/agents/known.test.ts b/src/features/agents/known.test.ts
new file mode 100644
index 00000000..11a6e636
--- /dev/null
+++ b/src/features/agents/known.test.ts
@@ -0,0 +1,14 @@
+import { expect, it } from "vitest";
+import { knownAgentPubkeys } from "./known";
+
+it("combines exact local-library identities with self-authored agent profiles", () => {
+  const profiles = new Map([
+    ["relay-agent", { name: "Relay", isAgent: true as const }],
+    ["person", { name: "Person" }],
+  ]);
+  const keys = knownAgentPubkeys(profiles, {
+    definitions: [],
+    identities: [{ pubkey: "local-agent", name: "Local" }],
+  });
+  expect([...keys]).toEqual(["relay-agent", "local-agent"]);
+});
diff --git a/src/features/agents/known.ts b/src/features/agents/known.ts
new file mode 100644
index 00000000..cd81a719
--- /dev/null
+++ b/src/features/agents/known.ts
@@ -0,0 +1,15 @@
+import type { AgentLibrary } from "./library";
+import type { Profile } from "../relay/contracts";
+
+/** Exact identity keys from authenticated profile metadata plus the local Buzz library. */
+export function knownAgentPubkeys(
+  profiles: ReadonlyMap<string, Profile>,
+  library?: AgentLibrary,
+): ReadonlySet<string> {
+  const keys = new Set<string>();
+  for (const [pubkey, profile] of profiles) {
+    if (profile.isAgent) keys.add(pubkey);
+  }
+  for (const identity of library?.identities ?? []) keys.add(identity.pubkey);
+  return keys;
+}
diff --git a/src/features/agents/use-known.ts b/src/features/agents/use-known.ts
new file mode 100644
index 00000000..42d4c4bc
--- /dev/null
+++ b/src/features/agents/use-known.ts
@@ -0,0 +1,20 @@
+import { useMemo, useSyncExternalStore } from "react";
+import type { Profile } from "../relay/contracts";
+import type { RelaySession } from "../relay/session";
+import { knownAgentPubkeys } from "./known";
+
+/** One subscribed projection per owning surface; exact keys, never display names. */
+export function useKnownAgentPubkeys(
+  session: RelaySession,
+  profiles: ReadonlyMap<string, Profile>,
+): ReadonlySet<string> {
+  const library = useSyncExternalStore(
+    session.agentLibrary.subscribe,
+    session.agentLibrary.snapshot,
+    session.agentLibrary.snapshot,
+  );
+  return useMemo(
+    () => knownAgentPubkeys(profiles, library),
+    [profiles, library],
+  );
+}
diff --git a/src/features/messages/ChannelTimeline.tsx b/src/features/messages/ChannelTimeline.tsx
index 1312d2f9..927ff3ce 100644
--- a/src/features/messages/ChannelTimeline.tsx
+++ b/src/features/messages/ChannelTimeline.tsx
@@ -13,6 +13,7 @@ import { readView, writeView } from "../../shared/view-state";
 import styles from "./Messages.module.css";
 import { useReading } from "./use-reading";
 import { messageViewKey } from "./view-key";
+import { useKnownAgentPubkeys } from "../agents/use-known";
 
 const EDGE_HEIGHT = 56;
 type ReadingPosition = {
@@ -103,6 +104,7 @@ function Timeline({
   const restoredAnchor = useRef<string | undefined>(undefined);
   const rows = useMemo(() => membershipRows(window.rows), [window.rows]);
   const profiles = useRowProfiles(queries.profiles, window.rows);
+  const agentPubkeys = useKnownAgentPubkeys(queries, profiles);
   const geometry = useMemo(() => geometryFor(queries.channels), [queries]);
   const signature = useMemo(
     () => geometrySignature(window.rows, profiles),
@@ -429,6 +431,7 @@ function Timeline({
                 profiles={profiles}
                 viewer={viewer}
                 media={queries.media}
+                agentPubkeys={agentPubkeys}
                 day={day}
               />
             ) : (
@@ -439,6 +442,7 @@ function Timeline({
                 extensions={extensions}
                 profile={profiles.get(row.authorId)}
                 participantProfiles={profiles}
+                agentPubkeys={agentPubkeys}
                 media={queries.media}
                 onOpenLink={onOpenLink}
                 canOpenLink={canOpenLink}
diff --git a/src/features/messages/MembershipRow.tsx b/src/features/messages/MembershipRow.tsx
index e806f2f9..cb23fac3 100644
--- a/src/features/messages/MembershipRow.tsx
+++ b/src/features/messages/MembershipRow.tsx
@@ -9,12 +9,14 @@ export const MembershipRow = memo(function MembershipRow({
   profiles,
   viewer,
   media,
+  agentPubkeys,
   day,
 }: {
   row: TimelineRow;
   profiles: ReadonlyMap<string, Profile>;
   viewer?: string | undefined;
   media(url: string): string | undefined;
+  agentPubkeys?: ReadonlySet<string> | undefined;
   day: boolean;
 }) {
   const { targets, text, title } = membershipDescription(
@@ -44,7 +46,13 @@ export const MembershipRow = memo(function MembershipRow({
               ? media(profile.picture)
               : undefined;
             return (
-              <span className={styles.membershipAvatar} key={id}>
+              <span
+                className={styles.membershipAvatar}
+                data-avatar-shape={
+                  agentPubkeys?.has(id) ? "squircle" : "circle"
+                }
+                key={id}
+              >
                 {name.slice(0, 2).toUpperCase()}
                 {picture && (
                   <img
diff --git a/src/features/messages/MessageRow.test.tsx b/src/features/messages/MessageRow.test.tsx
index 3894998d..e441eedc 100644
--- a/src/features/messages/MessageRow.test.tsx
+++ b/src/features/messages/MessageRow.test.tsx
@@ -287,3 +287,20 @@ it("does not bypass the session media resolver to paint an inaccessible attachme
   expect(html).not.toContain("<canvas");
   expect(html).not.toContain("<img");
 });
+
+it("uses the reviewed SVG squircle only for identities classified as agents", () => {
+  const agent = "a".repeat(64);
+  const html = renderToStaticMarkup(
+    <MessageRow
+      row={{ ...row, authorId: agent }}
+      profile={{ name: "Carl" }}
+      agentPubkeys={new Set([agent])}
+      media={() => undefined}
+      onOpenLink={() => false}
+      day={false}
+      retry={undefined}
+    />,
+  );
+  expect(html).toContain('data-avatar-shape="squircle"');
+  expect(render({}, 0).html).toContain('data-avatar-shape="circle"');
+});
diff --git a/src/features/messages/MessageRow.tsx b/src/features/messages/MessageRow.tsx
index 9cc74e38..d67d65f5 100644
--- a/src/features/messages/MessageRow.tsx
+++ b/src/features/messages/MessageRow.tsx
@@ -17,6 +17,7 @@ export type MessageRowProps = {
   extensions?: ConversationExtensions | undefined;
   profile: Profile | undefined;
   participantProfiles?: ReadonlyMap<string, Profile> | undefined;
+  agentPubkeys?: ReadonlySet<string> | undefined;
   canOpenLink?: ((target: string) => boolean) | undefined;
   media(url: string): string | undefined;
   onOpenLink(url: string): boolean;
@@ -37,6 +38,7 @@ export const MessageRow = memo(function MessageRow({
   retry,
   onOpenThread,
   participantProfiles,
+  agentPubkeys,
 }: MessageRowProps) {
   const threadUnread = useThreadUnread(
     row.replyCount > 0 && onOpenThread ? unread : undefined,
@@ -73,6 +75,9 @@ export const MessageRow = memo(function MessageRow({
       <div className={styles.message}>
         <AvatarTag
           className={styles.avatar}
+          data-avatar-shape={
+            agentPubkeys?.has(row.authorId) ? "squircle" : "circle"
+          }
           {...(clickable
             ? {
                 type: "button" as const,
@@ -177,6 +182,9 @@ export const MessageRow = memo(function MessageRow({
                       <span
                         key={id}
                         className={styles.threadAvatar}
+                        data-avatar-shape={
+                          agentPubkeys?.has(id) ? "squircle" : "circle"
+                        }
                         title={name}
                       >
                         {name.slice(0, 2).toUpperCase()}
diff --git a/src/features/messages/Messages.module.css b/src/features/messages/Messages.module.css
index 87a1faeb..8dbea6f5 100644
--- a/src/features/messages/Messages.module.css
+++ b/src/features/messages/Messages.module.css
@@ -710,3 +710,9 @@ button.avatar:focus-visible,
   height: 100%;
   object-fit: cover;
 }
+
+.avatar[data-avatar-shape="squircle"],
+.threadAvatar[data-avatar-shape="squircle"],
+.membershipAvatar[data-avatar-shape="squircle"] {
+  clip-path: path("M .5 0 C .93 0 1 .07 1 .5 C 1 .93 .93 1 .5 1 C .07 1 0 .93 0 .5 C 0 .07 .07 0 .5 0 Z");
+}
diff --git a/src/features/messages/ThreadPanel.tsx b/src/features/messages/ThreadPanel.tsx
index 80a01d32..3cced766 100644
--- a/src/features/messages/ThreadPanel.tsx
+++ b/src/features/messages/ThreadPanel.tsx
@@ -17,6 +17,7 @@ import { MessageComposer } from "./MessageComposer";
 import styles from "./Messages.module.css";
 import { useReading } from "./use-reading";
 import { messageViewKey } from "./view-key";
+import { useKnownAgentPubkeys } from "../agents/use-known";
 
 export type ThreadPanelProps = {
   extensions?: ConversationExtensions | undefined;
@@ -167,6 +168,7 @@ function ThreadMessages({
         .catch(() => {});
   }, [session.profiles, authors]);
   const profiles = useRowProfiles(session.profiles, rows);
+  const agentPubkeys = useKnownAgentPubkeys(session, profiles);
   const scroller = useRef<HTMLElement>(null);
   const positioned = useRef(false);
   const follow = useRef(true);
@@ -235,6 +237,7 @@ function ThreadMessages({
             row={snapshot.root}
             profile={profiles.get(snapshot.root.authorId)}
             participantProfiles={profiles}
+            agentPubkeys={agentPubkeys}
             media={session.media}
             onOpenLink={onOpenLink}
             canOpenLink={canOpenLink}
@@ -258,6 +261,7 @@ function ThreadMessages({
                 row={row}
                 profile={profiles.get(row.authorId)}
                 participantProfiles={profiles}
+                agentPubkeys={agentPubkeys}
                 media={session.media}
                 onOpenLink={onOpenLink}
                 canOpenLink={canOpenLink}
diff --git a/src/features/relay/contracts.ts b/src/features/relay/contracts.ts
index d7900c75..9d902777 100644
--- a/src/features/relay/contracts.ts
+++ b/src/features/relay/contracts.ts
@@ -19,6 +19,8 @@ export type Profile = Readonly<{
   name: string;
   picture?: string;
   about?: string;
+  /** Self-authored profile metadata; additive to the local agent library. */
+  isAgent?: true;
 }>;
 export type Attachment = Readonly<{
   url: string;
diff --git a/src/features/relay/profile-details.test.ts b/src/features/relay/profile-details.test.ts
index d1919044..075ae6dc 100644
--- a/src/features/relay/profile-details.test.ts
+++ b/src/features/relay/profile-details.test.ts
@@ -2,7 +2,7 @@ import { expect, it } from "vitest";
 import { foldProfiles } from "./profiles";
 import { createProfileDirectory } from "./profile-directory";
 import { createRelayReader } from "./reader";
-import { keypair, profile, scriptedTransport } from "./testing";
+import { keypair, profile, scriptedTransport, signed } from "./testing";
 const user = keypair();
 it("projects about safely and publishes an about-only replacement/removal", () => {
   const wire = scriptedTransport(user.pubkey, keypair().pubkey);
@@ -29,3 +29,15 @@ it("projects about safely and publishes an about-only replacement/removal", () =
     reader.dispose();
   }
 });
+
+it("retains self-authored agent metadata without inferring it from display names", () => {
+  const author = keypair();
+  const profiles = foldProfiles([
+    signed(author, {
+      kind: 0,
+      content: JSON.stringify({ name: "Agent-looking human", is_agent: true }),
+      tags: [],
+    }),
+  ]);
+  expect(profiles.get(author.pubkey)?.isAgent).toBe(true);
+});
diff --git a/src/features/relay/profiles.ts b/src/features/relay/profiles.ts
index 85909795..43cfa589 100644
--- a/src/features/relay/profiles.ts
+++ b/src/features/relay/profiles.ts
@@ -20,6 +20,8 @@ export function foldProfiles(
         name?: unknown;
         picture?: unknown;
         about?: unknown;
+        is_agent?: unknown;
+        isAgent?: unknown;
       };
       const name = [body.display_name, body.name].find(
         (value): value is string =>
@@ -37,6 +39,9 @@ export function foldProfiles(
           ...(typeof body.about === "string" && body.about.trim()
             ? { about: body.about.trim() }
             : {}),
+          ...(body.is_agent === true || body.isAgent === true
+            ? { isAgent: true as const }
+            : {}),
         }),
       );
     } catch {
diff --git a/src/shared/Avatar.tsx b/src/shared/Avatar.tsx
index 62776d39..8cc780f9 100644
--- a/src/shared/Avatar.tsx
+++ b/src/shared/Avatar.tsx
@@ -5,10 +5,12 @@ export function Avatar({
   name,
   src,
   className = "",
+  shape = "circle",
 }: {
   name: string;
   src?: string | undefined;
   className?: string;
+  shape?: "circle" | "squircle";
 }) {
   const [failed, setFailed] = useState<string>();
   const initials =
@@ -21,6 +23,7 @@ export function Avatar({
       .toUpperCase() || "?";
   return (
     <span
+      data-avatar-shape={shape}
       className={`relative inline-grid shrink-0 place-items-center overflow-hidden rounded-2xl bg-[#ece9f4] font-semibold text-[#675780] ${className}`}
       aria-hidden="true"
     >
diff --git a/src/shared/design-system/styles/components.css b/src/shared/design-system/styles/components.css
index 3ff57cd5..4b07c86e 100644
--- a/src/shared/design-system/styles/components.css
+++ b/src/shared/design-system/styles/components.css
@@ -920,3 +920,9 @@
     }
   }
 }
+
+@layer components {
+  .buzz-avatar[data-avatar-shape="squircle"] {
+    clip-path: path("M .5 0 C .93 0 1 .07 1 .5 C 1 .93 .93 1 .5 1 C .07 1 0 .93 0 .5 C 0 .07 .07 0 .5 0 Z");
+  }
+}
diff --git a/src/shared/design-system/ui/Avatar.tsx b/src/shared/design-system/ui/Avatar.tsx
index f416304e..585343a9 100644
--- a/src/shared/design-system/ui/Avatar.tsx
+++ b/src/shared/design-system/ui/Avatar.tsx
@@ -36,11 +36,13 @@ export function Avatar({
   alt,
   fallback,
   size = "default",
+  shape = "circle",
 }: {
   src?: string | null;
   alt: string;
   fallback: string;
   size?: AvatarSize;
+  shape?: "circle" | "squircle";
 }) {
   const initial = fallback.slice(0, 1).toUpperCase();
   return (
@@ -48,6 +50,7 @@ export function Avatar({
       data-buzz-ui=""
       className="buzz-avatar"
       data-size={size}
+      data-avatar-shape={shape}
       role="img"
       aria-label={alt}
     >
diff --git a/tests/browser/fixture.mjs b/tests/browser/fixture.mjs
index 392fe4ec..623ab257 100644
--- a/tests/browser/fixture.mjs
+++ b/tests/browser/fixture.mjs
@@ -377,6 +377,7 @@ export const test = base.extend({
                 [],
                 JSON.stringify({
                   name: key === membershipKeys[0] ? "Pinky" : "Brain",
+                  ...(key === membershipKeys[1] ? { is_agent: true } : {}),
                 }),
                 key,
               ),
diff --git a/tests/browser/membership.spec.mjs b/tests/browser/membership.spec.mjs
index 01f5b909..f880ca79 100644
--- a/tests/browser/membership.spec.mjs
+++ b/tests/browser/membership.spec.mjs
@@ -26,6 +26,10 @@ test("Channels renders grouped history and live membership without turning activ
     "Pinky added by you, along with Brain",
   );
   await expect(groups.locator("button")).toHaveCount(0);
+  const avatars = groups.first().locator("[data-avatar-shape]");
+  await expect(avatars).toHaveCount(2);
+  await expect(avatars.nth(0)).toHaveAttribute("data-avatar-shape", "circle");
+  await expect(avatars.nth(1)).toHaveAttribute("data-avatar-shape", "squircle");
   const centered = await groups.first().evaluate((row) => {
     const content = row.querySelector("p");
     const avatars = row.querySelector('[aria-hidden="true"]');

From ef1b60c9fc888cb1fc4b93d56961259591aae8f2 Mon Sep 17 00:00:00 2001
From: Taylor Ho <taylorkmho@gmail.com>
Date: Sun, 13 Sep 2026 10:34:01 -1000
Subject: [PATCH 2/7] test(avatars): cover agent and human shapes in browser

Co-authored-by: Carl <acda9e433d19dcd0e6b6840f7f4b98f3a56f1fab98049d444c087019e6d36560@buzz.block.builderlab.xyz>
Signed-off-by: Taylor Ho <taylorkmho@gmail.com>
---
 tests/browser/agents.spec.mjs     |  3 ++
 tests/browser/membership.spec.mjs | 10 +++++--
 tests/browser/messages.spec.mjs   | 49 ++++++++++++++++++++++++++++++-
 tests/browser/profiles.spec.mjs   |  9 ++++++
 tests/browser/typeahead.spec.mjs  | 37 +++++++++++++++++++++++
 tests/fixtures/mentions.tsx       |  2 +-
 tests/fixtures/messages.tsx       |  5 +++-
 tests/fixtures/profiles.tsx       |  2 +-
 8 files changed, 111 insertions(+), 6 deletions(-)

diff --git a/tests/browser/agents.spec.mjs b/tests/browser/agents.spec.mjs
index f802408a..fc1535ab 100644
--- a/tests/browser/agents.spec.mjs
+++ b/tests/browser/agents.spec.mjs
@@ -33,6 +33,9 @@ test("My agents reads the existing library with exact linked keys and session-sa
       .poll(() => agents.locator("img").evaluate((image) => image.naturalWidth))
       .toBeGreaterThan(0);
     await expect(agents.locator("img")).toHaveCSS("opacity", "1");
+    await expect(agents.locator("[data-avatar-shape]")).toHaveCount(2);
+    for (const avatar of await agents.locator("[data-avatar-shape]").all())
+      await expect(avatar).toHaveAttribute("data-avatar-shape", "squircle");
     await expect(
       agents.getByRole("img", { name: "A Brain", exact: true }),
     ).toHaveCount(2);
diff --git a/tests/browser/membership.spec.mjs b/tests/browser/membership.spec.mjs
index f880ca79..d7de5956 100644
--- a/tests/browser/membership.spec.mjs
+++ b/tests/browser/membership.spec.mjs
@@ -28,8 +28,14 @@ test("Channels renders grouped history and live membership without turning activ
   await expect(groups.locator("button")).toHaveCount(0);
   const avatars = groups.first().locator("[data-avatar-shape]");
   await expect(avatars).toHaveCount(2);
-  await expect(avatars.nth(0)).toHaveAttribute("data-avatar-shape", "circle");
-  await expect(avatars.nth(1)).toHaveAttribute("data-avatar-shape", "squircle");
+  await expect(avatars.filter({ hasText: "PI" })).toHaveAttribute(
+    "data-avatar-shape",
+    "circle",
+  );
+  await expect(avatars.filter({ hasText: "BR" })).toHaveAttribute(
+    "data-avatar-shape",
+    "squircle",
+  );
   const centered = await groups.first().evaluate((row) => {
     const content = row.querySelector("p");
     const avatars = row.querySelector('[aria-hidden="true"]');
diff --git a/tests/browser/messages.spec.mjs b/tests/browser/messages.spec.mjs
index 99b1c3d1..ba6cdd80 100644
--- a/tests/browser/messages.spec.mjs
+++ b/tests/browser/messages.spec.mjs
@@ -7,7 +7,7 @@ import { fileURLToPath } from "node:url";
 // thread reader and durable outbox. No developer env, broker, credentials or relay.
 test("shared thread UI auto-loads, follows live replies, retries and isolates retargeted drafts", async ({
   page,
-}) => {
+}, testInfo) => {
   const server = await createServer({
     root: fileURLToPath(new URL("../../", import.meta.url)),
     configFile: false,
@@ -55,6 +55,13 @@ test("shared thread UI auto-loads, follows live replies, retries and isolates re
       exact: true,
     });
     const history = panel.getByRole("region", { name: "Thread messages" });
+    const feedAuthorAvatar = feed.locator(
+      '[data-message-id="ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"] [data-avatar-shape]',
+    );
+    await expect(feedAuthorAvatar).toHaveAttribute(
+      "data-avatar-shape",
+      "circle",
+    );
     const draft = panel.getByRole("textbox", {
       name: "Reply to thread",
       exact: true,
@@ -110,6 +117,46 @@ test("shared thread UI auto-loads, follows live replies, retries and isolates re
     await expect(
       history.getByRole("heading", { name: "Agent Markdown", level: 3 }),
     ).toBeVisible();
+    const threadAgentAvatar = history
+      .getByRole("heading", { name: "Agent Markdown" })
+      .locator("xpath=ancestor::*[@data-message-id][1]")
+      .locator("[data-avatar-shape]")
+      .first();
+    await expect(threadAgentAvatar).toHaveAttribute(
+      "data-avatar-shape",
+      "squircle",
+    );
+    const threadHumanAvatar = history
+      .getByText("First root", { exact: true })
+      .locator("xpath=ancestor::*[@data-message-id][1]")
+      .locator("[data-avatar-shape]")
+      .first();
+    await expect(threadHumanAvatar).toHaveAttribute(
+      "data-avatar-shape",
+      "circle",
+    );
+    await page.evaluate(() => {
+      document.documentElement.dataset.colorMode = "dark";
+    });
+    const evidence = testInfo.outputPath("human-agent-thread-avatars.png");
+    const humanBox = await threadHumanAvatar.boundingBox();
+    const agentBox = await threadAgentAvatar.boundingBox();
+    const panelBox = await panel.boundingBox();
+    if (!humanBox || !agentBox || !panelBox)
+      throw new Error("Missing avatar evidence bounds");
+    const top = Math.max(0, Math.min(humanBox.y, agentBox.y) - panelBox.y - 36);
+    const bottom =
+      Math.max(humanBox.y + humanBox.height, agentBox.y + agentBox.height) -
+      panelBox.y +
+      72;
+    await panel.screenshot({
+      path: evidence,
+      clip: { x: 0, y: top, width: 440, height: bottom - top },
+    });
+    await testInfo.attach("human-agent-thread-avatars", {
+      path: evidence,
+      contentType: "image/png",
+    });
     await expect(
       history.getByText("Rendered from an agent envelope", { exact: true }),
     ).toHaveCSS("font-weight", /^(650|700)$/);
diff --git a/tests/browser/profiles.spec.mjs b/tests/browser/profiles.spec.mjs
index 8a9ea388..e4834ffa 100644
--- a/tests/browser/profiles.spec.mjs
+++ b/tests/browser/profiles.spec.mjs
@@ -35,6 +35,7 @@ test("profile plumbing: exact avatar/mention targets, thread enrichment, lifecyc
       exact: true,
     });
     await expect(avatar).toHaveCount(1);
+    await expect(avatar).toHaveAttribute("data-avatar-shape", "circle");
     await avatar.focus();
     await avatar.press("Enter");
     await expect(key).toHaveText(npubs.viewer);
@@ -74,6 +75,10 @@ test("profile plumbing: exact avatar/mention targets, thread enrichment, lifecyc
     });
     await mention.click();
     await expect(key).toHaveText(npubs.mic);
+    await expect(panel.locator("[data-avatar-shape]")).toHaveAttribute(
+      "data-avatar-shape",
+      "circle",
+    );
     await panel.getByRole("button", { name: "Close channel panel" }).click();
     await expect(mention).toBeFocused();
     await mention.press("Space");
@@ -103,6 +108,10 @@ test("profile plumbing: exact avatar/mention targets, thread enrichment, lifecyc
     await expect(threadMention).toBeVisible();
     await threadMention.click();
     await expect(key).toHaveText(npubs.pinky);
+    await expect(panel.locator("[data-avatar-shape]")).toHaveAttribute(
+      "data-avatar-shape",
+      "squircle",
+    );
     await expect(
       panel.getByText("Agent profile", { exact: true }),
     ).toBeVisible();
diff --git a/tests/browser/typeahead.spec.mjs b/tests/browser/typeahead.spec.mjs
index d0107a59..a6165990 100644
--- a/tests/browser/typeahead.spec.mjs
+++ b/tests/browser/typeahead.spec.mjs
@@ -24,6 +24,43 @@ const open = async (page) => {
   );
   return page.getByRole("textbox", { name: "Message #General" });
 };
+const expectAvatarShape = async (target, shape) => {
+  await expect(target.locator("[data-avatar-shape]")).toHaveAttribute(
+    "data-avatar-shape",
+    shape,
+  );
+};
+test("mention completion distinguishes exact agent identity without reshaping a namesake human", async ({
+  page,
+}) => {
+  const input = await open(page);
+  const keys = await page.evaluate(() => ({
+    human: window.mentionFixture.first,
+    agent: window.mentionFixture.second,
+  }));
+  await input.fill("@Ho");
+  await expectAvatarShape(
+    page.getByRole("option", { name: `Honey ${keys.human}`, exact: true }),
+    "circle",
+  );
+  await expectAvatarShape(
+    page.getByRole("option", { name: `Honey ${keys.agent}`, exact: true }),
+    "squircle",
+  );
+  await input.fill("");
+  await page
+    .getByRole("button", { name: "Mention a member", exact: true })
+    .click();
+  const picker = page.getByRole("region", { name: "Mention a channel member" });
+  await expectAvatarShape(
+    picker.getByRole("button", { name: `Honey ${keys.human}`, exact: true }),
+    "circle",
+  );
+  await expectAvatarShape(
+    picker.getByRole("button", { name: `Honey ${keys.agent}`, exact: true }),
+    "squircle",
+  );
+});
 test("typeahead replaces only the query and publishes selected namesake identity, including replies", async ({
   page,
 }) => {
diff --git a/tests/fixtures/mentions.tsx b/tests/fixtures/mentions.tsx
index 4bfa9da8..8224e2b5 100644
--- a/tests/fixtures/mentions.tsx
+++ b/tests/fixtures/mentions.tsx
@@ -52,7 +52,7 @@ const owner = createRelaySession(
         metadata(relay, "other", "Other"),
         profile(viewer, { name: "Viewer" }),
         profile(first, { name: delayed ? "Mary Jane" : "Honey" }),
-        profile(second, { name: "Honey" }),
+        profile(second, { name: "Honey", is_agent: true }),
         ...publications,
       ];
       return events.filter((event) =>
diff --git a/tests/fixtures/messages.tsx b/tests/fixtures/messages.tsx
index a102fe2e..7ccd8601 100644
--- a/tests/fixtures/messages.tsx
+++ b/tests/fixtures/messages.tsx
@@ -132,7 +132,10 @@ const owner = createRelaySession({
           metadata(relay, "two", "Two"),
         ];
       if (filter.kinds?.includes(0))
-        return [profile(viewer, { name: "Fixture Reader" })];
+        return [
+          profile(viewer, { name: "Fixture Reader" }),
+          profile(agent, { name: "Agent Fixture", is_agent: true }),
+        ].filter((event) => filter.authors?.includes(event.pubkey));
       if (filter.ids)
         return events.filter((event) => filter.ids?.includes(event.id));
       if (filter.depth_limit) {
diff --git a/tests/fixtures/profiles.tsx b/tests/fixtures/profiles.tsx
index d5f6b18f..cb1073e6 100644
--- a/tests/fixtures/profiles.tsx
+++ b/tests/fixtures/profiles.tsx
@@ -44,7 +44,7 @@ let failMissing = true;
 const data = [
   profile(viewer, { name: "Viewer", about: "Human profile" }),
   profile(mic, { name: "Mic", about: "Mic biography" }),
-  profile(pinky, { name: "Pinky", about: "Agent profile" }),
+  profile(pinky, { name: "Pinky", about: "Agent profile", is_agent: true }),
 ];
 function session() {
   return createRelaySession({

From ae4238e5d68f1ae9f6e70cc3a72a42e99564a357 Mon Sep 17 00:00:00 2001
From: Carl
 <acda9e433d19dcd0e6b6840f7f4b98f3a56f1fab98049d444c087019e6d36560@buzz.block.builderlab.xyz>
Date: Mon, 14 Sep 2026 08:24:58 -1000
Subject: [PATCH 3/7] fix(avatars): scale agent squircles and refresh identity
 hints

Signed-off-by: Carl <acda9e433d19dcd0e6b6840f7f4b98f3a56f1fab98049d444c087019e6d36560@buzz.block.builderlab.xyz>
---
 docs/profiles.md                              |  21 ++-
 src/bundled/mentions/MentionCompletion.tsx    |   1 +
 src/features/agents/known.ts                  |   3 +-
 src/features/agents/use-known.ts              |   3 +-
 .../messages/ChannelTimeline.test.tsx         |   4 +
 src/features/messages/MembershipRow.tsx       |   6 +-
 src/features/messages/MessageRow.test.tsx     |  30 +++++
 src/features/messages/MessageRow.tsx          |  30 +++--
 src/features/messages/Messages.module.css     |  26 ++--
 src/features/messages/ThreadPanel.test.tsx    |   2 +
 src/features/relay/contracts.ts               |   4 +-
 src/features/relay/fold.test.ts               |  40 ++++++
 src/features/relay/fold.ts                    |   1 +
 src/features/relay/profile-details.test.ts    |  57 +++++++-
 src/features/relay/profile-directory.ts       |   3 +-
 src/shared/Avatar.tsx                         |   1 +
 .../design-system/styles/avatar-shape.css     |  12 ++
 .../design-system/styles/avatar-squircle.svg  |   1 +
 .../design-system/styles/components.css       |   6 -
 src/shared/design-system/ui/Avatar.tsx        |   1 +
 src/shared/design-system/ui/registry.ts       |   5 +-
 tests/browser/avatar-shapes.spec.mjs          | 123 ++++++++++++++++++
 tests/browser/profiles.spec.mjs               |   5 +-
 tests/browser/typeahead.spec.mjs              |  43 ++++++
 tests/fixtures/avatar-shapes.html             |   1 +
 tests/fixtures/avatar-shapes.tsx              | 103 +++++++++++++++
 .../design-system/ui/componentSpecimens.tsx   |  15 +++
 tests/fixtures/mentions.tsx                   |  17 +++
 tests/fixtures/messages.tsx                   |   2 +-
 29 files changed, 527 insertions(+), 39 deletions(-)
 create mode 100644 src/shared/design-system/styles/avatar-shape.css
 create mode 100644 src/shared/design-system/styles/avatar-squircle.svg
 create mode 100644 tests/browser/avatar-shapes.spec.mjs
 create mode 100644 tests/fixtures/avatar-shapes.html
 create mode 100644 tests/fixtures/avatar-shapes.tsx

diff --git a/docs/profiles.md b/docs/profiles.md
index 0965bbc3..5d808c9e 100644
--- a/docs/profiles.md
+++ b/docs/profiles.md
@@ -3,7 +3,7 @@
 The bundled `buzz.profiles` plugin supplies a minimal, read-only panel for any
 public identity, human or agent. It uses the current session's shared profile
 directory. Agents retains agent-specific configuration/operations; this slice
-adds no ownership/running badge, editor, agent-library lookup or execution API.
+adds no ownership/running badge, editor, agent-library read or execution API.
 When Agent Activity is enabled and the host supplies conversation context, **View
 activity** opens its raw panel for this exact identity and originating channel.
 This action is offered for any public identity: it does not infer that the identity
@@ -45,6 +45,25 @@ Button use the host-loaded styles directly. The profile content marks its
 owns layout, not component overrides. No new theme owner, second global reset or
 shell migration. Designers own later refinement.
 
+Agent avatar shapes are display-only. Original kind-40002 messages retain an
+`agentEnvelope` hint through the existing fold, including after edits; their author
+avatar can be a squircle without profile or library evidence. Other avatar surfaces
+use self-declared `is_agent`/`isAgent` profile metadata or exact keys in the
+already-loaded session library. These hints establish neither ownership nor running
+state. Library evidence remains lazy: opening Agents/Refresh loads it, and clearing
+it removes that fallback. Avatars never initiate a library read or scan telemetry.
+
+The shared, bundled SVG mask scales the same curve across avatar sizes. It clips
+artwork only; the message profile button retains its unmasked keyboard focus ring.
+`avatar-shapes.spec.mjs` checks actual painted pixels and focus in Chromium/WebKit,
+in light/dark at 390, 900 and 1280px. The open-completion regression checks library
+hint changes without another keystroke, and directory tests cover marker-only
+profile updates. The focused channel-opening check kept optional profiles held and
+added no warm head reads: local warm paints were 11.9–20.6ms in Chromium and
+36–40ms in WebKit (cold visibility upper bounds 60.3/81ms, including test IPC).
+These synthetic Apple Silicon measurements are not a live-network SLA. Full scan
+and native/package acceptance remain deferred.
+
 Use the normal `bin/just desktop` or `bin/just web` workflow in the feature worktree
 with the existing public live-mode pin; run only one dev target at a time.
 
diff --git a/src/bundled/mentions/MentionCompletion.tsx b/src/bundled/mentions/MentionCompletion.tsx
index 62fbc7d6..70efb442 100644
--- a/src/bundled/mentions/MentionCompletion.tsx
+++ b/src/bundled/mentions/MentionCompletion.tsx
@@ -140,6 +140,7 @@ export function MentionCompletion({
     channelId,
     memberKey,
     profiles,
+    agentPubkeys,
     query.query,
     publish,
     error,
diff --git a/src/features/agents/known.ts b/src/features/agents/known.ts
index cd81a719..68e9664f 100644
--- a/src/features/agents/known.ts
+++ b/src/features/agents/known.ts
@@ -1,7 +1,8 @@
 import type { AgentLibrary } from "./library";
 import type { Profile } from "../relay/contracts";
 
-/** Exact identity keys from authenticated profile metadata plus the local Buzz library. */
+/** Exact keys from self-declared profile hints plus the local Buzz library.
+ * Display-only evidence, not proof of ownership, membership or authority. */
 export function knownAgentPubkeys(
   profiles: ReadonlyMap<string, Profile>,
   library?: AgentLibrary,
diff --git a/src/features/agents/use-known.ts b/src/features/agents/use-known.ts
index 42d4c4bc..e5ec7bc4 100644
--- a/src/features/agents/use-known.ts
+++ b/src/features/agents/use-known.ts
@@ -3,7 +3,8 @@ import type { Profile } from "../relay/contracts";
 import type { RelaySession } from "../relay/session";
 import { knownAgentPubkeys } from "./known";
 
-/** One subscribed projection per owning surface; exact keys, never display names. */
+/** One display-only projection per owning surface; exact keys, never display names.
+ * Subscribes to existing evidence without initiating library reads. */
 export function useKnownAgentPubkeys(
   session: RelaySession,
   profiles: ReadonlyMap<string, Profile>,
diff --git a/src/features/messages/ChannelTimeline.test.tsx b/src/features/messages/ChannelTimeline.test.tsx
index 27b235f7..bd656e04 100644
--- a/src/features/messages/ChannelTimeline.test.tsx
+++ b/src/features/messages/ChannelTimeline.test.tsx
@@ -2,6 +2,7 @@ import { afterEach, expect, it, vi } from "vitest";
 import type { ReactElement } from "react";
 import { Virtualizer } from "virtua";
 import { ChannelTimeline } from "./ChannelTimeline";
+import { createAgentLibrary } from "../agents/library";
 import { createRelaySession } from "../relay/session";
 import {
   bounds,
@@ -87,6 +88,8 @@ vi.mock("react", async (original) => ({
       });
     }
   },
+  useSyncExternalStore: (_subscribe: unknown, snapshot: () => unknown) =>
+    snapshot(),
 }));
 vi.mock("../relay/react", () => ({
   useRowProfiles: () => new Map(),
@@ -226,6 +229,7 @@ function setup({
     ({
       channels: { loadOlder, window: snapshot },
       profiles: {},
+      agentLibrary: createAgentLibrary(undefined).queries,
       // Geometry fixtures are read-only; reading behavior has its own boundary tests.
       unread: { sync: () => ({ capability: "unsupported" }) },
       media: () => undefined,
diff --git a/src/features/messages/MembershipRow.tsx b/src/features/messages/MembershipRow.tsx
index cb23fac3..bbfcd7df 100644
--- a/src/features/messages/MembershipRow.tsx
+++ b/src/features/messages/MembershipRow.tsx
@@ -1,3 +1,4 @@
+import "../../shared/design-system/styles/avatar-shape.css";
 import { memo } from "react";
 import type { Profile } from "../relay/contracts";
 import { membershipDescription, type TimelineRow } from "./membership-rows";
@@ -69,7 +70,10 @@ export const MembershipRow = memo(function MembershipRow({
             );
           })}
           {targets.length > 3 && (
-            <span className={styles.membershipAvatar}>
+            <span
+              className={styles.membershipAvatar}
+              data-avatar-shape="circle"
+            >
               +{targets.length - 3}
             </span>
           )}
diff --git a/src/features/messages/MessageRow.test.tsx b/src/features/messages/MessageRow.test.tsx
index e441eedc..d490e4bc 100644
--- a/src/features/messages/MessageRow.test.tsx
+++ b/src/features/messages/MessageRow.test.tsx
@@ -304,3 +304,33 @@ it("uses the reviewed SVG squircle only for identities classified as agents", ()
   expect(html).toContain('data-avatar-shape="squircle"');
   expect(render({}, 0).html).toContain('data-avatar-shape="circle"');
 });
+
+it.each([9, 40002])(
+  "renders kind %s author shape from the existing fold without profile/library evidence",
+  (kind) => {
+    const author = keypair(),
+      relay = keypair();
+    const [folded] = foldMessages("channel", relay.pubkey, [
+      signed(author, {
+        kind,
+        content:
+          kind === 40002 ? JSON.stringify({ content: "Reply" }) : "Reply",
+        tags: [["h", "channel"]],
+      }),
+    ]);
+    if (!folded) throw new Error("Missing row");
+    const html = renderToStaticMarkup(
+      <MessageRow
+        row={folded}
+        profile={undefined}
+        media={() => undefined}
+        onOpenLink={() => false}
+        day={false}
+        retry={undefined}
+      />,
+    );
+    expect(html).toContain(
+      `data-avatar-shape="${kind === 40002 ? "squircle" : "circle"}"`,
+    );
+  },
+);
diff --git a/src/features/messages/MessageRow.tsx b/src/features/messages/MessageRow.tsx
index d67d65f5..76bdfa4b 100644
--- a/src/features/messages/MessageRow.tsx
+++ b/src/features/messages/MessageRow.tsx
@@ -1,3 +1,4 @@
+import "../../shared/design-system/styles/avatar-shape.css";
 import { memo, useCallback, useSyncExternalStore } from "react";
 import type { UnreadCapability } from "../relay/unread";
 import { profileTarget } from "../profiles/target";
@@ -74,10 +75,7 @@ export const MessageRow = memo(function MessageRow({
       )}
       <div className={styles.message}>
         <AvatarTag
-          className={styles.avatar}
-          data-avatar-shape={
-            agentPubkeys?.has(row.authorId) ? "squircle" : "circle"
-          }
+          className={styles.avatarButton}
           {...(clickable
             ? {
                 type: "button" as const,
@@ -89,11 +87,20 @@ export const MessageRow = memo(function MessageRow({
               }
             : {})}
         >
-          {picture ? (
-            <img src={picture} alt="" loading="lazy" />
-          ) : (
-            name.slice(0, 2).toUpperCase()
-          )}
+          <span
+            className={styles.avatar}
+            data-avatar-shape={
+              row.agentEnvelope || agentPubkeys?.has(row.authorId)
+                ? "squircle"
+                : "circle"
+            }
+          >
+            {picture ? (
+              <img src={picture} alt="" loading="lazy" />
+            ) : (
+              name.slice(0, 2).toUpperCase()
+            )}
+          </span>
         </AvatarTag>
         <div className={styles.messageBody}>
           <div className={styles.byline}>
@@ -203,7 +210,10 @@ export const MessageRow = memo(function MessageRow({
                     );
                   })}
                   {row.participants.length > 3 && (
-                    <span className={styles.threadAvatar}>
+                    <span
+                      className={styles.threadAvatar}
+                      data-avatar-shape="circle"
+                    >
                       +{row.participants.length - 3}
                     </span>
                   )}
diff --git a/src/features/messages/Messages.module.css b/src/features/messages/Messages.module.css
index 8dbea6f5..8ad3c3e7 100644
--- a/src/features/messages/Messages.module.css
+++ b/src/features/messages/Messages.module.css
@@ -82,11 +82,20 @@
   gap: 12px;
   padding: 8px 0 24px;
 }
+.avatarButton {
+  flex-shrink: 0;
+  align-self: flex-start;
+  border-radius: var(--radius-sm);
+}
+html[data-keyboard-navigation] button.avatarButton:focus-visible {
+  outline: 2px solid var(--focus);
+  outline-offset: 2px;
+}
+
 .avatar {
   width: 40px;
   height: 40px;
   flex-shrink: 0;
-  border-radius: 50%;
   background: var(--surface-accent);
   color: var(--text-muted);
   display: grid;
@@ -470,7 +479,6 @@
   margin-right: -3px;
   overflow: hidden;
   border: 2px solid var(--surface);
-  border-radius: 50%;
   background: var(--surface-accent);
   color: var(--text-muted);
   font-size: calc(9px * var(--buzz-text-scale, 1));
@@ -642,12 +650,14 @@
   font-style: italic;
 }
 
-button.avatar {
+button.avatarButton {
   padding: 0;
   border: 0;
+  background: transparent;
   cursor: pointer;
 }
-button.avatar:hover {
+button.avatarButton:hover {
+  background: transparent;
   box-shadow: 0 0 0 2px var(--border);
 }
 .mention {
@@ -664,7 +674,6 @@ button.avatar:hover {
 .mention:hover {
   text-decoration: underline;
 }
-button.avatar:focus-visible,
 .mention:focus-visible {
   outline: 2px solid var(--focus);
   outline-offset: 2px;
@@ -697,7 +706,6 @@ button.avatar:focus-visible,
   height: 28px;
   margin-right: -6px;
   border: 2px solid var(--surface);
-  border-radius: 9px;
   overflow: hidden;
   background: var(--surface-accent);
   color: var(--text-muted);
@@ -710,9 +718,3 @@ button.avatar:focus-visible,
   height: 100%;
   object-fit: cover;
 }
-
-.avatar[data-avatar-shape="squircle"],
-.threadAvatar[data-avatar-shape="squircle"],
-.membershipAvatar[data-avatar-shape="squircle"] {
-  clip-path: path("M .5 0 C .93 0 1 .07 1 .5 C 1 .93 .93 1 .5 1 C .07 1 0 .93 0 .5 C 0 .07 .07 0 .5 0 Z");
-}
diff --git a/src/features/messages/ThreadPanel.test.tsx b/src/features/messages/ThreadPanel.test.tsx
index 8ef9d60b..efdf660f 100644
--- a/src/features/messages/ThreadPanel.test.tsx
+++ b/src/features/messages/ThreadPanel.test.tsx
@@ -1,6 +1,7 @@
 import { beforeEach, expect, it, vi } from "vitest";
 import { isValidElement, type ReactElement, type ReactNode } from "react";
 import { ThreadPanel } from "./ThreadPanel";
+import { createAgentLibrary } from "../agents/library";
 import { MessageRow } from "./MessageRow";
 import { MessageMarkdown } from "./MessageMarkdown";
 import { MessageComposer } from "./MessageComposer";
@@ -130,6 +131,7 @@ function setup() {
   const session = {
     thread,
     profiles: { ensure },
+    agentLibrary: createAgentLibrary(undefined).queries,
     messages: { retry: vi.fn() },
     // Geometry fixtures are read-only; reading behavior has its own boundary tests.
     unread: { sync: () => ({ capability: "unsupported" }) },
diff --git a/src/features/relay/contracts.ts b/src/features/relay/contracts.ts
index 9d902777..f00f2eb6 100644
--- a/src/features/relay/contracts.ts
+++ b/src/features/relay/contracts.ts
@@ -19,7 +19,7 @@ export type Profile = Readonly<{
   name: string;
   picture?: string;
   about?: string;
-  /** Self-authored profile metadata; additive to the local agent library. */
+  /** Self-declared display hint, not proof of ownership, membership or authority. */
   isAgent?: true;
 }>;
 export type Attachment = Readonly<{
@@ -44,6 +44,8 @@ export type ChannelMessage = Readonly<{
   /** Unix seconds from the signed event. Ordering is (createdAt asc, id desc); no clock inference. */
   createdAt: number;
   content: string;
+  /** Original kind 40002, regardless of edits; self-declared display evidence, not authority. */
+  agentEnvelope?: true;
   membership?: MembershipChange;
   /** Current body came from a replacement edit; original recipients do not bind its prose. */
   edited?: true;
diff --git a/src/features/relay/fold.test.ts b/src/features/relay/fold.test.ts
index fe77b4bd..480997f8 100644
--- a/src/features/relay/fold.test.ts
+++ b/src/features/relay/fold.test.ts
@@ -194,6 +194,46 @@ describe("message fold", () => {
     },
   );
 
+  it.each([
+    [9, "Plain message"],
+    [9, JSON.stringify({ content: "Envelope-looking prose", is_agent: true })],
+    [40002, JSON.stringify({ content: "Agent message" })],
+    [40002, "Malformed envelope"],
+  ])(
+    "keeps the original kind %s display hint independent of body and edits (%s)",
+    (kind, content) => {
+      const original = signed(alice, {
+        kind,
+        content,
+        created_at: 10,
+        tags: [["h", channel]],
+      });
+      const hint = kind === 40002 ? true : undefined;
+      expect(
+        foldMessages(channel, relay.pubkey, [original])[0]?.agentEnvelope,
+      ).toBe(hint);
+      for (const replacement of [
+        "Plain edit",
+        JSON.stringify({ content: "Envelope edit" }),
+      ]) {
+        const edit = signed(alice, {
+          kind: 40003,
+          content: replacement,
+          created_at: 11,
+          tags: [["e", original.id]],
+        });
+        const [row] = foldMessages(channel, relay.pubkey, [original, edit]);
+        expect(row?.edited).toBe(true);
+        expect(row?.agentEnvelope).toBe(hint);
+        expect(row?.content).toBe(
+          kind === 40002 && replacement.startsWith("{")
+            ? "Envelope edit"
+            : replacement,
+        );
+      }
+    },
+  );
+
   it("unwraps agent envelopes and projects valid CommonMark images through one safe URL policy", () => {
     const agent = signed(bob, {
       kind: 40002,
diff --git a/src/features/relay/fold.ts b/src/features/relay/fold.ts
index b404f69d..abc298ef 100644
--- a/src/features/relay/fold.ts
+++ b/src/features/relay/fold.ts
@@ -165,6 +165,7 @@ export function foldMessages(
         authorId: event.pubkey,
         createdAt: event.created_at,
         content: projected.content,
+        ...(event.kind === 40002 ? { agentEnvelope: true as const } : {}),
         ...(edits.length ? { edited: true as const } : {}),
         ...(projected.content !== content &&
         projected.content !== content.trimEnd()
diff --git a/src/features/relay/profile-details.test.ts b/src/features/relay/profile-details.test.ts
index 075ae6dc..9bc8b1e6 100644
--- a/src/features/relay/profile-details.test.ts
+++ b/src/features/relay/profile-details.test.ts
@@ -1,4 +1,5 @@
-import { expect, it } from "vitest";
+import { expect, it, vi } from "vitest";
+import { selectProfiles } from "./profile-selection";
 import { foldProfiles } from "./profiles";
 import { createProfileDirectory } from "./profile-directory";
 import { createRelayReader } from "./reader";
@@ -41,3 +42,57 @@ it("retains self-authored agent metadata without inferring it from display names
   ]);
   expect(profiles.get(author.pubkey)?.isAgent).toBe(true);
 });
+
+it.each([
+  { field: "is_agent", removal: { is_agent: false } },
+  { field: "isAgent", removal: {} },
+])(
+  "notifies the directory and selected profile on $field-only addition/removal",
+  ({ field, removal }) => {
+    const wire = scriptedTransport(user.pubkey, keypair().pubkey);
+    const reader = createRelayReader(wire.transport);
+    const directory = createProfileDirectory(reader.reader);
+    const selection = selectProfiles(directory.queries, [user.pubkey]);
+    const directoryChanged = vi.fn();
+    const selectedChanged = vi.fn();
+    const unsubscribeDirectory = directory.queries.subscribe(directoryChanged);
+    const unsubscribeSelection = selection.subscribe(selectedChanged);
+    try {
+      directory.accept([profile(user, { name: "Mic" }, 1)]);
+      const before = selection.snapshot();
+      directoryChanged.mockClear();
+      selectedChanged.mockClear();
+
+      directory.accept([profile(user, { name: "Mic", [field]: true }, 2)]);
+      const added = selection.snapshot();
+      expect(added).not.toBe(before);
+      expect(added.get(user.pubkey)).toBe(
+        directory.queries.snapshot().get(user.pubkey),
+      );
+      expect(added.get(user.pubkey)).toEqual({ name: "Mic", isAgent: true });
+      expect(directoryChanged).toHaveBeenCalledTimes(1);
+      expect(selectedChanged).toHaveBeenCalledTimes(1);
+
+      // A newer event with identical display values must still preserve identity.
+      directory.accept([profile(user, { name: "Mic", [field]: true }, 3)]);
+      expect(selection.snapshot()).toBe(added);
+      expect(directoryChanged).toHaveBeenCalledTimes(1);
+      expect(selectedChanged).toHaveBeenCalledTimes(1);
+
+      directory.accept([profile(user, { name: "Mic", ...removal }, 4)]);
+      const removed = selection.snapshot();
+      expect(removed).not.toBe(added);
+      expect(removed.get(user.pubkey)).toBe(
+        directory.queries.snapshot().get(user.pubkey),
+      );
+      expect(removed.get(user.pubkey)).toEqual({ name: "Mic" });
+      expect(directoryChanged).toHaveBeenCalledTimes(2);
+      expect(selectedChanged).toHaveBeenCalledTimes(2);
+    } finally {
+      unsubscribeSelection();
+      unsubscribeDirectory();
+      directory.dispose();
+      reader.dispose();
+    }
+  },
+);
diff --git a/src/features/relay/profile-directory.ts b/src/features/relay/profile-directory.ts
index a3c895ee..731de677 100644
--- a/src/features/relay/profile-directory.ts
+++ b/src/features/relay/profile-directory.ts
@@ -54,7 +54,8 @@ export function createProfileDirectory(
       if (
         old?.name === value.name &&
         old?.picture === value.picture &&
-        old?.about === value.about
+        old?.about === value.about &&
+        old?.isAgent === value.isAgent
       )
         next.set(id, old);
     }
diff --git a/src/shared/Avatar.tsx b/src/shared/Avatar.tsx
index 8cc780f9..68345cea 100644
--- a/src/shared/Avatar.tsx
+++ b/src/shared/Avatar.tsx
@@ -1,3 +1,4 @@
+import "./design-system/styles/avatar-shape.css";
 import { useState } from "react";
 
 /** Caller resolves private relay media through the current session. */
diff --git a/src/shared/design-system/styles/avatar-shape.css b/src/shared/design-system/styles/avatar-shape.css
new file mode 100644
index 00000000..b4caa7e4
--- /dev/null
+++ b/src/shared/design-system/styles/avatar-shape.css
@@ -0,0 +1,12 @@
+/* Shared by system and legacy avatars. The SVG viewBox scales the same curve
+   at every size; CSS path() coordinates would be fixed pixels. Apply only to
+   artwork, never its interactive wrapper, so focus and hover remain unclipped.
+   Unlayered to replace legacy utility/module radii as well as system defaults. */
+[data-avatar-shape="circle"] {
+  border-radius: 50%;
+}
+
+[data-avatar-shape="squircle"] {
+  border-radius: 0;
+  mask: url("./avatar-squircle.svg") center / 100% 100% no-repeat;
+}
diff --git a/src/shared/design-system/styles/avatar-squircle.svg b/src/shared/design-system/styles/avatar-squircle.svg
new file mode 100644
index 00000000..219f65e1
--- /dev/null
+++ b/src/shared/design-system/styles/avatar-squircle.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1 1"><path d="M .5 0 C .93 0 1 .07 1 .5 C 1 .93 .93 1 .5 1 C .07 1 0 .93 0 .5 C 0 .07 .07 0 .5 0 Z"/></svg>
diff --git a/src/shared/design-system/styles/components.css b/src/shared/design-system/styles/components.css
index 4b07c86e..3ff57cd5 100644
--- a/src/shared/design-system/styles/components.css
+++ b/src/shared/design-system/styles/components.css
@@ -920,9 +920,3 @@
     }
   }
 }
-
-@layer components {
-  .buzz-avatar[data-avatar-shape="squircle"] {
-    clip-path: path("M .5 0 C .93 0 1 .07 1 .5 C 1 .93 .93 1 .5 1 C .07 1 0 .93 0 .5 C 0 .07 .07 0 .5 0 Z");
-  }
-}
diff --git a/src/shared/design-system/ui/Avatar.tsx b/src/shared/design-system/ui/Avatar.tsx
index 585343a9..35058abf 100644
--- a/src/shared/design-system/ui/Avatar.tsx
+++ b/src/shared/design-system/ui/Avatar.tsx
@@ -1,3 +1,4 @@
+import "../styles/avatar-shape.css";
 import { Avatar as BaseAvatar } from "@base-ui/react/avatar";
 import { useEffect, useState } from "react";
 
diff --git a/src/shared/design-system/ui/registry.ts b/src/shared/design-system/ui/registry.ts
index f6f9a4f1..cea0d941 100644
--- a/src/shared/design-system/ui/registry.ts
+++ b/src/shared/design-system/ui/registry.ts
@@ -178,9 +178,10 @@ export const COMPONENTS: readonly ComponentDefinition[] = [
   {
     slug: "avatar",
     name: "Avatar",
-    purpose: "A person or agent identity image with a stable fallback.",
+    purpose:
+      "A person or agent identity image with a stable fallback. Circle by default; callers can select the proposed squircle shape from display-only agent evidence.",
     behavior: "Base UI Avatar",
-    variants: ["small", "default", "large"],
+    variants: ["small", "default", "large", "circle", "squircle"],
     status: "proposed",
     collection: "components",
     owner: "desktop-new Messages",
diff --git a/tests/browser/avatar-shapes.spec.mjs b/tests/browser/avatar-shapes.spec.mjs
new file mode 100644
index 00000000..c54f83cd
--- /dev/null
+++ b/tests/browser/avatar-shapes.spec.mjs
@@ -0,0 +1,123 @@
+import { expect, test } from "@playwright/test";
+import { createServer } from "vite";
+import react from "@vitejs/plugin-react";
+import { fileURLToPath } from "node:url";
+
+// Sample actual browser paint, not just shape attributes or bounding boxes.
+async function pixels(page, locator) {
+  const png = await locator.screenshot();
+  return page.evaluate(async (base64) => {
+    const image = new Image();
+    image.src = `data:image/png;base64,${base64}`;
+    await image.decode();
+    const canvas = document.createElement("canvas");
+    canvas.width = image.width;
+    canvas.height = image.height;
+    const context = canvas.getContext("2d");
+    context.drawImage(image, 0, 0);
+    const at = (fraction) => [
+      ...context.getImageData(
+        Math.floor(image.width * fraction),
+        Math.floor(image.height * fraction),
+        1,
+        1,
+      ).data,
+    ];
+    return { corner: at(0), shoulder: at(0.1), center: at(0.5) };
+  }, png.toString("base64"));
+}
+
+test("avatar shapes paint at every size and preserve pointer/keyboard profile controls", async ({
+  page,
+  browserName,
+}, testInfo) => {
+  const server = await createServer({
+    root: fileURLToPath(new URL("../../", import.meta.url)),
+    configFile: false,
+    envFile: false,
+    plugins: [react()],
+    logLevel: "error",
+    server: { host: "127.0.0.1", port: 0 },
+  });
+  await server.listen();
+  try {
+    await page.goto(
+      `http://127.0.0.1:${server.httpServer.address().port}/tests/fixtures/avatar-shapes.html`,
+    );
+    const avatars = page.locator("[data-avatar-shape]");
+    await expect(avatars).toHaveCount(12);
+    for (const image of await avatars.locator("img").all()) {
+      await expect
+        .poll(() => image.evaluate((el) => el.complete && el.naturalWidth > 0))
+        .toBe(true);
+      await expect(image).toHaveCSS("opacity", "1");
+    }
+    const system = page.getByRole("region", { name: "System avatars" });
+    for (const mode of ["light", "dark"]) {
+      await page.evaluate((mode) => {
+        document.documentElement.dataset.colorMode = mode;
+      }, mode);
+      for (const width of [390, 900, 1280]) {
+        await page.setViewportSize({ width, height: 800 });
+        for (const avatar of await avatars.all()) {
+          const shape = await avatar.getAttribute("data-avatar-shape");
+          await expect(avatar).toHaveCSS("clip-path", "none");
+          await expect(avatar).toHaveCSS(
+            "border-radius",
+            shape === "squircle" ? "0px" : "50%",
+          );
+          await expect(avatar).toHaveCSS(
+            "mask-image",
+            shape === "squircle" ? /^url\(/ : "none",
+          );
+        }
+        for (const avatar of await system
+          .locator("[data-avatar-shape]")
+          .all()) {
+          const shape = await avatar.getAttribute("data-avatar-shape");
+          const paint = await pixels(page, avatar);
+          expect(
+            paint.center,
+            `${mode}/${width}/${shape}: artwork is painted`,
+          ).not.toEqual(paint.corner);
+          if (shape === "squircle")
+            expect(
+              paint.shoulder,
+              "squircle extends beyond a circle",
+            ).not.toEqual(paint.corner);
+          else
+            expect(paint.shoulder, "human corner stays circular").toEqual(
+              paint.corner,
+            );
+        }
+      }
+    }
+    const button = page.getByRole("button", { name: "View Agent profile" });
+    await expect(button).toHaveCSS("background-color", "rgba(0, 0, 0, 0)");
+    await button.hover();
+    await expect(button).toHaveCSS("background-color", "rgba(0, 0, 0, 0)");
+    await button.click();
+    await expect(page.getByRole("status")).toHaveText("Profile opened");
+    await expect(button).toHaveCSS("outline-style", "none");
+    await page.getByRole("button", { name: "Before avatars" }).focus();
+    // Safari on macOS uses Option-Tab to include all controls, like the other focus journeys.
+    await page.keyboard.press(
+      browserName === "webkit" && process.platform === "darwin"
+        ? "Alt+Tab"
+        : "Tab",
+    );
+    await expect(button).toBeFocused();
+    await expect(button).toHaveCSS("outline-style", "solid");
+    await expect(button).toHaveCSS("outline-width", "2px");
+    await expect(button).toHaveCSS("mask-image", "none");
+    await expect(button).toHaveCSS("clip-path", "none");
+    await expect(button).toHaveCSS("overflow", "visible");
+    await page.keyboard.press("Enter");
+    await expect(page.getByRole("status")).toHaveText("Profile opened");
+    await page.screenshot({
+      path: testInfo.outputPath("avatar-shapes-dark-keyboard.png"),
+    });
+  } finally {
+    await server.close();
+  }
+});
diff --git a/tests/browser/profiles.spec.mjs b/tests/browser/profiles.spec.mjs
index e4834ffa..0fb1faa7 100644
--- a/tests/browser/profiles.spec.mjs
+++ b/tests/browser/profiles.spec.mjs
@@ -35,7 +35,10 @@ test("profile plumbing: exact avatar/mention targets, thread enrichment, lifecyc
       exact: true,
     });
     await expect(avatar).toHaveCount(1);
-    await expect(avatar).toHaveAttribute("data-avatar-shape", "circle");
+    await expect(avatar.locator("[data-avatar-shape]")).toHaveAttribute(
+      "data-avatar-shape",
+      "circle",
+    );
     await avatar.focus();
     await avatar.press("Enter");
     await expect(key).toHaveText(npubs.viewer);
diff --git a/tests/browser/typeahead.spec.mjs b/tests/browser/typeahead.spec.mjs
index a6165990..7b6f78cb 100644
--- a/tests/browser/typeahead.spec.mjs
+++ b/tests/browser/typeahead.spec.mjs
@@ -61,6 +61,49 @@ test("mention completion distinguishes exact agent identity without reshaping a
     "squircle",
   );
 });
+test("open completion republishes library-only display hints without changing the query", async ({
+  page,
+}) => {
+  const input = await open(page);
+  const keys = await page.evaluate(() => ({
+    first: window.mentionFixture.first,
+    second: window.mentionFixture.second,
+  }));
+  await input.fill("@Ho");
+  const first = page.getByRole("option", {
+    name: `Honey ${keys.first}`,
+    exact: true,
+  });
+  const second = page.getByRole("option", {
+    name: `Honey ${keys.second}`,
+    exact: true,
+  });
+  await expectAvatarShape(first, "circle");
+  await expectAvatarShape(second, "squircle");
+  // Opening completion subscribes to the library; it must not load it.
+  expect(await page.evaluate(() => window.mentionFixture.libraryReads())).toBe(
+    0,
+  );
+
+  for (const [included, reads] of [
+    [true, 1],
+    [false, 2],
+  ]) {
+    await page.evaluate(
+      (included) => window.mentionFixture.setLibraryAgent(included),
+      included,
+    );
+    await expectAvatarShape(first, included ? "squircle" : "circle");
+    await expectAvatarShape(second, "squircle");
+    await expect(input).toHaveValue("@Ho");
+    await expect(input).toBeFocused();
+    await expect(page.getByRole("listbox")).toBeVisible();
+    expect(
+      await page.evaluate(() => window.mentionFixture.libraryReads()),
+    ).toBe(reads);
+  }
+});
+
 test("typeahead replaces only the query and publishes selected namesake identity, including replies", async ({
   page,
 }) => {
diff --git a/tests/fixtures/avatar-shapes.html b/tests/fixtures/avatar-shapes.html
new file mode 100644
index 00000000..cd834f87
--- /dev/null
+++ b/tests/fixtures/avatar-shapes.html
@@ -0,0 +1 @@
+<!doctype html><html lang="en"><head><meta charset="UTF-8"><title>Avatar shapes</title></head><body><div id="root"></div><script type="module" src="./avatar-shapes.tsx"></script></body></html>
diff --git a/tests/fixtures/avatar-shapes.tsx b/tests/fixtures/avatar-shapes.tsx
new file mode 100644
index 00000000..85bb9585
--- /dev/null
+++ b/tests/fixtures/avatar-shapes.tsx
@@ -0,0 +1,103 @@
+// Real avatar consumers with local display-only data, no session/broker/network reads.
+import "../../src/shared/styles/globals.css";
+import { useState } from "react";
+import { createRoot } from "react-dom/client";
+import { Avatar } from "../../src/shared/design-system/ui/Avatar";
+import { Avatar as LegacyAvatar } from "../../src/shared/Avatar";
+import { useKeyboardFocusVisibility } from "../../src/shared/design-system/useKeyboardFocusVisibility";
+import { MessageRow } from "../../src/features/messages/MessageRow";
+import { MembershipRow } from "../../src/features/messages/MembershipRow";
+import type { ChannelMessage } from "../../src/features/relay/contracts";
+import artwork from "./design-system/assets/avatar.png";
+
+const agent = "a".repeat(64),
+  human = "b".repeat(64);
+const profiles = new Map([
+  [agent, { name: "Agent", picture: artwork }],
+  [human, { name: "Human", picture: artwork }],
+]);
+const agentPubkeys = new Set([agent]);
+const row: ChannelMessage = {
+  id: "message",
+  authorId: agent,
+  channelId: "fixture",
+  createdAt: 1,
+  content: "A message",
+  mentions: [],
+  attachments: [],
+  reactions: [],
+  participants: [agent, human],
+  replyCount: 2,
+};
+function Fixture() {
+  useKeyboardFocusVisibility();
+  const [opened, setOpened] = useState(false);
+  return (
+    <main style={{ padding: 24 }}>
+      <button type="button">Before avatars</button>
+      <section
+        aria-label="System avatars"
+        style={{ display: "flex", gap: 16, marginBlock: 24 }}
+      >
+        {(["small", "default", "large"] as const).flatMap((size) =>
+          (["circle", "squircle"] as const).map((shape) => (
+            <Avatar
+              key={`${size}-${shape}`}
+              size={size}
+              shape={shape}
+              src={size === "small" ? undefined : artwork}
+              alt={`${size} ${shape}`}
+              fallback="Avatar"
+            />
+          )),
+        )}
+      </section>
+      <section
+        aria-label="Legacy avatars"
+        style={{ display: "flex", gap: 16, marginBlock: 24 }}
+      >
+        <LegacyAvatar
+          name="Human"
+          src={artwork}
+          shape="circle"
+          className="size-7 rounded-lg"
+        />
+        <LegacyAvatar
+          name="Agent"
+          src={artwork}
+          shape="squircle"
+          className="size-7 rounded-lg"
+        />
+      </section>
+      <MessageRow
+        row={{ ...row, agentEnvelope: true }}
+        profile={profiles.get(agent)}
+        participantProfiles={profiles}
+        agentPubkeys={agentPubkeys}
+        media={(url) => url}
+        canOpenLink={() => true}
+        onOpenLink={() => {
+          setOpened(true);
+          return true;
+        }}
+        day={false}
+        retry={undefined}
+        onOpenThread={() => {}}
+      />
+      <MembershipRow
+        row={{
+          ...row,
+          membership: { type: "member_joined", actor: agent, target: agent },
+        }}
+        profiles={profiles}
+        agentPubkeys={agentPubkeys}
+        media={(url) => url}
+        day={false}
+      />
+      {opened && <p role="status">Profile opened</p>}
+    </main>
+  );
+}
+const root = document.getElementById("root");
+if (!root) throw new Error("Missing fixture root");
+createRoot(root).render(<Fixture />);
diff --git a/tests/fixtures/design-system/ui/componentSpecimens.tsx b/tests/fixtures/design-system/ui/componentSpecimens.tsx
index 76584557..d5800bea 100644
--- a/tests/fixtures/design-system/ui/componentSpecimens.tsx
+++ b/tests/fixtures/design-system/ui/componentSpecimens.tsx
@@ -302,6 +302,21 @@ function AvatarSpecimen() {
           </Specimen>
         </div>
       </SpecimenGroup>
+      <SpecimenGroup label="Agent shape (proposed)">
+        <div className="component-specimen-row">
+          <Specimen prop='shape="squircle"'>
+            <Avatar
+              src={avatarUrl}
+              alt="Agent artwork"
+              fallback="Agent"
+              shape="squircle"
+            />
+          </Specimen>
+          <Specimen prop='shape="squircle", no src'>
+            <Avatar alt="Agent fallback" fallback="Agent" shape="squircle" />
+          </Specimen>
+        </div>
+      </SpecimenGroup>
       {/* No `src`, so the fallback initial shows. Same three sizes, because a
           fallback has to hold the ramp as well as an image does. */}
       <SpecimenGroup label="Fallback, with no src">
diff --git a/tests/fixtures/mentions.tsx b/tests/fixtures/mentions.tsx
index 8224e2b5..fc84f127 100644
--- a/tests/fixtures/mentions.tsx
+++ b/tests/fixtures/mentions.tsx
@@ -26,6 +26,8 @@ let time = 1700000000;
 const publications: RelayEvent[] = [];
 let incoming = (_events: readonly RelayEvent[]) => {};
 let releaseProfiles = () => {};
+let libraryReads = 0;
+let libraryIncludesFirst = false;
 const delayed = new URLSearchParams(location.search).has("delayed-profiles");
 const profileGate = delayed
   ? new Promise<void>((resolve) => {
@@ -37,6 +39,16 @@ const owner = createRelaySession(
     viewer: viewer.pubkey,
     relayAuthor: relay.pubkey,
     media: (url) => url,
+    // Synthetic, lazy capability: only the explicit fixture action loads it.
+    async readAgentLibrary() {
+      libraryReads++;
+      return {
+        definitions: [],
+        identities: libraryIncludesFirst
+          ? [{ pubkey: first.pubkey, name: "Honey" }]
+          : [],
+      };
+    },
     subscribe(callbacks) {
       incoming = callbacks.receive;
       callbacks.state({ status: "connected", routes: [] });
@@ -135,6 +147,11 @@ Object.assign(window, {
       owner.session.channels.refreshList?.();
     },
     releaseProfiles: () => releaseProfiles(),
+    libraryReads: () => libraryReads,
+    setLibraryAgent(included: boolean) {
+      libraryIncludesFirst = included;
+      return owner.session.agentLibrary.refresh();
+    },
     list: () => owner.session.channels.list(),
     otherMessage() {
       incoming([message(viewer, "other", "Unrelated preview", ++time)]);
diff --git a/tests/fixtures/messages.tsx b/tests/fixtures/messages.tsx
index 7ccd8601..2d339ba8 100644
--- a/tests/fixtures/messages.tsx
+++ b/tests/fixtures/messages.tsx
@@ -134,7 +134,7 @@ const owner = createRelaySession({
       if (filter.kinds?.includes(0))
         return [
           profile(viewer, { name: "Fixture Reader" }),
-          profile(agent, { name: "Agent Fixture", is_agent: true }),
+          profile(agent, { name: "Agent Fixture" }),
         ].filter((event) => filter.authors?.includes(event.pubkey));
       if (filter.ids)
         return events.filter((event) => filter.ids?.includes(event.id));

From 76ef90439f0e7dea8b489072d4fcc82a5f48dea9 Mon Sep 17 00:00:00 2001
From: Carl
 <acda9e433d19dcd0e6b6840f7f4b98f3a56f1fab98049d444c087019e6d36560@buzz.block.builderlab.xyz>
Date: Mon, 14 Sep 2026 08:28:50 -1000
Subject: [PATCH 4/7] fix(avatars): label the squircle mask asset

Signed-off-by: Carl <acda9e433d19dcd0e6b6840f7f4b98f3a56f1fab98049d444c087019e6d36560@buzz.block.builderlab.xyz>
---
 src/shared/design-system/styles/avatar-squircle.svg | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/shared/design-system/styles/avatar-squircle.svg b/src/shared/design-system/styles/avatar-squircle.svg
index 219f65e1..f7806eb4 100644
--- a/src/shared/design-system/styles/avatar-squircle.svg
+++ b/src/shared/design-system/styles/avatar-squircle.svg
@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1 1"><path d="M .5 0 C .93 0 1 .07 1 .5 C 1 .93 .93 1 .5 1 C .07 1 0 .93 0 .5 C 0 .07 .07 0 .5 0 Z"/></svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1 1"><title>Squircle avatar mask</title><path d="M .5 0 C .93 0 1 .07 1 .5 C 1 .93 .93 1 .5 1 C .07 1 0 .93 0 .5 C 0 .07 .07 0 .5 0 Z"/></svg>

From f1fdb58814bc3090f6fa0699fa4fd1377727eeeb Mon Sep 17 00:00:00 2001
From: Carl
 <acda9e433d19dcd0e6b6840f7f4b98f3a56f1fab98049d444c087019e6d36560@buzz.block.builderlab.xyz>
Date: Mon, 14 Sep 2026 09:08:27 -1000
Subject: [PATCH 5/7] fix(avatars): keep plugin declarations and fixture caches
 isolated

Load the shared avatar mask through Messages.module.css so the type-only author package does not retain a runtime stylesheet import. Reuse the unchanged mainline Vite helper from a67102a for the avatar fixture and include listen failures in cleanup. Tighten the profile shape explanation and separate its coverage notes.

Co-authored-by: Brain <1a02c72794dcd0f07058a353bc3a81f4028b8c77c92c87fce6d5c8b85970a20b@buzz.block.builderlab.xyz>
Co-authored-by: Pinky <5f5ab050ec58ae208332edd544ebf705221e24c1b86d82a6ca07038a7a8f6ac9@buzz.block.builderlab.xyz>
Signed-off-by: Carl <acda9e433d19dcd0e6b6840f7f4b98f3a56f1fab98049d444c087019e6d36560@buzz.block.builderlab.xyz>
---
 docs/profiles.md                          | 32 +++++++++++------------
 src/features/messages/MessageRow.tsx      |  1 -
 src/features/messages/Messages.module.css |  2 ++
 tests/browser/avatar-shapes.spec.mjs      |  4 +--
 tests/browser/vite-server.mjs             | 24 +++++++++++++++++
 5 files changed, 43 insertions(+), 20 deletions(-)
 create mode 100644 tests/browser/vite-server.mjs

diff --git a/docs/profiles.md b/docs/profiles.md
index 5d808c9e..afb20924 100644
--- a/docs/profiles.md
+++ b/docs/profiles.md
@@ -45,30 +45,28 @@ Button use the host-loaded styles directly. The profile content marks its
 owns layout, not component overrides. No new theme owner, second global reset or
 shell migration. Designers own later refinement.
 
-Agent avatar shapes are display-only. Original kind-40002 messages retain an
-`agentEnvelope` hint through the existing fold, including after edits; their author
-avatar can be a squircle without profile or library evidence. Other avatar surfaces
-use self-declared `is_agent`/`isAgent` profile metadata or exact keys in the
-already-loaded session library. These hints establish neither ownership nor running
-state. Library evidence remains lazy: opening Agents/Refresh loads it, and clearing
-it removes that fallback. Avatars never initiate a library read or scan telemetry.
+Agent hints change avatar shape, not authority:
 
-The shared, bundled SVG mask scales the same curve across avatar sizes. It clips
-artwork only; the message profile button retains its unmasked keyboard focus ring.
-`avatar-shapes.spec.mjs` checks actual painted pixels and focus in Chromium/WebKit,
-in light/dark at 390, 900 and 1280px. The open-completion regression checks library
-hint changes without another keystroke, and directory tests cover marker-only
-profile updates. The focused channel-opening check kept optional profiles held and
-added no warm head reads: local warm paints were 11.9–20.6ms in Chromium and
-36–40ms in WebKit (cold visibility upper bounds 60.3/81ms, including test IPC).
-These synthetic Apple Silicon measurements are not a live-network SLA. Full scan
-and native/package acceptance remain deferred.
+- Profiles, mentions, participants and membership avatars use squircles for
+  self-declared `is_agent`/`isAgent` metadata or exact keys in the loaded session
+  library; otherwise they use circles. My Agents cards always use squircles.
+- Message authors also use these hints. An original kind-40002 envelope is enough
+  on its own and keeps that treatment through edits.
+- Library hints are lazy: opening or refreshing Agents loads them; clearing the
+  library removes that fallback. Avatars never fetch the library or scan telemetry.
+
+None of these hints proves ownership or running state. One bundled SVG mask scales
+across sizes and clips only artwork, leaving the profile button's focus ring intact.
 
 Use the normal `bin/just desktop` or `bin/just web` workflow in the feature worktree
 with the existing public live-mode pin; run only one dev target at a time.
 
 ## Evidence and remaining checks
 
+`avatar-shapes.spec.mjs` covers painted pixels and focus across sizes, themes and
+viewports in Chromium/WebKit. Completion tests cover loaded-library changes without
+another keystroke; profile-directory tests cover marker-only updates.
+
 `tests/browser/profiles.spec.mjs` runs real React/ChannelsPage, thread reading,
 profile directory, panel registry and plugin lifecycle against a synthetic
 transport. It covers avatar/mention keys, keyboard/focus, disable/re-enable,
diff --git a/src/features/messages/MessageRow.tsx b/src/features/messages/MessageRow.tsx
index 76bdfa4b..3c523ad9 100644
--- a/src/features/messages/MessageRow.tsx
+++ b/src/features/messages/MessageRow.tsx
@@ -1,4 +1,3 @@
-import "../../shared/design-system/styles/avatar-shape.css";
 import { memo, useCallback, useSyncExternalStore } from "react";
 import type { UnreadCapability } from "../relay/unread";
 import { profileTarget } from "../profiles/target";
diff --git a/src/features/messages/Messages.module.css b/src/features/messages/Messages.module.css
index 8ad3c3e7..725a34df 100644
--- a/src/features/messages/Messages.module.css
+++ b/src/features/messages/Messages.module.css
@@ -1,3 +1,5 @@
+@import "../../shared/design-system/styles/avatar-shape.css";
+
 /* Reusable conversation components; plugins own placement and surrounding layout. */
 .thread {
   min-width: 0;
diff --git a/tests/browser/avatar-shapes.spec.mjs b/tests/browser/avatar-shapes.spec.mjs
index c54f83cd..2f57f9b5 100644
--- a/tests/browser/avatar-shapes.spec.mjs
+++ b/tests/browser/avatar-shapes.spec.mjs
@@ -1,5 +1,5 @@
 import { expect, test } from "@playwright/test";
-import { createServer } from "vite";
+import { createServer } from "./vite-server.mjs";
 import react from "@vitejs/plugin-react";
 import { fileURLToPath } from "node:url";
 
@@ -39,8 +39,8 @@ test("avatar shapes paint at every size and preserve pointer/keyboard profile co
     logLevel: "error",
     server: { host: "127.0.0.1", port: 0 },
   });
-  await server.listen();
   try {
+    await server.listen();
     await page.goto(
       `http://127.0.0.1:${server.httpServer.address().port}/tests/fixtures/avatar-shapes.html`,
     );
diff --git a/tests/browser/vite-server.mjs b/tests/browser/vite-server.mjs
new file mode 100644
index 00000000..48a44872
--- /dev/null
+++ b/tests/browser/vite-server.mjs
@@ -0,0 +1,24 @@
+import { createServer as createViteServer } from "vite";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// Parallel fixture servers must not invalidate each other's optimized imports.
+export async function createServer(config) {
+  const cacheDir = await mkdtemp(join(tmpdir(), "buzz-fixture-vite-"));
+  try {
+    const server = await createViteServer({ ...config, cacheDir });
+    const close = server.close.bind(server);
+    server.close = async () => {
+      try {
+        await close();
+      } finally {
+        await rm(cacheDir, { recursive: true, force: true });
+      }
+    };
+    return server;
+  } catch (error) {
+    await rm(cacheDir, { recursive: true, force: true });
+    throw error;
+  }
+}

From a5578c13fbd69cda5624bade896d5953e3a2b2b7 Mon Sep 17 00:00:00 2001
From: Carl
 <acda9e433d19dcd0e6b6840f7f4b98f3a56f1fab98049d444c087019e6d36560@buzz.block.builderlab.xyz>
Date: Tue, 15 Sep 2026 09:11:19 -1000
Subject: [PATCH 6/7] fix(avatars): clip inset reply and membership artwork

Scale the existing avatar shape independently inside overlap borders, preserving picture sizes, human circles, fallback initials and overflow counts. Cover the inset pixels and bounds in both browser engines.

Signed-off-by: Carl <acda9e433d19dcd0e6b6840f7f4b98f3a56f1fab98049d444c087019e6d36560@buzz.block.builderlab.xyz>
---
 docs/profiles.md                              |   4 +-
 src/features/messages/MembershipRow.tsx       |  30 +++--
 src/features/messages/MessageRow.tsx          |  30 +++--
 src/features/messages/Messages.module.css     |  17 ++-
 .../messages/membership-rows.test.tsx         |  24 +++-
 tests/browser/avatar-shapes.spec.mjs          | 114 ++++++++++++++----
 tests/fixtures/avatar-shapes.tsx              |  67 ++++++----
 tests/fixtures/profiles.tsx                   |   7 +-
 8 files changed, 218 insertions(+), 75 deletions(-)

diff --git a/docs/profiles.md b/docs/profiles.md
index afb20924..eb93d43a 100644
--- a/docs/profiles.md
+++ b/docs/profiles.md
@@ -64,7 +64,9 @@ with the existing public live-mode pin; run only one dev target at a time.
 ## Evidence and remaining checks
 
 `avatar-shapes.spec.mjs` covers painted pixels and focus across sizes, themes and
-viewports in Chromium/WebKit. Completion tests cover loaded-library changes without
+viewports in Chromium/WebKit, including the artwork inside participant/membership
+overlap borders (pictures and initials). Shape attributes alone do not prove that
+inset artwork is clipped. Completion tests cover loaded-library changes without
 another keystroke; profile-directory tests cover marker-only updates.
 
 `tests/browser/profiles.spec.mjs` runs real React/ChannelsPage, thread reading,
diff --git a/src/features/messages/MembershipRow.tsx b/src/features/messages/MembershipRow.tsx
index ea2a69de..f378099a 100644
--- a/src/features/messages/MembershipRow.tsx
+++ b/src/features/messages/MembershipRow.tsx
@@ -54,18 +54,20 @@ export const MembershipRow = memo(function MembershipRow({
                 }
                 key={id}
               >
-                {name.slice(0, 2).toUpperCase()}
-                {picture && (
-                  <img
-                    key={picture}
-                    src={picture}
-                    alt=""
-                    loading="lazy"
-                    onError={(event) => {
-                      event.currentTarget.hidden = true;
-                    }}
-                  />
-                )}
+                <span className={styles.insetAvatarArtwork}>
+                  {name.slice(0, 2).toUpperCase()}
+                  {picture && (
+                    <img
+                      key={picture}
+                      src={picture}
+                      alt=""
+                      loading="lazy"
+                      onError={(event) => {
+                        event.currentTarget.hidden = true;
+                      }}
+                    />
+                  )}
+                </span>
               </span>
             );
           })}
@@ -74,7 +76,9 @@ export const MembershipRow = memo(function MembershipRow({
               className={styles.membershipAvatar}
               data-avatar-shape="circle"
             >
-              +{targets.length - 3}
+              <span className={styles.insetAvatarArtwork}>
+                +{targets.length - 3}
+              </span>
             </span>
           )}
         </span>
diff --git a/src/features/messages/MessageRow.tsx b/src/features/messages/MessageRow.tsx
index 4974b21d..30c02295 100644
--- a/src/features/messages/MessageRow.tsx
+++ b/src/features/messages/MessageRow.tsx
@@ -240,18 +240,20 @@ export const MessageRow = memo(function MessageRow({
                         }
                         title={name}
                       >
-                        {name.slice(0, 2).toUpperCase()}
-                        {picture && (
-                          <img
-                            key={picture}
-                            src={picture}
-                            alt=""
-                            loading="lazy"
-                            onError={(event) => {
-                              event.currentTarget.hidden = true;
-                            }}
-                          />
-                        )}
+                        <span className={styles.insetAvatarArtwork}>
+                          {name.slice(0, 2).toUpperCase()}
+                          {picture && (
+                            <img
+                              key={picture}
+                              src={picture}
+                              alt=""
+                              loading="lazy"
+                              onError={(event) => {
+                                event.currentTarget.hidden = true;
+                              }}
+                            />
+                          )}
+                        </span>
                       </span>
                     );
                   })}
@@ -260,7 +262,9 @@ export const MessageRow = memo(function MessageRow({
                       className={styles.threadAvatar}
                       data-avatar-shape="circle"
                     >
-                      +{row.participants.length - 3}
+                      <span className={styles.insetAvatarArtwork}>
+                        +{row.participants.length - 3}
+                      </span>
                     </span>
                   )}
                 </span>
diff --git a/src/features/messages/Messages.module.css b/src/features/messages/Messages.module.css
index 3e4839a6..c52d2033 100644
--- a/src/features/messages/Messages.module.css
+++ b/src/features/messages/Messages.module.css
@@ -399,7 +399,7 @@ html[data-keyboard-navigation] button.avatarButton:focus-visible {
   margin-right: calc(-1 * var(--space-half));
   overflow: hidden;
   border: 2px solid var(--surface);
-  background: var(--surface-accent);
+  background: var(--surface);
   color: var(--text-muted);
   font-size: var(--text-caption);
   line-height: var(--text-caption--line-height);
@@ -654,7 +654,7 @@ button.avatarButton:hover {
   margin-right: calc(-1 * var(--space-1h));
   border: 2px solid var(--surface);
   overflow: hidden;
-  background: var(--surface-accent);
+  background: var(--surface);
   color: var(--text-muted);
   font-size: var(--text-caption);
   line-height: var(--text-caption--line-height);
@@ -668,6 +668,19 @@ button.avatarButton:hover {
   object-fit: cover;
 }
 
+/* The overlap border and its inset artwork need independently scaled curves. */
+.insetAvatarArtwork {
+  position: relative;
+  display: grid;
+  place-items: center;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+  background: var(--surface-accent);
+  border-radius: inherit;
+  mask: inherit;
+}
+
 .typing {
   color: var(--text-muted);
   font-size: var(--text-caption);
diff --git a/src/features/messages/membership-rows.test.tsx b/src/features/messages/membership-rows.test.tsx
index e313bb82..a6fd7a8e 100644
--- a/src/features/messages/membership-rows.test.tsx
+++ b/src/features/messages/membership-rows.test.tsx
@@ -1,4 +1,4 @@
-import { assert, expect, it } from "vitest";
+import { assert, expect, it, vi } from "vitest";
 import { renderToStaticMarkup } from "react-dom/server";
 import type { ChannelMessage, MembershipChange } from "../relay/contracts";
 import { membershipRows, membershipDescription } from "./membership-rows";
@@ -181,6 +181,28 @@ it("caps visible names/avatars with an overflow count, retaining all names in th
   expect(html).toContain("data-membership-row");
   expect(html).toContain("dddddddddd");
 });
+it.each([false, true])(
+  "keeps small membership media requests with agent hint %s",
+  (agent) => {
+    const picture = "https://image.test/member.png";
+    const media = vi.fn((url: string) => url);
+    const html = renderToStaticMarkup(
+      <MembershipRow
+        row={row("join", joined(pinky, pinky))}
+        profiles={new Map([[pinky, { name: "Pinky", picture }]])}
+        agentPubkeys={new Set(agent ? [pinky] : [])}
+        media={media}
+        day={false}
+      />,
+    );
+    expect(media).toHaveBeenCalledWith(picture, "small");
+    expect(html).toContain(
+      `data-avatar-shape="${agent ? "squircle" : "circle"}"`,
+    );
+    expect(html).toContain('aria-hidden="true"');
+    expect(html).not.toContain("button");
+  },
+);
 it("actor/subject profile enrichment invalidates cached system-row geometry", () => {
   const rows = [row("a", joined(wes, pinky))];
   const original = geometrySignature(rows, profiles);
diff --git a/tests/browser/avatar-shapes.spec.mjs b/tests/browser/avatar-shapes.spec.mjs
index 2f57f9b5..e594ce56 100644
--- a/tests/browser/avatar-shapes.spec.mjs
+++ b/tests/browser/avatar-shapes.spec.mjs
@@ -4,27 +4,32 @@ import react from "@vitejs/plugin-react";
 import { fileURLToPath } from "node:url";
 
 // Sample actual browser paint, not just shape attributes or bounding boxes.
-async function pixels(page, locator) {
+async function pixels(page, locator, inset = 0) {
+  const bounds = await locator.boundingBox();
   const png = await locator.screenshot();
-  return page.evaluate(async (base64) => {
-    const image = new Image();
-    image.src = `data:image/png;base64,${base64}`;
-    await image.decode();
-    const canvas = document.createElement("canvas");
-    canvas.width = image.width;
-    canvas.height = image.height;
-    const context = canvas.getContext("2d");
-    context.drawImage(image, 0, 0);
-    const at = (fraction) => [
-      ...context.getImageData(
-        Math.floor(image.width * fraction),
-        Math.floor(image.height * fraction),
-        1,
-        1,
-      ).data,
-    ];
-    return { corner: at(0), shoulder: at(0.1), center: at(0.5) };
-  }, png.toString("base64"));
+  return page.evaluate(
+    async ({ base64, inset, width }) => {
+      const image = new Image();
+      image.src = `data:image/png;base64,${base64}`;
+      await image.decode();
+      const canvas = document.createElement("canvas");
+      canvas.width = image.width;
+      canvas.height = image.height;
+      const context = canvas.getContext("2d");
+      context.drawImage(image, 0, 0);
+      const padding = inset * (image.width / width);
+      const at = (fraction) => [
+        ...context.getImageData(
+          Math.floor(padding + (image.width - 2 * padding) * fraction),
+          Math.floor(padding + (image.height - 2 * padding) * fraction),
+          1,
+          1,
+        ).data,
+      ];
+      return { corner: at(0), shoulder: at(0.1), center: at(0.5) };
+    },
+    { base64: png.toString("base64"), inset, width: bounds.width },
+  );
 }
 
 test("avatar shapes paint at every size and preserve pointer/keyboard profile controls", async ({
@@ -45,7 +50,7 @@ test("avatar shapes paint at every size and preserve pointer/keyboard profile co
       `http://127.0.0.1:${server.httpServer.address().port}/tests/fixtures/avatar-shapes.html`,
     );
     const avatars = page.locator("[data-avatar-shape]");
-    await expect(avatars).toHaveCount(12);
+    await expect(avatars).toHaveCount(15);
     for (const image of await avatars.locator("img").all()) {
       await expect
         .poll(() => image.evaluate((el) => el.complete && el.naturalWidth > 0))
@@ -53,6 +58,68 @@ test("avatar shapes paint at every size and preserve pointer/keyboard profile co
       await expect(image).toHaveCSS("opacity", "1");
     }
     const system = page.getByRole("region", { name: "System avatars" });
+    const insetAvatars = page.locator(
+      "button[aria-label^='View thread:'] [data-avatar-shape], [data-membership-row] [data-avatar-shape]",
+    );
+    await expect(insetAvatars).toHaveCount(4);
+    async function expectInsetArtwork(pictures = true) {
+      for (const avatar of await insetAvatars.all()) {
+        const shape = await avatar.getAttribute("data-avatar-shape");
+        const size = await avatar.evaluate((el) =>
+          el.closest("[data-membership-row]") ? 28 : 24,
+        );
+        await expect(avatar).toHaveCSS("width", `${size}px`);
+        await expect(avatar).toHaveCSS("height", `${size}px`);
+        await expect(avatar).toHaveCSS("border-width", "2px");
+        for (const image of await avatar.locator("img").all()) {
+          await expect(image).toHaveCSS("width", `${size - 4}px`);
+          await expect(image).toHaveCSS("height", `${size - 4}px`);
+        }
+        // Sample inside the overlap border: an outer mask alone leaves the
+        // actual image/fallback corners square even when its CSS says squircle.
+        const paint = await pixels(page, avatar, 2);
+        const surface = await avatar.evaluate((el) => {
+          const rgb = getComputedStyle(el)
+            .borderTopColor.match(/\d+/g)
+            .map(Number);
+          return [...rgb.slice(0, 3), 255];
+        });
+        const artwork = pictures
+          ? [255, 0, 255, 255]
+          : await avatar
+              .locator("span")
+              .first()
+              .evaluate((el) => {
+                const rgb = getComputedStyle(el)
+                  .backgroundColor.match(/\d+/g)
+                  .map(Number);
+                return [...rgb.slice(0, 3), 255];
+              });
+        // Edge pixels are antialiased at these tiny sizes. Compare whether the
+        // pixel is mostly background or artwork, rather than demanding zero
+        // coverage at the boundary (or confusing photo texture with clipping).
+        const distance = (pixel, color) =>
+          pixel.reduce((sum, value, i) => sum + (value - color[i]) ** 2, 0);
+        expect(
+          distance(paint.corner, surface),
+          `${shape}: inset corner is clipped`,
+        ).toBeLessThan(distance(paint.corner, artwork));
+        if (pictures)
+          expect(paint.center, "inset picture is painted").toEqual(artwork);
+        if (shape === "squircle")
+          // At 20px the shoulder itself can be mostly antialiasing. It must
+          // still paint beyond the clipped corner, not promise full coverage.
+          expect(
+            distance(paint.shoulder, artwork),
+            "inset squircle retains its shoulder",
+          ).toBeLessThan(distance(paint.corner, artwork));
+        else
+          expect(
+            distance(paint.shoulder, surface),
+            "inset human avatar stays circular",
+          ).toBeLessThan(distance(paint.shoulder, artwork));
+      }
+    }
     for (const mode of ["light", "dark"]) {
       await page.evaluate((mode) => {
         document.documentElement.dataset.colorMode = mode;
@@ -71,6 +138,7 @@ test("avatar shapes paint at every size and preserve pointer/keyboard profile co
             shape === "squircle" ? /^url\(/ : "none",
           );
         }
+        await expectInsetArtwork();
         for (const avatar of await system
           .locator("[data-avatar-shape]")
           .all()) {
@@ -92,6 +160,10 @@ test("avatar shapes paint at every size and preserve pointer/keyboard profile co
         }
       }
     }
+    await page.getByRole("checkbox", { name: "Show pictures" }).uncheck();
+    await expect(insetAvatars.locator("img")).toHaveCount(0);
+    await expectInsetArtwork(false);
+    await page.getByRole("checkbox", { name: "Show pictures" }).check();
     const button = page.getByRole("button", { name: "View Agent profile" });
     await expect(button).toHaveCSS("background-color", "rgba(0, 0, 0, 0)");
     await button.hover();
diff --git a/tests/fixtures/avatar-shapes.tsx b/tests/fixtures/avatar-shapes.tsx
index 85bb9585..4604ec3e 100644
--- a/tests/fixtures/avatar-shapes.tsx
+++ b/tests/fixtures/avatar-shapes.tsx
@@ -12,9 +12,13 @@ import artwork from "./design-system/assets/avatar.png";
 
 const agent = "a".repeat(64),
   human = "b".repeat(64);
+// Flat color lets the paint test distinguish clipping from photo texture.
+const insetArtwork = `data:image/svg+xml,${encodeURIComponent(
+  '<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32"><path fill="#ff00ff" d="M0 0h32v32H0z"/></svg>',
+)}`;
 const profiles = new Map([
-  [agent, { name: "Agent", picture: artwork }],
-  [human, { name: "Human", picture: artwork }],
+  [agent, { name: "Agent", picture: insetArtwork }],
+  [human, { name: "Human", picture: insetArtwork }],
 ]);
 const agentPubkeys = new Set([agent]);
 const row: ChannelMessage = {
@@ -32,29 +36,34 @@ const row: ChannelMessage = {
 function Fixture() {
   useKeyboardFocusVisibility();
   const [opened, setOpened] = useState(false);
+  const [pictures, setPictures] = useState(true);
   return (
     <main style={{ padding: 24 }}>
       <button type="button">Before avatars</button>
       <section
         aria-label="System avatars"
-        style={{ display: "flex", gap: 16, marginBlock: 24 }}
+        style={{ display: "flex", flexWrap: "wrap", gap: 16, marginBlock: 24 }}
       >
-        {(["small", "default", "large"] as const).flatMap((size) =>
+        {(["small", "default", "large", "fill"] as const).flatMap((size) =>
           (["circle", "squircle"] as const).map((shape) => (
-            <Avatar
+            <div
               key={`${size}-${shape}`}
-              size={size}
-              shape={shape}
-              src={size === "small" ? undefined : artwork}
-              alt={`${size} ${shape}`}
-              fallback="Avatar"
-            />
+              style={size === "fill" ? { width: 128, height: 128 } : undefined}
+            >
+              <Avatar
+                size={size}
+                shape={shape}
+                src={size === "small" ? undefined : artwork}
+                alt={`${size} ${shape}`}
+                fallback="Avatar"
+              />
+            </div>
           )),
         )}
       </section>
       <section
         aria-label="Legacy avatars"
-        style={{ display: "flex", gap: 16, marginBlock: 24 }}
+        style={{ display: "flex", flexWrap: "wrap", gap: 16, marginBlock: 24 }}
       >
         <LegacyAvatar
           name="Human"
@@ -74,7 +83,7 @@ function Fixture() {
         profile={profiles.get(agent)}
         participantProfiles={profiles}
         agentPubkeys={agentPubkeys}
-        media={(url) => url}
+        media={(url) => (pictures ? url : undefined)}
         canOpenLink={() => true}
         onOpenLink={() => {
           setOpened(true);
@@ -84,16 +93,28 @@ function Fixture() {
         retry={undefined}
         onOpenThread={() => {}}
       />
-      <MembershipRow
-        row={{
-          ...row,
-          membership: { type: "member_joined", actor: agent, target: agent },
-        }}
-        profiles={profiles}
-        agentPubkeys={agentPubkeys}
-        media={(url) => url}
-        day={false}
-      />
+      {[agent, human].map((target) => (
+        <MembershipRow
+          key={target}
+          row={{
+            ...row,
+            id: `membership-${target}`,
+            membership: { type: "member_joined", actor: agent, target },
+          }}
+          profiles={profiles}
+          agentPubkeys={agentPubkeys}
+          media={(url) => (pictures ? url : undefined)}
+          day={false}
+        />
+      ))}
+      <label>
+        <input
+          type="checkbox"
+          checked={pictures}
+          onChange={(event) => setPictures(event.currentTarget.checked)}
+        />
+        Show pictures
+      </label>
       {opened && <p role="status">Profile opened</p>}
     </main>
   );
diff --git a/tests/fixtures/profiles.tsx b/tests/fixtures/profiles.tsx
index 758cae7b..747a21ce 100644
--- a/tests/fixtures/profiles.tsx
+++ b/tests/fixtures/profiles.tsx
@@ -50,7 +50,12 @@ let failMissing = true;
 const data = [
   profile(viewer, { name: "Viewer", about: "Human profile", picture }),
   profile(mic, { name: "Mic", about: "Mic biography" }),
-  profile(pinky, { name: "Pinky", about: "Agent profile", is_agent: true }),
+  profile(pinky, {
+    name: "Pinky",
+    about: "Agent profile",
+    is_agent: true,
+    picture,
+  }),
 ];
 function session() {
   return createRelaySession({

From d41c87c5bb383be92e0037da4b322a0c5bfed032 Mon Sep 17 00:00:00 2001
From: Carl
 <acda9e433d19dcd0e6b6840f7f4b98f3a56f1fab98049d444c087019e6d36560@buzz.block.builderlab.xyz>
Date: Tue, 15 Sep 2026 09:25:05 -1000
Subject: [PATCH 7/7] test(avatars): preserve paint checks across shared
 foundations

Map fractional screenshot bounds to artwork coordinates and render the fixture on the actual panel surface. Keep the library-refresh assertion against the contenteditable composer. Both browser engines reject an unmasked inset with the corrected sampler.

Signed-off-by: Carl <acda9e433d19dcd0e6b6840f7f4b98f3a56f1fab98049d444c087019e6d36560@buzz.block.builderlab.xyz>
---
 tests/browser/avatar-shapes.spec.mjs | 32 ++++++++++++++++++++++------
 tests/browser/typeahead.spec.mjs     |  2 +-
 tests/fixtures/avatar-shapes.tsx     |  4 +++-
 3 files changed, 29 insertions(+), 9 deletions(-)

diff --git a/tests/browser/avatar-shapes.spec.mjs b/tests/browser/avatar-shapes.spec.mjs
index e594ce56..b6e767f8 100644
--- a/tests/browser/avatar-shapes.spec.mjs
+++ b/tests/browser/avatar-shapes.spec.mjs
@@ -5,10 +5,19 @@ import { fileURLToPath } from "node:url";
 
 // Sample actual browser paint, not just shape attributes or bounding boxes.
 async function pixels(page, locator, inset = 0) {
+  await locator.scrollIntoViewIfNeeded();
   const bounds = await locator.boundingBox();
-  const png = await locator.screenshot();
+  // Browser crops round outward to device pixels. Keep the fractional artwork
+  // origin rather than treating that rounded image as the avatar's own bounds.
+  const clip = {
+    x: Math.floor(bounds.x),
+    y: Math.floor(bounds.y),
+    width: Math.ceil(bounds.x + bounds.width) - Math.floor(bounds.x),
+    height: Math.ceil(bounds.y + bounds.height) - Math.floor(bounds.y),
+  };
+  const png = await page.screenshot({ clip, scale: "css" });
   return page.evaluate(
-    async ({ base64, inset, width }) => {
+    async ({ base64, inset, bounds, clip }) => {
       const image = new Image();
       image.src = `data:image/png;base64,${base64}`;
       await image.decode();
@@ -17,18 +26,27 @@ async function pixels(page, locator, inset = 0) {
       canvas.height = image.height;
       const context = canvas.getContext("2d");
       context.drawImage(image, 0, 0);
-      const padding = inset * (image.width / width);
       const at = (fraction) => [
         ...context.getImageData(
-          Math.floor(padding + (image.width - 2 * padding) * fraction),
-          Math.floor(padding + (image.height - 2 * padding) * fraction),
+          Math.floor(
+            bounds.x - clip.x + inset + (bounds.width - 2 * inset) * fraction,
+          ),
+          Math.floor(
+            bounds.y - clip.y + inset + (bounds.height - 2 * inset) * fraction,
+          ),
           1,
           1,
         ).data,
       ];
-      return { corner: at(0), shoulder: at(0.1), center: at(0.5) };
+      // One pixel inside the inset exposes a missing inner clip; its exact
+      // outermost corner can still be clipped by the parent's mask alone.
+      return {
+        corner: at(inset ? 0.05 : 0),
+        shoulder: at(0.1),
+        center: at(0.5),
+      };
     },
-    { base64: png.toString("base64"), inset, width: bounds.width },
+    { base64: png.toString("base64"), inset, bounds, clip },
   );
 }
 
diff --git a/tests/browser/typeahead.spec.mjs b/tests/browser/typeahead.spec.mjs
index 1c1770e2..b831e8c8 100644
--- a/tests/browser/typeahead.spec.mjs
+++ b/tests/browser/typeahead.spec.mjs
@@ -75,7 +75,7 @@ test("open completion republishes library-only display hints without changing th
     );
     await expectAvatarShape(first, included ? "squircle" : "circle");
     await expectAvatarShape(second, "squircle");
-    await expect(input).toHaveValue("@Ho");
+    await expect(input).toHaveText("@Ho");
     await expect(input).toBeFocused();
     await expect(page.getByRole("listbox")).toBeVisible();
     expect(
diff --git a/tests/fixtures/avatar-shapes.tsx b/tests/fixtures/avatar-shapes.tsx
index 4604ec3e..9e68ec49 100644
--- a/tests/fixtures/avatar-shapes.tsx
+++ b/tests/fixtures/avatar-shapes.tsx
@@ -38,7 +38,9 @@ function Fixture() {
   const [opened, setOpened] = useState(false);
   const [pictures, setPictures] = useState(true);
   return (
-    <main style={{ padding: 24 }}>
+    // Match the message panel's opaque surface so clipped pixels have the same
+    // backdrop as the overlap border in either theme, not the document canvas.
+    <main style={{ padding: 24, background: "var(--surface)" }}>
       <button type="button">Before avatars</button>
       <section
         aria-label="System avatars"