Merge branch 'dev' of ssh://git.commumedia.org:2222/alex/headquarter into dev

apps/api/alembic/versions/2026_05_28_add_monitoring_tables.py

@@ -0,0 +1,122 @@
+"""add monitoring tables
+
+Revision ID: 2026_05_28_add_monitoring_tables
+Revises: 2026_05_28_drop_tool_configs_and_config_folders
+Create Date: 2026-05-28
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "2026_05_28_add_monitoring_tables"
+down_revision: str | None = "2026_05_28_drop_tool_configs_and_config_folders"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "instance_events",
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column(
+            "instance_id",
+            sa.Uuid(),
+            nullable=False,
+        ),
+        sa.Column("event_type", sa.String(length=50), nullable=False),
+        sa.Column("status", sa.String(length=50), nullable=True),
+        sa.Column("message", sa.Text(), nullable=True),
+        sa.Column("created_by", sa.Uuid(), nullable=True),
+        sa.Column(
+            "metadata",
+            sa.JSON(),
+            nullable=False,
+            server_default="{}",
+        ),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.ForeignKeyConstraint(
+            ["instance_id"],
+            ["tool_instances.id"],
+            ondelete="CASCADE",
+        ),
+        sa.ForeignKeyConstraint(
+            ["created_by"],
+            ["users.id"],
+            ondelete="SET NULL",
+        ),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        "idx_instance_events_instance_id",
+        "instance_events",
+        ["instance_id"],
+    )
+    op.create_index(
+        "idx_instance_events_created_at",
+        "instance_events",
+        ["created_at"],
+        postgresql_using="btree",
+    )
+    op.create_index(
+        "idx_instance_events_event_type",
+        "instance_events",
+        ["event_type"],
+    )
+
+    op.create_table(
+        "health_checks",
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column(
+            "instance_id",
+            sa.Uuid(),
+            nullable=False,
+        ),
+        sa.Column("container_status", sa.String(length=50), nullable=True),
+        sa.Column("container_healthy", sa.Boolean(), nullable=True),
+        sa.Column("tunnel_healthy", sa.Boolean(), nullable=True),
+        sa.Column("exit_code", sa.Integer(), nullable=True),
+        sa.Column("probe_status", sa.String(length=50), nullable=True),
+        sa.Column("probe_output", sa.Text(), nullable=True),
+        sa.Column(
+            "checked_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.ForeignKeyConstraint(
+            ["instance_id"],
+            ["tool_instances.id"],
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        "idx_health_checks_instance_id",
+        "health_checks",
+        ["instance_id"],
+    )
+    op.create_index(
+        "idx_health_checks_checked_at",
+        "health_checks",
+        ["checked_at"],
+        postgresql_using="btree",
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("idx_health_checks_checked_at", table_name="health_checks")
+    op.drop_index("idx_health_checks_instance_id", table_name="health_checks")
+    op.drop_table("health_checks")
+    op.drop_index("idx_instance_events_event_type", table_name="instance_events")
+    op.drop_index("idx_instance_events_created_at", table_name="instance_events")
+    op.drop_index("idx_instance_events_instance_id", table_name="instance_events")
+    op.drop_table("instance_events")

apps/api/src/api/__init__.py

@@ -1,4 +1,5 @@
 from src.api.auth import router as auth_router
+from src.api.events import router as events_router
 from src.api.users import router as users_router
 
-__all__ = ["auth_router", "users_router"]
+__all__ = ["auth_router", "events_router", "users_router"]

apps/api/src/api/events.py

@@ -0,0 +1,80 @@
+"""SSE streaming endpoint for instance events."""
+
+import asyncio
+import contextlib
+import json
+import uuid
+from collections.abc import AsyncGenerator
+
+from fastapi import APIRouter, Depends, HTTPException, Request, status
+from fastapi.responses import StreamingResponse
+
+from src.auth.dependencies import get_current_user_id
+from src.services.event_bus import InstanceEventBus, InstanceEventPayload
+
+router = APIRouter(prefix="/events", tags=["events"])
+
+# In-memory connection counter per user (single-process assumption)
+_connection_counts: dict[uuid.UUID, int] = {}
+MAX_CONNECTIONS_PER_USER = 5
+
+
+@router.get("/stream")
+async def events_stream(
+    request: Request,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+) -> StreamingResponse:
+    """Stream instance events via Server-Sent Events.
+
+    Enforces a maximum of 5 concurrent connections per user.
+    """
+    current = _connection_counts.get(user_id, 0)
+    if current >= MAX_CONNECTIONS_PER_USER:
+        raise HTTPException(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            detail="Too many SSE connections",
+        )
+
+    _connection_counts[user_id] = current + 1
+
+    async def event_generator() -> AsyncGenerator[str, None]:
+        event_bus = InstanceEventBus()
+        queue: asyncio.Queue[InstanceEventPayload] = asyncio.Queue(maxsize=100)
+
+        async def on_event(payload: InstanceEventPayload) -> None:
+            try:
+                queue.put_nowait(payload)
+            except asyncio.QueueFull:
+                # Drop oldest event to make room
+                with contextlib.suppress(asyncio.QueueEmpty):
+                    queue.get_nowait()
+                with contextlib.suppress(asyncio.QueueFull):
+                    queue.put_nowait(payload)
+
+        unsubscribe = event_bus.subscribe("*", on_event)
+
+        try:
+            while True:
+                try:
+                    payload = await asyncio.wait_for(queue.get(), timeout=30.0)
+                    yield f"event: {payload['event']}\ndata: {json.dumps(payload)}\n\n"
+                except asyncio.TimeoutError:
+                    yield ":ping\n\n"
+        except asyncio.CancelledError:
+            # Client disconnected
+            raise
+        finally:
+            unsubscribe()
+            _connection_counts[user_id] = max(0, _connection_counts.get(user_id, 1) - 1)
+            if _connection_counts[user_id] == 0:
+                _connection_counts.pop(user_id, None)
+
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        },
+    )

apps/api/src/api/tool_instances.py

@@ -28,6 +28,8 @@ from src.auth.dependencies import (
     get_current_user_id,
     get_db_session,
 )
+from src.services.event_bus import InstanceEventBus
+from src.services.lifecycle_hooks import publish_lifecycle_event
 from src.models.config_profile import ConfigProfile
 from src.models.git_repository import GitRepository
 from src.models.project import Project
@@ -77,6 +79,7 @@ from src.services.readiness_probe import execute_probe
 from src.services.ssh_keys import cleanup_ssh_key_files, prepare_ssh_key_files
 
 logger = logging.getLogger(__name__)
+_event_bus = InstanceEventBus()
 
 
 async def _resolve_git_mounts(
@@ -958,6 +961,15 @@ services:
         session.add(instance)
         await session.commit()
         await session.refresh(instance)
+        await publish_lifecycle_event(
+            event_bus=_event_bus,
+            session=session,
+            instance=instance,
+            event_type="instance.created",
+            created_by=user_id,
+            status="pending",
+            message="Instance created",
+        )
 
         return {
             "id": str(instance.id),
@@ -1502,6 +1514,15 @@ async def start_instance(
         instance.status = "starting"
         instance.last_started_at = datetime.now()
         await session.commit()
+        await publish_lifecycle_event(
+            event_bus=_event_bus,
+            session=session,
+            instance=instance,
+            event_type="instance.started",
+            created_by=user_id,
+            status="starting",
+            message="Container starting...",
+        )
         logger.debug("Instance %s: verifying container startup...", instance.id)
 
         startup_result = wait_for_container_running(
@@ -1519,6 +1540,19 @@ async def start_instance(
 
             instance.status = "error"
             await session.commit()
+            await publish_lifecycle_event(
+                event_bus=_event_bus,
+                session=session,
+                instance=instance,
+                event_type="instance.error",
+                created_by=user_id,
+                status="error",
+                message=error_msg,
+                metadata={
+                    "exit_code": startup_result["exit_code"],
+                    "error_type": "container",
+                },
+            )
             logger.error(
                 "Instance %s container startup failed after %.1fs: %s\nLogs:\n%s",
                 instance.id,
@@ -1608,6 +1642,16 @@ async def start_instance(
             if not success:
                 instance.status = "unhealthy"
                 await session.commit()
+                await publish_lifecycle_event(
+                    event_bus=_event_bus,
+                    session=session,
+                    instance=instance,
+                    event_type="instance.health_changed",
+                    created_by=user_id,
+                    status="unhealthy",
+                    message="Readiness probe failed",
+                    metadata={"probe_output": "\n".join(probe_logs)},
+                )
                 logger.error(
                     "Readiness probe failed for instance %s after %ds: %s",
                     instance.id,
@@ -1624,6 +1668,16 @@ async def start_instance(
 
     instance.status = "running"
     await session.commit()
+    await publish_lifecycle_event(
+        event_bus=_event_bus,
+        session=session,
+        instance=instance,
+        event_type="instance.health_changed",
+        created_by=user_id,
+        status="running",
+        message="Container running",
+        metadata={"previous_status": "starting"},
+    )
     logger.info("Instance %s is now running", instance.id)
 
     # Get tool type for default port
@@ -1632,6 +1686,15 @@ async def start_instance(
         logger.error("Tool type %s not found", instance.tool_type_id)
         instance.status = "error"
         await session.commit()
+        await publish_lifecycle_event(
+            event_bus=_event_bus,
+            session=session,
+            instance=instance,
+            event_type="instance.error",
+            created_by=user_id,
+            status="error",
+            message=f"Tool type '{instance.tool_type_id}' not found",
+        )
         return {
             "status": "error",
             "error": f"Tool type '{instance.tool_type_id}' not found",
@@ -1757,6 +1820,15 @@ async def stop_instance(
     instance.public_url = None
     instance.tunnel_id = None
     await session.commit()
+    await publish_lifecycle_event(
+        event_bus=_event_bus,
+        session=session,
+        instance=instance,
+        event_type="instance.stopped",
+        created_by=user_id,
+        status="stopped",
+        message="Instance stopped",
+    )
 
     return {"status": instance.status}
 
@@ -1893,6 +1965,15 @@ async def restart_instance(
                 instance.public_url = None
 
             await session.commit()
+            await publish_lifecycle_event(
+                event_bus=_event_bus,
+                session=session,
+                instance=instance,
+                event_type="instance.restarted",
+                created_by=user_id,
+                status="running",
+                message="Instance restarted",
+            )
             return {"status": instance.status, "url": instance.url}
 
     instance.status = "error"
@@ -1979,6 +2060,15 @@ async def delete_instance(
 
             shutil.rmtree(instance_dir)
 
+    await publish_lifecycle_event(
+        event_bus=_event_bus,
+        session=session,
+        instance=instance,
+        event_type="instance.deleted",
+        created_by=user_id,
+        status="deleted",
+        message="Instance deleted",
+    )
     await session.delete(instance)
     await session.commit()
 
@@ -2195,6 +2285,65 @@ async def check_instance_tunnel_health(
     return response
 
 
+@router.get(
+    "/{project_id}/repositories/{repo_id}/instances/{instance_id}/events",
+    summary="Get instance events history",
+    description="Get lifecycle event history for a tool instance.",
+)
+async def get_instance_events(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    instance_id: uuid.UUID,
+    limit: int = 50,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> list[dict]:
+    """Get lifecycle event history for an instance.
+
+    Args:
+        project_id: UUID of the project.
+        repo_id: UUID of the repository.
+        instance_id: UUID of the instance.
+        limit: Maximum number of events to return (default: 50).
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        List of event dictionaries.
+    """
+    from sqlalchemy import select
+    from src.models.instance_event import InstanceEvent
+
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+
+    instance = await session.get(ToolInstance, instance_id)
+    if instance is None or instance.repository_id != repo_id:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="instance not found"
+        )
+
+    result = await session.execute(
+        select(InstanceEvent)
+        .where(InstanceEvent.instance_id == instance_id)
+        .order_by(InstanceEvent.created_at.desc())
+        .limit(limit)
+    )
+    rows = result.scalars().all()
+
+    return [
+        {
+            "id": str(row.id),
+            "event_type": row.event_type,
+            "status": row.status,
+            "message": row.message,
+            "metadata": row.event_metadata,
+            "created_at": row.created_at.isoformat() if row.created_at else None,
+        }
+        for row in rows
+    ]
+
+
 @router.get(
     "/{project_id}/repositories/{repo_id}/instances/{instance_id}/proxy/{path:path}",
     summary="Proxy to instance",

apps/api/src/logging_config.py

@@ -1,15 +1,52 @@
+"""Structured JSON logging configuration."""
+
+import json
 import logging
 import sys
 import time
 import traceback
-from typing import Callable
+from collections.abc import Callable
 
 from fastapi import Request, Response
 from starlette.middleware.base import BaseHTTPMiddleware
 
+from src.services.correlation import get_correlation_id
+
 logger = logging.getLogger(__name__)
 
 
+class CorrelationIdFilter(logging.Filter):
+    """Inject correlation_id into every log record from context var."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        record.correlation_id = get_correlation_id()  # type: ignore[attr-defined]
+        return True
+
+
+class JSONFormatter(logging.Formatter):
+    """Emit log records as single-line JSON."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        log_obj: dict = {
+            "timestamp": self.formatTime(record),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+            "correlation_id": getattr(record, "correlation_id", None),
+        }
+        # Optional extra fields
+        for key in ("instance_id", "event_type"):
+            value = getattr(record, key, None)
+            if value is not None:
+                log_obj[key] = value
+        if record.exc_info:
+            log_obj["exception"] = self.formatException(record.exc_info)
+        return json.dumps(log_obj, default=str)
+
+    def formatTime(self, record: logging.LogRecord, datefmt: str | None = None) -> str:
+        return time.strftime("%Y-%m-%dT%H:%M:%S", time.gmtime(record.created))
+
+
 class RequestLoggingMiddleware(BaseHTTPMiddleware):
     """Log all HTTP requests with timing and status codes."""
 
@@ -17,7 +54,6 @@ class RequestLoggingMiddleware(BaseHTTPMiddleware):
         start_time = time.time()
         client_host = request.client.host if request.client else "unknown"
 
-        # Log the incoming request
         logger.info(
             "→ Request: %s %s (client: %s)",
             request.method,
@@ -29,7 +65,6 @@ class RequestLoggingMiddleware(BaseHTTPMiddleware):
             response = await call_next(request)
             duration = time.time() - start_time
 
-            # Log the response
             logger.info(
                 "← Response: %s %s → %d (%dms)",
                 request.method,
@@ -69,15 +104,13 @@ class ExceptionLoggingMiddleware(BaseHTTPMiddleware):
 
 
 def configure_logging(level: int = logging.INFO) -> None:
-    """Configure structured logging for the application."""
-    formatter = logging.Formatter(
-        fmt="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
-        datefmt="%Y-%m-%d %H:%M:%S",
-    )
+    """Configure structured JSON logging for the application."""
+    formatter = JSONFormatter()
 
     # Console handler
     console_handler = logging.StreamHandler(sys.stdout)
     console_handler.setFormatter(formatter)
+    console_handler.addFilter(CorrelationIdFilter())
 
     # Configure root logger
     root_logger = logging.getLogger()

apps/api/src/main.py

@@ -9,6 +9,7 @@ from fastapi.staticfiles import StaticFiles
 
 from src.api.auth import router as auth_router
 from src.api.dashboard import router as dashboard_router
+from src.api.events import router as events_router
 from src.api.git_repositories import router as git_repositories_router
 from src.api.health import router as health_router
 from src.api.projects import router as projects_router
@@ -30,6 +31,9 @@ from src.logging_config import (
     RequestLoggingMiddleware,
     configure_logging,
 )
+from src.services.correlation import CorrelationIdMiddleware
+from src.services.event_bus import InstanceEventBus
+from src.services.health_monitor import HealthMonitor
 
 # Configure logging early
 log_level = os.getenv("LOG_LEVEL", "INFO").upper()
@@ -54,6 +58,7 @@ app.add_middleware(
     allow_headers=["*"],
 )
 
+app.add_middleware(CorrelationIdMiddleware)
 app.add_middleware(RequestLoggingMiddleware)
 app.add_middleware(ExceptionLoggingMiddleware)
 
@@ -103,6 +108,11 @@ async def validation_exception_handler(request: Request, exc: RequestValidationE
     )
 
 
+# Global services
+_event_bus = InstanceEventBus()
+_health_monitor = HealthMonitor(_event_bus)
+
+
 @app.on_event("startup")
 async def on_startup():
     logger.info("Starting up Headquarter API...")
@@ -115,9 +125,21 @@ async def on_startup():
 
         sys.exit(1)
 
+    # Start background health monitor
+    _health_monitor.start()
+    logger.info("Health monitor started")
+
     logger.info("Startup complete.")
 
 
+@app.on_event("shutdown")
+async def on_shutdown():
+    logger.info("Shutting down Headquarter API...")
+    _health_monitor.stop()
+    logger.info("Health monitor stopped")
+    logger.info("Shutdown complete.")
+
+
 app.include_router(health_router)
 app.include_router(auth_router)
 app.include_router(dashboard_router)
@@ -133,4 +155,5 @@ app.include_router(tool_instances_router)
 app.include_router(sessions_router)
 app.include_router(instance_proxy_router)
 app.include_router(terminal_router)
+app.include_router(events_router)
 app.mount("/uploads", StaticFiles(directory="uploads"), name="uploads")

apps/api/src/models/__init__.py

@@ -1,6 +1,8 @@
 from src.models.base import Base
 from src.models.config_profile import ConfigProfile, ConfigProfileInclude
 from src.models.git_repository import GitRepository
+from src.models.health_check import HealthCheck
+from src.models.instance_event import InstanceEvent
 from src.models.project import Project
 from src.models.ssh_key import SSHKey
 from src.models.terminal_session import TerminalSessionModel
@@ -15,6 +17,8 @@ __all__ = [
     "ConfigProfile",
     "ConfigProfileInclude",
     "GitRepository",
+    "HealthCheck",
+    "InstanceEvent",
     "Project",
     "SSHKey",
     "TerminalSessionModel",

apps/api/src/models/health_check.py

@@ -0,0 +1,30 @@
+"""SQLAlchemy model for health check snapshots."""
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import Boolean, DateTime, ForeignKey, Integer, String, Text, Uuid, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from src.models.base import Base, UUIDPrimaryKeyMixin
+
+
+class HealthCheck(UUIDPrimaryKeyMixin, Base):
+    __tablename__ = "health_checks"
+
+    instance_id: Mapped[uuid.UUID] = mapped_column(
+        Uuid(as_uuid=True),
+        ForeignKey("tool_instances.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    container_status: Mapped[str | None] = mapped_column(String(50), nullable=True)
+    container_healthy: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
+    tunnel_healthy: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
+    exit_code: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    probe_status: Mapped[str | None] = mapped_column(String(50), nullable=True)
+    probe_output: Mapped[str | None] = mapped_column(Text, nullable=True)
+    checked_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        nullable=False,
+    )

apps/api/src/models/instance_event.py

@@ -0,0 +1,39 @@
+"""SQLAlchemy model for instance lifecycle event audit rows."""
+
+import uuid
+from datetime import datetime
+from typing import Any
+
+from sqlalchemy import DateTime, ForeignKey, JSON, String, Text, Uuid, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from src.models.base import Base, UUIDPrimaryKeyMixin
+
+
+class InstanceEvent(UUIDPrimaryKeyMixin, Base):
+    __tablename__ = "instance_events"
+
+    instance_id: Mapped[uuid.UUID] = mapped_column(
+        Uuid(as_uuid=True),
+        ForeignKey("tool_instances.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    event_type: Mapped[str] = mapped_column(String(50), nullable=False)
+    status: Mapped[str | None] = mapped_column(String(50), nullable=True)
+    message: Mapped[str | None] = mapped_column(Text, nullable=True)
+    created_by: Mapped[uuid.UUID | None] = mapped_column(
+        Uuid(as_uuid=True),
+        ForeignKey("users.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    event_metadata: Mapped[dict[str, Any]] = mapped_column(
+        "metadata",
+        JSON,
+        nullable=False,
+        default=dict,
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        nullable=False,
+    )

apps/api/src/services/correlation.py

@@ -0,0 +1,32 @@
+"""Async correlation ID context variable and helpers."""
+
+import contextvars
+import uuid
+
+from fastapi import Request
+from starlette.middleware.base import BaseHTTPMiddleware
+
+CORRELATION_ID: contextvars.ContextVar[str] = contextvars.ContextVar("correlation_id")
+
+
+def get_correlation_id() -> str:
+    """Return the current correlation ID or generate a new UUID."""
+    try:
+        return CORRELATION_ID.get()
+    except LookupError:
+        return str(uuid.uuid4())
+
+
+class CorrelationIdMiddleware(BaseHTTPMiddleware):
+    """Set correlation ID from X-Request-ID header or generate a new UUID."""
+
+    async def dispatch(self, request: Request, call_next):
+        request_id = request.headers.get("X-Request-ID")
+        correlation_id = request_id or str(uuid.uuid4())
+        token = CORRELATION_ID.set(correlation_id)
+        try:
+            response = await call_next(request)
+            response.headers["X-Request-ID"] = correlation_id
+            return response
+        finally:
+            CORRELATION_ID.reset(token)

apps/api/src/services/event_bus.py

@@ -0,0 +1,97 @@
+"""In-memory typed event bus for instance lifecycle and health events."""
+
+import asyncio
+import inspect
+import logging
+import uuid
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+InstanceEventPayload = dict[str, Any]
+EventCallback = Callable[[InstanceEventPayload], Awaitable[None] | None]  # noqa: UP044
+
+
+class InstanceEventBus:
+    """Singleton in-memory event bus with typed pub/sub and exception isolation."""
+
+    _instance: "InstanceEventBus | None" = None
+    _lock: asyncio.Lock = asyncio.Lock()
+
+    def __init__(self) -> None:
+        self._subscribers: dict[str, list[tuple[str, EventCallback]]] = {}
+
+    def __new__(cls) -> "InstanceEventBus":
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._subscribers = {}
+        return cls._instance
+
+    def _reset_for_testing(self) -> None:
+        """Clear all subscribers. For test use only."""
+        self._subscribers.clear()
+
+    def subscribe(
+        self,
+        event_type: str,
+        callback: EventCallback,
+    ) -> Callable[[], None]:
+        """Register a callback for an event type.
+
+        Args:
+            event_type: The event type to subscribe to.
+            callback: A sync or async callable that receives the payload.
+
+        Returns:
+            An unsubscribe function.
+        """
+        if event_type not in self._subscribers:
+            self._subscribers[event_type] = []
+        callback_id = str(uuid.uuid4())
+        self._subscribers[event_type].append((callback_id, callback))
+
+        def unsubscribe() -> None:
+            self.unsubscribe(event_type, callback_id)
+
+        return unsubscribe
+
+    def unsubscribe(self, event_type: str, callback_id: str) -> None:
+        """Remove a specific callback by ID."""
+        if event_type in self._subscribers:
+            self._subscribers[event_type] = [
+                (cid, cb)
+                for cid, cb in self._subscribers[event_type]
+                if cid != callback_id
+            ]
+            if not self._subscribers[event_type]:
+                del self._subscribers[event_type]
+
+    def unsubscribe_all(self, event_type: str) -> None:
+        """Remove all subscribers for an event type."""
+        self._subscribers.pop(event_type, None)
+
+    async def publish(self, event_type: str, payload: InstanceEventPayload) -> None:
+        """Deliver payload to all subscribers of event_type.
+
+        Also delivers to subscribers registered under the wildcard "*".
+        Exceptions from individual subscribers are caught and logged;
+        delivery continues to remaining subscribers.
+        """
+        callbacks: list[tuple[str, EventCallback]] = []
+        callbacks.extend(self._subscribers.get(event_type, []))
+        callbacks.extend(self._subscribers.get("*", []))
+
+        for _callback_id, callback in callbacks:
+            try:
+                if inspect.iscoroutinefunction(callback):
+                    await callback(payload)
+                else:
+                    callback(payload)
+            except Exception:
+                correlation_id = payload.get("correlation_id", "unknown")
+                logger.exception(
+                    "Event subscriber failed for %s",
+                    event_type,
+                    extra={"correlation_id": correlation_id},
+                )

apps/api/src/services/health_monitor.py

@@ -0,0 +1,219 @@
+"""Background health monitor that polls container and tunnel health."""
+
+import asyncio
+import logging
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.database import SessionLocal
+from src.models.health_check import HealthCheck
+from src.models.tool_instance import ToolInstance
+from src.services.correlation import get_correlation_id
+from src.services.docker import check_tunnel_health, get_container_status
+from src.services.event_bus import InstanceEventBus, InstanceEventPayload
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class HealthSnapshot:
+    """In-memory snapshot of an instance's health state."""
+
+    container_status: str | None = None
+    container_healthy: bool | None = None
+    tunnel_healthy: bool | None = None
+    exit_code: int | None = None
+
+
+class HealthMonitor:
+    """Polls container and tunnel health, publishing events on state changes."""
+
+    POLL_INTERVAL_SECONDS: float = 15.0
+    _MONITORED_STATUSES: set[str] = {"starting", "running", "unhealthy"}
+
+    def __init__(self, event_bus: InstanceEventBus) -> None:
+        self._event_bus = event_bus
+        self._task: asyncio.Task | None = None
+        self._last_known_state: dict[uuid.UUID, HealthSnapshot] = {}
+
+    def start(self) -> None:
+        """Idempotent start of the background polling task."""
+        if self._task is not None and not self._task.done():
+            return
+        try:
+            loop = asyncio.get_running_loop()
+            self._task = loop.create_task(self._poll_loop())
+        except RuntimeError:
+            pass
+
+    def stop(self) -> None:
+        """Cancel the background task and clear state."""
+        if self._task is not None and not self._task.done():
+            self._task.cancel()
+        self._last_known_state.clear()
+        self._task = None
+
+    async def _poll_loop(self) -> None:
+        """Main polling loop."""
+        while True:
+            try:
+                await asyncio.sleep(self.POLL_INTERVAL_SECONDS)
+                await self._run_check_cycle()
+            except asyncio.CancelledError:
+                break
+            except Exception:
+                logger.exception("Health monitor poll loop error")
+
+    async def _run_check_cycle(self) -> None:
+        """Check all monitored instances in one cycle."""
+        async with SessionLocal() as session:
+            result = await session.execute(
+                select(ToolInstance).where(
+                    ToolInstance.status.in_(self._MONITORED_STATUSES)
+                )
+            )
+            instances = result.scalars().all()
+
+        for instance in instances:
+            async with SessionLocal() as session:
+                await self._check_instance(session, instance)
+
+    async def _check_instance(
+        self,
+        session: AsyncSession,
+        instance: ToolInstance,
+    ) -> None:
+        """Check a single instance and handle state transitions."""
+        try:
+            container_info = get_container_status(instance.container_id or "")
+        except Exception:
+            logger.exception(
+                "Health check failed for instance %s",
+                instance.id,
+                extra={
+                    "instance_id": str(instance.id),
+                    "correlation_id": get_correlation_id(),
+                },
+            )
+            return
+
+        container_status = container_info["status"]
+        exit_code = container_info["exit_code"]
+        container_healthy = (
+            container_info["health"] == "healthy" if container_info["health"] else None
+        )
+
+        tunnel_healthy: bool | None = None
+        if instance.public_url and container_status == "running":
+            try:
+                tunnel_result = check_tunnel_health(instance.public_url)
+                tunnel_healthy = tunnel_result.get("healthy", False)
+            except Exception:
+                logger.exception(
+                    "Tunnel health check failed for instance %s",
+                    instance.id,
+                    extra={
+                        "instance_id": str(instance.id),
+                        "correlation_id": get_correlation_id(),
+                    },
+                )
+                tunnel_healthy = False
+
+        snapshot = HealthSnapshot(
+            container_status=container_status,
+            container_healthy=container_healthy,
+            tunnel_healthy=tunnel_healthy,
+            exit_code=exit_code,
+        )
+
+        previous = self._last_known_state.get(instance.id)
+
+        # Determine new status
+        new_status = self._derive_status(snapshot)
+
+        # If first check or state changed
+        if previous is None or not self._snapshots_equal(previous, snapshot):
+            await self._handle_state_change(
+                session, instance, previous, snapshot, new_status
+            )
+            self._last_known_state[instance.id] = snapshot
+
+    def _derive_status(self, snapshot: HealthSnapshot) -> str:
+        """Derive instance status from health snapshot."""
+        if snapshot.container_status != "running":
+            return "error"
+        if snapshot.tunnel_healthy is False:
+            return "unhealthy"
+        return "running"
+
+    def _snapshots_equal(self, a: HealthSnapshot, b: HealthSnapshot) -> bool:
+        """Compare two snapshots for equality."""
+        return (
+            a.container_status == b.container_status
+            and a.container_healthy == b.container_healthy
+            and a.tunnel_healthy == b.tunnel_healthy
+            and a.exit_code == b.exit_code
+        )
+
+    async def _handle_state_change(
+        self,
+        session: AsyncSession,
+        instance: ToolInstance,
+        previous: HealthSnapshot | None,
+        snapshot: HealthSnapshot,
+        new_status: str,
+    ) -> None:
+        """Update DB, insert health check, and publish event."""
+        previous_status = instance.status
+
+        # Update instance status
+        instance.status = new_status
+        if new_status == "error":
+            instance.last_stopped_at = datetime.now(timezone.utc)
+
+        # Insert health check row
+        health_check = HealthCheck(
+            instance_id=instance.id,
+            container_status=snapshot.container_status,
+            container_healthy=snapshot.container_healthy,
+            tunnel_healthy=snapshot.tunnel_healthy,
+            exit_code=snapshot.exit_code,
+            probe_status=None,
+            probe_output=None,
+        )
+        session.add(health_check)
+        await session.commit()
+
+        # Build event payload
+        correlation_id = get_correlation_id()
+        metadata: dict = {"previous_status": previous_status}
+        if snapshot.exit_code is not None:
+            metadata["exit_code"] = snapshot.exit_code
+            metadata["error_type"] = "container"
+        if instance.public_url:
+            metadata["tunnel_url"] = instance.public_url
+
+        if new_status == "error":
+            event_type = "instance.error"
+            message = f"Container failed with status {snapshot.container_status}"
+            if snapshot.exit_code is not None:
+                message += f" (exit code: {snapshot.exit_code})"
+        else:
+            event_type = "instance.health_changed"
+            message = f"Container is now {new_status}"
+
+        payload: InstanceEventPayload = {
+            "event": event_type,
+            "instance_id": str(instance.id),
+            "status": new_status,
+            "message": message,
+            "metadata": metadata,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "correlation_id": correlation_id,
+        }
+
+        await self._event_bus.publish(event_type, payload)

apps/api/src/services/lifecycle_hooks.py

@@ -0,0 +1,98 @@
+"""Lifecycle hook helpers for instrumenting tool instance transitions."""
+
+import uuid
+from datetime import datetime, timezone
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.models.instance_event import InstanceEvent
+from src.models.tool_instance import ToolInstance
+from src.services.correlation import get_correlation_id
+from src.services.event_bus import InstanceEventBus, InstanceEventPayload
+
+
+def _build_payload(
+    event_type: str,
+    instance: ToolInstance,
+    status: str | None = None,
+    message: str | None = None,
+    metadata: dict | None = None,
+) -> InstanceEventPayload:
+    """Construct a standard event payload."""
+    return {
+        "event": event_type,
+        "instance_id": str(instance.id),
+        "status": status or instance.status,
+        "message": message,
+        "metadata": metadata or {},
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "correlation_id": get_correlation_id(),
+    }
+
+
+async def _write_audit_row(
+    session: AsyncSession,
+    instance: ToolInstance,
+    event_type: str,
+    created_by: uuid.UUID | None = None,
+    status: str | None = None,
+    message: str | None = None,
+    metadata: dict | None = None,
+) -> InstanceEvent:
+    """Persist an instance_events audit row."""
+    row = InstanceEvent(
+        instance_id=instance.id,
+        event_type=event_type.replace("instance.", ""),
+        status=status or instance.status,
+        message=message,
+        created_by=created_by,
+        event_metadata=metadata or {},
+    )
+    session.add(row)
+    await session.commit()
+    return row
+
+
+async def publish_lifecycle_event(
+    event_bus: InstanceEventBus,
+    session: AsyncSession,
+    instance: ToolInstance,
+    event_type: str,
+    created_by: uuid.UUID | None = None,
+    status: str | None = None,
+    message: str | None = None,
+    metadata: dict | None = None,
+) -> None:
+    """Publish a lifecycle event and write an audit row after DB commit.
+
+    Args:
+        event_bus: The global event bus.
+        session: Active async DB session.
+        instance: The affected tool instance.
+        event_type: One of instance.created, instance.started, etc.
+        created_by: User ID for user-initiated actions; None for system.
+        status: Optional status override.
+        message: Optional human-readable message.
+        metadata: Optional extra metadata.
+    """
+    payload = _build_payload(
+        event_type=event_type,
+        instance=instance,
+        status=status,
+        message=message,
+        metadata=metadata,
+    )
+
+    # Write audit row
+    await _write_audit_row(
+        session=session,
+        instance=instance,
+        event_type=event_type,
+        created_by=created_by,
+        status=status or instance.status,
+        message=message,
+        metadata=metadata,
+    )
+
+    # Publish to bus
+    await event_bus.publish(event_type, payload)

apps/api/tests/integration/test_events.py

@@ -0,0 +1,268 @@
+"""Integration tests for SSE endpoint and lifecycle event flow."""
+
+import asyncio
+import uuid
+from collections.abc import Generator
+from typing import Any
+
+import pytest
+from fastapi.testclient import TestClient
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.api import events as events_module
+from src.auth.session import decode_session_cookie
+from src.config import Settings
+from src.models.git_repository import GitRepository
+from src.models.instance_event import InstanceEvent
+from src.models.project import Project
+from src.models.tool_instance import ToolInstance
+from src.models.tool_type import ToolType
+from src.services.event_bus import InstanceEventBus, InstanceEventPayload
+
+
+@pytest.fixture
+def event_bus() -> Generator[InstanceEventBus, None, None]:
+    bus = InstanceEventBus()
+    bus._reset_for_testing()
+    yield bus
+    bus._reset_for_testing()
+
+
+@pytest.fixture
+def sample_payload() -> InstanceEventPayload:
+    return {
+        "event": "instance.started",
+        "instance_id": str(uuid.uuid4()),
+        "status": "starting",
+        "message": "Container starting...",
+        "metadata": {},
+        "timestamp": "2026-05-28T12:00:00Z",
+        "correlation_id": str(uuid.uuid4()),
+    }
+
+
+def _get_user_id_from_client(client: TestClient) -> uuid.UUID | None:
+    settings = Settings()
+    cookie = client.cookies.get("session")
+    if not cookie:
+        return None
+    session = decode_session_cookie(settings=settings, cookie_value=cookie)
+    if session and "user_id" in session:
+        return uuid.UUID(session["user_id"])
+    return None
+
+
+@pytest.mark.integration
+def test_sse_requires_auth(test_client: TestClient) -> None:
+    response = test_client.get("/events/stream")
+    assert response.status_code == 401
+
+
+@pytest.mark.integration
+def test_sse_enforces_connection_limit(authenticated_client: TestClient) -> None:
+    user_id = _get_user_id_from_client(authenticated_client)
+    assert user_id is not None
+
+    events_module._connection_counts[user_id] = events_module.MAX_CONNECTIONS_PER_USER
+    try:
+        response = authenticated_client.get("/events/stream")
+        assert response.status_code == 429
+    finally:
+        events_module._connection_counts.pop(user_id, None)
+
+
+@pytest.mark.integration
+def test_sse_event_generator_format() -> None:
+    """Test the SSE endpoint is registered."""
+    from src.api.events import router
+
+    route_paths = [getattr(r, "path", "") for r in router.routes]
+    assert any("/stream" in str(p) for p in route_paths)
+
+
+@pytest.mark.asyncio
+@pytest.mark.integration
+async def test_lifecycle_hook_publishes_event_and_persists(
+    authenticated_client: TestClient,
+    db_session: AsyncSession,
+    event_bus: InstanceEventBus,
+) -> None:
+    """Test that the lifecycle hook publishes an event and persists an audit row."""
+    user_id = _get_user_id_from_client(authenticated_client)
+    assert user_id is not None
+
+    project = Project(
+        id=uuid.uuid4(),
+        name="test-project",
+        description="Test",
+        owner_id=user_id,
+    )
+    repo = GitRepository(
+        id=uuid.uuid4(),
+        name="test-repo",
+        path="/tmp/test-repo",
+        project_id=project.id,
+        owner_id=user_id,
+        remote_url="https://github.com/test/repo.git",
+    )
+    tool_type = ToolType(
+        id=uuid.uuid4(),
+        name="test-tool",
+        display_name="Test Tool",
+        category="other",
+        interface_type="web",
+        requires_port=True,
+        default_port=8080,
+        definition_type="legacy",
+        compose_template="version: '3.8'\nservices:\n  app:\n    image: alpine\n    command: sleep 3600\n",
+    )
+    db_session.add_all([project, repo, tool_type])
+    await db_session.commit()
+
+    instance = ToolInstance(
+        id=uuid.uuid4(),
+        name="test-instance",
+        display_name="Test Instance",
+        tool_type_id=tool_type.id,
+        repository_id=repo.id,
+        project_id=project.id,
+        owner_id=user_id,
+        status="pending",
+        compose_path="/tmp/test-compose.yml",
+        port=8080,
+    )
+    db_session.add(instance)
+    await db_session.commit()
+
+    received: list[Any] = []
+
+    def subscriber(payload: InstanceEventPayload) -> None:
+        received.append(payload)
+
+    event_bus.subscribe("instance.created", subscriber)
+
+    from src.services.lifecycle_hooks import publish_lifecycle_event
+
+    await publish_lifecycle_event(
+        event_bus=event_bus,
+        session=db_session,
+        instance=instance,
+        event_type="instance.created",
+        created_by=user_id,
+        status="pending",
+        message="Instance created",
+    )
+
+    assert len(received) == 1
+    assert received[0]["event"] == "instance.created"
+
+    result = await db_session.execute(
+        select(InstanceEvent).where(InstanceEvent.instance_id == instance.id)
+    )
+    rows = result.scalars().all()
+    assert len(rows) == 1
+    assert rows[0].event_type == "created"
+    assert rows[0].created_by == user_id
+
+
+@pytest.mark.asyncio
+@pytest.mark.integration
+async def test_lifecycle_event_persists_audit_row(
+    authenticated_client: TestClient,
+    db_session: AsyncSession,
+    event_bus: InstanceEventBus,
+) -> None:
+    """Test that publishing a lifecycle event persists an audit row."""
+    user_id = _get_user_id_from_client(authenticated_client)
+    assert user_id is not None
+
+    project = Project(
+        id=uuid.uuid4(),
+        name="test-project",
+        description="Test",
+        owner_id=user_id,
+    )
+    repo = GitRepository(
+        id=uuid.uuid4(),
+        name="test-repo",
+        path="/tmp/test-repo",
+        project_id=project.id,
+        owner_id=user_id,
+        remote_url="https://github.com/test/repo.git",
+    )
+    tool_type = ToolType(
+        id=uuid.uuid4(),
+        name="test-tool-2",
+        display_name="Test Tool 2",
+        category="other",
+        interface_type="web",
+        requires_port=True,
+        default_port=8080,
+        definition_type="legacy",
+        compose_template="version: '3.8'\nservices:\n  app:\n    image: alpine\n    command: sleep 3600\n",
+    )
+    db_session.add_all([project, repo, tool_type])
+    await db_session.commit()
+
+    instance = ToolInstance(
+        id=uuid.uuid4(),
+        name="test-instance",
+        display_name="Test Instance",
+        tool_type_id=tool_type.id,
+        repository_id=repo.id,
+        project_id=project.id,
+        owner_id=user_id,
+        status="running",
+        compose_path="/tmp/test-compose.yml",
+        port=8080,
+    )
+    db_session.add(instance)
+    await db_session.commit()
+
+    from src.services.lifecycle_hooks import publish_lifecycle_event
+
+    await publish_lifecycle_event(
+        event_bus=event_bus,
+        session=db_session,
+        instance=instance,
+        event_type="instance.stopped",
+        created_by=user_id,
+        status="stopped",
+        message="Instance stopped",
+    )
+
+    result = await db_session.execute(
+        select(InstanceEvent).where(InstanceEvent.instance_id == instance.id)
+    )
+    rows = result.scalars().all()
+    assert len(rows) == 1
+    assert rows[0].event_type == "stopped"
+    assert rows[0].status == "stopped"
+    assert rows[0].created_by == user_id
+
+
+@pytest.mark.integration
+def test_event_bus_pubsub(event_bus: InstanceEventBus) -> None:
+    """Test that the event bus delivers events to subscribers."""
+    received: list[InstanceEventPayload] = []
+
+    def handler(payload: InstanceEventPayload) -> None:
+        received.append(payload)
+
+    event_bus.subscribe("test.event", handler)
+
+    payload: InstanceEventPayload = {
+        "event": "test.event",
+        "instance_id": str(uuid.uuid4()),
+        "status": "running",
+        "message": "Test",
+        "metadata": {},
+        "timestamp": "2026-05-28T12:00:00Z",
+        "correlation_id": str(uuid.uuid4()),
+    }
+
+    asyncio.run(event_bus.publish("test.event", payload))
+
+    assert len(received) == 1
+    assert received[0]["event"] == "test.event"

apps/api/tests/unit/test_event_bus.py

@@ -0,0 +1,148 @@
+"""Unit tests for InstanceEventBus."""
+
+import asyncio
+import uuid
+from typing import Any
+
+import pytest
+
+from src.services.event_bus import InstanceEventBus, InstanceEventPayload
+
+
+@pytest.fixture
+def event_bus() -> InstanceEventBus:
+    """Provide a fresh EventBus instance with reset singleton state."""
+    bus = InstanceEventBus()
+    bus._reset_for_testing()
+    return bus
+
+
+@pytest.fixture
+def sample_payload() -> InstanceEventPayload:
+    """Provide a sample event payload."""
+    return {
+        "event": "instance.started",
+        "instance_id": str(uuid.uuid4()),
+        "status": "starting",
+        "message": "Container starting...",
+        "metadata": {},
+        "timestamp": "2026-05-28T12:00:00Z",
+        "correlation_id": str(uuid.uuid4()),
+    }
+
+
+@pytest.mark.unit
+async def test_publish_delivers_to_all_subscribers(
+    event_bus: InstanceEventBus,
+    sample_payload: InstanceEventPayload,
+) -> None:
+    """All subscribed callbacks should receive the published payload."""
+    received: list[Any] = []
+
+    def callback_1(payload: InstanceEventPayload) -> None:
+        received.append(("callback_1", payload))
+
+    def callback_2(payload: InstanceEventPayload) -> None:
+        received.append(("callback_2", payload))
+
+    def callback_3(payload: InstanceEventPayload) -> None:
+        received.append(("callback_3", payload))
+
+    event_bus.subscribe("instance.started", callback_1)
+    event_bus.subscribe("instance.started", callback_2)
+    event_bus.subscribe("instance.started", callback_3)
+
+    await event_bus.publish("instance.started", sample_payload)
+
+    assert len(received) == 3
+    assert received[0][0] == "callback_1"
+    assert received[1][0] == "callback_2"
+    assert received[2][0] == "callback_3"
+
+
+@pytest.mark.unit
+async def test_subscriber_exception_isolation(
+    event_bus: InstanceEventBus,
+    sample_payload: InstanceEventPayload,
+) -> None:
+    """If one subscriber raises, others should still receive the event."""
+    received: list[str] = []
+
+    def bad_callback(_payload: InstanceEventPayload) -> None:
+        raise RuntimeError("boom")
+
+    def good_callback(_payload: InstanceEventPayload) -> None:
+        received.append("good_callback")
+
+    event_bus.subscribe("instance.started", bad_callback)
+    event_bus.subscribe("instance.started", good_callback)
+
+    # Should not raise
+    await event_bus.publish("instance.started", sample_payload)
+
+    assert received == ["good_callback"]
+
+
+@pytest.mark.unit
+async def test_unsubscribe_removes_callback(
+    event_bus: InstanceEventBus,
+    sample_payload: InstanceEventPayload,
+) -> None:
+    """After unsubscribing, the callback should not be called."""
+    received: list[str] = []
+
+    def callback(_payload: InstanceEventPayload) -> None:
+        received.append("callback")
+
+    unsubscribe = event_bus.subscribe("instance.started", callback)
+    unsubscribe()
+
+    await event_bus.publish("instance.started", sample_payload)
+
+    assert received == []
+
+
+@pytest.mark.unit
+async def test_publish_to_empty_subscriber_list(
+    event_bus: InstanceEventBus,
+    sample_payload: InstanceEventPayload,
+) -> None:
+    """Publishing to an event type with no subscribers should not raise."""
+    await event_bus.publish("instance.started", sample_payload)
+
+
+@pytest.mark.unit
+async def test_async_subscriber_supported(
+    event_bus: InstanceEventBus,
+    sample_payload: InstanceEventPayload,
+) -> None:
+    """Async callbacks should be awaited correctly."""
+    received: list[str] = []
+
+    async def async_callback(_payload: InstanceEventPayload) -> None:
+        await asyncio.sleep(0)
+        received.append("async_callback")
+
+    event_bus.subscribe("instance.started", async_callback)
+    await event_bus.publish("instance.started", sample_payload)
+
+    assert received == ["async_callback"]
+
+
+@pytest.mark.unit
+async def test_unsubscribe_all_clears_subscribers(
+    event_bus: InstanceEventBus,
+    sample_payload: InstanceEventPayload,
+) -> None:
+    """unsubscribe_all should remove all callbacks for an event type."""
+    received: list[str] = []
+
+    def callback(_payload: InstanceEventPayload) -> None:
+        received.append("callback")
+
+    event_bus.subscribe("instance.started", callback)
+    event_bus.unsubscribe_all("instance.started")
+
+    await event_bus.publish("instance.started", sample_payload)
+
+    assert received == []

apps/api/tests/unit/test_health_monitor.py

@@ -0,0 +1,292 @@
+"""Unit tests for HealthMonitor state-transition logic."""
+
+import asyncio
+import uuid
+from contextlib import suppress
+from unittest.mock import patch
+
+import pytest
+from sqlalchemy import select
+
+from src.models.health_check import HealthCheck
+from src.models.tool_instance import ToolInstance
+from src.models.user import User
+from src.services.event_bus import InstanceEventBus, InstanceEventPayload
+from src.services.health_monitor import HealthMonitor, HealthSnapshot
+
+
+@pytest.fixture
+def event_bus() -> InstanceEventBus:
+    """Provide a fresh EventBus instance."""
+    bus = InstanceEventBus()
+    bus._reset_for_testing()
+    return bus
+
+
+@pytest.fixture
+def health_monitor(event_bus: InstanceEventBus) -> HealthMonitor:
+    """Provide a HealthMonitor with a short poll interval for testing."""
+    monitor = HealthMonitor(event_bus)
+    monitor.POLL_INTERVAL_SECONDS = 0.1
+    return monitor
+
+
+async def _create_running_instance(db_session) -> ToolInstance:
+    """Helper to create a user and a running tool instance."""
+    user = User(
+        id=uuid.uuid4(),
+        email="hm@example.com",
+        name="HM Test",
+        authentik_id="auth-hm",
+    )
+    db_session.add(user)
+    await db_session.commit()
+
+    instance = ToolInstance(
+        id=uuid.uuid4(),
+        name="hm-test-instance",
+        display_name="HM Test Instance",
+        tool_type_id=uuid.uuid4(),
+        repository_id=uuid.uuid4(),
+        project_id=uuid.uuid4(),
+        owner_id=user.id,
+        status="running",
+        container_id="container123",
+        public_url="https://example.trycloudflare.com",
+    )
+    db_session.add(instance)
+    await db_session.commit()
+    return instance
+
+
+@pytest.mark.unit
+async def test_detects_container_crash(
+    db_session,
+    event_bus: InstanceEventBus,
+    health_monitor: HealthMonitor,
+) -> None:
+    """Monitor should detect exited container and publish error event."""
+    instance = await _create_running_instance(db_session)
+
+    events_captured: list[InstanceEventPayload] = []
+
+    def capture_event(payload: InstanceEventPayload) -> None:
+        events_captured.append(payload)
+
+    event_bus.subscribe("instance.error", capture_event)
+
+    with (
+        patch(
+            "src.services.health_monitor.get_container_status",
+            return_value={"status": "exited", "exit_code": 137, "health": None},
+        ),
+        patch(
+            "src.services.health_monitor.check_tunnel_health",
+            return_value={"healthy": False, "tunnel_status": "not_applicable"},
+        ),
+    ):
+        await health_monitor._check_instance(db_session, instance)
+
+    # Refresh instance from DB
+    await db_session.refresh(instance)
+    assert instance.status == "error"
+
+    # Event published
+    assert len(events_captured) == 1
+    assert events_captured[0]["event"] == "instance.error"
+    assert events_captured[0]["status"] == "error"
+    assert events_captured[0]["metadata"]["exit_code"] == 137
+
+    # Health check row inserted
+    result = await db_session.execute(
+        select(HealthCheck).where(HealthCheck.instance_id == instance.id)
+    )
+    check = result.scalar_one()
+    assert check.container_status == "exited"
+    assert check.exit_code == 137
+
+
+@pytest.mark.unit
+async def test_detects_tunnel_failure(
+    db_session,
+    event_bus: InstanceEventBus,
+    health_monitor: HealthMonitor,
+) -> None:
+    """Monitor should detect tunnel failure and mark unhealthy."""
+    instance = await _create_running_instance(db_session)
+
+    events_captured: list[InstanceEventPayload] = []
+
+    def capture_event(payload: InstanceEventPayload) -> None:
+        events_captured.append(payload)
+
+    event_bus.subscribe("instance.health_changed", capture_event)
+
+    with (
+        patch(
+            "src.services.health_monitor.get_container_status",
+            return_value={"status": "running", "exit_code": None, "health": "healthy"},
+        ),
+        patch(
+            "src.services.health_monitor.check_tunnel_health",
+            return_value={
+                "healthy": False,
+                "tunnel_status": "error_response",
+                "status_code": 502,
+            },
+        ),
+    ):
+        await health_monitor._check_instance(db_session, instance)
+
+    await db_session.refresh(instance)
+    assert instance.status == "unhealthy"
+
+    assert len(events_captured) == 1
+    assert events_captured[0]["event"] == "instance.health_changed"
+    assert events_captured[0]["status"] == "unhealthy"
+    assert events_captured[0]["metadata"]["previous_status"] == "running"
+
+    result = await db_session.execute(
+        select(HealthCheck).where(HealthCheck.instance_id == instance.id)
+    )
+    check = result.scalar_one()
+    assert check.tunnel_healthy is False
+
+
+@pytest.mark.unit
+async def test_detects_recovery(
+    db_session,
+    event_bus: InstanceEventBus,
+    health_monitor: HealthMonitor,
+) -> None:
+    """Monitor should detect recovery from unhealthy to running."""
+    instance = await _create_running_instance(db_session)
+    instance.status = "unhealthy"
+    await db_session.commit()
+
+    # Seed last known state as unhealthy
+    health_monitor._last_known_state[instance.id] = HealthSnapshot(
+        container_status="running",
+        container_healthy=None,
+        tunnel_healthy=False,
+        exit_code=None,
+    )
+
+    events_captured: list[InstanceEventPayload] = []
+
+    def capture_event(payload: InstanceEventPayload) -> None:
+        events_captured.append(payload)
+
+    event_bus.subscribe("instance.health_changed", capture_event)
+
+    with (
+        patch(
+            "src.services.health_monitor.get_container_status",
+            return_value={"status": "running", "exit_code": None, "health": None},
+        ),
+        patch(
+            "src.services.health_monitor.check_tunnel_health",
+            return_value={
+                "healthy": True,
+                "tunnel_status": "healthy",
+                "status_code": 200,
+            },
+        ),
+    ):
+        await health_monitor._check_instance(db_session, instance)
+
+    await db_session.refresh(instance)
+    assert instance.status == "running"
+
+    assert len(events_captured) == 1
+    assert events_captured[0]["status"] == "running"
+    assert events_captured[0]["metadata"]["previous_status"] == "unhealthy"
+
+    result = await db_session.execute(
+        select(HealthCheck).where(HealthCheck.instance_id == instance.id)
+    )
+    check = result.scalar_one()
+    assert check.tunnel_healthy is True
+
+
+@pytest.mark.unit
+async def test_skips_writes_when_no_state_change(
+    db_session,
+    event_bus: InstanceEventBus,
+    health_monitor: HealthMonitor,
+) -> None:
+    """Two identical polls should result in only one health_checks row."""
+    instance = await _create_running_instance(db_session)
+
+    with (
+        patch(
+            "src.services.health_monitor.get_container_status",
+            return_value={"status": "running", "exit_code": None, "health": None},
+        ),
+        patch(
+            "src.services.health_monitor.check_tunnel_health",
+            return_value={
+                "healthy": True,
+                "tunnel_status": "healthy",
+                "status_code": 200,
+            },
+        ),
+    ):
+        await health_monitor._check_instance(db_session, instance)
+        await health_monitor._check_instance(db_session, instance)
+
+    result = await db_session.execute(
+        select(HealthCheck).where(HealthCheck.instance_id == instance.id)
+    )
+    assert len(result.scalars().all()) == 1
+
+
+@pytest.mark.unit
+async def test_docker_exception_resilience(
+    db_session,
+    event_bus: InstanceEventBus,
+    health_monitor: HealthMonitor,
+) -> None:
+    """Docker exception should be caught and not propagate."""
+    instance = await _create_running_instance(db_session)
+
+    events_captured: list[InstanceEventPayload] = []
+
+    def capture_event(payload: InstanceEventPayload) -> None:
+        events_captured.append(payload)
+
+    event_bus.subscribe("instance.error", capture_event)
+    event_bus.subscribe("instance.health_changed", capture_event)
+
+    with patch(
+        "src.services.health_monitor.get_container_status",
+        side_effect=RuntimeError("docker exploded"),
+    ):
+        # Should not raise
+        await health_monitor._check_instance(db_session, instance)
+
+    # No DB writes
+    result = await db_session.execute(
+        select(HealthCheck).where(HealthCheck.instance_id == instance.id)
+    )
+    assert result.scalar_one_or_none() is None
+
+    # No events published
+    assert events_captured == []
+
+
+@pytest.mark.unit
+async def test_monitor_start_stop(health_monitor: HealthMonitor) -> None:
+    """Start and stop should manage the background task."""
+    health_monitor.start()
+    task = health_monitor._task
+    assert task is not None
+    assert not task.done()
+
+    health_monitor.stop()
+    if task is not None and not task.done():
+        with suppress(asyncio.CancelledError):
+            await task
+    assert task is not None
+    assert task.cancelled() or task.done()
+    assert health_monitor._last_known_state == {}

apps/api/tests/unit/test_monitoring_models.py

@@ -0,0 +1,143 @@
+"""Unit tests for monitoring models and migration compatibility."""
+
+import uuid
+from datetime import datetime
+
+import pytest
+from sqlalchemy import select
+
+from src.models.health_check import HealthCheck
+from src.models.instance_event import InstanceEvent
+from src.models.tool_instance import ToolInstance
+from src.models.user import User
+
+
+@pytest.mark.unit
+async def test_instance_event_creation(db_session) -> None:
+    """InstanceEvent model can be created and persisted."""
+    user = User(
+        id=uuid.uuid4(),
+        email="test@example.com",
+        name="Test",
+        authentik_id="auth-1",
+    )
+    db_session.add(user)
+    await db_session.commit()
+
+    instance = ToolInstance(
+        id=uuid.uuid4(),
+        name="test-instance",
+        display_name="Test Instance",
+        tool_type_id=uuid.uuid4(),
+        repository_id=uuid.uuid4(),
+        project_id=uuid.uuid4(),
+        owner_id=user.id,
+        status="pending",
+    )
+    db_session.add(instance)
+    await db_session.commit()
+
+    event = InstanceEvent(
+        instance_id=instance.id,
+        event_type="started",
+        status="starting",
+        message="Container starting...",
+        created_by=user.id,
+        event_metadata={"previous_status": "pending"},
+    )
+    db_session.add(event)
+    await db_session.commit()
+    await db_session.refresh(event)
+
+    assert event.id is not None
+    assert event.instance_id == instance.id
+    assert event.event_type == "started"
+    assert event.status == "starting"
+    assert event.created_by == user.id
+    assert event.event_metadata == {"previous_status": "pending"}
+    assert isinstance(event.created_at, datetime)
+
+
+@pytest.mark.unit
+async def test_health_check_creation(db_session) -> None:
+    """HealthCheck model can be created and persisted."""
+    user = User(
+        id=uuid.uuid4(),
+        email="test2@example.com",
+        name="Test2",
+        authentik_id="auth-2",
+    )
+    db_session.add(user)
+    await db_session.commit()
+
+    instance = ToolInstance(
+        id=uuid.uuid4(),
+        name="test-instance-2",
+        display_name="Test Instance 2",
+        tool_type_id=uuid.uuid4(),
+        repository_id=uuid.uuid4(),
+        project_id=uuid.uuid4(),
+        owner_id=user.id,
+        status="running",
+    )
+    db_session.add(instance)
+    await db_session.commit()
+
+    check = HealthCheck(
+        instance_id=instance.id,
+        container_status="running",
+        container_healthy=True,
+        tunnel_healthy=True,
+        exit_code=None,
+        probe_status="passed",
+        probe_output="OK",
+    )
+    db_session.add(check)
+    await db_session.commit()
+    await db_session.refresh(check)
+
+    assert check.id is not None
+    assert check.instance_id == instance.id
+    assert check.container_status == "running"
+    assert check.container_healthy is True
+    assert check.tunnel_healthy is True
+    assert isinstance(check.checked_at, datetime)
+
+
+@pytest.mark.unit
+async def test_instance_event_query_by_instance(db_session) -> None:
+    """InstanceEvent rows can be queried by instance_id."""
+    user = User(
+        id=uuid.uuid4(),
+        email="test3@example.com",
+        name="Test3",
+        authentik_id="auth-3",
+    )
+    db_session.add(user)
+    await db_session.commit()
+
+    instance = ToolInstance(
+        id=uuid.uuid4(),
+        name="test-instance-3",
+        display_name="Test Instance 3",
+        tool_type_id=uuid.uuid4(),
+        repository_id=uuid.uuid4(),
+        project_id=uuid.uuid4(),
+        owner_id=user.id,
+        status="pending",
+    )
+    db_session.add(instance)
+    await db_session.commit()
+
+    event = InstanceEvent(
+        instance_id=instance.id,
+        event_type="created",
+        status="pending",
+    )
+    db_session.add(event)
+    await db_session.commit()
+
+    result = await db_session.execute(
+        select(InstanceEvent).where(InstanceEvent.instance_id == instance.id)
+    )
+    assert result.scalar_one() is not None

apps/web/package-lock.json

@@ -16,6 +16,7 @@
         "react-dom": "^18.2.0",
         "react-router-dom": "^6.20.0",
         "react-simple-code-editor": "^0.14.1",
+        "sonner": "^1.7.4",
         "tailwindcss": "^3.3.0",
         "xterm": "^5.3.0",
         "xterm-addon-fit": "^0.8.0",
@@ -896,24 +897,6 @@
         "node": ">=12"
       }
     },
-    "node_modules/@esbuild/netbsd-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.0.tgz",
-      "integrity": "sha512-CR/RYotgtCKwtftMwJlUU7xCVNg3lMYZ0RzTmAHSfLCXw3NtZtNpswLEj/Kkf6kEL3Gw+BpOekRX0BYCtklhUw==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "netbsd"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
     "node_modules/@esbuild/netbsd-x64": {
       "version": "0.21.5",
       "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.21.5.tgz",
@@ -931,24 +914,6 @@
         "node": ">=12"
       }
     },
-    "node_modules/@esbuild/openbsd-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.0.tgz",
-      "integrity": "sha512-cXb5vApOsRsxsEl4mcZ1XY3D4DzcoMxR/nnc4IyqYs0rTI8ZKmW6kyyg+11Z8yvgMfAEldKzP7AdP64HnSC/6g==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "openbsd"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
     "node_modules/@esbuild/openbsd-x64": {
       "version": "0.21.5",
       "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.21.5.tgz",
@@ -966,24 +931,6 @@
         "node": ">=12"
       }
     },
-    "node_modules/@esbuild/openharmony-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.0.tgz",
-      "integrity": "sha512-FLGfyizszcef5C3YtoyQDACyg95+dndv79i2EekILBofh5wpCa1KuBqOWKrEHZg3zrL3t5ouE5jgr94vA+Wb2w==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "openharmony"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
     "node_modules/@esbuild/sunos-x64": {
       "version": "0.21.5",
       "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.21.5.tgz",
@@ -5522,6 +5469,16 @@
         "node": ">=8"
       }
     },
+    "node_modules/sonner": {
+      "version": "1.7.4",
+      "resolved": "https://registry.npmjs.org/sonner/-/sonner-1.7.4.tgz",
+      "integrity": "sha512-DIS8z4PfJRbIyfVFDVnK9rO3eYDtse4Omcm6bt0oEr5/jtLgysmjuBl1frJ9E/EQZrFmKx2A8m/s5s9CRXIzhw==",
+      "license": "MIT",
+      "peerDependencies": {
+        "react": "^18.0.0 || ^19.0.0 || ^19.0.0-rc",
+        "react-dom": "^18.0.0 || ^19.0.0 || ^19.0.0-rc"
+      }
+    },
     "node_modules/source-map-js": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
@@ -6107,420 +6064,6 @@
         }
       }
     },
-    "node_modules/vitest/node_modules/@esbuild/aix-ppc64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.0.tgz",
-      "integrity": "sha512-lhRUCeuOyJQURhTxl4WkpFTjIsbDayJHih5kZC1giwE+MhIzAb7mEsQMqMf18rHLsrb5qI1tafG20mLxEWcWlA==",
-      "cpu": [
-        "ppc64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "aix"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/vitest/node_modules/@esbuild/android-arm": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.0.tgz",
-      "integrity": "sha512-wqh0ByljabXLKHeWXYLqoJ5jKC4XBaw6Hk08OfMrCRd2nP2ZQ5eleDZC41XHyCNgktBGYMbqnrJKq/K/lzPMSQ==",
-      "cpu": [
-        "arm"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "android"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/vitest/node_modules/@esbuild/android-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.0.tgz",
-      "integrity": "sha512-+WzIXQOSaGs33tLEgYPYe/yQHf0WTU0X42Jca3y8NWMbUVhp7rUnw+vAsRC/QiDrdD31IszMrZy+qwPOPjd+rw==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "android"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/vitest/node_modules/@esbuild/android-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.0.tgz",
-      "integrity": "sha512-+VJggoaKhk2VNNqVL7f6S189UzShHC/mR9EE8rDdSkdpN0KflSwWY/gWjDrNxxisg8Fp1ZCD9jLMo4m0OUfeUA==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "android"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/vitest/node_modules/@esbuild/darwin-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.0.tgz",
-      "integrity": "sha512-0T+A9WZm+bZ84nZBtk1ckYsOvyA3x7e2Acj1KdVfV4/2tdG4fzUp91YHx+GArWLtwqp77pBXVCPn2We7Letr0Q==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/vitest/node_modules/@esbuild/darwin-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.0.tgz",
-      "integrity": "sha512-fyzLm/DLDl/84OCfp2f/XQ4flmORsjU7VKt8HLjvIXChJoFFOIL6pLJPH4Yhd1n1gGFF9mPwtlN5Wf82DZs+LQ==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/vitest/node_modules/@esbuild/freebsd-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.0.tgz",
-      "integrity": "sha512-l9GeW5UZBT9k9brBYI+0WDffcRxgHQD8ShN2Ur4xWq/NFzUKm3k5lsH4PdaRgb2w7mI9u61nr2gI2mLI27Nh3Q==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "freebsd"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/vitest/node_modules/@esbuild/freebsd-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.0.tgz",
-      "integrity": "sha512-BXoQai/A0wPO6Es3yFJ7APCiKGc1tdAEOgeTNy3SsB491S3aHn4S4r3e976eUnPdU+NbdtmBuLncYir2tMU9Nw==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "freebsd"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/vitest/node_modules/@esbuild/linux-arm": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.0.tgz",
-      "integrity": "sha512-CjaaREJagqJp7iTaNQjjidaNbCKYcd4IDkzbwwxtSvjI7NZm79qiHc8HqciMddQ6CKvJT6aBd8lO9kN/ZudLlw==",
-      "cpu": [
-        "arm"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/vitest/node_modules/@esbuild/linux-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.0.tgz",
-      "integrity": "sha512-RVyzfb3FWsGA55n6WY0MEIEPURL1FcbhFE6BffZEMEekfCzCIMtB5yyDcFnVbTnwk+CLAgTujmV/Lgvih56W+A==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/vitest/node_modules/@esbuild/linux-ia32": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.0.tgz",
-      "integrity": "sha512-KBnSTt1kxl9x70q+ydterVdl+Cn0H18ngRMRCEQfrbqdUuntQQ0LoMZv47uB97NljZFzY6HcfqEZ2SAyIUTQBQ==",
-      "cpu": [
-        "ia32"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/vitest/node_modules/@esbuild/linux-loong64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.0.tgz",
-      "integrity": "sha512-zpSlUce1mnxzgBADvxKXX5sl8aYQHo2ezvMNI8I0lbblJtp8V4odlm3Yzlj7gPyt3T8ReksE6bK+pT3WD+aJRg==",
-      "cpu": [
-        "loong64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/vitest/node_modules/@esbuild/linux-mips64el": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.0.tgz",
-      "integrity": "sha512-2jIfP6mmjkdmeTlsX/9vmdmhBmKADrWqN7zcdtHIeNSCH1SqIoNI63cYsjQR8J+wGa4Y5izRcSHSm8K3QWmk3w==",
-      "cpu": [
-        "mips64el"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/vitest/node_modules/@esbuild/linux-ppc64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.0.tgz",
-      "integrity": "sha512-bc0FE9wWeC0WBm49IQMPSPILRocGTQt3j5KPCA8os6VprfuJ7KD+5PzESSrJ6GmPIPJK965ZJHTUlSA6GNYEhg==",
-      "cpu": [
-        "ppc64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/vitest/node_modules/@esbuild/linux-riscv64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.0.tgz",
-      "integrity": "sha512-SQPZOwoTTT/HXFXQJG/vBX8sOFagGqvZyXcgLA3NhIqcBv1BJU1d46c0rGcrij2B56Z2rNiSLaZOYW5cUk7yLQ==",
-      "cpu": [
-        "riscv64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/vitest/node_modules/@esbuild/linux-s390x": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.0.tgz",
-      "integrity": "sha512-SCfR0HN8CEEjnYnySJTd2cw0k9OHB/YFzt5zgJEwa+wL/T/raGWYMBqwDNAC6dqFKmJYZoQBRfHjgwLHGSrn3Q==",
-      "cpu": [
-        "s390x"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/vitest/node_modules/@esbuild/linux-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.0.tgz",
-      "integrity": "sha512-us0dSb9iFxIi8srnpl931Nvs65it/Jd2a2K3qs7fz2WfGPHqzfzZTfec7oxZJRNPXPnNYZtanmRc4AL/JwVzHQ==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/vitest/node_modules/@esbuild/netbsd-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.0.tgz",
-      "integrity": "sha512-nU1yhmYutL+fQ71Kxnhg8uEOdC0pwEW9entHykTgEbna2pw2dkbFSMeqjjyHZoCmt8SBkOSvV+yNmm94aUrrqw==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "netbsd"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/vitest/node_modules/@esbuild/openbsd-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.0.tgz",
-      "integrity": "sha512-8wZM2qqtv9UP3mzy7HiGYNH/zjTA355mpeuA+859TyR+e+Tc08IHYpLJuMsfpDJwoLo1ikIJI8jC3GFjnRClzA==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "openbsd"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/vitest/node_modules/@esbuild/sunos-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.0.tgz",
-      "integrity": "sha512-1ZgjUoEdHZZl/YlV76TSCz9Hqj9h9YmMGAgAPYd+q4SicWNX3G5GCyx9uhQWSLcbvPW8Ni7lj4gDa1T40akdlw==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "sunos"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/vitest/node_modules/@esbuild/win32-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.0.tgz",
-      "integrity": "sha512-Q9StnDmQ/enxnpxCCLSg0oo4+34B9TdXpuyPeTedN/6+iXBJ4J+zwfQI28u/Jl40nOYAxGoNi7mFP40RUtkmUA==",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/vitest/node_modules/@esbuild/win32-ia32": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.0.tgz",
-      "integrity": "sha512-zF3ag/gfiCe6U2iczcRzSYJKH1DCI+ByzSENHlM2FcDbEeo5Zd2C86Aq0tKUYAJJ1obRP84ymxIAksZUcdztHA==",
-      "cpu": [
-        "ia32"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/vitest/node_modules/@esbuild/win32-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.0.tgz",
-      "integrity": "sha512-pEl1bO9mfAmIC+tW5btTmrKaujg3zGtUmWNdCw/xs70FBjwAL3o9OEKNHvNmnyylD6ubxUERiEhdsL0xBQ9efw==",
-      "cpu": [
-        "x64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "win32"
-      ],
-      "peer": true,
-      "engines": {
-        "node": ">=18"
-      }
-    },
     "node_modules/vitest/node_modules/@vitest/mocker": {
       "version": "4.1.6",
       "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.6.tgz",
@@ -6548,50 +6091,6 @@
         }
       }
     },
-    "node_modules/vitest/node_modules/esbuild": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.0.tgz",
-      "integrity": "sha512-sNR9MHpXSUV/XB4zmsFKN+QgVG82Cc7+/aaxJ8Adi8hyOac+EXptIp45QBPaVyX3N70664wRbTcLTOemCAnyqw==",
-      "dev": true,
-      "hasInstallScript": true,
-      "license": "MIT",
-      "optional": true,
-      "peer": true,
-      "bin": {
-        "esbuild": "bin/esbuild"
-      },
-      "engines": {
-        "node": ">=18"
-      },
-      "optionalDependencies": {
-        "@esbuild/aix-ppc64": "0.28.0",
-        "@esbuild/android-arm": "0.28.0",
-        "@esbuild/android-arm64": "0.28.0",
-        "@esbuild/android-x64": "0.28.0",
-        "@esbuild/darwin-arm64": "0.28.0",
-        "@esbuild/darwin-x64": "0.28.0",
-        "@esbuild/freebsd-arm64": "0.28.0",
-        "@esbuild/freebsd-x64": "0.28.0",
-        "@esbuild/linux-arm": "0.28.0",
-        "@esbuild/linux-arm64": "0.28.0",
-        "@esbuild/linux-ia32": "0.28.0",
-        "@esbuild/linux-loong64": "0.28.0",
-        "@esbuild/linux-mips64el": "0.28.0",
-        "@esbuild/linux-ppc64": "0.28.0",
-        "@esbuild/linux-riscv64": "0.28.0",
-        "@esbuild/linux-s390x": "0.28.0",
-        "@esbuild/linux-x64": "0.28.0",
-        "@esbuild/netbsd-arm64": "0.28.0",
-        "@esbuild/netbsd-x64": "0.28.0",
-        "@esbuild/openbsd-arm64": "0.28.0",
-        "@esbuild/openbsd-x64": "0.28.0",
-        "@esbuild/openharmony-arm64": "0.28.0",
-        "@esbuild/sunos-x64": "0.28.0",
-        "@esbuild/win32-arm64": "0.28.0",
-        "@esbuild/win32-ia32": "0.28.0",
-        "@esbuild/win32-x64": "0.28.0"
-      }
-    },
     "node_modules/vitest/node_modules/picomatch": {
       "version": "4.0.4",
       "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",

apps/web/src/api/events.ts

@@ -0,0 +1,22 @@
+const BASE_URL = import.meta.env.VITE_API_BASE_URL ?? "http://localhost:8000";
+
+export function createEventSource(): EventSource {
+	return new EventSource(`${BASE_URL}/events/stream`, {
+		withCredentials: true,
+	});
+}
+
+export async function probeEventStreamStatus(): Promise<number | null> {
+	try {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), 2000);
+		const res = await fetch(`${BASE_URL}/events/stream`, {
+			credentials: "include",
+			signal: controller.signal,
+		});
+		clearTimeout(timer);
+		return res.status;
+	} catch {
+		return null;
+	}
+}

apps/web/src/components/app-shell.tsx

@@ -7,135 +7,164 @@ import { useTheme } from "../hooks/use-theme";
 import { useAuth } from "../state/auth";
 import { useSessions } from "../state/sessions";
 import { useMobileViewport } from "../hooks/use-mobile-viewport";
+import { EventProvider } from "../state/events";
+import { ToastProvider } from "../state/toast";
+import { EventToastBridge } from "./event-toast-bridge";
 import { Icon } from "./icon";
 import { MobileNav } from "./mobile-nav";
 import type { IconName } from "../utils/icons";
 
-const NAV_ITEMS: { to: string; label: string; icon: IconName; badge?: "sessions" }[] = [
-  { to: "/", label: "Home", icon: "dashboard" },
-  { to: "/sessions", label: "Sessions", icon: "terminal", badge: "sessions" },
-  { to: "/projects", label: "Projects", icon: "projects" },
-  { to: "/tool-workshop", label: "Tool Workshop", icon: "settings" },
-  { to: "/config-profiles", label: "Config Profiles", icon: "folder" },
-  { to: "/settings", label: "Settings", icon: "settings" }
+const NAV_ITEMS: {
+	to: string;
+	label: string;
+	icon: IconName;
+	badge?: "sessions";
+}[] = [
+	{ to: "/", label: "Home", icon: "dashboard" },
+	{ to: "/sessions", label: "Sessions", icon: "terminal", badge: "sessions" },
+	{ to: "/projects", label: "Projects", icon: "projects" },
+	{ to: "/tool-workshop", label: "Tool Workshop", icon: "settings" },
+	{ to: "/config-profiles", label: "Config Profiles", icon: "folder" },
+	{ to: "/settings", label: "Settings", icon: "settings" },
 ];
 
 const SessionItem = ({ session }: { session: Session }) => {
-  const isRunning = session.status === "running";
+	const isRunning = session.status === "running";
 
-  return (
-    <a
-      href={session.url ?? `/projects/${session.project_id}`}
-      target={session.url ? "_blank" : undefined}
-      rel={session.url ? "noopener noreferrer" : undefined}
-      className="nav-item session-item"
-      title={`${session.display_name} (${session.status})`}
-    >
-      <span className={`session-status ${isRunning ? "running" : ""}`} />
-      <Icon name={session.tool_icon as IconName} size="sm" />
-      <span className="session-name">{session.display_name}</span>
-    </a>
-  );
+	return (
+		<a
+			href={session.url ?? `/projects/${session.project_id}`}
+			target={session.url ? "_blank" : undefined}
+			rel={session.url ? "noopener noreferrer" : undefined}
+			className="nav-item session-item"
+			title={`${session.display_name} (${session.status})`}
+		>
+			<span className={`session-status ${isRunning ? "running" : ""}`} />
+			<Icon name={session.tool_icon as IconName} size="sm" />
+			<span className="session-name">{session.display_name}</span>
+		</a>
+	);
 };
 
 export const AppShell = () => {
-  useTheme();
-  const { user, logout } = useAuth();
-  const { sessions, setAllSessions } = useSessions();
-  const location = useLocation();
-  const isMobile = useMobileViewport();
-  const isMobileTerminal = isMobile && location.pathname.includes("/instances/") && location.pathname.includes("/terminal");
+	useTheme();
+	const { user, logout } = useAuth();
+	const { sessions, setAllSessions } = useSessions();
+	const location = useLocation();
+	const isMobile = useMobileViewport();
+	const isMobileTerminal =
+		isMobile &&
+		location.pathname.includes("/instances/") &&
+		location.pathname.includes("/terminal");
 
-  const loadSessions = useCallback(async () => {
-    try {
-      const data = await getUserSessions();
-      setAllSessions(data);
-    } catch {
-      // Silently fail - sessions are optional
-    }
-  }, [setAllSessions]);
+	const loadSessions = useCallback(async () => {
+		try {
+			const data = await getUserSessions();
+			setAllSessions(data);
+		} catch {
+			// Silently fail - sessions are optional
+		}
+	}, [setAllSessions]);
 
-  useEffect(() => {
-    void loadSessions();
-    // Poll every 30 seconds (reduced from 10s to avoid ERR_NETWORK_CHANGED from Docker network changes)
-    const interval = setInterval(() => {
-      void loadSessions();
-    }, 30000);
-    return () => clearInterval(interval);
-  }, [loadSessions]);
+	useEffect(() => {
+		void loadSessions();
+		// Poll every 30 seconds (reduced from 10s to avoid ERR_NETWORK_CHANGED from Docker network changes)
+		const interval = setInterval(() => {
+			void loadSessions();
+		}, 30000);
+		return () => clearInterval(interval);
+	}, [loadSessions]);
 
-  if (isMobileTerminal) {
-    return (
-      <div className="shell mobile-terminal-shell">
-        <Outlet />
-      </div>
-    );
-  }
+	if (isMobileTerminal) {
+		return (
+			<EventProvider>
+				<ToastProvider>
+					<EventToastBridge />
+					<div className="shell mobile-terminal-shell">
+						<Outlet />
+					</div>
+				</ToastProvider>
+			</EventProvider>
+		);
+	}
 
-  return (
-    <div className="shell">
-      <header className="shell-header">
-        <Link className="brand" to="/">
-          Headquarter
-        </Link>
-        <div className="header-actions">
-          <Link className="user-chip" to="/profile">
-            {user?.name ?? "User"}
-          </Link>
-          <button
-            className="ghost-button"
-            onClick={() => {
-              void logout();
-            }}
-            type="button"
-          >
-            <Icon name="logout" size="sm" />
-            Logout
-          </button>
-        </div>
-      </header>
+	return (
+		<EventProvider>
+			<ToastProvider>
+				<EventToastBridge />
+				<div className="shell">
+					<header className="shell-header">
+						<Link className="brand" to="/">
+							Headquarter
+						</Link>
+						<div className="header-actions">
+							<Link className="user-chip" to="/profile">
+								{user?.name ?? "User"}
+							</Link>
+							<button
+								className="ghost-button"
+								onClick={() => {
+									void logout();
+								}}
+								type="button"
+							>
+								<Icon name="logout" size="sm" />
+								Logout
+							</button>
+						</div>
+					</header>
 
-      <div className="shell-body">
-        {!isMobile && (
-          <aside className="shell-nav" aria-label="Primary navigation">
-            {NAV_ITEMS.map((item) => {
-              const activeCount = sessions.filter((s) => s.status === "running").length;
-              return (
-                <NavLink
-                  key={item.to}
-                  to={item.to}
-                  className={({ isActive }) => (isActive ? "nav-item nav-item-active" : "nav-item")}
-                  end={item.to === "/"}
-                >
-                  <Icon name={item.icon} size="sm" />
-                  {item.label}
-                  {item.badge === "sessions" && activeCount > 0 && (
-                    <span className="nav-badge">{activeCount}</span>
-                  )}
-                </NavLink>
-              );
-            })}
-            
-            {sessions.length > 0 && (
-              <>
-                <div className="nav-divider" />
-                <div className="nav-section-title">Live sessions</div>
-                {sessions.map((session) => (
-                  <SessionItem key={session.id} session={session} />
-                ))}
-              </>
-            )}
-          </aside>
-        )}
+					<div className="shell-body">
+						{!isMobile && (
+							<aside className="shell-nav" aria-label="Primary navigation">
+								{NAV_ITEMS.map((item) => {
+									const activeCount = sessions.filter(
+										(s) => s.status === "running",
+									).length;
+									return (
+										<NavLink
+											key={item.to}
+											to={item.to}
+											className={({ isActive }) =>
+												isActive ? "nav-item nav-item-active" : "nav-item"
+											}
+											end={item.to === "/"}
+										>
+											<Icon name={item.icon} size="sm" />
+											{item.label}
+											{item.badge === "sessions" && activeCount > 0 && (
+												<span className="nav-badge">{activeCount}</span>
+											)}
+										</NavLink>
+									);
+								})}
 
-        <main className={`shell-content ${isMobile ? "mobile" : ""}`}>
-          <Outlet />
-        </main>
-      </div>
+								{sessions.length > 0 && (
+									<>
+										<div className="nav-divider" />
+										<div className="nav-section-title">Live sessions</div>
+										{sessions.map((session) => (
+											<SessionItem key={session.id} session={session} />
+										))}
+									</>
+								)}
+							</aside>
+						)}
 
-      {isMobile && (
-        <MobileNav sessionCount={sessions.filter((s) => s.status === "running").length} />
-      )}
-    </div>
-  );
+						<main className={`shell-content ${isMobile ? "mobile" : ""}`}>
+							<Outlet />
+						</main>
+					</div>
+
+					{isMobile && (
+						<MobileNav
+							sessionCount={
+								sessions.filter((s) => s.status === "running").length
+							}
+						/>
+					)}
+				</div>
+			</ToastProvider>
+		</EventProvider>
+	);
 };

apps/web/src/components/event-toast-bridge.tsx

@@ -0,0 +1,19 @@
+import { useEffect, useRef } from "react";
+import { useEventContext } from "../state/events";
+import { handleEventToast } from "./toast-rules";
+
+export function EventToastBridge(): JSX.Element | null {
+	const { events } = useEventContext();
+	const processedRef = useRef<Set<string>>(new Set());
+
+	useEffect(() => {
+		for (const event of events) {
+			const key = `${event.correlation_id}:${event.timestamp}`;
+			if (processedRef.current.has(key)) continue;
+			processedRef.current.add(key);
+			handleEventToast(event);
+		}
+	}, [events]);
+
+	return null;
+}

apps/web/src/components/instance-list.tsx

@@ -3,463 +3,476 @@ import { useNavigate } from "react-router-dom";
 import { Icon } from "./icon";
 import type { ToolInstance } from "../api/sessions";
 import {
-  checkInstanceHealth,
-  deleteInstance,
-  listInstances,
-  recreateInstanceTunnel,
-  restartInstance,
-  startInstance,
-  stopInstance,
+	deleteInstance,
+	listInstances,
+	restartInstance,
+	startInstance,
+	stopInstance,
 } from "../api/sessions";
 import type { ToolType } from "../api/tool_types";
 import { CreateSessionForm } from "./create-session-form";
 import { listConfigProfiles, type ConfigProfile } from "../api/config_profiles";
+import { useEventContext } from "../state/events";
 
-const API_BASE_URL = import.meta.env.VITE_API_BASE_URL ?? "http://localhost:8000";
+const API_BASE_URL =
+	import.meta.env.VITE_API_BASE_URL ?? "http://localhost:8000";
 
 interface InstanceListProps {
-  projectId: string;
-  repoId: string;
-  projectName?: string;
-  repoName?: string;
-  toolTypes: ToolType[];
+	projectId: string;
+	repoId: string;
+	projectName?: string;
+	repoName?: string;
+	toolTypes: ToolType[];
 }
 
-export const InstanceList = ({ projectId, repoId, projectName, repoName, toolTypes }: InstanceListProps) => {
-  const navigate = useNavigate();
-  const [instances, setInstances] = useState<ToolInstance[]>([]);
-  const [loading, setLoading] = useState(false);
-  const [showCreate, setShowCreate] = useState(false);
-  const [error, setError] = useState<string | null>(null);
+export const InstanceList = ({
+	projectId,
+	repoId,
+	projectName,
+	repoName,
+	toolTypes,
+}: InstanceListProps) => {
+	const navigate = useNavigate();
+	const [instances, setInstances] = useState<ToolInstance[]>([]);
+	const [loading, setLoading] = useState(false);
+	const [showCreate, setShowCreate] = useState(false);
+	const [error, setError] = useState<string | null>(null);
 
-  // Stop confirmation
-  const [stopConfirmId, setStopConfirmId] = useState<string | null>(null);
+	// Stop confirmation
+	const [stopConfirmId, setStopConfirmId] = useState<string | null>(null);
 
-  // Health check state
-  const [healthStatus, setHealthStatus] = useState<Record<string, { healthy: boolean; lastCheck: number }>>({});
+	// Config profile selection for start/restart
+	const [configProfiles, setConfigProfiles] = useState<ConfigProfile[]>([]);
+	const [profileSelectInstanceId, setProfileSelectInstanceId] = useState<
+		string | null
+	>(null);
+	const [selectedProfileForAction, setSelectedProfileForAction] = useState("");
 
-  // Config profile selection for start/restart
-  const [configProfiles, setConfigProfiles] = useState<ConfigProfile[]>([]);
-  const [profileSelectInstanceId, setProfileSelectInstanceId] = useState<string | null>(null);
-  const [selectedProfileForAction, setSelectedProfileForAction] = useState("");
+	// Per-instance busy state for actions
+	const [busyInstanceId, setBusyInstanceId] = useState<string | null>(null);
 
-  // Per-instance busy state for actions
-  const [busyInstanceId, setBusyInstanceId] = useState<string | null>(null);
+	const loadInstances = useCallback(async () => {
+		setLoading(true);
+		try {
+			const data = await listInstances(projectId, repoId);
+			setInstances(data);
+		} catch {
+			setError("Failed to load instances");
+		} finally {
+			setLoading(false);
+		}
+	}, [projectId, repoId]);
 
-  const loadInstances = useCallback(async () => {
-    setLoading(true);
-    try {
-      const data = await listInstances(projectId, repoId);
-      setInstances(data);
-    } catch {
-      setError("Failed to load instances");
-    } finally {
-      setLoading(false);
-    }
-  }, [projectId, repoId]);
+	const { events } = useEventContext();
 
-  useEffect(() => {
-    void loadInstances();
-  }, [loadInstances]);
+	useEffect(() => {
+		void loadInstances();
+	}, [loadInstances]);
 
-  // Health check polling
-  useEffect(() => {
-    const runningInstances = instances.filter(i => i.status === "running" && i.url?.startsWith("http"));
-    if (runningInstances.length === 0) return;
+	// Lightweight list refresh every 60 seconds for resilience
+	useEffect(() => {
+		const interval = setInterval(() => void loadInstances(), 60000);
+		return () => clearInterval(interval);
+	}, [loadInstances]);
 
-    const checkHealth = async () => {
-      for (const instance of runningInstances) {
-        try {
-          const health = await checkInstanceHealth(projectId, repoId, instance.id);
-          setHealthStatus(prev => ({
-            ...prev,
-            [instance.id]: { healthy: health.healthy, lastCheck: Date.now() }
-          }));
-        } catch {
-          setHealthStatus(prev => ({
-            ...prev,
-            [instance.id]: { healthy: false, lastCheck: Date.now() }
-          }));
-        }
-      }
-    };
+	// Real-time status updates from SSE events
+	useEffect(() => {
+		if (events.length === 0) return;
+		const latestEvent = events[events.length - 1];
+		const statusEvents = [
+			"instance.started",
+			"instance.health_changed",
+			"instance.error",
+			"instance.stopped",
+			"instance.restarted",
+		];
+		if (!statusEvents.includes(latestEvent.event)) return;
 
-    // Check immediately
-    void checkHealth();
-    
-    // Then every 30 seconds
-    const interval = setInterval(() => void checkHealth(), 30000);
-    return () => clearInterval(interval);
-  }, [instances, projectId, repoId]);
+		setInstances((prev) =>
+			prev.map((inst) =>
+				inst.id === latestEvent.instance_id
+					? { ...inst, status: latestEvent.status ?? inst.status }
+					: inst,
+			),
+		);
+	}, [events]);
 
-  const handleCreateSuccess = async () => {
-    setShowCreate(false);
-    await loadInstances();
-  };
+	const handleCreateSuccess = async () => {
+		setShowCreate(false);
+		await loadInstances();
+	};
 
-  const loadConfigProfiles = useCallback(async (toolTypeId: string) => {
-    try {
-      const profiles = await listConfigProfiles(projectId, toolTypeId);
-      setConfigProfiles(profiles);
-    } catch {
-      // ignore
-    }
-  }, [projectId]);
+	const loadConfigProfiles = useCallback(
+		async (toolTypeId: string) => {
+			try {
+				const profiles = await listConfigProfiles(projectId, toolTypeId);
+				setConfigProfiles(profiles);
+			} catch {
+				// ignore
+			}
+		},
+		[projectId],
+	);
 
-  const handleStart = async (instanceId: string, configProfileId?: string) => {
-    setBusyInstanceId(instanceId);
-    try {
-      await startInstance(projectId, repoId, instanceId, configProfileId);
-      setProfileSelectInstanceId(null);
-      setSelectedProfileForAction("");
-      await loadInstances();
-    } catch {
-      setError("Failed to start instance");
-    } finally {
-      setBusyInstanceId(null);
-    }
-  };
+	const handleStart = async (instanceId: string, configProfileId?: string) => {
+		setBusyInstanceId(instanceId);
+		try {
+			await startInstance(projectId, repoId, instanceId, configProfileId);
+			setProfileSelectInstanceId(null);
+			setSelectedProfileForAction("");
+			await loadInstances();
+		} catch {
+			setError("Failed to start instance");
+		} finally {
+			setBusyInstanceId(null);
+		}
+	};
 
-  const handleStop = async (instanceId: string) => {
-    setBusyInstanceId(instanceId);
-    try {
-      await stopInstance(projectId, repoId, instanceId);
-      setStopConfirmId(null);
-      await loadInstances();
-    } catch {
-      setError("Failed to stop instance");
-    } finally {
-      setBusyInstanceId(null);
-    }
-  };
+	const handleStop = async (instanceId: string) => {
+		setBusyInstanceId(instanceId);
+		try {
+			await stopInstance(projectId, repoId, instanceId);
+			setStopConfirmId(null);
+			await loadInstances();
+		} catch {
+			setError("Failed to stop instance");
+		} finally {
+			setBusyInstanceId(null);
+		}
+	};
 
-  const handleRestart = async (instanceId: string, configProfileId?: string) => {
-    setBusyInstanceId(instanceId);
-    try {
-      await restartInstance(projectId, repoId, instanceId, configProfileId);
-      setProfileSelectInstanceId(null);
-      setSelectedProfileForAction("");
-      await loadInstances();
-    } catch {
-      setError("Failed to restart instance");
-    } finally {
-      setBusyInstanceId(null);
-    }
-  };
+	const handleRestart = async (
+		instanceId: string,
+		configProfileId?: string,
+	) => {
+		setBusyInstanceId(instanceId);
+		try {
+			await restartInstance(projectId, repoId, instanceId, configProfileId);
+			setProfileSelectInstanceId(null);
+			setSelectedProfileForAction("");
+			await loadInstances();
+		} catch {
+			setError("Failed to restart instance");
+		} finally {
+			setBusyInstanceId(null);
+		}
+	};
 
-  const handleDelete = async (instanceId: string) => {
-    if (!confirm("Are you sure you want to delete this instance?")) return;
-    setBusyInstanceId(instanceId);
-    try {
-      await deleteInstance(projectId, repoId, instanceId);
-      // Update state immediately instead of reloading
-      setInstances(prev => prev.filter(i => i.id !== instanceId));
-    } catch {
-      setError("Failed to delete instance");
-    } finally {
-      setBusyInstanceId(null);
-    }
-  };
+	const handleDelete = async (instanceId: string) => {
+		if (!confirm("Are you sure you want to delete this instance?")) return;
+		setBusyInstanceId(instanceId);
+		try {
+			await deleteInstance(projectId, repoId, instanceId);
+			// Update state immediately instead of reloading
+			setInstances((prev) => prev.filter((i) => i.id !== instanceId));
+		} catch {
+			setError("Failed to delete instance");
+		} finally {
+			setBusyInstanceId(null);
+		}
+	};
 
-  const handleRecreateTunnel = async (instanceId: string) => {
-    setBusyInstanceId(instanceId);
-    try {
-      await recreateInstanceTunnel(projectId, repoId, instanceId);
-      await loadInstances();
-    } catch {
-      setError("Failed to recreate tunnel");
-    } finally {
-      setBusyInstanceId(null);
-    }
-  };
+	const getStatusColor = (status: string) => {
+		switch (status) {
+			case "running":
+				return "var(--success)";
+			case "starting":
+			case "probing":
+				return "var(--info)";
+			case "unhealthy":
+				return "var(--warning)";
+			case "error":
+				return "var(--danger)";
+			case "pending":
+			case "building":
+				return "var(--warning)";
+			default:
+				return "var(--muted)";
+		}
+	};
 
-  const getStatusColor = (status: string) => {
-    switch (status) {
-      case "running":
-        return "var(--success)";
-      case "error":
-        return "var(--danger)";
-      case "pending":
-      case "building":
-        return "var(--warning)";
-      default:
-        return "var(--muted)";
-    }
-  };
+	return (
+		<div className="instance-list">
+			<div className="instance-list-header">
+				<h3>Tool Instances</h3>
+				<button
+					className="secondary-button small"
+					onClick={() => setShowCreate(true)}
+					type="button"
+				>
+					<Icon name="add" size="sm" />
+					Launch Tool
+				</button>
+			</div>
 
-  const isTunnelUnhealthy = (instance: ToolInstance) => {
-    if (instance.status !== "running") return false;
-    if (!instance.url?.startsWith("http")) return false;
-    const health = healthStatus[instance.id];
-    if (!health) return false;
-    return !health.healthy;
-  };
+			{error && <div className="error-message">{error}</div>}
 
-  return (
-    <div className="instance-list">
-      <div className="instance-list-header">
-        <h3>Tool Instances</h3>
-        <button
-          className="secondary-button small"
-          onClick={() => setShowCreate(true)}
-          type="button"
-        >
-          <Icon name="add" size="sm" />
-          Launch Tool
-        </button>
-      </div>
+			{loading ? (
+				<p className="muted">Loading instances...</p>
+			) : instances.length === 0 ? (
+				<p className="muted">No instances yet. Launch a tool to get started.</p>
+			) : (
+				<div className="instance-grid">
+					{instances.map((instance) => (
+						<div
+							key={instance.id}
+							className={`instance-card ${busyInstanceId === instance.id ? "busy" : ""}`}
+						>
+							{busyInstanceId === instance.id && (
+								<div className="instance-busy-overlay">
+									<Icon name="loading" size="md" />
+								</div>
+							)}
+							<div className="instance-info">
+								<div className="instance-name">{instance.display_name}</div>
+								<div className="instance-meta">
+									<span
+										className="status-dot"
+										style={{ backgroundColor: getStatusColor(instance.status) }}
+									/>
+									{instance.status}
+								</div>
+								{instance.selected_config_profile_id && (
+									<div className="instance-profile">
+										<span className="badge">
+											Profile:{" "}
+											{configProfiles.find(
+												(p) => p.id === instance.selected_config_profile_id,
+											)?.name || instance.selected_config_profile_id}
+										</span>
+									</div>
+								)}
+							</div>
+							<div className="instance-actions">
+								{instance.status === "running" &&
+									instance.url &&
+									instance.tool_type_interfaces.includes("web") && (
+										<>
+											<a
+												href={
+													instance.url.startsWith("http")
+														? instance.url
+														: `${API_BASE_URL}${instance.url}`
+												}
+												target="_blank"
+												rel="noopener noreferrer"
+												className="secondary-button small"
+											>
+												<Icon name="external" size="sm" />
+												Open
+											</a>
+										</>
+									)}
+								{instance.status === "running" &&
+									instance.tool_type_interfaces.includes("terminal") && (
+										<button
+											className="secondary-button small"
+											onClick={() =>
+												navigate(`/instances/${instance.id}/terminal`)
+											}
+											type="button"
+											disabled={busyInstanceId === instance.id}
+										>
+											<Icon name="terminal" size="sm" />
+											Terminal
+										</button>
+									)}
+								{instance.status !== "running" && (
+									<>
+										{profileSelectInstanceId === instance.id ? (
+											<div className="inline-profile-select">
+												<select
+													value={selectedProfileForAction}
+													onChange={(e) =>
+														setSelectedProfileForAction(e.target.value)
+													}
+												>
+													<option value="">Default (none)</option>
+													{configProfiles.map((p) => (
+														<option key={p.id} value={p.id}>
+															{p.name}
+														</option>
+													))}
+												</select>
+												<button
+													className="primary-button small"
+													onClick={() =>
+														void handleStart(
+															instance.id,
+															selectedProfileForAction || undefined,
+														)
+													}
+													type="button"
+													disabled={busyInstanceId === instance.id}
+												>
+													<Icon name="play" size="sm" />
+													Start
+												</button>
+												<button
+													className="ghost-button small"
+													onClick={() => {
+														setProfileSelectInstanceId(null);
+														setSelectedProfileForAction("");
+													}}
+													type="button"
+													disabled={busyInstanceId === instance.id}
+												>
+													Cancel
+												</button>
+											</div>
+										) : (
+											<button
+												className="secondary-button small"
+												onClick={() => {
+													const toolType = toolTypes.find(
+														(t) => t.id === instance.tool_type_id,
+													);
+													if (toolType) {
+														void loadConfigProfiles(toolType.id);
+													}
+													setProfileSelectInstanceId(instance.id);
+													setSelectedProfileForAction(
+														instance.selected_config_profile_id || "",
+													);
+												}}
+												type="button"
+												disabled={busyInstanceId === instance.id}
+											>
+												<Icon name="play" size="sm" />
+												Start
+											</button>
+										)}
+									</>
+								)}
+								{instance.status === "running" && (
+									<>
+										{stopConfirmId === instance.id ? (
+											<div className="inline-confirm">
+												<span>Stop?</span>
+												<button
+													className="ghost-button small danger-text"
+													onClick={() => void handleStop(instance.id)}
+													type="button"
+													disabled={busyInstanceId === instance.id}
+												>
+													Yes
+												</button>
+												<button
+													className="ghost-button small"
+													onClick={() => setStopConfirmId(null)}
+													type="button"
+													disabled={busyInstanceId === instance.id}
+												>
+													No
+												</button>
+											</div>
+										) : (
+											<button
+												className="ghost-button small"
+												onClick={() => setStopConfirmId(instance.id)}
+												type="button"
+												disabled={busyInstanceId === instance.id}
+											>
+												<Icon name="stop" size="sm" />
+											</button>
+										)}
+										{profileSelectInstanceId === instance.id ? (
+											<div className="inline-profile-select">
+												<select
+													value={selectedProfileForAction}
+													onChange={(e) =>
+														setSelectedProfileForAction(e.target.value)
+													}
+												>
+													<option value="">Default (none)</option>
+													{configProfiles.map((p) => (
+														<option key={p.id} value={p.id}>
+															{p.name}
+														</option>
+													))}
+												</select>
+												<button
+													className="primary-button small"
+													onClick={() =>
+														void handleRestart(
+															instance.id,
+															selectedProfileForAction || undefined,
+														)
+													}
+													type="button"
+													disabled={busyInstanceId === instance.id}
+												>
+													<Icon name="refresh" size="sm" />
+													Restart
+												</button>
+												<button
+													className="ghost-button small"
+													onClick={() => {
+														setProfileSelectInstanceId(null);
+														setSelectedProfileForAction("");
+													}}
+													type="button"
+													disabled={busyInstanceId === instance.id}
+												>
+													Cancel
+												</button>
+											</div>
+										) : (
+											<button
+												className="ghost-button small"
+												onClick={() => {
+													const toolType = toolTypes.find(
+														(t) => t.id === instance.tool_type_id,
+													);
+													if (toolType) {
+														void loadConfigProfiles(toolType.id);
+													}
+													setProfileSelectInstanceId(instance.id);
+													setSelectedProfileForAction(
+														instance.selected_config_profile_id || "",
+													);
+												}}
+												type="button"
+												disabled={busyInstanceId === instance.id}
+											>
+												<Icon name="refresh" size="sm" />
+											</button>
+										)}
+									</>
+								)}
+								<button
+									className="ghost-button small danger-text"
+									onClick={() => void handleDelete(instance.id)}
+									type="button"
+									disabled={busyInstanceId === instance.id}
+								>
+									<Icon name="delete" size="sm" />
+								</button>
+							</div>
+						</div>
+					))}
+				</div>
+			)}
 
-      {error && (
-        <div className="error-message">{error}</div>
-      )}
-
-      {loading ? (
-        <p className="muted">Loading instances...</p>
-      ) : instances.length === 0 ? (
-        <p className="muted">No instances yet. Launch a tool to get started.</p>
-      ) : (
-        <div className="instance-grid">
-          {instances.map((instance) => (
-            <div key={instance.id} className={`instance-card ${busyInstanceId === instance.id ? "busy" : ""}`}>
-              {busyInstanceId === instance.id && (
-                <div className="instance-busy-overlay">
-                  <Icon name="loading" size="md" />
-                </div>
-              )}
-              <div className="instance-info">
-                <div className="instance-name">{instance.display_name}</div>
-                <div className="instance-meta">
-                  <span
-                    className="status-dot"
-                    style={{ backgroundColor: getStatusColor(instance.status) }}
-                  />
-                  {instance.status}
-                  {isTunnelUnhealthy(instance) && (
-                    <span className="error-badge" title="Tunnel unreachable">
-                      <Icon name="warning" size="sm" />
-                      tunnel error
-                    </span>
-                  )}
-                </div>
-                {instance.selected_config_profile_id && (
-                  <div className="instance-profile">
-                    <span className="badge">
-                      Profile: {configProfiles.find((p) => p.id === instance.selected_config_profile_id)?.name || instance.selected_config_profile_id}
-                    </span>
-                  </div>
-                )}
-              </div>
-              <div className="instance-actions">
-                {instance.status === "running" && instance.url && instance.tool_type_interfaces.includes("web") && (
-                  <>
-                    <a
-                      href={instance.url.startsWith("http") ? instance.url : `${API_BASE_URL}${instance.url}`}
-                      target="_blank"
-                      rel="noopener noreferrer"
-                      className="secondary-button small"
-                    >
-                      <Icon name="external" size="sm" />
-                      Open
-                    </a>
-                    {isTunnelUnhealthy(instance) && (
-                      <button
-                        className="secondary-button small warning"
-                        onClick={() => void handleRecreateTunnel(instance.id)}
-                        type="button"
-                        title="Recreate tunnel"
-                        disabled={busyInstanceId === instance.id}
-                      >
-                        <Icon name="refresh" size="sm" />
-                        Fix Tunnel
-                      </button>
-                    )}
-                  </>
-                )}
-                {instance.status === "running" && instance.tool_type_interfaces.includes("terminal") && (
-                  <button
-                    className="secondary-button small"
-                    onClick={() => navigate(`/instances/${instance.id}/terminal`)}
-                    type="button"
-                    disabled={busyInstanceId === instance.id}
-                  >
-                    <Icon name="terminal" size="sm" />
-                    Terminal
-                  </button>
-                )}
-                {instance.status !== "running" && (
-                  <>
-                    {profileSelectInstanceId === instance.id ? (
-                      <div className="inline-profile-select">
-                        <select
-                          value={selectedProfileForAction}
-                          onChange={(e) => setSelectedProfileForAction(e.target.value)}
-                        >
-                          <option value="">Default (none)</option>
-                          {configProfiles.map((p) => (
-                            <option key={p.id} value={p.id}>
-                              {p.name}
-                            </option>
-                          ))}
-                        </select>
-                        <button
-                          className="primary-button small"
-                          onClick={() => void handleStart(instance.id, selectedProfileForAction || undefined)}
-                          type="button"
-                          disabled={busyInstanceId === instance.id}
-                        >
-                          <Icon name="play" size="sm" />
-                          Start
-                        </button>
-                        <button
-                          className="ghost-button small"
-                          onClick={() => {
-                            setProfileSelectInstanceId(null);
-                            setSelectedProfileForAction("");
-                          }}
-                          type="button"
-                          disabled={busyInstanceId === instance.id}
-                        >
-                          Cancel
-                        </button>
-                      </div>
-                    ) : (
-                      <button
-                        className="secondary-button small"
-                        onClick={() => {
-                          const toolType = toolTypes.find((t) => t.id === instance.tool_type_id);
-                          if (toolType) {
-                            void loadConfigProfiles(toolType.id);
-                          }
-                          setProfileSelectInstanceId(instance.id);
-                          setSelectedProfileForAction(instance.selected_config_profile_id || "");
-                        }}
-                        type="button"
-                        disabled={busyInstanceId === instance.id}
-                      >
-                        <Icon name="play" size="sm" />
-                        Start
-                      </button>
-                    )}
-                  </>
-                )}
-                {instance.status === "running" && (
-                  <>
-                    {stopConfirmId === instance.id ? (
-                      <div className="inline-confirm">
-                        <span>Stop?</span>
-                        <button
-                          className="ghost-button small danger-text"
-                          onClick={() => void handleStop(instance.id)}
-                          type="button"
-                          disabled={busyInstanceId === instance.id}
-                        >
-                          Yes
-                        </button>
-                        <button
-                          className="ghost-button small"
-                          onClick={() => setStopConfirmId(null)}
-                          type="button"
-                          disabled={busyInstanceId === instance.id}
-                        >
-                          No
-                        </button>
-                      </div>
-                    ) : (
-                      <button
-                        className="ghost-button small"
-                        onClick={() => setStopConfirmId(instance.id)}
-                        type="button"
-                        disabled={busyInstanceId === instance.id}
-                      >
-                        <Icon name="stop" size="sm" />
-                      </button>
-                    )}
-                    {profileSelectInstanceId === instance.id ? (
-                      <div className="inline-profile-select">
-                        <select
-                          value={selectedProfileForAction}
-                          onChange={(e) => setSelectedProfileForAction(e.target.value)}
-                        >
-                          <option value="">Default (none)</option>
-                          {configProfiles.map((p) => (
-                            <option key={p.id} value={p.id}>
-                              {p.name}
-                            </option>
-                          ))}
-                        </select>
-                        <button
-                          className="primary-button small"
-                          onClick={() => void handleRestart(instance.id, selectedProfileForAction || undefined)}
-                          type="button"
-                          disabled={busyInstanceId === instance.id}
-                        >
-                          <Icon name="refresh" size="sm" />
-                          Restart
-                        </button>
-                        <button
-                          className="ghost-button small"
-                          onClick={() => {
-                            setProfileSelectInstanceId(null);
-                            setSelectedProfileForAction("");
-                          }}
-                          type="button"
-                          disabled={busyInstanceId === instance.id}
-                        >
-                          Cancel
-                        </button>
-                      </div>
-                    ) : (
-                      <button
-                        className="ghost-button small"
-                        onClick={() => {
-                          const toolType = toolTypes.find((t) => t.id === instance.tool_type_id);
-                          if (toolType) {
-                            void loadConfigProfiles(toolType.id);
-                          }
-                          setProfileSelectInstanceId(instance.id);
-                          setSelectedProfileForAction(instance.selected_config_profile_id || "");
-                        }}
-                        type="button"
-                        disabled={busyInstanceId === instance.id}
-                      >
-                        <Icon name="refresh" size="sm" />
-                      </button>
-                    )}
-                  </>
-                )}
-                <button
-                  className="ghost-button small danger-text"
-                  onClick={() => void handleDelete(instance.id)}
-                  type="button"
-                  disabled={busyInstanceId === instance.id}
-                >
-                  <Icon name="delete" size="sm" />
-                </button>
-              </div>
-            </div>
-          ))}
-        </div>
-      )}
-
-      {showCreate && (
-        <div className="dialog-overlay" role="dialog" aria-modal="true">
-          <div className="dialog">
-            <h2>Launch Tool</h2>
-            <CreateSessionForm
-              projects={[]}
-              repositories={[]}
-              toolTypes={toolTypes}
-              fixedProjectId={projectId}
-              fixedRepoId={repoId}
-              projectName={projectName}
-              repoName={repoName}
-              onSuccess={handleCreateSuccess}
-              onCancel={() => setShowCreate(false)}
-              submitLabel="Launch"
-            />
-          </div>
-        </div>
-      )}
-    </div>
-  );
+			{showCreate && (
+				<div className="dialog-overlay" role="dialog" aria-modal="true">
+					<div className="dialog">
+						<h2>Launch Tool</h2>
+						<CreateSessionForm
+							projects={[]}
+							repositories={[]}
+							toolTypes={toolTypes}
+							fixedProjectId={projectId}
+							fixedRepoId={repoId}
+							projectName={projectName}
+							repoName={repoName}
+							onSuccess={handleCreateSuccess}
+							onCancel={() => setShowCreate(false)}
+							submitLabel="Launch"
+						/>
+					</div>
+				</div>
+			)}
+		</div>
+	);
 };

apps/web/src/components/session-card.tsx

@@ -6,333 +6,357 @@ import { MobileActionSheet } from "./mobile-action-sheet";
 import type { IconName } from "./icon";
 
 export interface SessionCardProps {
-  session: Session;
-  onOpen?: (session: Session) => void;
-  onStart?: (session: Session) => void;
-  onStop?: (session: Session) => void;
-  onDelete?: (session: Session) => void;
-  onRecreateTunnel?: (session: Session) => void;
-  isBusy?: boolean;
-  tunnelHealth?: {
-    healthy: boolean;
-    container_status: string;
-    container_health: string | null;
-    tunnel_status: string;
-    tunnel_status_code: number | null;
-    probe_status: string;
-    last_probe_output: string | null;
-    error: string | null;
-  } | null;
+	session: Session;
+	onOpen?: (session: Session) => void;
+	onStart?: (session: Session) => void;
+	onStop?: (session: Session) => void;
+	onDelete?: (session: Session) => void;
+	onRecreateTunnel?: (session: Session) => void;
+	isBusy?: boolean;
+	tunnelHealth?: {
+		healthy: boolean;
+		container_status: string;
+		container_health: string | null;
+		tunnel_status: string;
+		tunnel_status_code: number | null;
+		probe_status: string;
+		last_probe_output: string | null;
+		error: string | null;
+	} | null;
 }
 
 const statusConfig: Record<string, { color: string; label: string }> = {
-  running: { color: "green", label: "Running" },
-  building: { color: "yellow", label: "Building" },
-  starting: { color: "yellow", label: "Starting" },
-  probing: { color: "yellow", label: "Probing" },
-  pending: { color: "yellow", label: "Pending" },
-  stopped: { color: "gray", label: "Stopped" },
-  error: { color: "red", label: "Error" },
-  unhealthy: { color: "orange", label: "Unhealthy" },
+	running: { color: "running", label: "Running" },
+	building: { color: "pending", label: "Building" },
+	starting: { color: "starting", label: "Starting" },
+	probing: { color: "probing", label: "Probing" },
+	pending: { color: "pending", label: "Pending" },
+	stopped: { color: "stopped", label: "Stopped" },
+	error: { color: "error", label: "Error" },
+	unhealthy: { color: "unhealthy", label: "Unhealthy" },
 };
 
 export function SessionCard({
-  session,
-  onOpen,
-  onStart,
-  onStop,
-  onDelete,
-  onRecreateTunnel,
-  isBusy = false,
-  tunnelHealth = null,
+	session,
+	onOpen,
+	onStart,
+	onStop,
+	onDelete,
+	onRecreateTunnel,
+	isBusy = false,
+	tunnelHealth = null,
 }: SessionCardProps) {
-  const [showStopConfirm, setShowStopConfirm] = useState(false);
-  const [showDeleteConfirm, setShowDeleteConfirm] = useState(false);
-  const [showActionSheet, setShowActionSheet] = useState(false);
-  const isMobile = useMobileViewport();
+	const [showStopConfirm, setShowStopConfirm] = useState(false);
+	const [showDeleteConfirm, setShowDeleteConfirm] = useState(false);
+	const [showActionSheet, setShowActionSheet] = useState(false);
+	const isMobile = useMobileViewport();
 
-  const status = statusConfig[session.status] || { color: "gray", label: session.status };
-  const isTerminalOnly = session.tool_type_interfaces?.includes("terminal") && !session.tool_type_interfaces?.includes("web");
-  const hasTunnelError = !isTerminalOnly && tunnelHealth?.tunnel_status === "unreachable";
-  const hasAppError = !isTerminalOnly && tunnelHealth?.tunnel_status === "error_response";
+	const status = statusConfig[session.status] || {
+		color: "gray",
+		label: session.status,
+	};
+	const isTerminalOnly =
+		session.tool_type_interfaces?.includes("terminal") &&
+		!session.tool_type_interfaces?.includes("web");
+	const hasTunnelError =
+		!isTerminalOnly && tunnelHealth?.tunnel_status === "unreachable";
+	const hasAppError =
+		!isTerminalOnly && tunnelHealth?.tunnel_status === "error_response";
 
-  const handleStop = () => {
-    if (showStopConfirm) {
-      setShowStopConfirm(false);
-      onStop?.(session);
-    } else {
-      setShowStopConfirm(true);
-    }
-  };
+	const handleStop = () => {
+		if (showStopConfirm) {
+			setShowStopConfirm(false);
+			onStop?.(session);
+		} else {
+			setShowStopConfirm(true);
+		}
+	};
 
-  const handleDelete = () => {
-    if (showDeleteConfirm) {
-      setShowDeleteConfirm(false);
-      onDelete?.(session);
-    } else {
-      setShowDeleteConfirm(true);
-    }
-  };
+	const handleDelete = () => {
+		if (showDeleteConfirm) {
+			setShowDeleteConfirm(false);
+			onDelete?.(session);
+		} else {
+			setShowDeleteConfirm(true);
+		}
+	};
 
-  const handleCancelStop = () => setShowStopConfirm(false);
-  const handleCancelDelete = () => setShowDeleteConfirm(false);
+	const handleCancelStop = () => setShowStopConfirm(false);
+	const handleCancelDelete = () => setShowDeleteConfirm(false);
 
-  const isActive = ["running", "building", "starting", "probing", "pending", "unhealthy"].includes(session.status);
+	const isActive = [
+		"running",
+		"building",
+		"starting",
+		"probing",
+		"pending",
+		"unhealthy",
+	].includes(session.status);
 
-  return (
-    <article className={`card session-card ${isBusy ? "busy" : ""}`}>
-      {isBusy && (
-        <div className="session-busy-overlay">
-          <Icon name="loading" size="md" />
-        </div>
-      )}
-      <div className="session-card-content">
-        <div className="session-card-header">
-          <div className="session-card-title">
-            <h4>{session.display_name}</h4>
-            <div className="session-card-status-badges">
-              <span className={`status-badge ${status.color}`}>{status.label}</span>
-              {hasTunnelError && (
-                <span className="status-badge error">Tunnel Error</span>
-              )}
-              {hasAppError && (
-                <span className="status-badge warning">App Error {tunnelHealth?.tunnel_status_code}</span>
-              )}
-            </div>
-          </div>
-          <p className="muted session-card-meta">
-            {session.tool_type_name}
-            {session.project_name && ` · ${session.project_name}`}
-            {session.repository_name && ` · ${session.repository_name}`}
-          </p>
-          {session.clone_mode && (
-            <p className="muted session-card-meta">
-              <Icon name="branch" size="sm" />
-              {session.clone_mode === "clone"
-                ? `Clone${session.branch ? ` (${session.branch})` : ""}`
-                : "Mount"}
-            </p>
-          )}
-          {session.url && (
-            <p className="session-card-url">
-              <a href={session.url} target="_blank" rel="noopener noreferrer">
-                {session.url}
-              </a>
-            </p>
-          )}
-          {session.created_at && (
-            <p className="muted session-card-meta">
-              Created: {new Date(session.created_at).toLocaleString()}
-            </p>
-          )}
-        </div>
-      </div>
+	return (
+		<article className={`card session-card ${isBusy ? "busy" : ""}`}>
+			{isBusy && (
+				<div className="session-busy-overlay">
+					<Icon name="loading" size="md" />
+				</div>
+			)}
+			<div className="session-card-content">
+				<div className="session-card-header">
+					<div className="session-card-title">
+						<h4>{session.display_name}</h4>
+						<div className="session-card-status-badges">
+							<span className={`status-badge ${status.color}`}>
+								{status.label}
+							</span>
+							{hasTunnelError && (
+								<span className="status-badge error">Tunnel Error</span>
+							)}
+							{hasAppError && (
+								<span className="status-badge warning">
+									App Error {tunnelHealth?.tunnel_status_code}
+								</span>
+							)}
+						</div>
+					</div>
+					<p className="muted session-card-meta">
+						{session.tool_type_name}
+						{session.project_name && ` · ${session.project_name}`}
+						{session.repository_name && ` · ${session.repository_name}`}
+					</p>
+					{session.clone_mode && (
+						<p className="muted session-card-meta">
+							<Icon name="branch" size="sm" />
+							{session.clone_mode === "clone"
+								? `Clone${session.branch ? ` (${session.branch})` : ""}`
+								: "Mount"}
+						</p>
+					)}
+					{session.url && (
+						<p className="session-card-url">
+							<a href={session.url} target="_blank" rel="noopener noreferrer">
+								{session.url}
+							</a>
+						</p>
+					)}
+					{session.created_at && (
+						<p className="muted session-card-meta">
+							Created: {new Date(session.created_at).toLocaleString()}
+						</p>
+					)}
+				</div>
+			</div>
 
-      {isMobile ? (
-        <div className="session-card-actions mobile">
-          {isActive && (
-            <>
-              {session.url ? (
-                <a
-                  href={session.url}
-                  target="_blank"
-                  rel="noopener noreferrer"
-                  className="secondary-button mobile-primary"
-                >
-                  <Icon name="external" size="sm" />
-                  Open
-                </a>
-              ) : (
-                <button
-                  className="secondary-button mobile-primary"
-                  onClick={() => onOpen?.(session)}
-                  type="button"
-                  disabled={isBusy}
-                >
-                  <Icon name="external" size="sm" />
-                  Open
-                </button>
-              )}
-              <button
-                className="ghost-button mobile-more"
-                onClick={() => setShowActionSheet(true)}
-                type="button"
-                disabled={isBusy}
-              >
-<Icon name="menu" size="sm" />
-              </button>
-            </>
-          )}
-          {!isActive && onStart && (
-            <button
-              className="secondary-button mobile-primary"
-              onClick={() => onStart(session)}
-              type="button"
-              disabled={isBusy}
-            >
-              <Icon name="play" size="sm" />
-              Start
-            </button>
-          )}
-          {!isActive && (
-            <button
-              className="ghost-button mobile-more"
-              onClick={() => setShowActionSheet(true)}
-              type="button"
-              disabled={isBusy}
-            >
-              <Icon name="menu" size="sm" />
-            </button>
-          )}
-        </div>
-      ) : (
-        <div className="session-card-actions">
-          {isActive && (
-            <>
-              {session.url ? (
-                <a
-                  href={session.url}
-                  target="_blank"
-                  rel="noopener noreferrer"
-                  className="secondary-button small"
-                >
-                  <Icon name="external" size="sm" />
-                  <span className="action-label">Open</span>
-                </a>
-              ) : (
-                <button
-                  className="secondary-button small"
-                  onClick={() => onOpen?.(session)}
-                  type="button"
-                  disabled={isBusy}
-                >
-                  <Icon name="external" size="sm" />
-                  <span className="action-label">Open</span>
-                </button>
-              )}
+			{isMobile ? (
+				<div className="session-card-actions mobile">
+					{isActive && (
+						<>
+							{session.url ? (
+								<a
+									href={session.url}
+									target="_blank"
+									rel="noopener noreferrer"
+									className="secondary-button mobile-primary"
+								>
+									<Icon name="external" size="sm" />
+									Open
+								</a>
+							) : (
+								<button
+									className="secondary-button mobile-primary"
+									onClick={() => onOpen?.(session)}
+									type="button"
+									disabled={isBusy}
+								>
+									<Icon name="external" size="sm" />
+									Open
+								</button>
+							)}
+							<button
+								className="ghost-button mobile-more"
+								onClick={() => setShowActionSheet(true)}
+								type="button"
+								disabled={isBusy}
+							>
+								<Icon name="menu" size="sm" />
+							</button>
+						</>
+					)}
+					{!isActive && onStart && (
+						<button
+							className="secondary-button mobile-primary"
+							onClick={() => onStart(session)}
+							type="button"
+							disabled={isBusy}
+						>
+							<Icon name="play" size="sm" />
+							Start
+						</button>
+					)}
+					{!isActive && (
+						<button
+							className="ghost-button mobile-more"
+							onClick={() => setShowActionSheet(true)}
+							type="button"
+							disabled={isBusy}
+						>
+							<Icon name="menu" size="sm" />
+						</button>
+					)}
+				</div>
+			) : (
+				<div className="session-card-actions">
+					{isActive && (
+						<>
+							{session.url ? (
+								<a
+									href={session.url}
+									target="_blank"
+									rel="noopener noreferrer"
+									className="secondary-button small"
+								>
+									<Icon name="external" size="sm" />
+									<span className="action-label">Open</span>
+								</a>
+							) : (
+								<button
+									className="secondary-button small"
+									onClick={() => onOpen?.(session)}
+									type="button"
+									disabled={isBusy}
+								>
+									<Icon name="external" size="sm" />
+									<span className="action-label">Open</span>
+								</button>
+							)}
 
-              {hasTunnelError && onRecreateTunnel && (
-                <button
-                  className="secondary-button small"
-                  onClick={() => onRecreateTunnel(session)}
-                  type="button"
-                  disabled={isBusy}
-                >
-                  <Icon name="refresh" size="sm" />
-                  <span className="action-label">Tunnel</span>
-                </button>
-              )}
+							{hasTunnelError && onRecreateTunnel && (
+								<button
+									className="secondary-button small"
+									onClick={() => onRecreateTunnel(session)}
+									type="button"
+									disabled={isBusy}
+								>
+									<Icon name="refresh" size="sm" />
+									<span className="action-label">Tunnel</span>
+								</button>
+							)}
 
-              {showStopConfirm ? (
-                <div className="confirm-inline">
-                  <span className="confirm-text">Stop?</span>
-                  <button
-                    className="danger-button small"
-                    onClick={handleStop}
-                    type="button"
-                    disabled={isBusy}
-                  >
-                    Stop
-                  </button>
-                  <button
-                    className="ghost-button small"
-                    onClick={handleCancelStop}
-                    type="button"
-                  >
-                    Cancel
-                  </button>
-                </div>
-              ) : (
-                <button
-                  className="ghost-button small"
-                  onClick={handleStop}
-                  type="button"
-                  disabled={isBusy}
-                >
-                  <Icon name="stop" size="sm" />
-                  <span className="action-label">Stop</span>
-                </button>
-              )}
-            </>
-          )}
+							{showStopConfirm ? (
+								<div className="confirm-inline">
+									<span className="confirm-text">Stop?</span>
+									<button
+										className="danger-button small"
+										onClick={handleStop}
+										type="button"
+										disabled={isBusy}
+									>
+										Stop
+									</button>
+									<button
+										className="ghost-button small"
+										onClick={handleCancelStop}
+										type="button"
+									>
+										Cancel
+									</button>
+								</div>
+							) : (
+								<button
+									className="ghost-button small"
+									onClick={handleStop}
+									type="button"
+									disabled={isBusy}
+								>
+									<Icon name="stop" size="sm" />
+									<span className="action-label">Stop</span>
+								</button>
+							)}
+						</>
+					)}
 
-          {!isActive && onStart && (
-            <button
-              className="secondary-button small"
-              onClick={() => onStart(session)}
-              type="button"
-              disabled={isBusy}
-            >
-              <Icon name="play" size="sm" />
-              <span className="action-label">Start</span>
-            </button>
-          )}
+					{!isActive && onStart && (
+						<button
+							className="secondary-button small"
+							onClick={() => onStart(session)}
+							type="button"
+							disabled={isBusy}
+						>
+							<Icon name="play" size="sm" />
+							<span className="action-label">Start</span>
+						</button>
+					)}
 
-          {showDeleteConfirm ? (
-            <div className="confirm-inline">
-              <span className="confirm-text">Delete?</span>
-              <button
-                className="danger-button small"
-                onClick={handleDelete}
-                type="button"
-                disabled={isBusy}
-              >
-                Delete
-              </button>
-              <button
-                className="ghost-button small"
-                onClick={handleCancelDelete}
-                type="button"
-              >
-                Cancel
-              </button>
-            </div>
-          ) : (
-            <button
-              className="ghost-button small danger-text"
-              onClick={handleDelete}
-              type="button"
-              disabled={isBusy}
-            >
-              <Icon name="delete" size="sm" />
-            </button>
-          )}
-        </div>
-      )}
+					{showDeleteConfirm ? (
+						<div className="confirm-inline">
+							<span className="confirm-text">Delete?</span>
+							<button
+								className="danger-button small"
+								onClick={handleDelete}
+								type="button"
+								disabled={isBusy}
+							>
+								Delete
+							</button>
+							<button
+								className="ghost-button small"
+								onClick={handleCancelDelete}
+								type="button"
+							>
+								Cancel
+							</button>
+						</div>
+					) : (
+						<button
+							className="ghost-button small danger-text"
+							onClick={handleDelete}
+							type="button"
+							disabled={isBusy}
+						>
+							<Icon name="delete" size="sm" />
+						</button>
+					)}
+				</div>
+			)}
 
-      <MobileActionSheet
-        isOpen={showActionSheet}
-        onClose={() => setShowActionSheet(false)}
-        title={session.display_name}
-        actions={[
-          ...(isActive && hasTunnelError && onRecreateTunnel
-            ? [{
-                id: "tunnel",
-                label: "Recreate Tunnel",
-                icon: "refresh" as IconName,
-                onClick: () => onRecreateTunnel(session),
-              }]
-            : []),
-          ...(isActive && onStop
-            ? [{
-                id: "stop",
-                label: "Stop",
-                icon: "stop" as IconName,
-                variant: "danger" as const,
-                onClick: () => onStop(session),
-              }]
-            : []),
-          ...(onDelete
-            ? [{
-                id: "delete",
-                label: "Delete",
-                icon: "delete" as IconName,
-                variant: "danger" as const,
-                onClick: () => onDelete(session),
-              }]
-            : []),
-        ]}
-      />
-    </article>
-  );
+			<MobileActionSheet
+				isOpen={showActionSheet}
+				onClose={() => setShowActionSheet(false)}
+				title={session.display_name}
+				actions={[
+					...(isActive && hasTunnelError && onRecreateTunnel
+						? [
+								{
+									id: "tunnel",
+									label: "Recreate Tunnel",
+									icon: "refresh" as IconName,
+									onClick: () => onRecreateTunnel(session),
+								},
+							]
+						: []),
+					...(isActive && onStop
+						? [
+								{
+									id: "stop",
+									label: "Stop",
+									icon: "stop" as IconName,
+									variant: "danger" as const,
+									onClick: () => onStop(session),
+								},
+							]
+						: []),
+					...(onDelete
+						? [
+								{
+									id: "delete",
+									label: "Delete",
+									icon: "delete" as IconName,
+									variant: "danger" as const,
+									onClick: () => onDelete(session),
+								},
+							]
+						: []),
+				]}
+			/>
+		</article>
+	);
 }

apps/web/src/components/toast-rules.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { handleEventToast, clearToastDedup } from "./toast-rules";
+import type { InstanceEventPayload } from "../types/events";
+
+const mockToastInfo = vi.fn();
+const mockToastSuccess = vi.fn();
+const mockToastWarning = vi.fn();
+const mockToastError = vi.fn();
+
+vi.mock("../state/toast", () => ({
+	toast: {
+		info: (...args: unknown[]) => mockToastInfo(...args),
+		success: (...args: unknown[]) => mockToastSuccess(...args),
+		warning: (...args: unknown[]) => mockToastWarning(...args),
+		error: (...args: unknown[]) => mockToastError(...args),
+	},
+}));
+
+describe("toast-rules", () => {
+	beforeEach(() => {
+		clearToastDedup();
+		mockToastInfo.mockClear();
+		mockToastSuccess.mockClear();
+		mockToastWarning.mockClear();
+		mockToastError.mockClear();
+	});
+
+	it("maps instance.started to info toast", () => {
+		const event: InstanceEventPayload = {
+			event: "instance.started",
+			instance_id: "inst-1",
+			status: "starting",
+			message: "Container starting...",
+			metadata: {},
+			timestamp: "2026-05-28T12:00:00Z",
+			correlation_id: "corr-1",
+		};
+
+		handleEventToast(event);
+		expect(mockToastInfo).toHaveBeenCalledWith("Container starting...", {
+			duration: 3000,
+		});
+	});
+
+	it("maps health_changed to running to success toast", () => {
+		const event: InstanceEventPayload = {
+			event: "instance.health_changed",
+			instance_id: "inst-1",
+			status: "running",
+			message: "Container is running",
+			metadata: { previous_status: "starting" },
+			timestamp: "2026-05-28T12:00:00Z",
+			correlation_id: "corr-1",
+		};
+
+		handleEventToast(event);
+		expect(mockToastSuccess).toHaveBeenCalledWith("Container running", {
+			duration: 3000,
+		});
+	});
+
+	it("maps health_changed to unhealthy to warning toast", () => {
+		const event: InstanceEventPayload = {
+			event: "instance.health_changed",
+			instance_id: "inst-1",
+			status: "unhealthy",
+			message: "Container is unhealthy",
+			metadata: { previous_status: "running" },
+			timestamp: "2026-05-28T12:00:00Z",
+			correlation_id: "corr-1",
+		};
+
+		handleEventToast(event);
+		expect(mockToastWarning).toHaveBeenCalledWith("Container unhealthy", {
+			duration: 5000,
+		});
+	});
+
+	it("maps instance.error to error toast with exit code", () => {
+		const event: InstanceEventPayload = {
+			event: "instance.error",
+			instance_id: "inst-1",
+			status: "error",
+			message: "Container crashed",
+			metadata: { exit_code: 137 },
+			timestamp: "2026-05-28T12:00:00Z",
+			correlation_id: "corr-1",
+		};
+
+		handleEventToast(event);
+		expect(mockToastError).toHaveBeenCalledWith(
+			"Container crashed (exit code: 137)",
+			{ duration: 10000 },
+		);
+	});
+
+	it("maps instance.error to error toast without exit code", () => {
+		const event: InstanceEventPayload = {
+			event: "instance.error",
+			instance_id: "inst-1",
+			status: "error",
+			message: "Build failed",
+			metadata: {},
+			timestamp: "2026-05-28T12:00:00Z",
+			correlation_id: "corr-1",
+		};
+
+		handleEventToast(event);
+		expect(mockToastError).toHaveBeenCalledWith("Build failed", {
+			duration: 10000,
+		});
+	});
+
+	it("deduplicates within one second", () => {
+		const event: InstanceEventPayload = {
+			event: "instance.started",
+			instance_id: "inst-1",
+			status: "starting",
+			message: "Container starting...",
+			metadata: {},
+			timestamp: "2026-05-28T12:00:00Z",
+			correlation_id: "corr-1",
+		};
+
+		handleEventToast(event);
+		handleEventToast(event);
+		expect(mockToastInfo).toHaveBeenCalledTimes(1);
+	});
+
+	it("allows duplicate after one second", () => {
+		vi.useFakeTimers();
+		const event: InstanceEventPayload = {
+			event: "instance.started",
+			instance_id: "inst-1",
+			status: "starting",
+			message: "Container starting...",
+			metadata: {},
+			timestamp: "2026-05-28T12:00:00Z",
+			correlation_id: "corr-1",
+		};
+
+		handleEventToast(event);
+		vi.advanceTimersByTime(1100);
+		handleEventToast(event);
+		expect(mockToastInfo).toHaveBeenCalledTimes(2);
+		vi.useRealTimers();
+	});
+});

apps/web/src/components/toast-rules.ts

@@ -0,0 +1,57 @@
+import { toast } from "../state/toast";
+import type { InstanceEventPayload } from "../types/events";
+
+const DEDUP_WINDOW_MS = 1000;
+const lastToastTime = new Map<string, number>();
+
+function makeDedupKey(instanceId: string, eventType: string): string {
+	return `${instanceId}:${eventType}`;
+}
+
+function shouldShowToast(instanceId: string, eventType: string): boolean {
+	const key = makeDedupKey(instanceId, eventType);
+	const now = Date.now();
+	const last = lastToastTime.get(key);
+	if (last && now - last < DEDUP_WINDOW_MS) {
+		return false;
+	}
+	lastToastTime.set(key, now);
+	return true;
+}
+
+export function handleEventToast(event: InstanceEventPayload): void {
+	const { event: eventType, instance_id, status, message, metadata } = event;
+
+	switch (eventType) {
+		case "instance.started":
+			if (shouldShowToast(instance_id, eventType)) {
+				toast.info("Container starting...", { duration: 3000 });
+			}
+			break;
+		case "instance.health_changed":
+			if (status === "running" && shouldShowToast(instance_id, eventType)) {
+				toast.success("Container running", { duration: 3000 });
+			} else if (
+				status === "unhealthy" &&
+				shouldShowToast(instance_id, eventType)
+			) {
+				toast.warning("Container unhealthy", { duration: 5000 });
+			}
+			break;
+		case "instance.error":
+			if (shouldShowToast(instance_id, eventType)) {
+				const msg = message ?? "Container error";
+				const exitCode = metadata?.exit_code;
+				const fullMsg =
+					exitCode !== undefined ? `${msg} (exit code: ${exitCode})` : msg;
+				toast.error(fullMsg, { duration: 10000 });
+			}
+			break;
+		default:
+			break;
+	}
+}
+
+export function clearToastDedup(): void {
+	lastToastTime.clear();
+}

apps/web/src/hooks/use-events.test.ts

@@ -0,0 +1,189 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, waitFor, act } from "@testing-library/react";
+import { useEvents } from "./use-events";
+
+// Mock the API client
+vi.mock("../api/events", () => ({
+	createEventSource: vi.fn(),
+	probeEventStreamStatus: vi.fn().mockResolvedValue(null),
+}));
+
+import { createEventSource, probeEventStreamStatus } from "../api/events";
+
+const mockedCreateEventSource = vi.mocked(createEventSource);
+const mockedProbeEventStreamStatus = vi.mocked(probeEventStreamStatus);
+
+describe("useEvents", () => {
+	let mockEs: EventSource;
+
+	beforeEach(() => {
+		vi.useFakeTimers({ shouldAdvanceTime: true });
+		mockEs = {
+			close: vi.fn(),
+			onopen: null,
+			onmessage: null,
+			onerror: null,
+			get readyState() {
+				return EventSource.OPEN;
+			},
+			url: "http://localhost:8000/events/stream",
+		} as unknown as EventSource;
+		mockedCreateEventSource.mockReturnValue(mockEs);
+		mockedProbeEventStreamStatus.mockResolvedValue(null);
+	});
+
+	afterEach(() => {
+		vi.useRealTimers();
+		vi.clearAllMocks();
+	});
+
+	it("parses sse event and adds to state", async () => {
+		const { result } = renderHook(() => useEvents());
+
+		// Simulate connection open
+		act(() => {
+			mockEs.onopen?.({} as Event);
+		});
+
+		const payload = {
+			event: "instance.started",
+			instance_id: "abc-123",
+			status: "starting",
+			message: "Container starting...",
+			metadata: {},
+			timestamp: "2026-05-28T12:00:00Z",
+			correlation_id: "corr-1",
+		};
+
+		act(() => {
+			mockEs.onmessage?.({
+				data: JSON.stringify(payload),
+			} as MessageEvent);
+		});
+
+		await waitFor(() => {
+			expect(result.current.events).toHaveLength(1);
+			expect(result.current.events[0].instance_id).toBe("abc-123");
+		});
+		expect(result.current.connected).toBe(true);
+	});
+
+	it("reconnects with exponential backoff on error", async () => {
+		renderHook(() => useEvents());
+
+		act(() => {
+			mockEs.onerror?.({} as Event);
+		});
+
+		expect(mockEs.close).toHaveBeenCalled();
+		expect(mockedCreateEventSource).toHaveBeenCalledTimes(1);
+
+		// Advance past first backoff (should be ~1000ms)
+		await act(async () => {
+			vi.advanceTimersByTime(1200);
+		});
+
+		expect(mockedCreateEventSource).toHaveBeenCalledTimes(2);
+
+		// Trigger another error
+		const secondEs = mockedCreateEventSource.mock.results[1]
+			.value as EventSource;
+		act(() => {
+			secondEs.onerror?.({} as Event);
+		});
+
+		// Advance past second backoff (should be ~2000ms)
+		await act(async () => {
+			vi.advanceTimersByTime(2500);
+		});
+
+		expect(mockedCreateEventSource).toHaveBeenCalledTimes(3);
+	});
+
+	it("caps reconnect delay at 30 seconds", async () => {
+		renderHook(() => useEvents());
+
+		// Trigger 6 errors to get past 1s, 2s, 4s, 8s, 16s
+		for (let i = 0; i < 6; i++) {
+			const currentEs =
+				i === 0
+					? mockEs
+					: (mockedCreateEventSource.mock.results[i]?.value as EventSource);
+			act(() => {
+				currentEs.onerror?.({} as Event);
+			});
+
+			// Advance enough to trigger next reconnect
+			await act(async () => {
+				vi.advanceTimersByTime(35000);
+			});
+		}
+
+		expect(mockedCreateEventSource.mock.calls.length).toBeGreaterThan(5);
+	});
+
+	it("stops reconnecting and redirects on 401", async () => {
+		mockedProbeEventStreamStatus.mockResolvedValue(401);
+		const originalLocation = window.location;
+		// @ts-expect-error - overriding readonly location for test
+		delete window.location;
+		// @ts-expect-error - mock location
+		window.location = { ...originalLocation, assign: vi.fn() };
+
+		renderHook(() => useEvents());
+
+		act(() => {
+			mockEs.onerror?.({} as Event);
+		});
+
+		await act(async () => {
+			vi.advanceTimersByTime(1500);
+		});
+
+		expect(window.location.assign).toHaveBeenCalled();
+		// @ts-expect-error - restoring location
+		window.location = originalLocation;
+	});
+
+	it("adds 5s penalty on 429", async () => {
+		mockedProbeEventStreamStatus.mockResolvedValue(429);
+
+		renderHook(() => useEvents());
+
+		act(() => {
+			mockEs.onerror?.({} as Event);
+		});
+
+		// First timeout fires (~1s), detects 429, schedules penalty timeout (~7s later)
+		await act(async () => {
+			vi.advanceTimersByTime(2000);
+		});
+
+		expect(mockedCreateEventSource).toHaveBeenCalledTimes(1);
+
+		// Advance past penalty delay (need enough for delay + 5000)
+		await act(async () => {
+			vi.advanceTimersByTime(10000);
+		});
+
+		expect(mockedCreateEventSource).toHaveBeenCalledTimes(2);
+	});
+
+	it("cleans up EventSource on unmount", () => {
+		const { unmount } = renderHook(() => useEvents());
+		unmount();
+		expect(mockEs.close).toHaveBeenCalled();
+	});
+
+	it("exposes reconnectCount", async () => {
+		const { result } = renderHook(() => useEvents());
+
+		act(() => {
+			mockEs.onerror?.({} as Event);
+		});
+
+		await waitFor(() => {
+			expect(result.current.reconnectCount).toBeGreaterThan(0);
+		});
+	});
+});

apps/web/src/hooks/use-events.ts

@@ -0,0 +1,108 @@
+import { useEffect, useRef, useState, useCallback } from "react";
+import { createEventSource, probeEventStreamStatus } from "../api/events";
+import type { InstanceEventPayload } from "../types/events";
+
+export interface UseEventsReturn {
+	events: InstanceEventPayload[];
+	connected: boolean;
+	reconnectCount: number;
+	error: Error | null;
+}
+
+const MAX_DELAY = 30000;
+const BASE_DELAY = 1000;
+
+export function useEvents(): UseEventsReturn {
+	const [events, setEvents] = useState<InstanceEventPayload[]>([]);
+	const [connected, setConnected] = useState(false);
+	const [reconnectCount, setReconnectCount] = useState(0);
+	const [error, setError] = useState<Error | null>(null);
+	const reconnectAttemptsRef = useRef(0);
+	const esRef = useRef<EventSource | null>(null);
+	const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+	const isMountedRef = useRef(true);
+
+	const connect = useCallback(() => {
+		if (timeoutRef.current) {
+			clearTimeout(timeoutRef.current);
+			timeoutRef.current = null;
+		}
+
+		const es = createEventSource();
+		esRef.current = es;
+
+		es.onopen = () => {
+			if (!isMountedRef.current) return;
+			setConnected(true);
+			setError(null);
+			reconnectAttemptsRef.current = 0;
+			setReconnectCount(0);
+		};
+
+		es.onmessage = (e) => {
+			if (!isMountedRef.current) return;
+			try {
+				const payload: InstanceEventPayload = JSON.parse(e.data);
+				setEvents((prev) => [...prev, payload]);
+			} catch {
+				// ignore malformed events
+			}
+		};
+
+		es.onerror = () => {
+			if (!isMountedRef.current) return;
+			setConnected(false);
+			es.close();
+			esRef.current = null;
+
+			const attempts = reconnectAttemptsRef.current;
+			const delay =
+				Math.min(MAX_DELAY, BASE_DELAY * Math.pow(2, attempts)) *
+				(0.8 + Math.random() * 0.4);
+			reconnectAttemptsRef.current = attempts + 1;
+			setReconnectCount(reconnectAttemptsRef.current);
+
+			timeoutRef.current = setTimeout(async () => {
+				if (!isMountedRef.current) return;
+
+				const status = await probeEventStreamStatus();
+				if (status === 401) {
+					const baseUrl =
+						import.meta.env.VITE_API_BASE_URL ?? "http://localhost:8000";
+					window.location.assign(`${baseUrl}/auth/login`);
+					return;
+				}
+
+				if (status === 429) {
+					const penaltyDelay = delay + 5000;
+					timeoutRef.current = setTimeout(() => {
+						if (isMountedRef.current) {
+							connect();
+						}
+					}, penaltyDelay);
+					return;
+				}
+
+				connect();
+			}, delay);
+		};
+	}, []);
+
+	useEffect(() => {
+		isMountedRef.current = true;
+		connect();
+		return () => {
+			isMountedRef.current = false;
+			if (timeoutRef.current) {
+				clearTimeout(timeoutRef.current);
+				timeoutRef.current = null;
+			}
+			if (esRef.current) {
+				esRef.current.close();
+				esRef.current = null;
+			}
+		};
+	}, [connect]);
+
+	return { events, connected, reconnectCount, error };
+}

apps/web/src/state/events.tsx

@@ -0,0 +1,30 @@
+import React, { createContext, useContext, useMemo } from "react";
+import { useEvents } from "../hooks/use-events";
+import type { InstanceEventPayload } from "../types/events";
+
+interface EventContextValue {
+	events: InstanceEventPayload[];
+	connected: boolean;
+	reconnectCount: number;
+}
+
+const EventContext = createContext<EventContextValue>({
+	events: [],
+	connected: false,
+	reconnectCount: 0,
+});
+
+export function EventProvider({ children }: { children: React.ReactNode }) {
+	const { events, connected, reconnectCount } = useEvents();
+	const value = useMemo(
+		() => ({ events, connected, reconnectCount }),
+		[events, connected, reconnectCount],
+	);
+	return (
+		<EventContext.Provider value={value}>{children}</EventContext.Provider>
+	);
+}
+
+export function useEventContext() {
+	return useContext(EventContext);
+}

apps/web/src/state/toast.tsx

@@ -0,0 +1,206 @@
+import React, {
+	createContext,
+	useContext,
+	useState,
+	useCallback,
+	useRef,
+	useEffect,
+} from "react";
+
+export type ToastSeverity = "info" | "success" | "warning" | "error";
+
+export interface ToastItem {
+	id: string;
+	message: string;
+	severity: ToastSeverity;
+	duration: number | null;
+	createdAt: number;
+}
+
+interface ToastContextValue {
+	toasts: ToastItem[];
+	addToast: (
+		message: string,
+		severity: ToastSeverity,
+		duration?: number | null,
+	) => void;
+	removeToast: (id: string) => void;
+}
+
+const ToastContext = createContext<ToastContextValue | null>(null);
+
+let globalToastId = 0;
+
+export function ToastProvider({ children }: { children: React.ReactNode }) {
+	const [toasts, setToasts] = useState<ToastItem[]>([]);
+	const timersRef = useRef<Map<string, ReturnType<typeof setTimeout>>>(
+		new Map(),
+	);
+
+	const removeToast = useCallback((id: string) => {
+		setToasts((prev) => prev.filter((t) => t.id !== id));
+		const timer = timersRef.current.get(id);
+		if (timer) {
+			clearTimeout(timer);
+			timersRef.current.delete(id);
+		}
+	}, []);
+
+	const addToast = useCallback(
+		(
+			message: string,
+			severity: ToastSeverity,
+			duration: number | null = 3000,
+		) => {
+			const id = `toast-${++globalToastId}`;
+			const toast: ToastItem = {
+				id,
+				message,
+				severity,
+				duration,
+				createdAt: Date.now(),
+			};
+			setToasts((prev) => [...prev, toast]);
+
+			if (duration !== null && duration > 0) {
+				const timer = setTimeout(() => {
+					removeToast(id);
+				}, duration);
+				timersRef.current.set(id, timer);
+			}
+		},
+		[removeToast],
+	);
+
+	useEffect(() => {
+		toast.info = (msg, opts) => addToast(msg, "info", opts?.duration ?? 3000);
+		toast.success = (msg, opts) =>
+			addToast(msg, "success", opts?.duration ?? 3000);
+		toast.warning = (msg, opts) =>
+			addToast(msg, "warning", opts?.duration ?? 5000);
+		toast.error = (msg, opts) =>
+			addToast(msg, "error", opts?.duration ?? 10000);
+		return () => {
+			toast.info = () => {};
+			toast.success = () => {};
+			toast.warning = () => {};
+			toast.error = () => {};
+		};
+	}, [addToast]);
+
+	return (
+		<ToastContext.Provider value={{ toasts, addToast, removeToast }}>
+			{children}
+			<ToastContainer toasts={toasts} onDismiss={removeToast} />
+		</ToastContext.Provider>
+	);
+}
+
+export function useToast() {
+	const ctx = useContext(ToastContext);
+	if (!ctx) {
+		throw new Error("useToast must be used within ToastProvider");
+	}
+	return ctx;
+}
+
+type ToastFn = (message: string, opts?: { duration?: number }) => void;
+
+export const toast: {
+	info: ToastFn;
+	success: ToastFn;
+	warning: ToastFn;
+	error: ToastFn;
+} = {
+	info: () => {
+		/* assigned by ToastProvider */
+	},
+	success: () => {
+		/* assigned by ToastProvider */
+	},
+	warning: () => {
+		/* assigned by ToastProvider */
+	},
+	error: () => {
+		/* assigned by ToastProvider */
+	},
+};
+
+function severityStyles(severity: ToastSeverity): React.CSSProperties {
+	switch (severity) {
+		case "success":
+			return { backgroundColor: "#16a34a", color: "#fff" };
+		case "warning":
+			return { backgroundColor: "#d97706", color: "#fff" };
+		case "error":
+			return { backgroundColor: "#dc2626", color: "#fff" };
+		case "info":
+		default:
+			return { backgroundColor: "#2563eb", color: "#fff" };
+	}
+}
+
+function ToastContainer({
+	toasts,
+	onDismiss,
+}: {
+	toasts: ToastItem[];
+	onDismiss: (id: string) => void;
+}) {
+	return (
+		<div
+			style={{
+				position: "fixed",
+				top: 16,
+				right: 16,
+				zIndex: 9999,
+				display: "flex",
+				flexDirection: "column",
+				gap: 8,
+				maxWidth: 360,
+				width: "100%",
+				pointerEvents: "none",
+			}}
+		>
+			{toasts.map((t) => (
+				<div
+					key={t.id}
+					style={{
+						pointerEvents: "auto",
+						padding: "12px 16px",
+						borderRadius: 8,
+						boxShadow: "0 4px 12px rgba(0,0,0,0.15)",
+						display: "flex",
+						alignItems: "center",
+						justifyContent: "space-between",
+						gap: 12,
+						animation: "toastSlideIn 0.3s ease-out",
+						...severityStyles(t.severity),
+					}}
+				>
+					<span style={{ fontSize: 14, fontWeight: 500, lineHeight: 1.4 }}>
+						{t.message}
+					</span>
+					<button
+						onClick={() => onDismiss(t.id)}
+						style={{
+							background: "none",
+							border: "none",
+							color: "inherit",
+							cursor: "pointer",
+							fontSize: 18,
+							lineHeight: 1,
+							padding: 0,
+							margin: 0,
+							opacity: 0.8,
+						}}
+						aria-label="Dismiss toast"
+						type="button"
+					>
+						×
+					</button>
+				</div>
+			))}
+		</div>
+	);
+}

apps/web/src/styles.css

@@ -3420,6 +3420,17 @@ a.nav-item,
 	color: var(--danger, #dc2626);
 }
 
+.status-badge.starting,
+.status-badge.probing {
+	background: var(--info-light, #dbeafe);
+	color: var(--info, #2563eb);
+}
+
+.status-badge.unhealthy {
+	background: var(--warning-light, #fef3c7);
+	color: var(--warning, #d97706);
+}
+
 /* ============================================
    Mobile Terminal Styles
    ============================================ */
@@ -4491,3 +4502,26 @@ a:active,
 	gap: 0.5rem;
 	margin-top: 0.25rem;
 }
+
+/* Toast animations */
+@keyframes toastSlideIn {
+	from {
+		opacity: 0;
+		transform: translateX(100%);
+	}
+	to {
+		opacity: 1;
+		transform: translateX(0);
+	}
+}
+
+@keyframes toastFadeOut {
+	from {
+		opacity: 1;
+		transform: translateX(0);
+	}
+	to {
+		opacity: 0;
+		transform: translateX(100%);
+	}
+}

apps/web/src/types/events.ts

@@ -0,0 +1,17 @@
+export interface InstanceEventMetadata {
+	exit_code?: number;
+	tunnel_url?: string;
+	probe_output?: string;
+	error_type?: "container" | "tunnel" | "probe";
+	previous_status?: string;
+}
+
+export interface InstanceEventPayload {
+	event: string;
+	instance_id: string;
+	status?: string;
+	message?: string;
+	metadata: InstanceEventMetadata;
+	timestamp: string;
+	correlation_id: string;
+}