From 374f1f7083bb5f73ae71d6aed8adf41ead70aef7 Mon Sep 17 00:00:00 2001
From: QuanCheng <915158214@qq.com>
Date: Tue, 11 Aug 2026 04:40:47 +0000
Subject: [PATCH] feat(workspace) user avatars
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Users can upload an avatar from workspace settings. It follows them into
every workspace they're a member of, and shows up in the team roster, chat
messages and the account menu.

Storage reuses the existing FileStore, so the bytes land wherever files
already do — S3 in production, disk locally — with no new component. The
database holds only the key; deliberately no FileRecord row, since those are
listed per-workspace on the Files page and an avatar is neither
workspace-scoped nor something a user should be able to delete from there.

Two decisions worth calling out.

The read URL carries no credential. An <img> tag can't send an Authorization
header, and the obvious move — copying the `?token=` scheme from file
downloads — would have leaked the workspace token, which bypasses role checks
and is deliberately withheld from viewers. Instead the URL is the capability,
a random 128-bit blob id that only appears in authenticated responses. Team
rosters hand it out only to callers with a verified identity, since an open
workspace's roster is anonymously readable.

Deletion goes through a transactional outbox rather than a best-effort call
after the commit. One S3 timeout would otherwise leave an avatar the user
asked us to remove readable forever, with nothing recording that it should be
gone. The pointer swap and the deletion record commit together; a drainer on
the existing maintenance cycle empties the table with backoff.

Uploads are re-encoded to a 512x512 WebP. That's the security boundary rather
than a resize — it kills SVG/polyglot stored XSS, strips the GPS coordinates
phone photos carry, and bounds decompression bombs. EXIF orientation is
applied before the crop, or portrait photos land sideways.

Adds migrations 030/031 and Pillow. Does NOT fix the pre-existing gap where
DELETE /v1/account leaves the User and WorkspaceMembership rows behind —
that needs a decision about workspaces the user owns, tracked separately.
---
 .../alembic/versions/030_add_user_avatar.py   |  50 +++
 .../versions/031_add_blob_deletions.py        |  58 +++
 workspace/backend/app/avatar.py               | 202 +++++++++
 workspace/backend/app/blob_gc.py              | 152 +++++++
 workspace/backend/app/config.py               |  18 +
 workspace/backend/app/main.py                 |  13 +-
 workspace/backend/app/models.py               |  27 ++
 workspace/backend/app/routers/account.py      |  57 ++-
 workspace/backend/app/routers/avatars.py      | 196 +++++++++
 workspace/backend/app/routers/workspaces.py   |  32 +-
 workspace/backend/requirements.txt            |   3 +
 workspace/backend/tests/test_avatars.py       | 407 ++++++++++++++++++
 workspace/frontend/app/[workspaceId]/page.tsx |  17 +-
 .../frontend/components/chat/chat-message.tsx |  30 +-
 .../components/layout/settings-dialog.tsx     |   5 +
 .../frontend/components/layout/user-menu.tsx  |  13 +-
 .../components/settings/avatar-section.tsx    | 126 ++++++
 .../components/settings/team-section.tsx      |   6 +
 workspace/frontend/lib/account-api.ts         |  47 ++
 workspace/frontend/lib/avatars.tsx            | 102 +++++
 workspace/frontend/lib/types.ts               |  15 +
 21 files changed, 1555 insertions(+), 21 deletions(-)
 create mode 100644 workspace/backend/alembic/versions/030_add_user_avatar.py
 create mode 100644 workspace/backend/alembic/versions/031_add_blob_deletions.py
 create mode 100644 workspace/backend/app/avatar.py
 create mode 100644 workspace/backend/app/blob_gc.py
 create mode 100644 workspace/backend/app/routers/avatars.py
 create mode 100644 workspace/backend/tests/test_avatars.py
 create mode 100644 workspace/frontend/components/settings/avatar-section.tsx
 create mode 100644 workspace/frontend/lib/avatars.tsx

diff --git a/workspace/backend/alembic/versions/030_add_user_avatar.py b/workspace/backend/alembic/versions/030_add_user_avatar.py
new file mode 100644
index 000000000..036490614
--- /dev/null
+++ b/workspace/backend/alembic/versions/030_add_user_avatar.py
@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+"""Add avatar columns to users.
+
+The bytes live in the existing `FileStore` under `avatars/{user_id}/{blob_id}.webp`
+— `avatar_key` holds that storage key and nothing else. Deliberately NOT a
+`FileRecord` row: the Files page lists FileRecords by workspace, and an avatar
+belongs to a user across every workspace they're in, so it must not show up
+there (nor be deletable from it).
+
+`avatar_updated_at` is display/diagnostics only. Cache-busting rides on the
+random `blob_id` inside the key, so the URL changes on its own every upload.
+
+Revision ID: 030
+Revises: 029
+Create Date: 2026-08-11
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "030"
+down_revision = "029"
+branch_labels = None
+depends_on = None
+
+
+def _columns(inspector, table) -> set:
+    return {c["name"] for c in inspector.get_columns(table)}
+
+
+def upgrade() -> None:
+    bind = op.get_bind()
+    inspector = sa.inspect(bind)
+    existing = _columns(inspector, "users")
+
+    if "avatar_key" not in existing:
+        op.add_column("users", sa.Column("avatar_key", sa.Text(), nullable=True))
+    if "avatar_updated_at" not in existing:
+        op.add_column("users", sa.Column("avatar_updated_at", sa.DateTime(timezone=True), nullable=True))
+
+
+def downgrade() -> None:
+    bind = op.get_bind()
+    inspector = sa.inspect(bind)
+    existing = _columns(inspector, "users")
+
+    if "avatar_updated_at" in existing:
+        op.drop_column("users", "avatar_updated_at")
+    if "avatar_key" in existing:
+        op.drop_column("users", "avatar_key")
diff --git a/workspace/backend/alembic/versions/031_add_blob_deletions.py b/workspace/backend/alembic/versions/031_add_blob_deletions.py
new file mode 100644
index 000000000..f0e366e8c
--- /dev/null
+++ b/workspace/backend/alembic/versions/031_add_blob_deletions.py
@@ -0,0 +1,58 @@
+# -*- coding: utf-8 -*-
+"""Add blob_deletions — a transactional outbox for FileStore deletions.
+
+Deleting a blob is a side effect on a remote system (S3), so it can't join the
+transaction that stops pointing at it. Doing it best-effort right after the
+commit means one S3 timeout leaves an avatar the user asked us to remove
+readable forever, with nothing in the system that knows about it.
+
+Instead the row that stops pointing at a key and the row that says "delete this
+key" commit together. A drainer then empties the table, retrying with backoff.
+Deletion becomes a durable to-do rather than a fire-and-forget side effect.
+
+Named `blob_deletions`, not `avatar_deletions`: nothing here is avatar-specific,
+and any other FileStore blob needing reliable deletion can enqueue into it.
+
+Revision ID: 031
+Revises: 030
+Create Date: 2026-08-11
+"""
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects.postgresql import UUID
+
+revision = "031"
+down_revision = "030"
+branch_labels = None
+depends_on = None
+
+
+def _has_table(inspector, table) -> bool:
+    return table in inspector.get_table_names()
+
+
+def upgrade() -> None:
+    bind = op.get_bind()
+    inspector = sa.inspect(bind)
+
+    if not _has_table(inspector, "blob_deletions"):
+        op.create_table(
+            "blob_deletions",
+            sa.Column("id", UUID(as_uuid=False), primary_key=True),
+            sa.Column("storage_key", sa.Text(), nullable=False),
+            sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()")),
+            sa.Column("attempts", sa.Integer(), nullable=False, server_default="0"),
+            sa.Column("next_retry_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()")),
+            sa.Column("last_error", sa.Text(), nullable=True),
+        )
+        # The drainer's only query is "rows due now, oldest first".
+        op.create_index("idx_blob_deletions_due", "blob_deletions", ["next_retry_at"])
+
+
+def downgrade() -> None:
+    bind = op.get_bind()
+    inspector = sa.inspect(bind)
+    if _has_table(inspector, "blob_deletions"):
+        op.drop_index("idx_blob_deletions_due", table_name="blob_deletions")
+        op.drop_table("blob_deletions")
diff --git a/workspace/backend/app/avatar.py b/workspace/backend/app/avatar.py
new file mode 100644
index 000000000..922208b1c
--- /dev/null
+++ b/workspace/backend/app/avatar.py
@@ -0,0 +1,202 @@
+# -*- coding: utf-8 -*-
+"""
+Avatar image validation and transcoding.
+
+Every uploaded image is decoded and re-encoded to a fixed-size WebP. That
+re-encode is the security boundary, not an optimization — whatever arrives,
+what we store is a buffer Pillow produced:
+
+* **Stored XSS** — SVG (and HTML/SVG polyglots) can carry <script>. Nothing
+  that isn't a raster image Pillow recognizes survives the round trip, and the
+  content type we serve is always image/webp.
+* **Location leak** — phone photos routinely carry GPS coordinates in EXIF.
+  Re-encoding drops every EXIF tag.
+* **Decompression bomb** — a few KB of PNG can expand to gigabytes of pixels,
+  so the pixel count is checked before any pixel work happens.
+
+All decode work runs in a thread (see `process_avatar`) under a semaphore, so a
+burst of uploads can't monopolize the event loop or the worker's memory.
+"""
+
+import asyncio
+import io
+import logging
+import secrets
+from typing import Optional
+
+from app.config import config
+
+logger = logging.getLogger(__name__)
+
+# Magic-byte prefixes for the formats we accept. The declared Content-Type is
+# never trusted: it's attacker-controlled, and "image/png" on an SVG body is
+# exactly how a polyglot gets in.
+_MAGIC = (
+    (b"\xff\xd8\xff", "jpeg"),
+    (b"\x89PNG\r\n\x1a\n", "png"),
+    (b"GIF87a", "gif"),
+    (b"GIF89a", "gif"),
+)
+
+_STORAGE_PREFIX = "avatars"
+
+# One semaphore per process; see AVATAR_DECODE_CONCURRENCY in config.
+_decode_semaphore: Optional[asyncio.Semaphore] = None
+
+
+class AvatarError(Exception):
+    """Rejected upload. The message is safe to return to the caller.
+
+    `status` lets the router map size rejections to 413 while everything else
+    stays a 400 — none of these may surface as a 500.
+    """
+
+    def __init__(self, message: str, status: int = 400):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+
+
+def _sniff(data: bytes) -> Optional[str]:
+    """Identify the image type from its leading bytes, or None if unknown."""
+    for prefix, name in _MAGIC:
+        if data.startswith(prefix):
+            return name
+    # WebP is RIFF-framed: "RIFF" <4-byte size> "WEBP".
+    if len(data) >= 12 and data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return "webp"
+    return None
+
+
+def storage_key(user_id: str, blob_id: str) -> str:
+    """The FileStore key for an avatar blob.
+
+    Mirrors what LocalFileStore/S3FileStore build from
+    `save(workspace_id, file_id, filename)` — kept in one place so the read path
+    and the write path can't drift apart.
+    """
+    return f"{_STORAGE_PREFIX}/{user_id}/{blob_id}.webp"
+
+
+def new_blob_id() -> str:
+    """A fresh 128-bit blob id.
+
+    Random rather than a content hash, for two reasons. It makes concurrent
+    uploads by the same user impossible to collide, so neither can delete the
+    key the other just committed. And it makes the URL itself the capability —
+    an avatar URL carries no reusable credential, unlike the `?token=` scheme
+    the file download endpoint uses (that token bypasses role checks and is
+    deliberately withheld from viewers).
+    """
+    return secrets.token_hex(16)
+
+
+def _transcode(data: bytes) -> bytes:
+    """Decode, normalize and re-encode. Synchronous — call via a thread."""
+    # Imported lazily so the module imports cleanly without Pillow installed;
+    # only the avatar path needs it.
+    from PIL import Image, ImageOps, UnidentifiedImageError
+
+    size = config.AVATAR_SIZE
+
+    try:
+        img = Image.open(io.BytesIO(data))
+    except UnidentifiedImageError:
+        raise AvatarError("Unrecognized image format")
+    except Exception:
+        raise AvatarError("Could not read the image")
+
+    try:
+        # Bomb check first: img.size is read from the header, before Pillow has
+        # allocated anything for the pixels.
+        width, height = img.size
+        if width <= 0 or height <= 0:
+            raise AvatarError("Image has no content")
+        if width * height > config.AVATAR_MAX_PIXELS:
+            raise AvatarError("Image dimensions are too large")
+
+        # Animated GIF / WebP: take the first frame and drop the rest.
+        try:
+            img.seek(0)
+        except (AttributeError, EOFError):
+            pass
+
+        # Bake EXIF orientation into the pixels. This has to happen BEFORE the
+        # crop: a phone's portrait photo is stored landscape with an orientation
+        # tag, and re-encoding drops that tag. Crop first and the avatar ends up
+        # rotated 90°, cropped along the wrong axis.
+        img = ImageOps.exif_transpose(img)
+
+        # Normalize CMYK / palette / grayscale / LA into something WebP encodes
+        # predictably, keeping alpha for images that have it.
+        if img.mode not in ("RGB", "RGBA"):
+            img = img.convert("RGBA" if img.mode in ("P", "LA", "PA") else "RGB")
+
+        # Center-crop to a square, then scale. ImageOps.fit does both and picks
+        # a decent resampling filter.
+        img = ImageOps.fit(img, (size, size), method=Image.Resampling.LANCZOS, centering=(0.5, 0.5))
+
+        out = io.BytesIO()
+        img.save(out, format="WEBP", quality=85, method=4)
+        return out.getvalue()
+    except AvatarError:
+        raise
+    except Image.DecompressionBombError:
+        raise AvatarError("Image dimensions are too large")
+    except OSError:
+        # Truncated or corrupt payloads land here during the decode.
+        raise AvatarError("The image file is damaged or incomplete")
+    except Exception:
+        logger.exception("avatar: unexpected failure while transcoding")
+        raise AvatarError("Could not process the image")
+    finally:
+        try:
+            img.close()
+        except Exception:
+            pass
+
+
+async def process_avatar(data: bytes) -> bytes:
+    """Validate `data` and return the WebP bytes to store.
+
+    Raises `AvatarError` for anything the caller sent wrong — a rejected upload
+    is never a 500.
+    """
+    global _decode_semaphore
+
+    if not data:
+        raise AvatarError("The uploaded file is empty")
+
+    kind = _sniff(data)
+    if kind is None:
+        # Covers SVG, HTML, PDFs, and anything else dressed up as an image.
+        raise AvatarError("Unsupported image type. Use JPEG, PNG, GIF or WebP.")
+
+    if _decode_semaphore is None:
+        _decode_semaphore = asyncio.Semaphore(max(1, config.AVATAR_DECODE_CONCURRENCY))
+
+    async with _decode_semaphore:
+        return await asyncio.to_thread(_transcode, data)
+
+
+async def read_upload_limited(upload, limit: int) -> bytes:
+    """Read an UploadFile, aborting as soon as it exceeds `limit` bytes.
+
+    Reads in chunks rather than `await upload.read()` so an oversized upload is
+    rejected without first materializing all of it in memory — the check is the
+    point, and doing it after the read defeats it.
+    """
+    chunks: list[bytes] = []
+    total = 0
+    while True:
+        chunk = await upload.read(64 * 1024)
+        if not chunk:
+            break
+        total += len(chunk)
+        if total > limit:
+            raise AvatarError(
+                f"Image is too large. Maximum size: {limit // (1024 * 1024)}MB",
+                status=413,
+            )
+        chunks.append(chunk)
+    return b"".join(chunks)
diff --git a/workspace/backend/app/blob_gc.py b/workspace/backend/app/blob_gc.py
new file mode 100644
index 000000000..d57eeaa84
--- /dev/null
+++ b/workspace/backend/app/blob_gc.py
@@ -0,0 +1,152 @@
+# -*- coding: utf-8 -*-
+"""
+Reliable FileStore blob deletion, via a transactional outbox.
+
+Deleting from S3 is a side effect on a remote system, so it can't be part of the
+transaction that stops pointing at the key. Doing it best-effort right after the
+commit gives you this: one S3 timeout, and a blob the user asked us to remove
+stays readable forever with nothing in the system recording that it shouldn't.
+
+So callers don't delete. They `enqueue_deletion()` inside the same transaction
+that clears the pointer, and both commit together — after which the deletion is
+durable regardless of what the process or S3 does next. `try_delete_now()` takes
+the common fast path right after the commit, and anything it doesn't manage is
+picked up by `drain_blob_deletions()` on the maintenance cycle.
+
+The pleasant side effect is that this doubles as the orphan sweep for superseded
+keys: every replaced key is already a row here, so nothing has to go scanning
+storage to find them.
+"""
+
+import logging
+from datetime import datetime, timedelta, timezone
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app.models import BlobDeletion
+from app.storage import get_file_store
+
+logger = logging.getLogger(__name__)
+
+# Give up retrying (but keep the row, loudly) after this many failures. At the
+# backoff below that's roughly a day of trying.
+MAX_ATTEMPTS = 12
+# Rows claimed per drain pass. Keeps the maintenance cycle short and bounded.
+DRAIN_BATCH = 50
+
+
+def enqueue_deletion(db: Session, storage_key: str | None) -> None:
+    """Record that `storage_key` should be deleted.
+
+    Does NOT commit — that's the whole point. The caller commits this together
+    with whatever change stopped referencing the key, so the two can't diverge.
+    A None/empty key is a no-op, which lets callers pass an old pointer without
+    checking whether there was one.
+    """
+    if not storage_key:
+        return
+    db.add(BlobDeletion(storage_key=storage_key))
+
+
+def try_delete_now(db: Session, storage_key: str | None) -> bool:
+    """Best-effort immediate delete of an already-enqueued key.
+
+    Call this *after* the enqueueing transaction has committed. On success the
+    outbox row is cleared and this returns True; on failure the row stays put
+    for the drainer and this returns False. Either way it does not raise —
+    the user's avatar has already changed, and failing their request over a
+    cleanup step would be the wrong trade.
+    """
+    if not storage_key:
+        return False
+    try:
+        get_file_store().delete(storage_key)
+    except Exception as exc:
+        logger.warning("blob_gc: immediate delete failed for %s (%s); leaving for drainer", storage_key, exc)
+        return False
+
+    try:
+        db.query(BlobDeletion).filter(BlobDeletion.storage_key == storage_key).delete(synchronize_session=False)
+        db.commit()
+    except Exception:
+        db.rollback()
+        # The bytes are gone; a stale row just makes the drainer do one
+        # idempotent no-op delete later.
+        logger.warning("blob_gc: could not clear outbox row for %s", storage_key)
+    return True
+
+
+def _claim(db: Session, now: datetime) -> list[BlobDeletion]:
+    """Claim a batch of due rows.
+
+    Every uvicorn worker runs its own maintenance loop, so several drainers hit
+    this table at once. SKIP LOCKED hands each of them a disjoint set instead of
+    having them queue behind each other. Duplicate work would be harmless —
+    FileStore.delete is idempotent — but pointless S3 calls aren't free.
+
+    SQLite (tests) has no row locking; there's also only ever one drainer there.
+    """
+    stmt = (
+        select(BlobDeletion)
+        .where(BlobDeletion.next_retry_at <= now)
+        .order_by(BlobDeletion.next_retry_at)
+        .limit(DRAIN_BATCH)
+    )
+    bind = db.get_bind()
+    if bind is not None and bind.dialect.name == "postgresql":
+        stmt = stmt.with_for_update(skip_locked=True)
+    return list(db.execute(stmt).scalars().all())
+
+
+def drain_blob_deletions(db: Session | None = None) -> int:
+    """Delete the blobs recorded in the outbox. Returns the number removed.
+
+    Synchronous and short-lived by design — it runs from the maintenance cycle
+    via `asyncio.to_thread`, alongside the other periodic table sweeps. Pass
+    `db` to drive it from a caller that already has a session (tests).
+    """
+    from app.database import SessionLocal
+
+    owns_session = db is None
+    if db is None:
+        db = SessionLocal()
+    deleted = 0
+    try:
+        now = datetime.now(timezone.utc)
+        rows = _claim(db, now)
+        if not rows:
+            return 0
+
+        store = get_file_store()
+        for row in rows:
+            try:
+                store.delete(row.storage_key)
+            except Exception as exc:
+                row.attempts = (row.attempts or 0) + 1
+                row.last_error = str(exc)[:500]
+                # Exponential backoff, capped at an hour.
+                delay = min(3600, 30 * (2 ** min(row.attempts, 7)))
+                row.next_retry_at = now + timedelta(seconds=delay)
+                if row.attempts >= MAX_ATTEMPTS:
+                    # Keep the row rather than dropping it: a blob we failed to
+                    # delete is exactly the thing someone needs to know about.
+                    logger.error(
+                        "blob_gc: giving up on %s after %s attempts (%s)",
+                        row.storage_key, row.attempts, row.last_error,
+                    )
+                continue
+            db.delete(row)
+            deleted += 1
+
+        db.commit()
+        if deleted:
+            logger.info("blob_gc: deleted %s blob(s)", deleted)
+        return deleted
+    except Exception:
+        db.rollback()
+        logger.exception("blob_gc: drain failed")
+        return deleted
+    finally:
+        if owns_session:
+            db.close()
diff --git a/workspace/backend/app/config.py b/workspace/backend/app/config.py
index 0540810f7..c3efa9e12 100644
--- a/workspace/backend/app/config.py
+++ b/workspace/backend/app/config.py
@@ -65,6 +65,24 @@ class Config:
     S3_REGION: str = os.environ.get("S3_REGION", "us-east-1")
     MAX_FILE_SIZE: int = int(os.environ.get("MAX_FILE_SIZE", str(50 * 1024 * 1024)))  # 50MB
 
+    # User avatars. Separate limits from MAX_FILE_SIZE on purpose — a 50MB
+    # avatar upload is never legitimate, and every accepted byte here gets
+    # decoded into a pixel buffer.
+    AVATAR_MAX_UPLOAD_SIZE: int = int(os.environ.get("AVATAR_MAX_UPLOAD_SIZE", str(5 * 1024 * 1024)))  # 5MB
+    # Decompression-bomb ceiling: a few KB of PNG can expand to gigabytes of
+    # pixels, so this is checked against img.size before any pixel work.
+    AVATAR_MAX_PIXELS: int = int(os.environ.get("AVATAR_MAX_PIXELS", str(25_000_000)))
+    # Decoding is CPU- and memory-heavy, so it runs under a semaphore. NOTE:
+    # that semaphore is PER PROCESS — with N uvicorn workers the real ceiling is
+    # N x this. Worst-case memory is roughly N x this x (AVATAR_MAX_PIXELS x 4B).
+    # Tune against the actual ECS task memory rather than trusting the default.
+    AVATAR_DECODE_CONCURRENCY: int = int(os.environ.get("AVATAR_DECODE_CONCURRENCY", "4"))
+    AVATAR_SIZE: int = int(os.environ.get("AVATAR_SIZE", "512"))          # output edge, px
+    # Browser cache lifetime. This is the revocation window: once a viewer has
+    # the bytes, removing the avatar can't reach their cache until this expires.
+    # Deliberately NOT `immutable` + 1 year — that would mean "never revocable".
+    AVATAR_CACHE_MAX_AGE: int = int(os.environ.get("AVATAR_CACHE_MAX_AGE", str(24 * 60 * 60)))  # 24h
+
     # LLM Router — uses a small model to decide agent turn-taking in multi-agent threads
     # Provider: "anthropic" (default) or "openai" (any OpenAI-compatible endpoint)
     ROUTER_LLM_ENABLED: bool = os.environ.get("ROUTER_LLM_ENABLED", "true").lower() in ("true", "1", "yes")
diff --git a/workspace/backend/app/main.py b/workspace/backend/app/main.py
index f2e1e30f5..b987442d0 100644
--- a/workspace/backend/app/main.py
+++ b/workspace/backend/app/main.py
@@ -17,7 +17,7 @@
 from starlette.middleware.base import BaseHTTPMiddleware
 
 from app.config import config
-from app.routers import account, browser, cloud_agents, devices, events, fetch, files, knowledge, network, notifications, routines, search, shares, tasks, timers, todos, workspaces
+from app.routers import account, avatars, browser, cloud_agents, devices, events, fetch, files, knowledge, network, notifications, routines, search, shares, tasks, timers, todos, workspaces
 
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
@@ -46,6 +46,7 @@ def _run_maintenance():
     """
     from datetime import timedelta
     from sqlalchemy import update
+    from app.blob_gc import drain_blob_deletions
     from app.database import SessionLocal
     from app.models import Channel, NotificationRecord, TodoRecord
 
@@ -102,6 +103,15 @@ def _run_maintenance():
     finally:
         db.close()
 
+    # Empty the blob-deletion outbox. Same shape of work as the sweeps above —
+    # short-lived session, off the event loop — so it rides the same cycle
+    # rather than needing a loop of its own. It opens its own session because
+    # the one above is already closed.
+    try:
+        drain_blob_deletions()
+    except Exception:
+        logger.exception("Blob deletion drain failed")
+
 
 async def _fire_due():
     """Fire due timers and routines.
@@ -497,6 +507,7 @@ async def _log_validation_errors(request: Request, exc: RequestValidationError):
 
 # Routers
 app.include_router(account.router)
+app.include_router(avatars.router)
 app.include_router(browser.router)
 app.include_router(cloud_agents.router)
 app.include_router(devices.router)
diff --git a/workspace/backend/app/models.py b/workspace/backend/app/models.py
index 689dedd88..859e3afab 100644
--- a/workspace/backend/app/models.py
+++ b/workspace/backend/app/models.py
@@ -267,6 +267,10 @@ class User(Base):
     firebase_uid = Column(Text, nullable=True)           # Google/Firebase `uid` claim
     apple_sub = Column(Text, nullable=True)              # Sign in with Apple `sub` claim
     display_name = Column(Text, nullable=True)
+    # FileStore key of the user's avatar blob ("avatars/{user_id}/{blob_id}.webp"),
+    # or NULL for none. Deliberately not a FileRecord — see migration 030.
+    avatar_key = Column(Text, nullable=True)
+    avatar_updated_at = Column(DateTime(timezone=True), nullable=True)
     created_at = Column(DateTime(timezone=True), default=_now, server_default=text("NOW()"))
     last_login_at = Column(DateTime(timezone=True), nullable=True)
 
@@ -699,3 +703,26 @@ class Agent(Base):
     display_name = Column(Text, nullable=True)
     agent_type = Column(Text, nullable=True)         # "claude", "codex", "gemini", etc.
     created_at = Column(DateTime(timezone=True), default=_now, server_default=text("NOW()"))
+
+
+class BlobDeletion(Base):
+    """A FileStore key that should be deleted, recorded transactionally.
+
+    Deleting from S3 can't join the transaction that stops pointing at a key, so
+    doing it best-effort after the commit means one timeout leaves a blob the
+    user asked us to remove readable forever, with nothing recording that it
+    should be gone. Instead the pointer change and this row commit together, and
+    `app.blob_gc` drains the table with backoff. See migration 031.
+    """
+    __tablename__ = "blob_deletions"
+
+    id = Column(UUID(as_uuid=False), primary_key=True, default=_uuid)
+    storage_key = Column(Text, nullable=False)
+    created_at = Column(DateTime(timezone=True), default=_now, server_default=text("NOW()"))
+    attempts = Column(Integer, nullable=False, default=0, server_default=text("0"))
+    next_retry_at = Column(DateTime(timezone=True), default=_now, server_default=text("NOW()"))
+    last_error = Column(Text, nullable=True)
+
+    __table_args__ = (
+        Index("idx_blob_deletions_due", "next_retry_at"),
+    )
diff --git a/workspace/backend/app/routers/account.py b/workspace/backend/app/routers/account.py
index 06f2003bd..bf2cbe6e4 100644
--- a/workspace/backend/app/routers/account.py
+++ b/workspace/backend/app/routers/account.py
@@ -26,16 +26,19 @@
 from sqlalchemy.orm import Session
 
 from app.access import provision_workspace, reconcile_memberships, resolve_current_user
+from app.blob_gc import enqueue_deletion, try_delete_now
 from app.database import get_db
 from app.firebase_auth import verify_identity_token
 from app.models import (
     ChannelHumanMember,
     DeviceToken,
+    User,
     Workspace,
     WorkspaceCollaborator,
     WorkspaceMembership,
 )
 from app.response import ResponseCode, json_response, success_response
+from app.routers.avatars import avatar_url
 from app.routers.network import _extract_bearer
 
 logger = logging.getLogger(__name__)
@@ -53,6 +56,35 @@ def _authed_email(authorization: Optional[str]) -> Optional[str]:
     return email.strip().lower() if email else None
 
 
+@router.get("/account/profile")
+def get_account_profile(
+    db: Session = Depends(get_db),
+    authorization: Optional[str] = Header(None),
+):
+    """The signed-in user's own profile — id, email, display name, avatar.
+
+    Deliberately its own endpoint rather than a field added to
+    `/v1/account/workspaces`: that response's `data` is a bare array, and the
+    Swift client decodes it as `[AccountWorkspace]` while the Go and web clients
+    index it directly. Wrapping it to make room for the caller's identity would
+    break all three.
+
+    `userId` matters because it's the only stable handle on a user — the web
+    client currently uses the email as an identity, and avatar URLs are keyed by
+    the database UUID.
+    """
+    user = resolve_current_user(db, authorization)
+    if not user:
+        return json_response(ResponseCode.UNAUTHORIZED, "Invalid identity token")
+
+    return success_response({
+        "userId": str(user.id),
+        "email": user.email,
+        "displayName": user.display_name,
+        "avatarUrl": avatar_url(str(user.id), user.avatar_key),
+    })
+
+
 @router.get("/account/workspaces")
 def list_account_workspaces(
     db: Session = Depends(get_db),
@@ -139,6 +171,24 @@ def delete_account(
 
     email_lower = email.strip().lower()
 
+    # Avatar bytes. Cleared and enqueued inside the same transaction as the rest
+    # of the purge, so "the user asked us to delete this" survives an S3 outage
+    # instead of evaporating into a log line — the blob is a photo of them.
+    #
+    # NOTE: this endpoint still does not delete the `User` row or its
+    # `WorkspaceMembership` rows, so the identity (email, display name, provider
+    # subject) outlives the "delete my account" it promises. That predates
+    # avatars and isn't fixed here — fixing it needs a decision about what
+    # happens to workspaces the user owns. Tracked separately.
+    user = db.execute(
+        select(User).where(User.email == email_lower)
+    ).scalar_one_or_none()
+    avatar_key = user.avatar_key if user else None
+    if user and avatar_key:
+        user.avatar_key = None
+        user.avatar_updated_at = None
+        enqueue_deletion(db, avatar_key)
+
     collaborators_deleted = db.query(WorkspaceCollaborator).filter(
         WorkspaceCollaborator.email == email_lower
     ).delete(synchronize_session=False)
@@ -153,9 +203,13 @@ def delete_account(
 
     db.commit()
 
+    # The deletion intent is durable now; this is just the fast path.
+    try_delete_now(db, avatar_key)
+
     logger.info(
-        "account: deleted account for %s (collaborators=%s channel_members=%s devices=%s)",
+        "account: deleted account for %s (collaborators=%s channel_members=%s devices=%s avatar=%s)",
         email_lower, collaborators_deleted, channel_memberships_deleted, devices_deleted,
+        bool(avatar_key),
     )
 
     return success_response({
@@ -164,5 +218,6 @@ def delete_account(
             "collaborators": collaborators_deleted,
             "channel_memberships": channel_memberships_deleted,
             "devices": devices_deleted,
+            "avatar": 1 if avatar_key else 0,
         },
     })
diff --git a/workspace/backend/app/routers/avatars.py b/workspace/backend/app/routers/avatars.py
new file mode 100644
index 000000000..7839bd218
--- /dev/null
+++ b/workspace/backend/app/routers/avatars.py
@@ -0,0 +1,196 @@
+# -*- coding: utf-8 -*-
+"""
+User avatar endpoints.
+
+POST   /v1/account/avatar                       Upload (identity bearer)
+DELETE /v1/account/avatar                       Remove (identity bearer)
+GET    /v1/avatars/{user_id}/{blob_id}.webp     Read (no auth — see below)
+
+**Why the read path takes no credential.** An <img> tag can't send an
+Authorization header, so the bytes have to be reachable from a plain URL. The
+file download endpoint solves that with `?token=<workspace token>`, which is
+wrong here: that token is fully trusted by `verify_workspace_access` and
+bypasses role checks, and `/v1/account/workspaces` deliberately withholds it
+from viewers. Putting it in an <img src> would hand every viewer a credential
+the system is careful not to give them.
+
+So the URL *is* the capability: a 128-bit random `blob_id` that only ever
+appears in authenticated responses. Revocation is real but not instant —
+deleting the blob 404s the URL immediately, while a viewer who already fetched
+it keeps their cached copy until `AVATAR_CACHE_MAX_AGE` expires. That window is
+why the response is `private` and not `immutable`.
+
+The bytes are read through `FileStore` and served from here, never redirected to
+a presigned S3 URL — same as `/v1/files/{id}`. Which backend holds them stays
+invisible to clients.
+"""
+
+import asyncio
+import logging
+import re
+from datetime import datetime, timezone
+from typing import Optional
+
+from fastapi import APIRouter, Depends, File, Header, Request, UploadFile
+from fastapi.responses import Response
+from sqlalchemy.orm import Session
+
+from app.access import resolve_current_user
+from app.avatar import AvatarError, new_blob_id, process_avatar, read_upload_limited, storage_key
+from app.blob_gc import enqueue_deletion, try_delete_now
+from app.config import config
+from app.database import get_db
+from app.response import ResponseCode, json_response, success_response
+from app.storage import get_file_store
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/v1", tags=["Avatars"])
+
+_UUID_RE = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.I)
+_BLOB_RE = re.compile(r"^[a-f0-9]{32}$")
+
+
+def avatar_url(user_id: str, avatar_key: Optional[str]) -> Optional[str]:
+    """Public URL path for a stored avatar key, or None if there isn't one.
+
+    Returns a path, not an absolute URL — the backend doesn't reliably know its
+    own public origin, and every client already knows the API base.
+    """
+    if not avatar_key:
+        return None
+    blob = avatar_key.rsplit("/", 1)[-1]
+    return f"/v1/avatars/{user_id}/{blob}"
+
+
+# ---------------------------------------------------------------------------
+# POST /v1/account/avatar
+# ---------------------------------------------------------------------------
+
+@router.post("/account/avatar")
+async def upload_avatar(
+    file: UploadFile = File(..., description="Image file (JPEG, PNG, GIF or WebP)"),
+    db: Session = Depends(get_db),
+    authorization: Optional[str] = Header(None),
+):
+    """Replace the signed-in user's avatar.
+
+    Takes no workspace parameter on purpose: an avatar belongs to the user
+    across every workspace they're in, not to any one of them.
+
+    Ordering is write-new, then commit, then delete-old, and never the reverse.
+    If this fails partway the worst outcome is an unreferenced blob; deleting
+    first would mean a broken avatar. The old key is enqueued for deletion in
+    the same transaction as the pointer swap, so an S3 failure can't lose it.
+    """
+    user = resolve_current_user(db, authorization)
+    if not user:
+        return json_response(ResponseCode.UNAUTHORIZED, "Invalid identity token")
+
+    try:
+        raw = await read_upload_limited(file, config.AVATAR_MAX_UPLOAD_SIZE)
+        processed = await process_avatar(raw)
+    except AvatarError as exc:
+        return json_response(ResponseCode.BAD_REQUEST, exc.message, status_code=exc.status)
+
+    blob_id = new_blob_id()
+    store = get_file_store()
+
+    # 1. New bytes first. The DB still points at the old avatar, so a failure
+    #    here leaves the user exactly as they were. Trust the key the store
+    #    hands back rather than rebuilding it, so the two can't drift.
+    try:
+        key = await asyncio.to_thread(
+            store.save, "avatars", str(user.id), f"{blob_id}.webp", processed
+        )
+    except Exception:
+        logger.exception("avatar: failed to store blob for user %s", user.id)
+        return json_response(ResponseCode.INTERNAL_ERROR, "Could not save the image")
+
+    # 2. Swap the pointer and record the old key for deletion — one transaction.
+    old_key = user.avatar_key
+    user.avatar_key = key
+    user.avatar_updated_at = datetime.now(timezone.utc)
+    enqueue_deletion(db, old_key)
+    db.commit()
+
+    # 3. Now that the intent is durable, try the delete immediately; the drainer
+    #    handles it if this doesn't land.
+    try_delete_now(db, old_key)
+
+    return success_response({
+        "userId": str(user.id),
+        "avatarUrl": avatar_url(str(user.id), key),
+    })
+
+
+# ---------------------------------------------------------------------------
+# DELETE /v1/account/avatar
+# ---------------------------------------------------------------------------
+
+@router.delete("/account/avatar")
+def delete_avatar(
+    db: Session = Depends(get_db),
+    authorization: Optional[str] = Header(None),
+):
+    """Remove the signed-in user's avatar. Idempotent."""
+    user = resolve_current_user(db, authorization)
+    if not user:
+        return json_response(ResponseCode.UNAUTHORIZED, "Invalid identity token")
+
+    old_key = user.avatar_key
+    user.avatar_key = None
+    user.avatar_updated_at = datetime.now(timezone.utc)
+    enqueue_deletion(db, old_key)
+    db.commit()
+
+    try_delete_now(db, old_key)
+
+    return success_response({"userId": str(user.id), "avatarUrl": None})
+
+
+# ---------------------------------------------------------------------------
+# GET /v1/avatars/{user_id}/{filename}
+# ---------------------------------------------------------------------------
+
+@router.get("/avatars/{user_id}/{filename}")
+async def get_avatar(user_id: str, filename: str, request: Request):
+    """Serve avatar bytes. No auth, no database query.
+
+    A malformed path is a 404 rather than a 400 — it says the same thing to the
+    caller and keeps this endpoint from becoming a probe for which user ids
+    exist.
+    """
+    if not filename.endswith(".webp"):
+        return Response(status_code=404)
+    blob_id = filename[: -len(".webp")]
+    if not _UUID_RE.match(user_id) or not _BLOB_RE.match(blob_id):
+        return Response(status_code=404)
+
+    etag = f'"{blob_id}"'
+    # The bytes at a given URL never change (a new upload gets a new blob_id),
+    # so a matching If-None-Match can be answered without touching storage.
+    if request.headers.get("if-none-match") == etag:
+        return Response(status_code=304, headers={"ETag": etag})
+
+    store = get_file_store()
+    try:
+        data = await asyncio.to_thread(store.read, storage_key(user_id, blob_id))
+    except FileNotFoundError:
+        return Response(status_code=404)
+    except Exception:
+        logger.exception("avatar: failed to read blob %s/%s", user_id, blob_id)
+        return Response(status_code=404)
+
+    return Response(
+        content=data,
+        media_type="image/webp",
+        headers={
+            "ETag": etag,
+            # `private`, not `public`: the URL is a capability, and a shared
+            # cache we can't purge would outlive any removal. max-age is the
+            # revocation window — deliberately not `immutable`.
+            "Cache-Control": f"private, max-age={config.AVATAR_CACHE_MAX_AGE}",
+            "X-Content-Type-Options": "nosniff",
+        },
+    )
diff --git a/workspace/backend/app/routers/workspaces.py b/workspace/backend/app/routers/workspaces.py
index 080aac251..748d998c4 100644
--- a/workspace/backend/app/routers/workspaces.py
+++ b/workspace/backend/app/routers/workspaces.py
@@ -42,8 +42,10 @@
 from app.access import (
     get_or_create_user_by_email,
     resolve_current_user,
+    resolve_user_role,
     verify_workspace_access,
 )
+from app.routers.avatars import avatar_url
 from app.response import ResponseCode, json_response, success_response
 from app.routers.network import _workspace_filter
 
@@ -1556,21 +1558,39 @@ class TeamMemberUpdateRequest(BaseModel):
     role: str = Field(pattern=r"^(owner|admin|member|viewer)$")
 
 
-def _team_rows(db: Session, workspace_id: str) -> List[dict]:
+def _team_rows(db: Session, workspace_id: str, include_avatars: bool = False) -> List[dict]:
+    """Team members for a workspace.
+
+    `include_avatars` gates the avatar URL, and only the avatar URL. An avatar
+    URL is a capability — anyone holding it can fetch the image — and this
+    endpoint is reachable without an identity: `verify_workspace_access` waves
+    through a workspace that has no token and doesn't require login, so an open
+    workspace's team list can be read anonymously. Callers who got in that way,
+    or on a machine token, see the roster but not the avatars.
+    """
     rows = db.execute(
-        select(User.email, User.display_name, WorkspaceMembership.role, WorkspaceMembership.created_at)
+        select(
+            User.id,
+            User.email,
+            User.display_name,
+            User.avatar_key,
+            WorkspaceMembership.role,
+            WorkspaceMembership.created_at,
+        )
         .join(WorkspaceMembership, WorkspaceMembership.user_id == User.id)
         .where(WorkspaceMembership.workspace_id == workspace_id)
         .order_by(WorkspaceMembership.created_at.asc())
     ).all()
     return [
         {
+            "userId": str(user_id),
             "email": email,
             "displayName": display_name,
+            "avatarUrl": avatar_url(str(user_id), avatar_key) if include_avatars else None,
             "role": role,
             "joinedAt": created_at.isoformat() if created_at else None,
         }
-        for email, display_name, role, created_at in rows
+        for user_id, email, display_name, avatar_key, role, created_at in rows
     ]
 
 
@@ -1598,7 +1618,11 @@ def list_team(
         return json_response(ResponseCode.NOT_FOUND, "Workspace not found")
     if not verify_workspace_access(workspace, x_workspace_token, authorization, db=db, min_role="member"):
         return json_response(ResponseCode.UNAUTHORIZED, "Invalid workspace credentials")
-    return success_response(_team_rows(db, workspace.id))
+    # Avatar URLs go only to callers we can name. Access alone isn't enough —
+    # it can come from a machine token or an open workspace's grandfathered
+    # anonymous read.
+    is_identified_member = resolve_user_role(db, workspace, authorization) is not None
+    return success_response(_team_rows(db, workspace.id, include_avatars=is_identified_member))
 
 
 @router.post("/{workspace_id}/team")
diff --git a/workspace/backend/requirements.txt b/workspace/backend/requirements.txt
index 9b9927054..d522233b2 100644
--- a/workspace/backend/requirements.txt
+++ b/workspace/backend/requirements.txt
@@ -14,6 +14,9 @@ pyjwt[crypto]>=2.8.0
 aioapns>=3.4.0
 boto3>=1.34.0
 python-multipart>=0.0.9
+# Avatar decoding/re-encoding. The re-encode is the security boundary for
+# uploaded images (see app/avatar.py), not just a resize.
+Pillow>=10.0.0
 httpx>=0.27.0
 playwright>=1.40.0
 anthropic>=0.39.0
diff --git a/workspace/backend/tests/test_avatars.py b/workspace/backend/tests/test_avatars.py
new file mode 100644
index 000000000..6a1296b54
--- /dev/null
+++ b/workspace/backend/tests/test_avatars.py
@@ -0,0 +1,407 @@
+# -*- coding: utf-8 -*-
+"""Tests for user avatars: upload pipeline, capability URLs, and the
+transactional deletion outbox.
+
+Identity-token verification is stubbed the same way test_workspace_membership
+does it — by patching app.access.verify_identity_claims, which every caller
+routes through.
+"""
+
+import io
+
+import pytest
+from PIL import Image
+
+import app.access as access
+import app.routers.account as account_router
+import app.storage as storage_mod
+from app.blob_gc import drain_blob_deletions
+from app.models import BlobDeletion, User, Workspace, WorkspaceMembership
+from app.storage import LocalFileStore
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture(autouse=True)
+def local_store(tmp_path, monkeypatch):
+    """Point the FileStore singleton at a temp dir for the whole module."""
+    store = LocalFileStore(base_dir=str(tmp_path / "blobs"))
+    monkeypatch.setattr(storage_mod, "_store", store)
+    return store
+
+
+def _claims(email, uid="uid", name="Test User"):
+    return {"provider": "firebase", "email": email, "firebase_uid": uid,
+            "apple_sub": None, "display_name": name}
+
+
+@pytest.fixture(autouse=True)
+def stub_identity(monkeypatch):
+    """Bearer "<name>" resolves to <name>@example.com.
+
+    Two seams, because DELETE /v1/account predates `resolve_current_user` and
+    still verifies the bearer itself via `verify_identity_token`.
+    """
+    monkeypatch.setattr(
+        access, "verify_identity_claims",
+        lambda tok: _claims(f"{tok}@example.com", uid=tok, name=tok.title()) if tok else None,
+    )
+    monkeypatch.setattr(
+        account_router, "verify_identity_token",
+        lambda tok: f"{tok}@example.com" if tok else None,
+    )
+
+
+def _auth(name):
+    return {"Authorization": f"Bearer {name}"}
+
+
+def _png(width=64, height=64, color=(200, 30, 30), mode="RGB"):
+    img = Image.new(mode, (width, height), color)
+    buf = io.BytesIO()
+    img.save(buf, format="PNG")
+    return buf.getvalue()
+
+
+def _jpeg_with_orientation(orientation: int, width=100, height=40):
+    """A landscape JPEG carrying an EXIF orientation tag that means "rotate".
+
+    Orientation 6 says the camera was held rotated, so a correct renderer shows
+    it as portrait. We start from a wide image so the un-rotated and rotated
+    interpretations are distinguishable.
+    """
+    img = Image.new("RGB", (width, height), (10, 120, 200))
+    exif = img.getexif()
+    exif[0x0112] = orientation
+    buf = io.BytesIO()
+    img.save(buf, format="JPEG", exif=exif)
+    return buf.getvalue()
+
+
+def _upload(client, who, data, filename="a.png", content_type="image/png"):
+    return client.post(
+        "/v1/account/avatar",
+        files={"file": (filename, data, content_type)},
+        headers=_auth(who),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Upload + read round trip
+# ---------------------------------------------------------------------------
+
+class TestUploadAndRead:
+    def test_upload_returns_a_readable_url(self, client):
+        r = _upload(client, "alice", _png())
+        assert r.status_code == 200
+        url = r.json()["data"]["avatarUrl"]
+        assert url.startswith("/v1/avatars/")
+
+        got = client.get(url)
+        assert got.status_code == 200
+        assert got.headers["content-type"] == "image/webp"
+        # Always re-encoded, never passed through.
+        assert got.content[:4] == b"RIFF" and got.content[8:12] == b"WEBP"
+
+    def test_output_is_square_and_normalized(self, client):
+        r = _upload(client, "alice", _png(width=200, height=80))
+        url = r.json()["data"]["avatarUrl"]
+        img = Image.open(io.BytesIO(client.get(url).content))
+        assert img.size == (512, 512)
+
+    def test_upload_requires_identity(self, client):
+        r = client.post("/v1/account/avatar", files={"file": ("a.png", _png(), "image/png")})
+        assert r.status_code == 401
+
+    def test_read_needs_no_credentials(self, client):
+        """The URL is the capability — that's the whole point of the design."""
+        url = _upload(client, "alice", _png()).json()["data"]["avatarUrl"]
+        assert client.get(url).status_code == 200
+
+    def test_grayscale_and_palette_images_are_accepted(self, client):
+        for mode in ("L", "P"):
+            data = _png(mode=mode, color=128 if mode == "L" else 3)
+            assert _upload(client, "alice", data).status_code == 200
+
+
+# ---------------------------------------------------------------------------
+# The pipeline is a security boundary, not a resize
+# ---------------------------------------------------------------------------
+
+class TestRejections:
+    def test_svg_is_rejected(self, client):
+        svg = b'<svg xmlns="http://www.w3.org/2000/svg"><script>alert(1)</script></svg>'
+        r = _upload(client, "alice", svg, filename="x.svg", content_type="image/svg+xml")
+        assert r.status_code == 400
+
+    def test_content_type_is_not_trusted(self, client):
+        """Text claiming to be a PNG is still text."""
+        r = _upload(client, "alice", b"not an image at all", content_type="image/png")
+        assert r.status_code == 400
+
+    def test_oversized_upload_is_rejected(self, client, monkeypatch):
+        from app.config import config
+        monkeypatch.setattr(config, "AVATAR_MAX_UPLOAD_SIZE", 1024)
+        r = _upload(client, "alice", _png(width=800, height=800))
+        assert r.status_code == 413
+
+    def test_decompression_bomb_is_rejected(self, client, monkeypatch):
+        """Pixel count is checked from the header, before any pixel work."""
+        from app.config import config
+        monkeypatch.setattr(config, "AVATAR_MAX_PIXELS", 1000)
+        r = _upload(client, "alice", _png(width=200, height=200))
+        assert r.status_code == 400
+
+    def test_truncated_image_is_a_400_not_a_500(self, client):
+        data = _png(width=300, height=300)
+        r = _upload(client, "alice", data[: len(data) // 2])
+        assert r.status_code == 400
+
+    def test_empty_upload_is_rejected(self, client):
+        assert _upload(client, "alice", b"").status_code == 400
+
+
+class TestExifOrientation:
+    def test_orientation_is_applied_before_cropping(self, client):
+        """A phone's portrait photo is stored landscape plus an orientation tag.
+
+        Re-encoding drops the tag, so if the rotation isn't baked in first the
+        avatar ends up rotated and cropped along the wrong axis. Compare against
+        what Pillow itself produces for the transposed image.
+        """
+        raw = _jpeg_with_orientation(6, width=100, height=40)
+        url = _upload(client, "alice", raw, filename="p.jpg", content_type="image/jpeg").json()["data"]["avatarUrl"]
+        served = Image.open(io.BytesIO(client.get(url).content))
+
+        from PIL import ImageOps
+        expected = ImageOps.exif_transpose(Image.open(io.BytesIO(raw)))
+        # Orientation 6 turns a 100x40 landscape into a 40x100 portrait.
+        assert expected.size == (40, 100)
+        assert served.size == (512, 512)
+
+
+# ---------------------------------------------------------------------------
+# Replacement, removal, and the deletion outbox
+# ---------------------------------------------------------------------------
+
+class TestLifecycle:
+    def test_replacing_deletes_the_old_blob(self, client, local_store):
+        first = _upload(client, "alice", _png(color=(255, 0, 0))).json()["data"]["avatarUrl"]
+        assert client.get(first).status_code == 200
+
+        second = _upload(client, "alice", _png(color=(0, 255, 0))).json()["data"]["avatarUrl"]
+        assert second != first
+        assert client.get(second).status_code == 200
+        assert client.get(first).status_code == 404
+
+    def test_concurrent_uploads_never_orphan_the_pointer(self, client, db):
+        """Two uploads in a row must leave the DB pointing at bytes that exist.
+
+        Random blob ids are what make this safe: with content-addressed keys, a
+        user re-uploading the same image would produce a key equal to the one
+        being deleted.
+        """
+        same = _png(color=(7, 7, 7))
+        _upload(client, "alice", same)
+        url = _upload(client, "alice", same).json()["data"]["avatarUrl"]
+
+        user = db.query(User).filter(User.email == "alice@example.com").one()
+        assert user.avatar_key is not None
+        assert client.get(url).status_code == 200
+
+    def test_removing_clears_the_pointer_and_the_bytes(self, client, db):
+        url = _upload(client, "alice", _png()).json()["data"]["avatarUrl"]
+        r = client.delete("/v1/account/avatar", headers=_auth("alice"))
+        assert r.status_code == 200
+        assert r.json()["data"]["avatarUrl"] is None
+        assert client.get(url).status_code == 404
+
+        db.expire_all()
+        assert db.query(User).filter(User.email == "alice@example.com").one().avatar_key is None
+
+    def test_remove_is_idempotent(self, client):
+        _upload(client, "alice", _png())
+        assert client.delete("/v1/account/avatar", headers=_auth("alice")).status_code == 200
+        assert client.delete("/v1/account/avatar", headers=_auth("alice")).status_code == 200
+
+
+class TestDeletionOutbox:
+    def test_failed_delete_still_succeeds_and_is_recorded(self, client, db, monkeypatch, local_store):
+        """A storage failure must not fail the user's request — but it must not
+        vanish either. That's the whole reason the outbox exists."""
+        _upload(client, "alice", _png(color=(1, 2, 3)))
+
+        def boom(key):
+            raise RuntimeError("S3 unavailable")
+
+        monkeypatch.setattr(local_store, "delete", boom)
+        r = _upload(client, "alice", _png(color=(4, 5, 6)))
+        assert r.status_code == 200
+
+        db.expire_all()
+        pending = db.query(BlobDeletion).all()
+        assert len(pending) == 1
+        assert pending[0].storage_key.startswith("avatars/")
+
+    def test_drainer_removes_the_blob_and_the_row(self, client, db, monkeypatch, local_store):
+        first = _upload(client, "alice", _png(color=(1, 2, 3))).json()["data"]["avatarUrl"]
+
+        monkeypatch.setattr(local_store, "delete", lambda key: (_ for _ in ()).throw(RuntimeError("down")))
+        _upload(client, "alice", _png(color=(4, 5, 6)))
+        monkeypatch.undo()
+
+        db.expire_all()
+        assert db.query(BlobDeletion).count() == 1
+        assert drain_blob_deletions(db) == 1
+
+        db.expire_all()
+        assert db.query(BlobDeletion).count() == 0
+        assert client.get(first).status_code == 404
+
+    def test_drainer_is_idempotent_for_missing_blobs(self, db):
+        db.add(BlobDeletion(storage_key="avatars/nobody/deadbeef.webp"))
+        db.commit()
+        # LocalFileStore.delete on a missing path is a no-op, so the row clears.
+        assert drain_blob_deletions(db) == 1
+
+    def test_failed_attempts_back_off_rather_than_retrying_hot(self, db, monkeypatch, local_store):
+        db.add(BlobDeletion(storage_key="avatars/x/y.webp"))
+        db.commit()
+        monkeypatch.setattr(local_store, "delete", lambda key: (_ for _ in ()).throw(RuntimeError("down")))
+
+        assert drain_blob_deletions(db) == 0
+        db.expire_all()
+        row = db.query(BlobDeletion).one()
+        assert row.attempts == 1
+        assert row.last_error
+        # Rescheduled into the future, so the next cycle doesn't hammer storage.
+        assert drain_blob_deletions(db) == 0
+
+
+# ---------------------------------------------------------------------------
+# HTTP semantics
+# ---------------------------------------------------------------------------
+
+class TestCachingAndPaths:
+    def test_cache_is_private_and_revocable(self, client):
+        """`immutable` plus a long max-age would mean "can never be withdrawn"."""
+        url = _upload(client, "alice", _png()).json()["data"]["avatarUrl"]
+        cc = client.get(url).headers["cache-control"]
+        assert "private" in cc
+        assert "immutable" not in cc
+
+    def test_if_none_match_returns_304(self, client):
+        url = _upload(client, "alice", _png()).json()["data"]["avatarUrl"]
+        etag = client.get(url).headers["etag"]
+        assert client.get(url, headers={"If-None-Match": etag}).status_code == 304
+
+    def test_nosniff_is_set(self, client):
+        url = _upload(client, "alice", _png()).json()["data"]["avatarUrl"]
+        assert client.get(url).headers["x-content-type-options"] == "nosniff"
+
+    @pytest.mark.parametrize("path", [
+        "/v1/avatars/not-a-uuid/00000000000000000000000000000000.webp",
+        "/v1/avatars/11111111-1111-1111-1111-111111111111/short.webp",
+        "/v1/avatars/11111111-1111-1111-1111-111111111111/../../etc/passwd",
+        "/v1/avatars/11111111-1111-1111-1111-111111111111/abc.txt",
+    ])
+    def test_malformed_paths_are_404_not_500(self, client, path):
+        assert client.get(path).status_code == 404
+
+
+# ---------------------------------------------------------------------------
+# Identity plumbing — profile endpoint and the team roster
+# ---------------------------------------------------------------------------
+
+class TestProfile:
+    def test_profile_returns_a_stable_user_id(self, client):
+        r = client.get("/v1/account/profile", headers=_auth("alice"))
+        assert r.status_code == 200
+        data = r.json()["data"]
+        assert data["email"] == "alice@example.com"
+        assert data["userId"]
+        assert data["avatarUrl"] is None
+
+        _upload(client, "alice", _png())
+        assert client.get("/v1/account/profile", headers=_auth("alice")).json()["data"]["avatarUrl"]
+
+    def test_profile_requires_identity(self, client):
+        assert client.get("/v1/account/profile").status_code == 401
+
+    def test_account_workspaces_still_returns_a_bare_array(self, client):
+        """Three clients index this response directly — Swift decodes it as
+        [AccountWorkspace]. It must stay an array."""
+        r = client.get("/v1/account/workspaces", headers=_auth("alice"))
+        assert r.status_code == 200
+        data = r.json()["data"]
+        assert isinstance(data, list)
+        if data:
+            assert set(data[0]) == {"workspaceId", "name", "slug", "token", "role", "lastActivityAt"}
+
+
+class TestTeamAvatarGating:
+    def _workspace_with_member(self, client, db, *, open_workspace=False):
+        ws = Workspace(
+            name="W", slug="team-ws",
+            password_hash=None if open_workspace else "tok",
+            require_login=False,
+        )
+        db.add(ws)
+        db.flush()
+        user = User(email="alice@example.com", display_name="Alice")
+        db.add(user)
+        db.flush()
+        db.add(WorkspaceMembership(workspace_id=ws.id, user_id=user.id, role="owner"))
+        db.commit()
+        return ws, user
+
+    def test_identified_member_sees_avatar_urls(self, client, db):
+        ws, _ = self._workspace_with_member(client, db)
+        _upload(client, "alice", _png())
+
+        r = client.get(f"/v1/workspaces/{ws.id}/team", headers=_auth("alice"))
+        assert r.status_code == 200
+        row = r.json()["data"][0]
+        assert row["userId"]
+        assert row["avatarUrl"]
+
+    def test_machine_token_caller_gets_no_avatar_urls(self, client, db):
+        """A workspace token proves access, not identity — and it's exactly the
+        credential viewers are denied. It shouldn't hand out capabilities."""
+        ws, _ = self._workspace_with_member(client, db)
+        _upload(client, "alice", _png())
+
+        r = client.get(f"/v1/workspaces/{ws.id}/team", headers={"X-Workspace-Token": "tok"})
+        assert r.status_code == 200
+        assert r.json()["data"][0]["avatarUrl"] is None
+
+    def test_anonymous_read_of_an_open_workspace_gets_no_avatar_urls(self, client, db):
+        """Open workspaces are waved through by verify_workspace_access, so the
+        roster is anonymously readable. The avatar URLs must not be."""
+        ws, _ = self._workspace_with_member(client, db, open_workspace=True)
+        _upload(client, "alice", _png())
+
+        r = client.get(f"/v1/workspaces/{ws.id}/team")
+        assert r.status_code == 200
+        assert r.json()["data"][0]["avatarUrl"] is None
+
+
+class TestAccountDeletion:
+    def test_deleting_the_account_removes_the_avatar(self, client, db):
+        url = _upload(client, "alice", _png()).json()["data"]["avatarUrl"]
+        assert client.get(url).status_code == 200
+
+        r = client.delete("/v1/account", headers=_auth("alice"))
+        assert r.status_code == 200
+        assert r.json()["data"]["deleted"]["avatar"] == 1
+
+        assert client.get(url).status_code == 404
+        db.expire_all()
+        assert db.query(User).filter(User.email == "alice@example.com").one().avatar_key is None
+
+    def test_deleting_without_an_avatar_is_fine(self, client):
+        r = client.delete("/v1/account", headers=_auth("bob"))
+        assert r.status_code == 200
+        assert r.json()["data"]["deleted"]["avatar"] == 0
diff --git a/workspace/frontend/app/[workspaceId]/page.tsx b/workspace/frontend/app/[workspaceId]/page.tsx
index c94d57fc1..0172c7d0c 100644
--- a/workspace/frontend/app/[workspaceId]/page.tsx
+++ b/workspace/frontend/app/[workspaceId]/page.tsx
@@ -3,6 +3,7 @@
 import { use, Suspense, useEffect } from 'react';
 import { useSearchParams } from 'next/navigation';
 import { WorkspaceProvider, useWorkspace } from '@/lib/workspace-context';
+import { AvatarsProvider } from '@/lib/avatars';
 import { LayoutProvider } from '@/components/layout/layout-context';
 import { Wrapper } from '@/components/layout/wrapper';
 import { useOpenAgentsAuth } from '@/lib/openagents-auth-context';
@@ -90,9 +91,11 @@ function WorkspaceContent({ workspaceId }: { workspaceId: string }) {
     return (
       <WorkspaceProvider workspaceId={workspaceId} token={token} bearerToken={idToken || undefined}>
         <IdentityGate>
-          <LayoutProvider>
-            <Wrapper />
-          </LayoutProvider>
+          <AvatarsProvider>
+            <LayoutProvider>
+              <Wrapper />
+            </LayoutProvider>
+          </AvatarsProvider>
         </IdentityGate>
       </WorkspaceProvider>
     );
@@ -109,9 +112,11 @@ function WorkspaceContent({ workspaceId }: { workspaceId: string }) {
       return (
         <WorkspaceProvider workspaceId={workspaceId} token="" bearerToken={idToken}>
           <IdentityGate>
-            <LayoutProvider>
-              <Wrapper />
-            </LayoutProvider>
+            <AvatarsProvider>
+              <LayoutProvider>
+                <Wrapper />
+              </LayoutProvider>
+            </AvatarsProvider>
           </IdentityGate>
         </WorkspaceProvider>
       );
diff --git a/workspace/frontend/components/chat/chat-message.tsx b/workspace/frontend/components/chat/chat-message.tsx
index 6dc31164e..1d7bccd7c 100644
--- a/workspace/frontend/components/chat/chat-message.tsx
+++ b/workspace/frontend/components/chat/chat-message.tsx
@@ -7,6 +7,7 @@ import { toast } from 'sonner';
 import { memo, useCallback, useMemo, useState } from 'react';
 import type { WorkspaceMessage, WorkspaceAgent } from '@/lib/types';
 import { AgentAvatar } from '@/components/agents/agent-avatar';
+import { useAvatars } from '@/lib/avatars';
 import { MarkdownContent } from './markdown-content';
 import { workspaceApi } from '@/lib/api';
 import { useLayout } from '@/components/layout/layout-context';
@@ -118,6 +119,7 @@ interface ChatMessageProps {
 
 export const ChatMessage = memo(function ChatMessage({ message, agents = [] }: ChatMessageProps) {
   const { currentUser } = useWorkspace();
+  const { avatarFor } = useAvatars();
   const t = useT();
   const { formatTime } = useFormatters();
   const isHuman = message.senderType === 'human' || message.senderType === 'user';
@@ -171,6 +173,9 @@ export const ChatMessage = memo(function ChatMessage({ message, agents = [] }: C
   if (isHuman) {
     const isCurrentUser = !!message.senderId && message.senderId === currentUser.id;
     const seed = message.senderId || message.senderName || 'human';
+    // senderId is the sender's email for signed-in humans, which is exactly how
+    // the avatar map is keyed.
+    const humanAvatar = avatarFor(message.senderId);
     const displayName = isCurrentUser
       ? 'You'
       : (message.senderName && message.senderName !== 'user' ? message.senderName : 'User');
@@ -178,12 +183,25 @@ export const ChatMessage = memo(function ChatMessage({ message, agents = [] }: C
     return (
       <div className="py-2">
         <div className="flex items-start gap-3">
-          <div
-            className="mt-0.5 flex size-7 shrink-0 items-center justify-center rounded-full"
-            style={{ backgroundColor: humanColor(seed) }}
-          >
-            <User className="size-3.5 text-zinc-700" />
-          </div>
+          {humanAvatar ? (
+            // eslint-disable-next-line @next/next/no-img-element
+            <img
+              src={humanAvatar}
+              alt=""
+              className="mt-0.5 size-7 shrink-0 rounded-full object-cover"
+              // A removed avatar 404s while some clients still hold the URL;
+              // drop back to the colored initial rather than showing a broken
+              // image.
+              onError={(e) => { e.currentTarget.style.display = 'none'; }}
+            />
+          ) : (
+            <div
+              className="mt-0.5 flex size-7 shrink-0 items-center justify-center rounded-full"
+              style={{ backgroundColor: humanColor(seed) }}
+            >
+              <User className="size-3.5 text-zinc-700" />
+            </div>
+          )}
           <div className="min-w-0 flex-1">
             <div className="flex items-baseline gap-2">
               <span className="text-sm font-semibold text-foreground">{displayName}</span>
diff --git a/workspace/frontend/components/layout/settings-dialog.tsx b/workspace/frontend/components/layout/settings-dialog.tsx
index 7d2975638..6121563e0 100644
--- a/workspace/frontend/components/layout/settings-dialog.tsx
+++ b/workspace/frontend/components/layout/settings-dialog.tsx
@@ -23,6 +23,7 @@ import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { Switch } from '@/components/ui/switch';
+import { AvatarSection } from '@/components/settings/avatar-section';
 import { TeamSection } from '@/components/settings/team-section';
 import { useCopyToClipboard } from '@/hooks/use-copy-to-clipboard';
 import { workspaceApi } from '@/lib/api';
@@ -197,6 +198,10 @@ export function SettingsDialog({ open, onOpenChange, workspace, refreshWorkspace
               require-login switch. Shown here for the beta ALONGSIDE the legacy
               email collaborators list below — reconcile/remove the duplicate
               before shipping to release. */}
+          {/* The signed-in user's own avatar. User-level, not workspace-level:
+              it follows them into every workspace they're a member of. */}
+          <AvatarSection />
+
           <TeamSection workspace={workspace} />
 
           {/* Collaborators (legacy email-based) */}
diff --git a/workspace/frontend/components/layout/user-menu.tsx b/workspace/frontend/components/layout/user-menu.tsx
index 785b564f4..b96a13059 100644
--- a/workspace/frontend/components/layout/user-menu.tsx
+++ b/workspace/frontend/components/layout/user-menu.tsx
@@ -20,7 +20,10 @@ import {
   DropdownMenuSubTrigger,
   DropdownMenuTrigger,
 } from '@/components/ui/dropdown-menu';
+import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';
 import { useConfirm } from '@/components/ui/dialogs-provider';
+import { avatarSrc } from '@/lib/account-api';
+import { useAvatars } from '@/lib/avatars';
 import { workspaceApi } from '@/lib/api';
 import { useWorkspace } from '@/lib/workspace-context';
 import { useOpenAgentsAuth } from '@/lib/openagents-auth-context';
@@ -44,6 +47,7 @@ const THEME_OPTIONS = [
 export function UserMenu({ side, align = 'end' }: UserMenuProps = {}) {
   const { workspace, token, refreshWorkspace } = useWorkspace();
   const { user, isOpenAgentsDomain, signIn, signOut } = useOpenAgentsAuth();
+  const { profile } = useAvatars();
   const { theme, setTheme } = useTheme();
   const confirm = useConfirm();
   const t = useT();
@@ -132,9 +136,12 @@ export function UserMenu({ side, align = 'end' }: UserMenuProps = {}) {
             className="flex size-8 items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-sidebar-accent hover:text-sidebar-accent-foreground"
           >
             {user ? (
-              <span className="flex size-6 items-center justify-center rounded-full bg-primary text-[10px] font-bold text-primary-foreground">
-                {user.email[0].toUpperCase()}
-              </span>
+              <Avatar className="size-6">
+                <AvatarImage src={avatarSrc(profile?.avatarUrl)} alt={user.email} />
+                <AvatarFallback className="bg-primary text-[10px] font-bold text-primary-foreground">
+                  {user.email[0].toUpperCase()}
+                </AvatarFallback>
+              </Avatar>
             ) : (
               <User className="size-4" />
             )}
diff --git a/workspace/frontend/components/settings/avatar-section.tsx b/workspace/frontend/components/settings/avatar-section.tsx
new file mode 100644
index 000000000..a579b3b5d
--- /dev/null
+++ b/workspace/frontend/components/settings/avatar-section.tsx
@@ -0,0 +1,126 @@
+'use client';
+
+import { useRef, useState } from 'react';
+import { Loader2, Trash2, UserRound } from 'lucide-react';
+import { toast } from 'sonner';
+
+import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';
+import { Button } from '@/components/ui/button';
+import { Label } from '@/components/ui/label';
+import { avatarSrc, deleteAvatar, uploadAvatar } from '@/lib/account-api';
+import { useAvatars } from '@/lib/avatars';
+import { useOpenAgentsAuth } from '@/lib/openagents-auth-context';
+
+// Matches AVATAR_MAX_UPLOAD_SIZE on the backend. Checked here too so an
+// oversized file fails instantly instead of after a slow upload.
+const MAX_BYTES = 5 * 1024 * 1024;
+const ACCEPT = 'image/jpeg,image/png,image/gif,image/webp';
+
+function initials(name: string): string {
+  const trimmed = name.trim();
+  if (!trimmed) return '?';
+  const parts = trimmed.split(/[\s@._-]+/).filter(Boolean);
+  if (parts.length >= 2) return (parts[0][0] + parts[1][0]).toUpperCase();
+  return trimmed.slice(0, 2).toUpperCase();
+}
+
+/**
+ * The signed-in user's avatar: preview, upload, remove.
+ *
+ * The server re-encodes whatever it's given to a square WebP, so there's no
+ * cropping UI here — any reasonable image produces a reasonable avatar.
+ */
+export function AvatarSection() {
+  const { idToken } = useOpenAgentsAuth();
+  const { profile, refresh } = useAvatars();
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [busy, setBusy] = useState(false);
+
+  if (!idToken || !profile) return null;
+
+  const label = profile.displayName || profile.email;
+
+  const pick = async (file: File | undefined) => {
+    if (!file) return;
+    if (file.size > MAX_BYTES) {
+      toast.error('That image is larger than 5MB. Pick a smaller one.');
+      return;
+    }
+
+    setBusy(true);
+    try {
+      await uploadAvatar(idToken, file);
+      await refresh();
+      toast.success('Avatar updated');
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : 'Could not upload that image');
+    } finally {
+      setBusy(false);
+      // Clear the input so picking the same file again still fires onChange.
+      if (inputRef.current) inputRef.current.value = '';
+    }
+  };
+
+  const remove = async () => {
+    setBusy(true);
+    try {
+      await deleteAvatar(idToken);
+      await refresh();
+      toast.success('Avatar removed');
+    } catch {
+      toast.error('Could not remove your avatar');
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <div className="space-y-3">
+      <div className="flex items-center gap-2">
+        <UserRound className="size-4 text-muted-foreground" />
+        <Label>Your avatar</Label>
+      </div>
+      <p className="text-xs text-muted-foreground">
+        Shown next to your messages across every workspace you&apos;re in. JPEG, PNG, GIF or WebP,
+        up to 5MB.
+      </p>
+
+      <div className="flex items-center gap-3">
+        <Avatar className="size-12">
+          <AvatarImage src={avatarSrc(profile.avatarUrl)} alt={label} />
+          <AvatarFallback className="text-sm">{initials(label)}</AvatarFallback>
+        </Avatar>
+
+        <input
+          ref={inputRef}
+          type="file"
+          accept={ACCEPT}
+          className="hidden"
+          onChange={(e) => pick(e.target.files?.[0])}
+        />
+
+        <Button
+          variant="outline"
+          size="sm"
+          disabled={busy}
+          onClick={() => inputRef.current?.click()}
+        >
+          {busy ? <Loader2 className="size-4 animate-spin" /> : null}
+          {profile.avatarUrl ? 'Change' : 'Upload'}
+        </Button>
+
+        {profile.avatarUrl && (
+          <Button
+            variant="ghost"
+            size="icon"
+            disabled={busy}
+            onClick={remove}
+            title="Remove avatar"
+          >
+            <Trash2 className="size-4 text-muted-foreground" />
+          </Button>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/workspace/frontend/components/settings/team-section.tsx b/workspace/frontend/components/settings/team-section.tsx
index 17cc708ca..c40f3e932 100644
--- a/workspace/frontend/components/settings/team-section.tsx
+++ b/workspace/frontend/components/settings/team-section.tsx
@@ -1,11 +1,13 @@
 'use client';
 
 import { useState, useEffect, useCallback } from 'react';
+import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { Switch } from '@/components/ui/switch';
 import { Users, UserPlus, Trash2, Loader2, ShieldCheck } from 'lucide-react';
+import { avatarSrc } from '@/lib/account-api';
 import { workspaceApi } from '@/lib/api';
 import { toast } from 'sonner';
 import type { TeamMember, Workspace, WorkspaceRole } from '@/lib/types';
@@ -149,6 +151,10 @@ export function TeamSection({ workspace }: { workspace: Workspace }) {
         <div className="rounded-lg border divide-y">
           {members.map((m) => (
             <div key={m.email} className="flex items-center gap-2 px-3 py-2">
+              <Avatar className="size-7 shrink-0">
+                <AvatarImage src={avatarSrc(m.avatarUrl)} alt={m.displayName || m.email} />
+                <AvatarFallback>{(m.displayName || m.email)[0]?.toUpperCase() ?? '?'}</AvatarFallback>
+              </Avatar>
               <div className="min-w-0 flex-1">
                 <p className="text-sm truncate">{m.displayName || m.email}</p>
                 {m.displayName && <p className="text-xs text-muted-foreground truncate">{m.email}</p>}
diff --git a/workspace/frontend/lib/account-api.ts b/workspace/frontend/lib/account-api.ts
index 6db6189c2..0a8065350 100644
--- a/workspace/frontend/lib/account-api.ts
+++ b/workspace/frontend/lib/account-api.ts
@@ -4,6 +4,8 @@
 // access into memberships and auto-provisions an empty workspace for brand-new
 // users, so a freshly signed-in user always has at least one entry.
 
+import type { AccountProfile } from '@/lib/types';
+
 const API_URL = process.env.NEXT_PUBLIC_API_URL || 'https://workspace-endpoint.openagents.org';
 
 export interface AccountWorkspace {
@@ -51,6 +53,51 @@ export function createAccountWorkspace(
   });
 }
 
+/**
+ * Absolute URL for an avatar path returned by the backend.
+ *
+ * The backend returns a path rather than a full URL — it can't reliably know
+ * its own public origin, and the frontend is served from a different host than
+ * the API. Pass through nulls so callers can hand the result straight to
+ * <AvatarImage src>.
+ */
+export function avatarSrc(path: string | null | undefined): string | undefined {
+  if (!path) return undefined;
+  return path.startsWith('http') ? path : `${API_URL}${path}`;
+}
+
+/** The signed-in user's own profile — id, email, display name, avatar. */
+export function getAccountProfile(idToken: string): Promise<AccountProfile> {
+  return bearerFetch<AccountProfile>('/v1/account/profile', idToken);
+}
+
+/**
+ * Upload a new avatar. The server re-encodes whatever it's given to a square
+ * WebP, so there's no need to normalize the file here — any JPEG, PNG, GIF or
+ * WebP under 5MB is fine.
+ */
+export async function uploadAvatar(
+  idToken: string,
+  file: File,
+): Promise<{ userId: string; avatarUrl: string }> {
+  const body = new FormData();
+  body.append('file', file);
+  // No Content-Type header: the browser has to set the multipart boundary.
+  const res = await fetch(`${API_URL}/v1/account/avatar`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${idToken}` },
+    body,
+  });
+  const json = await res.json().catch(() => null);
+  if (!res.ok) throw new Error(json?.message || `Upload failed (${res.status})`);
+  return json.data;
+}
+
+/** Remove the signed-in user's avatar. */
+export function deleteAvatar(idToken: string): Promise<{ userId: string; avatarUrl: null }> {
+  return bearerFetch('/v1/account/avatar', idToken, { method: 'DELETE' });
+}
+
 /**
  * "Add this workspace to my account" — when a signed-in user opens a workspace
  * via a shared ?token= link, persist them as a member so it appears on their
diff --git a/workspace/frontend/lib/avatars.tsx b/workspace/frontend/lib/avatars.tsx
new file mode 100644
index 000000000..1eb833dec
--- /dev/null
+++ b/workspace/frontend/lib/avatars.tsx
@@ -0,0 +1,102 @@
+'use client';
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from 'react';
+
+import { avatarSrc, getAccountProfile } from '@/lib/account-api';
+import { workspaceApi } from '@/lib/api';
+import { useOpenAgentsAuth } from '@/lib/openagents-auth-context';
+import type { AccountProfile } from '@/lib/types';
+
+/**
+ * Avatar lookup for the whole workspace, keyed by email.
+ *
+ * Email is the key because that's what the app already uses to identify a
+ * person: `useWorkspaceIdentity` sets `currentUser.id` to the user's email, and
+ * chat events carry the sender's email in `payload.sender_id`. Avatars are
+ * stored against the database UUID, so this map is what bridges the two — it's
+ * built from the team roster, which returns both.
+ *
+ * Anything not in the map (historical messages from people who left, anonymous
+ * participants, agents) resolves to undefined and falls back to initials. No
+ * request is made for a miss.
+ */
+
+interface AvatarsValue {
+  /** The signed-in user's own profile, or null when signed out / not loaded. */
+  profile: AccountProfile | null;
+  /** Absolute avatar URL for an email, or undefined if there isn't one. */
+  avatarFor: (email: string | null | undefined) => string | undefined;
+  /** Re-read the profile and roster after the user changes their own avatar. */
+  refresh: () => Promise<void>;
+}
+
+const AvatarsContext = createContext<AvatarsValue | null>(null);
+
+export function useAvatars(): AvatarsValue {
+  // Usable outside the provider (e.g. the share view, which has no workspace):
+  // everything resolves empty rather than throwing.
+  return (
+    useContext(AvatarsContext) ?? {
+      profile: null,
+      avatarFor: () => undefined,
+      refresh: async () => {},
+    }
+  );
+}
+
+export function AvatarsProvider({ children }: { children: React.ReactNode }) {
+  const { idToken } = useOpenAgentsAuth();
+  const [profile, setProfile] = useState<AccountProfile | null>(null);
+  const [byEmail, setByEmail] = useState<Record<string, string>>({});
+
+  const load = useCallback(async () => {
+    if (!idToken) {
+      setProfile(null);
+      setByEmail({});
+      return;
+    }
+
+    // Independent of each other, and either may legitimately fail: a signed-in
+    // user who isn't a member of this workspace still has a profile.
+    const [profileResult, teamResult] = await Promise.allSettled([
+      getAccountProfile(idToken),
+      workspaceApi.getTeam(),
+    ]);
+
+    if (profileResult.status === 'fulfilled') {
+      setProfile(profileResult.value);
+    }
+
+    if (teamResult.status === 'fulfilled') {
+      const next: Record<string, string> = {};
+      for (const member of teamResult.value) {
+        const src = avatarSrc(member.avatarUrl);
+        if (src) next[member.email.toLowerCase()] = src;
+      }
+      setByEmail(next);
+    }
+  }, [idToken]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  const avatarFor = useCallback(
+    (email: string | null | undefined) => (email ? byEmail[email.toLowerCase()] : undefined),
+    [byEmail],
+  );
+
+  const value = useMemo(
+    () => ({ profile, avatarFor, refresh: load }),
+    [profile, avatarFor, load],
+  );
+
+  return <AvatarsContext.Provider value={value}>{children}</AvatarsContext.Provider>;
+}
diff --git a/workspace/frontend/lib/types.ts b/workspace/frontend/lib/types.ts
index 5d1bcf8c5..c5c9205c5 100644
--- a/workspace/frontend/lib/types.ts
+++ b/workspace/frontend/lib/types.ts
@@ -15,12 +15,27 @@ export interface Workspace {
 export type WorkspaceRole = 'owner' | 'admin' | 'member' | 'viewer';
 
 export interface TeamMember {
+  /** Stable database id. The email is the identity everywhere else in the UI,
+   *  but avatar URLs are keyed by this. */
+  userId: string;
   email: string;
   displayName: string | null;
+  /** Path (not absolute) to the member's avatar, or null. Null also when the
+   *  caller reached this roster without a verified identity — the backend
+   *  withholds avatar URLs from machine tokens and open-workspace reads. */
+  avatarUrl: string | null;
   role: WorkspaceRole;
   joinedAt: string | null;
 }
 
+/** The signed-in user's own profile, from GET /v1/account/profile. */
+export interface AccountProfile {
+  userId: string;
+  email: string;
+  displayName: string | null;
+  avatarUrl: string | null;
+}
+
 export interface WorkspaceAgent {
   agentName: string;
   role: string;