fix: use host bind mount for repos so tool instances can access workspace files

Replace named Docker volume (repo_data) with bind mount (/data/repos) in both
development and production compose files. The named volume trapped repo files
inside the API container; tool instances started via Docker socket on the host
could not see them, causing /workspace to mount as an empty directory.

Also fix 6 pre-existing test failures in test_tool_instances_legacy.py caused
by get_container_id/get_container_name moving to docker.py and new helpers
(_ensure_web_bind_address, _ensure_container_name_in_compose) being added.

- docker-compose.yml: repo_data:/data/repos -> /data/repos:/data/repos
- docker-compose.traefik.yml: same change + remove repo_data volume decl
- tests: update patch targets and add missing mock parameters

Quality gates: pytest test_tool_instances_legacy.py (10 passed)

.atl/.skill-registry.cache.json

@@ -1,3 +1,3 @@
 {
-  "fingerprint": "c324de9e9faf30231900c691aca5f3a07c7db099"
+  "fingerprint": "fdea8a74bb4c7449c01c4bd61646c895b10ede78"
 }

.atl/skill-registry.md

@@ -2,11 +2,12 @@
 
 <!-- Auto-generated by gentle-pi extensions/skill-registry.ts. Run /skill-registry:refresh to regenerate. -->
 
-Last updated: 2026-05-27
+Last updated: 2026-05-28
 
 ## Sources scanned
 
 - .opencode/skills
+- .claude/skills
 - /home/alex/.config/opencode/skills
 
 ## Contract
@@ -25,6 +26,7 @@ Last updated: 2026-05-27
 | `openspec-archive-change` | Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete. | project | `/home/alex/projects/headquarter/.opencode/skills/openspec-archive-change/SKILL.md` |
 | `openspec-explore` | Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change. | project | `/home/alex/projects/headquarter/.opencode/skills/openspec-explore/SKILL.md` |
 | `openspec-propose` | Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation. | project | `/home/alex/projects/headquarter/.opencode/skills/openspec-propose/SKILL.md` |
+| `sift-backlog` | Triage and organize backlog tasks into actionable plans. Use when asked to review the backlog, prioritize tasks, create plans from backlog items, or move tasks from backlog to open status. Handles the full workflow of listing backlog tasks, grouping related tasks into plans, setting priorities and dependencies, activating plans, and changing task status from backlog to open. | project | `/home/alex/projects/headquarter/.claude/skills/sift-backlog/SKILL.md` |
 
 ## Loading protocol
 

AGENTS.md

@@ -4,6 +4,10 @@
 
 OpenSpec is the source of truth. Superpowers is the default workflow. Keep changes small, scoped, and verified.
 
+## Communication
+
+All agent output, code comments, commit messages, documentation, and artifacts must be in **English** unless the user explicitly requests another language.
+
 ## Priority order
 
 1. Current user instruction

apps/api/alembic/versions/069d3da4dc9b_add_ssh_key_id_to_config_profiles.py

@@ -0,0 +1,32 @@
+"""add_ssh_key_id_to_config_profiles
+
+Revision ID: 069d3da4dc9b
+Revises: 2026_05_29_add_notifications_table
+Create Date: 2026-05-29 12:30:16.580532
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = "069d3da4dc9b"
+down_revision = "2026_05_29_add_notifications_table"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "config_profiles",
+        sa.Column(
+            "ssh_key_id",
+            sa.Uuid(),
+            sa.ForeignKey("ssh_keys.id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("config_profiles", "ssh_key_id")

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/alembic/versions/2026_05_28_add_tool_definition_manifests.py

@@ -232,14 +232,6 @@ def upgrade() -> None:
                             "writable": True,
                             "owner": "user",
                         },
-                        {
-                            "name": "ssh_keys",
-                            "target": "/home/user/.ssh",
-                            "source_type": "ssh_key",
-                            "mode": "0700",
-                            "file_mode": "0600",
-                            "readonly": True,
-                        },
                         {
                             "name": "pi_state",
                             "target": "/tmp/.pi/agents",

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

@@ -0,0 +1,69 @@
+"""add notifications table
+
+Revision ID: 2026_05_29_add_notifications_table
+Revises: 2026_05_28_add_monitoring_tables
+Create Date: 2026-05-29
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "2026_05_29_add_notifications_table"
+down_revision: str | None = "2026_05_28_add_monitoring_tables"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "notifications",
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column("user_id", sa.Uuid(), nullable=False),
+        sa.Column("category", sa.String(length=32), nullable=False),
+        sa.Column("severity", sa.String(length=16), nullable=False),
+        sa.Column("title", sa.String(length=255), nullable=False),
+        sa.Column("message", sa.Text(), nullable=True),
+        sa.Column("source_type", sa.String(length=64), nullable=True),
+        sa.Column("source_id", sa.Uuid(), nullable=True),
+        sa.Column(
+            "metadata",
+            sa.JSON(),
+            nullable=False,
+            server_default="{}",
+        ),
+        sa.Column("read_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("dismissed_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.ForeignKeyConstraint(
+            ["user_id"],
+            ["users.id"],
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        "idx_notifications_user_created_at",
+        "notifications",
+        ["user_id", sa.text("created_at DESC")],
+    )
+    op.create_index(
+        "idx_notifications_user_unread",
+        "notifications",
+        ["user_id", "read_at"],
+        postgresql_where=sa.text("read_at IS NULL"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("idx_notifications_user_unread", table_name="notifications")
+    op.drop_index("idx_notifications_user_created_at", table_name="notifications")
+    op.drop_table("notifications")

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

@@ -0,0 +1,27 @@
+"""add_ssh_key_ids_to_tool_instances
+
+Revision ID: 2026_05_29_add_ssh_key_ids_to_tool_instances
+Revises: 2026_05_29_drop_ssh_key_id_from_config_profiles
+Create Date: 2026-05-29 12:46:00.000000
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = "2026_05_29_add_ssh_key_ids_to_tool_instances"
+down_revision = "2026_05_29_drop_ssh_key_id_from_config_profiles"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "tool_instances",
+        sa.Column("ssh_key_ids", sa.JSON(), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("tool_instances", "ssh_key_ids")

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

@@ -0,0 +1,32 @@
+"""drop_ssh_key_id_from_config_profiles
+
+Revision ID: 2026_05_29_drop_ssh_key_id_from_config_profiles
+Revises: 069d3da4dc9b
+Create Date: 2026-05-29 12:45:00.000000
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = "2026_05_29_drop_ssh_key_id_from_config_profiles"
+down_revision = "069d3da4dc9b"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.drop_column("config_profiles", "ssh_key_id")
+
+
+def downgrade() -> None:
+    op.add_column(
+        "config_profiles",
+        sa.Column(
+            "ssh_key_id",
+            sa.Uuid(),
+            sa.ForeignKey("ssh_keys.id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+    )

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

@@ -0,0 +1,54 @@
+"""fix code-server bind-addr to host in DB template
+
+Revision ID: 2026_05_29_fix_code_server_bind_addr
+Revises: 2026_05_29_fix_web_tool_bind_address
+Create Date: 2026-05-29 15:00:00.000000
+
+"""
+
+from typing import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "2026_05_29_fix_code_server_bind_addr"
+down_revision: str | None = "2026_05_29_fix_web_tool_bind_address"
+branch_labels: Sequence[str] | None = None
+depends_on: Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # Find code-server tool types with broken --bind-addr in compose template
+    result = conn.execute(
+        sa.text("""
+            SELECT id, compose_template
+            FROM tool_types
+            WHERE name = 'code-server'
+            AND compose_template LIKE '%--bind-addr%'
+        """)
+    ).fetchall()
+
+    for tool_id, compose_template in result:
+        updated = compose_template.replace(
+            "--bind-addr 0.0.0.0:8443", "--host 0.0.0.0"
+        ).replace("--bind-addr", "--host 0.0.0.0")
+
+        conn.execute(
+            sa.text("""
+                UPDATE tool_types
+                SET compose_template = :compose_template
+                WHERE id = :id
+            """),
+            {"compose_template": updated, "id": tool_id},
+        )
+
+        print(
+            f"Fixed code-server template ({tool_id}): replaced --bind-addr with --host"
+        )
+
+
+def downgrade() -> None:
+    pass

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

@@ -0,0 +1,148 @@
+"""Fix code-server bind address to include port
+
+Revision ID: 2026_05_29_fix_code_server_bind_addr_port
+Revises: 2026_05_29_remove_lsio_command_override
+Create Date: 2026-05-29 18:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+import yaml
+
+# revision identifiers, used by Alembic.
+revision: str = "2026_05_29_fix_code_server_bind_addr_port"
+down_revision: Union[str, None] = "2026_05_29_remove_lsio_command_override"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def _fix_tool_type_templates(conn) -> None:
+    """Fix code-server tool type templates with broken --host override."""
+    result = conn.execute(
+        sa.text("""
+            SELECT id, compose_template, default_port
+            FROM tool_types
+            WHERE name = 'code-server'
+            AND compose_template LIKE '%--host%'
+        """)
+    ).fetchall()
+
+    for tool_id, compose_template, default_port in result:
+        port = default_port or 8443
+        expected = f"--bind-addr 0.0.0.0:{port}"
+
+        # Replace any line containing --host with the correct bind-addr
+        lines = compose_template.split("\n")
+        new_lines = []
+        modified = False
+        for line in lines:
+            if "command:" in line and "--host" in line:
+                indent = line[: len(line) - len(line.lstrip())]
+                new_lines.append(f"{indent}command: {expected}")
+                modified = True
+            else:
+                new_lines.append(line)
+
+        if not modified:
+            continue
+
+        updated = "\n".join(new_lines)
+        conn.execute(
+            sa.text("""
+                UPDATE tool_types
+                SET compose_template = :compose_template
+                WHERE id = :id
+            """),
+            {"compose_template": updated, "id": tool_id},
+        )
+        print(f"Fixed code-server template ({tool_id}): replaced --host with {expected}")
+
+
+def _fix_instance_compose_files(conn) -> None:
+    """Fix existing instance compose files on disk with broken --host override."""
+    from pathlib import Path
+
+    # Use information_schema to check if compose_path column exists
+    col_result = conn.execute(
+        sa.text("""
+            SELECT column_name
+            FROM information_schema.columns
+            WHERE table_name = 'tool_instances'
+            AND column_name = 'compose_path'
+        """)
+    ).fetchone()
+
+    if not col_result:
+        print("compose_path column not found, skipping instance file fixes")
+        return
+
+    result = conn.execute(
+        sa.text("""
+            SELECT id, compose_path, tool_type_id
+            FROM tool_instances
+            WHERE compose_path IS NOT NULL
+        """)
+    ).fetchall()
+
+    for instance_id, compose_path, tool_type_id in result:
+        path = Path(compose_path)
+        if not path.exists():
+            continue
+
+        try:
+            content = path.read_text()
+        except Exception:
+            continue
+
+        if "--host" not in content:
+            continue
+
+        # Get default_port from tool_type
+        port_result = conn.execute(
+            sa.text("""
+                SELECT default_port FROM tool_types WHERE id = :id
+            """),
+            {"id": tool_type_id},
+        ).fetchone()
+        port = port_result[0] if port_result and port_result[0] else 8443
+        expected = f"--bind-addr 0.0.0.0:{port}"
+
+        try:
+            data = yaml.safe_load(content)
+        except Exception:
+            continue
+
+        if not data or "services" not in data:
+            continue
+
+        modified = False
+        for svc in data["services"].values():
+            if "command" in svc:
+                cmd = svc["command"]
+                if "--host" in cmd:
+                    svc["command"] = expected
+                    modified = True
+
+        if not modified:
+            continue
+
+        try:
+            path.write_text(yaml.dump(data, default_flow_style=False))
+            print(
+                f"Fixed code-server instance compose ({instance_id}): "
+                f"replaced --host with {expected}"
+            )
+        except Exception as exc:
+            print(f"Failed to fix instance {instance_id}: {exc}")
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    _fix_tool_type_templates(conn)
+    _fix_instance_compose_files(conn)
+
+
+def downgrade() -> None:
+    pass

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

@@ -0,0 +1,140 @@
+"""fix web tool bind address to 0.0.0.0
+
+Revision ID: 2026_05_29_fix_web_tool_bind_address
+Revises: 2026_05_29_remove_ssh_keys_mount_from_manifest
+Create Date: 2026-05-29 14:00:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "2026_05_29_fix_web_tool_bind_address"
+down_revision: Union[str, None] = "2026_05_29_remove_ssh_keys_mount_from_manifest"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def _fix_code_server_compose(conn) -> None:
+    """Update code-server compose template to bind to 0.0.0.0."""
+    result = conn.execute(
+        sa.text("""
+            SELECT id, compose_template, definition_type
+            FROM tool_types
+            WHERE name = 'code-server'
+        """)
+    ).fetchone()
+
+    if result is None:
+        return
+
+    tool_id, compose_template, definition_type = result
+
+    if definition_type != "compose" or not compose_template:
+        return
+
+    # Fix or add command to bind to 0.0.0.0
+    lines = compose_template.split("\n")
+    new_lines = []
+    image_line_idx = -1
+    command_fixed = False
+    for i, line in enumerate(lines):
+        # Replace broken --bind-addr with correct --host
+        if "command:" in line and "--bind-addr" in line:
+            indent = line[: len(line) - len(line.lstrip())]
+            new_lines.append(f"{indent}command: --host 0.0.0.0")
+            command_fixed = True
+            continue
+        new_lines.append(line)
+        if "image:" in line and image_line_idx == -1:
+            image_line_idx = i
+
+    # If no command line exists, insert one after image
+    if not command_fixed and image_line_idx != -1:
+        image_line = lines[image_line_idx]
+        indent = image_line[: len(image_line) - len(image_line.lstrip())]
+        # Insert after the image line in new_lines
+        insert_idx = new_lines.index(image_line) + 1
+        new_lines.insert(insert_idx, f"{indent}command: --host 0.0.0.0")
+        command_fixed = True
+
+    if not command_fixed:
+        return
+
+    updated_compose = "\n".join(new_lines)
+
+    conn.execute(
+        sa.text("""
+            UPDATE tool_types
+            SET compose_template = :compose_template
+            WHERE id = :id
+        """),
+        {"compose_template": updated_compose, "id": tool_id},
+    )
+
+    print(f"Updated code-server tool type ({tool_id}) to bind to 0.0.0.0")
+
+
+def _fix_jupyter_compose(conn) -> None:
+    """Update jupyter-notebook compose template to bind to 0.0.0.0."""
+    result = conn.execute(
+        sa.text("""
+            SELECT id, compose_template, definition_type
+            FROM tool_types
+            WHERE name = 'jupyter-notebook'
+        """)
+    ).fetchone()
+
+    if result is None:
+        return
+
+    tool_id, compose_template, definition_type = result
+
+    if definition_type != "compose" or not compose_template:
+        return
+
+    if "command:" in compose_template:
+        return
+
+    lines = compose_template.split("\n")
+    new_lines = []
+    image_line_idx = -1
+    for i, line in enumerate(lines):
+        new_lines.append(line)
+        if "image:" in line and image_line_idx == -1:
+            image_line_idx = i
+            indent = line[: len(line) - len(line.lstrip())]
+            # Jupyter needs --ip=0.0.0.0 to bind to all interfaces
+            new_lines.append(
+                f"{indent}command: start-notebook.sh --ip=0.0.0.0 --port=8888 --no-browser"
+            )
+
+    if image_line_idx == -1:
+        return
+
+    updated_compose = "\n".join(new_lines)
+
+    conn.execute(
+        sa.text("""
+            UPDATE tool_types
+            SET compose_template = :compose_template
+            WHERE id = :id
+        """),
+        {"compose_template": updated_compose, "id": tool_id},
+    )
+
+    print(f"Updated jupyter-notebook tool type ({tool_id}) to bind to 0.0.0.0:8888")
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    _fix_code_server_compose(conn)
+    _fix_jupyter_compose(conn)
+
+
+def downgrade() -> None:
+    # Cannot safely downgrade without knowing the original compose_template
+    pass

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

@@ -0,0 +1,121 @@
+"""Remove broken command override from LSIO code-server templates
+
+Revision ID: 2026_05_29_remove_lsio_command_override
+Revises: 2026_05_29_fix_code_server_bind_addr
+Create Date: 2026-05-29 15:05:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "2026_05_29_remove_lsio_command_override"
+down_revision: str | None = "2026_05_29_fix_code_server_bind_addr"
+branch_labels: Sequence[str] | None = None
+depends_on: Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # Fix tool_types templates in DB
+    result = conn.execute(
+        sa.text("""
+            SELECT id, compose_template
+            FROM tool_types
+            WHERE name = 'code-server'
+        """)
+    ).fetchall()
+
+    import yaml
+    from pathlib import Path
+
+    for tool_id, compose_template in result:
+        try:
+            data = yaml.safe_load(compose_template)
+        except Exception:
+            continue
+
+        if not data or "services" not in data:
+            continue
+
+        modified = False
+        for svc in data["services"].values():
+            image = svc.get("image", "")
+            if not image or "linuxserver" not in image:
+                continue
+            if "command" in svc:
+                cmd = svc["command"]
+                if "--bind-addr" in cmd or "--host" in cmd:
+                    del svc["command"]
+                    modified = True
+
+        if modified:
+            updated = yaml.dump(data, default_flow_style=False)
+            conn.execute(
+                sa.text("""
+                    UPDATE tool_types
+                    SET compose_template = :compose_template
+                    WHERE id = :id
+                """),
+                {"compose_template": updated, "id": tool_id},
+            )
+            print(f"Removed broken command override from LSIO template ({tool_id})")
+
+    # Fix existing instance compose files on disk
+    # Use information_schema to check if compose_path column exists
+    col_result = conn.execute(
+        sa.text("""
+            SELECT column_name
+            FROM information_schema.columns
+            WHERE table_name = 'tool_instances'
+            AND column_name = 'compose_path'
+        """)
+    ).fetchone()
+
+    if col_result:
+        result = conn.execute(
+            sa.text("""
+                SELECT id, compose_path
+                FROM tool_instances
+                WHERE compose_path IS NOT NULL
+            """)
+        ).fetchall()
+
+        for instance_id, compose_path in result:
+            path = Path(compose_path)
+            if not path.exists():
+                continue
+            try:
+                content = path.read_text()
+                data = yaml.safe_load(content)
+            except Exception:
+                continue
+
+            if not data or "services" not in data:
+                continue
+
+            modified = False
+            for svc in data["services"].values():
+                image = svc.get("image", "")
+                if not image or "linuxserver" not in image:
+                    continue
+                if "command" in svc:
+                    cmd = svc["command"]
+                    if "--bind-addr" in cmd or "--host" in cmd:
+                        del svc["command"]
+                        modified = True
+
+            if modified:
+                path.write_text(yaml.dump(data, default_flow_style=False))
+                print(
+                    f"Removed broken command override from instance compose "
+                    f"({instance_id})"
+                )
+
+
+def downgrade() -> None:
+    pass

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

@@ -0,0 +1,105 @@
+"""remove ssh_keys mount from pi-agent manifest
+
+Revision ID: 2026_05_29_remove_ssh_keys_mount_from_manifest
+Revises: 2026_05_29_add_ssh_key_ids_to_tool_instances
+Create Date: 2026-05-29 14:00:00.000000
+
+"""
+
+import json
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "2026_05_29_remove_ssh_keys_mount_from_manifest"
+down_revision: Union[str, None] = "2026_05_29_add_ssh_key_ids_to_tool_instances"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Remove the ssh_keys mount from the pi-agent manifest."""
+    conn = op.get_bind()
+
+    # Get the pi-agent manifest
+    result = conn.execute(
+        sa.text(
+            "SELECT id, manifest FROM tool_definition_manifests WHERE name = 'pi-agent'"
+        )
+    )
+    row = result.fetchone()
+    if not row:
+        return
+
+    manifest_id, manifest_json = row
+    manifest = (
+        manifest_json if isinstance(manifest_json, dict) else json.loads(manifest_json)
+    )
+
+    mounts = manifest.get("mounts", [])
+    original_count = len(mounts)
+
+    # Remove any mount named "ssh_keys"
+    filtered_mounts = [m for m in mounts if m.get("name") != "ssh_keys"]
+
+    if len(filtered_mounts) < original_count:
+        manifest["mounts"] = filtered_mounts
+        conn.execute(
+            sa.text(
+                "UPDATE tool_definition_manifests SET manifest = :manifest WHERE id = :id"
+            ),
+            {
+                "manifest": json.dumps(manifest),
+                "id": manifest_id,
+            },
+        )
+
+
+def downgrade() -> None:
+    """Restore the ssh_keys mount to the pi-agent manifest."""
+    conn = op.get_bind()
+
+    result = conn.execute(
+        sa.text(
+            "SELECT id, manifest FROM tool_definition_manifests WHERE name = 'pi-agent'"
+        )
+    )
+    row = result.fetchone()
+    if not row:
+        return
+
+    manifest_id, manifest_json = row
+    manifest = (
+        manifest_json if isinstance(manifest_json, dict) else json.loads(manifest_json)
+    )
+
+    mounts = manifest.get("mounts", [])
+
+    # Check if ssh_keys mount already exists
+    if any(m.get("name") == "ssh_keys" for m in mounts):
+        return
+
+    # Add the ssh_keys mount back
+    mounts.append(
+        {
+            "name": "ssh_keys",
+            "target": "/home/user/.ssh",
+            "source_type": "ssh_key",
+            "mode": "0700",
+            "file_mode": "0600",
+            "readonly": True,
+        }
+    )
+    manifest["mounts"] = mounts
+
+    conn.execute(
+        sa.text(
+            "UPDATE tool_definition_manifests SET manifest = :manifest WHERE id = :id"
+        ),
+        {
+            "manifest": json.dumps(manifest),
+            "id": manifest_id,
+        },
+    )

apps/api/src/api/__init__.py

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

apps/api/src/api/config_profiles.py

@@ -1,6 +1,8 @@
 """Config profile API endpoints."""
 
 import logging
+import os
+import subprocess
 import uuid
 from typing import Any
 
@@ -21,6 +23,7 @@ from src.services.config_profile_resolver import (
     resolve_profile,
     resolved_profile_to_dict,
 )
+from src.utils.git_url_parser import parse_git_url
 
 logger = logging.getLogger(__name__)
 
@@ -835,3 +838,171 @@ async def resolve_default_profile(
     # Fall back to first created compatible profile
     first = profiles[0]
     return {"profile_id": str(first.id), "profile_name": first.name}
+
+
+class ValidateGitUrlRequest(BaseModel):
+    url: str = Field(description="Git remote URL to validate")
+    ssh_key_id: str | None = Field(
+        default=None, description="Optional SSH key ID for private repos"
+    )
+
+
+class ValidateGitUrlResponse(BaseModel):
+    valid: bool
+    suggested_url: str | None = None
+    branches: list[str] | None = None
+    default_branch: str | None = None
+    error: str | None = None
+    error_code: str | None = None
+
+
+@router.post("/validate-git-url", response_model=ValidateGitUrlResponse)
+async def validate_git_url(
+    data: ValidateGitUrlRequest,
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> ValidateGitUrlResponse:
+    """Validate a git remote URL and list available branches.
+
+    Parses the URL, suggests corrections for browser URLs, and runs
+    git ls-remote to verify reachability and enumerate branches.
+    """
+    parse_result = parse_git_url(data.url)
+    original_url = data.url.strip()
+    url_to_check = parse_result.get("base_url") or original_url
+
+    if not url_to_check:
+        return ValidateGitUrlResponse(
+            valid=False,
+            error=parse_result.get("message", "Invalid URL"),
+            error_code=parse_result.get("error_code", "INVALID_URL"),
+        )
+
+    # If the URL needed parsing, return suggestion without checking remote
+    if parse_result.get("needs_parsing") and url_to_check != original_url:
+        return ValidateGitUrlResponse(
+            valid=False,
+            suggested_url=url_to_check,
+            error=parse_result.get("message"),
+            error_code=parse_result.get("error_code", "URL_NEEDS_PARSING"),
+        )
+
+    # Optional SSH key for private repos
+    env = None
+    key_path = None
+    if data.ssh_key_id:
+        from src.models.ssh_key import SSHKey
+        from src.services.ssh_keys import _get_fernet
+
+        try:
+            ssh_key_uuid = uuid.UUID(data.ssh_key_id)
+        except ValueError:
+            return ValidateGitUrlResponse(
+                valid=False,
+                error="Invalid SSH key ID format",
+                error_code="INVALID_SSH_KEY",
+            )
+
+        ssh_key = await session.get(SSHKey, ssh_key_uuid)
+        if ssh_key is None or ssh_key.user_id != current_user_id:
+            return ValidateGitUrlResponse(
+                valid=False,
+                error="SSH key not found or not authorized",
+                error_code="SSH_KEY_NOT_FOUND",
+            )
+
+        import tempfile
+
+        fernet = _get_fernet()
+        private_key = fernet.decrypt(ssh_key.private_key_encrypted.encode()).decode()
+        fd, key_path = tempfile.mkstemp(prefix="ssh_key_")
+        try:
+            os.write(fd, private_key.encode())
+        finally:
+            os.close(fd)
+        os.chmod(key_path, 0o600)
+        env = {
+            "GIT_SSH_COMMAND": f"ssh -i {key_path} -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null"
+        }
+
+    try:
+        result = subprocess.run(
+            ["git", "ls-remote", "--heads", url_to_check],
+            capture_output=True,
+            text=True,
+            timeout=30,
+            env={**os.environ, **env} if env else None,
+        )
+    except subprocess.TimeoutExpired:
+        if key_path and os.path.exists(key_path):
+            os.unlink(key_path)
+        return ValidateGitUrlResponse(
+            valid=False,
+            error="Remote repository check timed out",
+            error_code="TIMEOUT",
+        )
+    except FileNotFoundError:
+        if key_path and os.path.exists(key_path):
+            os.unlink(key_path)
+        return ValidateGitUrlResponse(
+            valid=False,
+            error="git command not found on server",
+            error_code="GIT_NOT_FOUND",
+        )
+    finally:
+        if key_path and os.path.exists(key_path):
+            os.unlink(key_path)
+
+    if result.returncode != 0:
+        stderr = result.stderr.strip()
+        if (
+            "could not resolve" in stderr.lower()
+            or "unable to access" in stderr.lower()
+        ):
+            error_msg = "Could not reach repository. Check the URL and network access."
+            error_code = "UNREACHABLE"
+        elif (
+            "authentication" in stderr.lower() or "permission denied" in stderr.lower()
+        ):
+            error_msg = (
+                "Authentication failed. Provide an SSH key for private repositories."
+            )
+            error_code = "AUTH_FAILED"
+        else:
+            error_msg = f"Repository not accessible: {stderr[:200]}"
+            error_code = "REMOTE_ERROR"
+        return ValidateGitUrlResponse(
+            valid=False,
+            error=error_msg,
+            error_code=error_code,
+        )
+
+    # Parse branches from ls-remote output
+    branches: list[str] = []
+    default_branch = "main"
+    for line in result.stdout.strip().split("\n"):
+        if not line.strip():
+            continue
+        parts = line.split()
+        if len(parts) == 2:
+            ref = parts[1]
+            # refs/heads/branch-name
+            if ref.startswith("refs/heads/"):
+                branch_name = ref[len("refs/heads/") :]
+                branches.append(branch_name)
+                if branch_name in ("main", "master"):
+                    default_branch = branch_name
+
+    if not branches:
+        return ValidateGitUrlResponse(
+            valid=False,
+            error="No branches found in remote repository",
+            error_code="NO_BRANCHES",
+        )
+
+    return ValidateGitUrlResponse(
+        valid=True,
+        suggested_url=url_to_check if url_to_check != original_url else None,
+        branches=branches,
+        default_branch=default_branch,
+    )

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/notifications.py

@@ -0,0 +1,161 @@
+"""Notification API endpoints."""
+
+import uuid
+from datetime import datetime
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from pydantic import BaseModel, ConfigDict, Field
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.auth.dependencies import get_current_user, get_db_session
+from src.models.user import User
+from src.models.user_config import UserConfig
+from src.services.notification_service import notification_service
+
+router = APIRouter(prefix="/notifications", tags=["notifications"])
+
+
+class NotificationItem(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    user_id: uuid.UUID
+    category: str
+    severity: str
+    title: str
+    message: str | None
+    source_type: str | None
+    source_id: uuid.UUID | None
+    notification_metadata: dict = Field(serialization_alias="metadata")
+    read_at: datetime | None
+    dismissed_at: datetime | None
+    created_at: datetime
+
+
+class NotificationListResponse(BaseModel):
+    items: list[NotificationItem]
+    total: int
+    limit: int
+    offset: int
+
+
+class UnreadCountResponse(BaseModel):
+    count: int
+
+
+class MarkAllReadResponse(BaseModel):
+    marked_count: int
+
+
+class ClearAllResponse(BaseModel):
+    cleared_count: int
+
+
+async def _get_mute_categories(
+    session: AsyncSession,
+    user_id: uuid.UUID,
+) -> list[str]:
+    """Read notification mute categories from user config."""
+    from sqlalchemy import select
+
+    result = await session.execute(
+        select(UserConfig).where(UserConfig.user_id == user_id)
+    )
+    config = result.scalar_one_or_none()
+    if config is None:
+        return []
+    mute_categories = config.config.get("notification_mute_categories", [])
+    if isinstance(mute_categories, list):
+        return mute_categories
+    return []
+
+
+@router.get("", response_model=NotificationListResponse)
+async def list_notifications(
+    limit: int = Query(20, ge=1, le=100),
+    offset: int = Query(0, ge=0),
+    unread_only: bool = Query(False),
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_db_session),
+) -> NotificationListResponse:
+    """List notifications for the authenticated user."""
+    mute_categories = await _get_mute_categories(session, user.id)
+    items, total = await notification_service.list_notifications(
+        session,
+        user.id,
+        limit=limit,
+        offset=offset,
+        unread_only=unread_only,
+        mute_categories=mute_categories,
+    )
+    return NotificationListResponse(
+        items=[NotificationItem.model_validate(item) for item in items],
+        total=total,
+        limit=limit,
+        offset=offset,
+    )
+
+
+@router.get("/unread", response_model=UnreadCountResponse)
+async def get_unread_count(
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_db_session),
+) -> UnreadCountResponse:
+    """Get unread notification count for the authenticated user."""
+    count = await notification_service.get_unread_count(session, user.id)
+    return UnreadCountResponse(count=count)
+
+
+@router.patch("/{notification_id}/read", response_model=NotificationItem)
+async def mark_notification_read(
+    notification_id: uuid.UUID,
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_db_session),
+) -> NotificationItem:
+    """Mark a single notification as read."""
+    try:
+        notification = await notification_service.mark_read(
+            session, notification_id, user.id
+        )
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Notification not found",
+        ) from exc
+    return NotificationItem.model_validate(notification)
+
+
+@router.post("/mark-all-read", response_model=MarkAllReadResponse)
+async def mark_all_read(
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_db_session),
+) -> MarkAllReadResponse:
+    """Mark all unread notifications as read."""
+    marked = await notification_service.mark_all_read(session, user.id)
+    return MarkAllReadResponse(marked_count=marked)
+
+
+@router.delete("", status_code=status.HTTP_200_OK)
+async def clear_all_notifications(
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_db_session),
+) -> ClearAllResponse:
+    """Dismiss all notifications for the authenticated user."""
+    cleared = await notification_service.dismiss_all(session, user.id)
+    return ClearAllResponse(cleared_count=cleared)
+
+
+@router.delete("/{notification_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def dismiss_notification(
+    notification_id: uuid.UUID,
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_db_session),
+) -> None:
+    """Soft-delete (dismiss) a single notification."""
+    try:
+        await notification_service.dismiss(session, notification_id, user.id)
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Notification not found",
+        ) from exc

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
@@ -50,10 +52,10 @@ from src.services.docker import (
     find_free_port,
     get_container_id,
     get_container_logs,
-    get_container_name,
     get_container_status,
     recreate_tunnel,
     render_compose_template,
+    sort_volumes_by_specificity,
     start_cloudflared_tunnel,
     stop_cloudflared_tunnel,
     wait_for_container_running,
@@ -72,11 +74,12 @@ from src.services.manifest_compiler import (
     merge_with_config,
     resolve_base,
 )
-from src.services.permission_fixer import apply_mount_permissions
+from src.services.permission_fixer import apply_mount_permissions, apply_ssh_permissions
 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(
@@ -431,6 +434,9 @@ class CreateInstanceRequest(BaseModel):
     config_profile_id: str | None = Field(
         default=None, description="Optional config profile ID for launch"
     )
+    ssh_key_ids: list[str] = Field(
+        default_factory=list, description="SSH key IDs to mount into container ~/.ssh"
+    )
 
 
 class StartInstanceRequest(BaseModel):
@@ -441,6 +447,9 @@ class StartInstanceRequest(BaseModel):
     config_profile_id: str | None = Field(
         default=None, description="Config profile ID to apply, or null for none"
     )
+    ssh_key_ids: list[str] = Field(
+        default_factory=list, description="SSH key IDs to mount into container ~/.ssh"
+    )
 
 
 async def _validate_config_profile(
@@ -465,7 +474,7 @@ async def _validate_config_profile(
     Raises:
         HTTPException: If profile is not found, not owned, or incompatible.
     """
-    if profile_id is None:
+    if not profile_id:
         return None
 
     try:
@@ -596,12 +605,149 @@ def _modify_compose_file(
                 else:
                     service_config["volumes"].append(f"{source}:{target}:{vol_type}")
 
+        # Sort volumes so parent paths come before child paths
+        if service_config.get("volumes"):
+            service_config["volumes"] = sort_volumes_by_specificity(
+                service_config["volumes"]
+            )
+
         break  # Only modify the first service
 
     # Write back
     compose_file.write_text(yaml.dump(compose_data, default_flow_style=False))
 
 
+def _ensure_container_name_in_compose(compose_path: str, container_name: str) -> None:
+    """Ensure compose file has explicit container_name for predictable naming.
+
+    Docker Compose auto-generates container names from the project directory
+    when container_name is absent. This breaks tunnel connectivity because
+    get_container_name(instance.name) cannot find the container. We inject
+    container_name into every service so the container has a predictable name.
+    """
+    import yaml
+    from pathlib import Path
+
+    compose_file = Path(compose_path)
+    if not compose_file.exists():
+        return
+
+    content = compose_file.read_text()
+    compose_data = yaml.safe_load(content)
+
+    if not compose_data or "services" not in compose_data:
+        return
+
+    modified = False
+    for svc_name, svc_config in compose_data["services"].items():
+        if "container_name" not in svc_config:
+            svc_config["container_name"] = container_name.lower()
+            modified = True
+
+    if modified:
+        compose_file.write_text(yaml.dump(compose_data, default_flow_style=False))
+        logger.info(
+            "Injected container_name '%s' into compose file",
+            container_name.lower(),
+        )
+
+
+def _ensure_web_bind_address(
+    compose_path: str, tool_type_name: str, default_port: int
+) -> None:
+    """Auto-inject bind address for known web tools that default to 127.0.0.1.
+
+    Many web tools (code-server, jupyter) bind to localhost by default,
+    making them inaccessible from the Docker network. This function detects
+    known tool images and injects the correct --bind-addr or --ip flag.
+    """
+    import yaml
+    from pathlib import Path
+
+    if default_port <= 0:
+        return
+
+    KNOWN_BIND_FIXES: dict[str, str] = {
+        "code-server": f"--bind-addr 0.0.0.0:{default_port}",
+        "jupyter-notebook": f"start-notebook.sh --ip=0.0.0.0 --port={default_port} --no-browser",
+    }
+
+    bind_command = KNOWN_BIND_FIXES.get(tool_type_name)
+    if not bind_command:
+        return
+
+    compose_file = Path(compose_path)
+    if not compose_file.exists():
+        return
+
+    content = compose_file.read_text()
+    compose_data = yaml.safe_load(content)
+
+    if not compose_data or "services" not in compose_data:
+        return
+
+    for service_config in compose_data["services"].values():
+        image = service_config.get("image", "")
+        if not image:
+            continue
+
+        # LSIO images already bind to 0.0.0.0 — command override breaks s6 init
+        if "linuxserver" in image:
+            existing_command = service_config.get("command", "")
+            if "--bind-addr" in existing_command or "--host" in existing_command:
+                del service_config["command"]
+                compose_file.write_text(
+                    yaml.dump(compose_data, default_flow_style=False)
+                )
+                logger.warning(
+                    "Removed broken command override from LSIO image: %s",
+                    existing_command,
+                )
+                return
+            return
+
+        # Check if the image matches a known tool
+        is_code_server = tool_type_name == "code-server" and (
+            "code-server" in image or "coder" in image
+        )
+        is_jupyter = tool_type_name == "jupyter-notebook" and (
+            "jupyter" in image or "notebook" in image
+        )
+        if not is_code_server and not is_jupyter:
+            continue
+
+        existing_command = service_config.get("command", "")
+        if existing_command:
+            # Already correct — nothing to do
+            if bind_command in existing_command:
+                return
+            # Fix broken or outdated bind flags
+            if (
+                "--bind-addr" in existing_command
+                or "--host" in existing_command
+                or "--ip=" in existing_command
+            ):
+                service_config["command"] = bind_command
+                compose_file.write_text(
+                    yaml.dump(compose_data, default_flow_style=False)
+                )
+                logger.warning(
+                    "Replaced broken bind address for %s: %s → %s",
+                    tool_type_name,
+                    existing_command,
+                    bind_command,
+                )
+                return
+            # Some other command override exists — don't touch it
+            return
+
+        # No command yet — inject the correct bind address
+        service_config["command"] = bind_command
+        compose_file.write_text(yaml.dump(compose_data, default_flow_style=False))
+        logger.info("Injected bind address for %s: %s", tool_type_name, bind_command)
+        return
+
+
 @router.post(
     "/{project_id}/repositories/{repo_id}/instances",
     summary="Create tool instance",
@@ -838,7 +984,7 @@ services:
                     )
 
             # Determine home directory for path expansion
-            home_dir = get_manifest_home_dir(manifest)
+            _home_dir = get_manifest_home_dir(manifest)
 
             image_tag = compute_image_tag(tool_type.name, manifest)
 
@@ -954,10 +1100,20 @@ services:
             if data.new_branch
             else (data.branch if data.clone_mode == "clone" else None),
             selected_config_profile_id=selected_profile_id,
+            ssh_key_ids=data.ssh_key_ids or None,
         )
         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),
@@ -1035,6 +1191,7 @@ async def list_instances(
                 "port": i.port,
                 "clone_mode": i.clone_mode,
                 "branch": i.branch,
+                "ssh_key_ids": i.ssh_key_ids or [],
                 "created_at": i.created_at.isoformat(),
             }
         )
@@ -1281,6 +1438,11 @@ async def start_instance(
         instance.selected_config_profile_id = selected_profile_id
         await session.commit()
 
+    # Store SSH key selection if provided
+    if data and data.ssh_key_ids is not None:
+        instance.ssh_key_ids = data.ssh_key_ids or None
+        await session.commit()
+
     if not instance.compose_path or not os.path.exists(instance.compose_path):
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST, detail="compose file not found"
@@ -1298,14 +1460,38 @@ async def start_instance(
     working_directory = None
     extra_volumes = []
 
-    # Fetch tool type early to determine home directory
+    # Fetch tool type early to determine home directory and container user
     tool_type = await session.get(ToolType, instance.tool_type_id)
     home_dir = "/root"
+    container_uid = 0
+    container_gid = 0
     if tool_type and tool_type.definition_type == "manifest" and tool_type.manifest_id:
         from src.models.tool_definition_manifest import ToolDefinitionManifest
+
         manifest_def = await session.get(ToolDefinitionManifest, tool_type.manifest_id)
         if manifest_def:
-            home_dir = get_manifest_home_dir(dict(manifest_def.manifest))
+            manifest = dict(manifest_def.manifest)
+            # Merge with base definition if referenced (user config is often in base)
+            if manifest_def.base_definition_id:
+                base_def = await session.get(
+                    ToolDefinitionManifest, manifest_def.base_definition_id
+                )
+                if base_def:
+                    manifest = resolve_base(
+                        deep_merge(dict(base_def.manifest), manifest)
+                    )
+            home_dir = get_manifest_home_dir(manifest)
+            user_cfg = manifest.get("user")
+            if user_cfg:
+                container_uid = user_cfg.get("uid", 0)
+                container_gid = user_cfg.get("gid", 0)
+            logger.debug(
+                "Manifest user resolved for instance %s: uid=%s, gid=%s, home=%s",
+                instance.id,
+                container_uid,
+                container_gid,
+                home_dir,
+            )
 
     # Apply selected config profile if any
     instance_dir = os.path.dirname(instance.compose_path)
@@ -1368,6 +1554,47 @@ async def start_instance(
             "Wrote %d config files for instance %s", len(config_files), instance.id
         )
 
+    # Mount selected SSH keys into container home dir
+    if instance.ssh_key_ids:
+        for key_id in instance.ssh_key_ids:
+            ssh_key = await session.get(SSHKey, uuid.UUID(key_id))
+            if ssh_key and ssh_key.user_id == user_id:
+                try:
+                    ssh_dir = prepare_ssh_key_files(
+                        instance_dir,
+                        ssh_key,
+                        subdir=f"mounts/ssh/{key_id}/.ssh",
+                        uid=container_uid,
+                        gid=container_gid,
+                    )
+                    ssh_target = os.path.join(home_dir, ".ssh")
+                    extra_volumes.append(
+                        {
+                            "source": ssh_dir,
+                            "target": ssh_target,
+                            "type": "bind",
+                        }
+                    )
+                    logger.debug(
+                        "Mounted SSH key %s for instance %s to %s",
+                        ssh_key.name,
+                        instance.id,
+                        ssh_target,
+                    )
+                except Exception as exc:
+                    logger.error(
+                        "Failed to prepare SSH key %s for instance %s: %s",
+                        key_id,
+                        instance.id,
+                        exc,
+                    )
+            else:
+                logger.warning(
+                    "SSH key %s not found or not authorized for user %s",
+                    key_id,
+                    user_id,
+                )
+
     # ── MANIFEST-BASED FLOW ──────────────────────────────────────
     resolved_manifest = None
 
@@ -1418,12 +1645,14 @@ async def start_instance(
                 ssh_key = await session.get(SSHKey, repo.ssh_key_id)
                 if ssh_key:
                     try:
-                        ssh_dir = prepare_ssh_key_files(instance_dir, ssh_key)
+                        ssh_dir = prepare_ssh_key_files(
+                            instance_dir, ssh_key, uid=0, gid=0
+                        )
                         extra_volumes.append(
                             {
                                 "source": ssh_dir,
                                 "target": "/root/.ssh",
-                                "type": "ro",
+                                "type": "bind",
                             }
                         )
                         logger.debug(
@@ -1451,6 +1680,15 @@ async def start_instance(
     # Sanitize compose file to remove invalid port mappings from old instances
     _sanitize_compose_file(instance.compose_path)
 
+    # Auto-fix bind address for known web tools that default to localhost
+    if tool_type and tool_type.interface_type == "web":
+        _ensure_web_bind_address(
+            instance.compose_path, tool_type.name, tool_type.default_port
+        )
+
+    # Ensure predictable container name for tunnel connectivity
+    _ensure_container_name_in_compose(instance.compose_path, instance.name)
+
     # Execute docker compose up with env file
     logger.debug(
         "Running docker compose up for instance %s (compose_path=%s)",
@@ -1477,30 +1715,38 @@ async def start_instance(
             detail=f"failed to start instance: {stderr}",
         )
 
-    # Get container ID and name
-    container_id = get_container_id(instance.name)
+    # Get container ID and name (use predictable name from compose)
+    expected_container_name = instance.name.lower()
+    container_id = get_container_id(expected_container_name)
     if container_id:
         instance.container_id = container_id
         logger.debug("Container ID for instance %s: %s", instance.id, container_id)
 
-    container_name = get_container_name(instance.name)
-    if container_name:
-        instance.container_name = container_name
-        logger.debug("Container name for instance %s: %s", instance.id, container_name)
+    instance.container_name = expected_container_name
+    logger.debug("Container name for instance %s: %s", instance.id, expected_container_name)
 
-        # Connect container to backend network so API can reach it
-        logger.debug("Connecting container %s to backend network...", container_name)
-        connected = connect_container_to_network(container_name, "backend")
-        if connected:
-            logger.debug("Successfully connected %s to backend network", container_name)
-        else:
-            logger.warning("Failed to connect %s to backend network", container_name)
+    # Connect container to backend network so API can reach it
+    logger.debug("Connecting container %s to backend network...", expected_container_name)
+    connected = connect_container_to_network(expected_container_name, "backend")
+    if connected:
+        logger.debug("Successfully connected %s to backend network", expected_container_name)
+    else:
+        logger.warning("Failed to connect %s to backend network", expected_container_name)
 
     # Verify container reached running state
     if instance.container_id:
         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(
@@ -1518,6 +1764,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,
@@ -1559,6 +1818,34 @@ async def start_instance(
                             result["error"],
                         )
 
+        # Fix SSH key ownership/permissions inside the container
+        if instance.ssh_key_ids and instance.container_id:
+            container_user = (
+                "root"
+                if home_dir == "/root"
+                else home_dir[6:]
+                if home_dir.startswith("/home/")
+                else "root"
+            )
+            ssh_target = os.path.join(home_dir, ".ssh")
+            logger.debug(
+                "Applying SSH permissions for user %s on %s in instance %s",
+                container_user,
+                ssh_target,
+                instance.id,
+            )
+            ssh_perm_result = apply_ssh_permissions(
+                instance.container_id,
+                ssh_target,
+                container_user,
+            )
+            if not ssh_perm_result["success"]:
+                logger.warning(
+                    "SSH permission fix failed for instance %s: %s",
+                    instance.id,
+                    ssh_perm_result["error"],
+                )
+
     # Execute readiness probe if configured
     tool_type = await session.get(ToolType, instance.tool_type_id)
     if tool_type and instance.container_id:
@@ -1607,6 +1894,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,
@@ -1623,6 +1920,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
@@ -1631,6 +1938,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",
@@ -1756,6 +2072,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}
 
@@ -1833,6 +2158,15 @@ async def restart_instance(
                     exc,
                 )
 
+        # Re-apply compose fixes in case they were updated since last start
+        _sanitize_compose_file(instance.compose_path)
+        tool_type = await session.get(ToolType, instance.tool_type_id)
+        if tool_type and tool_type.interface_type == "web":
+            _ensure_web_bind_address(
+                instance.compose_path, tool_type.name, tool_type.default_port
+            )
+        _ensure_container_name_in_compose(instance.compose_path, instance.name)
+
         returncode, stdout, stderr = execute_compose_command(
             instance.compose_path, "restart"
         )
@@ -1862,7 +2196,7 @@ async def restart_instance(
                 # Create new temporary tunnel
                 try:
                     tunnel_info = start_cloudflared_tunnel(
-                        container_name=instance.container_name or instance.name,
+                        container_name=instance.name.lower(),
                         port=instance_port,
                     )
                     instance.tunnel_id = tunnel_info["pid"]
@@ -1892,6 +2226,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"
@@ -1978,6 +2321,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()
 
@@ -2194,6 +2546,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/api/user_config.py

@@ -14,7 +14,9 @@ logger = logging.getLogger(__name__)
 router = APIRouter(prefix="/users/me", tags=["user-config"])
 
 
-async def _get_or_create_config(session: AsyncSession, user_id: uuid.UUID) -> UserConfig:
+async def _get_or_create_config(
+    session: AsyncSession, user_id: uuid.UUID
+) -> UserConfig:
     """Get or create user config record.
 
     Args:
@@ -24,7 +26,9 @@ async def _get_or_create_config(session: AsyncSession, user_id: uuid.UUID) -> Us
     Returns:
         The user's config, creating a new one if it doesn't exist.
     """
-    result = await session.execute(select(UserConfig).where(UserConfig.user_id == user_id))
+    result = await session.execute(
+        select(UserConfig).where(UserConfig.user_id == user_id)
+    )
     config = result.scalar_one_or_none()
     if config is None:
         config = UserConfig(user_id=user_id, config={})
@@ -42,6 +46,8 @@ class UserConfigResponse(BaseModel):
     git_user_name: str | None = None
     git_user_email: str | None = None
     last_session_id: str | None = None
+    notification_mute_categories: list[str] | None = None
+    notification_toast_level: str | None = None
 
 
 class UserConfigUpdate(BaseModel):
@@ -50,6 +56,8 @@ class UserConfigUpdate(BaseModel):
     git_user_name: str | None = None
     git_user_email: str | None = None
     last_session_id: str | None = None
+    notification_mute_categories: list[str] | None = None
+    notification_toast_level: str | None = None
 
 
 @router.get(

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
@@ -20,9 +21,11 @@ from src.api.tool_definitions import router as tool_definitions_router
 from src.api.tool_instances import router as tool_instances_router
 from src.api.tool_instances import sessions_router
 from src.api.tool_types import router as tool_types_router
+from src.api.notifications import router as notifications_router
 from src.api.user_config import router as user_config_router
 from src.api.users import router as users_router
 from src.config import Settings
+from src.models.notification import Notification  # noqa: F401 – Alembic model discovery
 from src.models.terminal_session import TerminalSessionModel  # noqa: F401 – Alembic model discovery
 from src.database import init_database
 from src.logging_config import (
@@ -30,6 +33,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 +60,7 @@ app.add_middleware(
     allow_headers=["*"],
 )
 
+app.add_middleware(CorrelationIdMiddleware)
 app.add_middleware(RequestLoggingMiddleware)
 app.add_middleware(ExceptionLoggingMiddleware)
 
@@ -103,6 +110,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 +127,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 +157,6 @@ 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.include_router(notifications_router)
 app.mount("/uploads", StaticFiles(directory="uploads"), name="uploads")

apps/api/src/models/__init__.py

@@ -1,6 +1,9 @@
 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.notification import Notification
 from src.models.project import Project
 from src.models.ssh_key import SSHKey
 from src.models.terminal_session import TerminalSessionModel
@@ -15,6 +18,9 @@ __all__ = [
     "ConfigProfile",
     "ConfigProfileInclude",
     "GitRepository",
+    "HealthCheck",
+    "InstanceEvent",
+    "Notification",
     "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/models/notification.py

@@ -0,0 +1,43 @@
+"""Notification SQLAlchemy model."""
+
+from datetime import datetime
+from typing import Any
+import uuid
+
+from sqlalchemy import DateTime, ForeignKey, JSON, String, Text
+from sqlalchemy import Uuid as UUID
+from sqlalchemy.orm import Mapped, mapped_column
+from sqlalchemy.sql import func
+
+from src.models.base import Base, UUIDPrimaryKeyMixin
+
+
+class Notification(UUIDPrimaryKeyMixin, Base):
+    __tablename__ = "notifications"
+
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    category: Mapped[str] = mapped_column(String(32), nullable=False)
+    severity: Mapped[str] = mapped_column(String(16), nullable=False)
+    title: Mapped[str] = mapped_column(String(255), nullable=False)
+    message: Mapped[str | None] = mapped_column(Text, nullable=True)
+    source_type: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    source_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True), nullable=True
+    )
+    notification_metadata: Mapped[dict[str, Any]] = mapped_column(
+        "metadata", JSON, nullable=False, default=dict
+    )
+    read_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True, index=True
+    )
+    dismissed_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False, index=True
+    )

apps/api/src/models/tool_instance.py

@@ -59,6 +59,7 @@ class ToolInstance(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     selected_config_profile_id: Mapped[uuid.UUID | None] = mapped_column(
         UUID(), ForeignKey("config_profiles.id", ondelete="SET NULL"), nullable=True
     )
+    ssh_key_ids: Mapped[list[str] | None] = mapped_column(JSON, nullable=True)
 
     tool_type: Mapped["ToolType"] = relationship()
     repository: Mapped["GitRepository"] = relationship()

apps/api/src/services/config_profile_resolver.py

@@ -494,13 +494,16 @@ def apply_resolved_profile(
             full_path.parent.mkdir(parents=True, exist_ok=True)
             full_path.write_text(content)
 
-        volume_mounts.append(
-            {
-                "source": str(mount_dir),
-                "target": expanded_target,
-                "type": "bind",
-            }
-        )
+            # Mount each file individually so sibling files from other mounts
+            # (e.g. git repo directories) are preserved.
+            file_target = os.path.join(expanded_target, file_path)
+            volume_mounts.append(
+                {
+                    "source": str(full_path),
+                    "target": file_target,
+                    "type": "bind",
+                }
+            )
 
     return env_vars, files, volume_mounts, resolved.runtime_hints
 

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/docker.py

@@ -1,12 +1,54 @@
 """Docker service for managing tool instances."""
 
+import logging
 import os
 import re
 import subprocess
 import time
+from collections import Counter
 from pathlib import Path
 from typing import Any
 
+logger = logging.getLogger(__name__)
+
+
+def sort_volumes_by_specificity(volumes: list[str]) -> list[str]:
+    """Sort volume strings so parent paths come before child paths.
+
+    Docker Compose mounts volumes in array order. A later mount at a parent
+    path hides earlier mounts at child paths. By sorting shallow paths first
+    and deep paths last, deeper (more specific) mounts overlay correctly.
+
+    Volume format: source:target or source:target:type
+
+    Args:
+        volumes: List of Docker volume mount strings.
+
+    Returns:
+        Sorted list with parent paths before child paths.
+    """
+
+    def _target_depth(vol: str) -> int:
+        parts = vol.split(":")
+        if len(parts) < 2:
+            return 0
+        target = parts[1].rstrip("/")
+        if not target or target == "/":
+            return 0
+        return target.count("/")
+
+    # Detect duplicate targets and warn
+    targets = []
+    for vol in volumes:
+        parts = vol.split(":")
+        targets.append(parts[1] if len(parts) > 1 else "")
+    dupes = [t for t, c in Counter(targets).items() if c > 1]
+    if dupes:
+        logger.warning("Duplicate mount targets detected: %s", dupes)
+
+    # Stable sort: parent paths first, child paths last
+    return sorted(volumes, key=_target_depth)
+
 
 def render_compose_template(template: str, variables: dict[str, Any]) -> str:
     """Render a Docker Compose template with variable substitution.
@@ -117,7 +159,7 @@ def execute_compose_command(
         cmd.extend(["--env-file", env_file])
 
     if action == "up":
-        cmd.extend(["up", "-d"])
+        cmd.extend(["up", "-d", "--force-recreate"])
     elif action == "down":
         cmd.extend(["down", "-v"])
     elif action in ("start", "stop", "restart"):
@@ -342,6 +384,85 @@ def find_free_port(start: int = 10000, end: int = 20000) -> int:
     raise RuntimeError(f"No free port found in range {start}-{end}")
 
 
+def _check_app_binding(container_name: str, port: int) -> dict[str, str | bool]:
+    """Diagnose whether the app is bound to 127.0.0.1 or 0.0.0.0.
+
+    Checks from both inside the container (localhost) and outside
+    (via Docker network) to detect binding issues.
+
+    Returns:
+        Dict with 'internal_ok', 'external_ok', 'internal_status',
+        'external_status', and 'diagnosis'.
+    """
+    import subprocess
+
+    result: dict[str, Any] = {
+        "internal_ok": False,
+        "external_ok": False,
+        "internal_status": None,
+        "external_status": None,
+        "diagnosis": "unknown",
+    }
+
+    # Check from inside the container (loopback)
+    internal = subprocess.run(
+        [
+            "docker",
+            "exec",
+            container_name,
+            "sh",
+            "-c",
+            f"curl -s -o /dev/null -w '%{{http_code}}' http://localhost:{port}",
+        ],
+        capture_output=True,
+        text=True,
+        timeout=5,
+    )
+    if internal.returncode == 0:
+        try:
+            result["internal_status"] = int(internal.stdout.strip())
+            result["internal_ok"] = result["internal_status"] > 0
+        except ValueError:
+            pass
+
+    # Check from outside the container (Docker network)
+    external = subprocess.run(
+        [
+            "curl",
+            "-s",
+            "-o",
+            "/dev/null",
+            "-w",
+            "%{http_code}",
+            f"http://{container_name}:{port}",
+        ],
+        capture_output=True,
+        text=True,
+        timeout=5,
+    )
+    if external.returncode == 0:
+        try:
+            result["external_status"] = int(external.stdout.strip())
+            result["external_ok"] = result["external_status"] > 0
+        except ValueError:
+            pass
+
+    # Diagnose binding issue
+    if result["internal_ok"] and not result["external_ok"]:
+        result["diagnosis"] = (
+            f"App appears to be bound to 127.0.0.1:{port} inside the container. "
+            f"It must bind to 0.0.0.0:{port} to be accessible from the tunnel."
+        )
+    elif result["internal_ok"] and result["external_ok"]:
+        result["diagnosis"] = "App is accessible on both interfaces."
+    elif not result["internal_ok"] and not result["external_ok"]:
+        result["diagnosis"] = f"App is not responding on port {port} at all."
+    else:
+        result["diagnosis"] = "Unexpected binding state."
+
+    return result
+
+
 def start_cloudflared_tunnel(
     container_name: str, port: int, timeout: int = 30
 ) -> dict[str, str]:
@@ -363,9 +484,11 @@ def start_cloudflared_tunnel(
 
     logger = logging.getLogger(__name__)
 
-    # First verify the container is accessible
+    # First verify the container is accessible from the Docker network
     logger.info("Checking connectivity to %s:%d...", container_name, port)
-    for attempt in range(10):
+    accessible = False
+    last_status = None
+    for attempt in range(30):  # 30 attempts × 1s = 30s max wait for app startup
         check = subprocess.run(
             [
                 "curl",
@@ -374,21 +497,59 @@ def start_cloudflared_tunnel(
                 "/dev/null",
                 "-w",
                 "%{http_code}",
+                "--max-time",
+                "3",
                 f"http://{container_name}:{port}",
             ],
             capture_output=True,
             text=True,
             timeout=5,
         )
+        status_str = check.stdout.strip()
         logger.info(
-            "Connectivity check %d: http_code=%s", attempt + 1, check.stdout.strip()
+            "Connectivity check %d/%d: http_code=%s (rc=%d)",
+            attempt + 1,
+            30,
+            status_str,
+            check.returncode,
         )
-        if check.returncode == 0:
-            break
+        try:
+            last_status = int(status_str)
+            # Accept 2xx, 3xx, 401, 403 as "app is listening"
+            if last_status in (401, 403) or 200 <= last_status < 400:
+                accessible = True
+                logger.info(
+                    "App on %s:%d is ready (HTTP %d)",
+                    container_name,
+                    port,
+                    last_status,
+                )
+                break
+        except ValueError:
+            pass
+
+        if check.returncode != 0:
+            logger.debug(
+                "curl failed: stderr=%s", check.stderr.strip() if check.stderr else ""
+            )
         time.sleep(1)
-    else:
+
+    if not accessible:
         logger.warning(
-            "Container %s:%d not responding to curl checks", container_name, port
+            "Container %s:%d not responding after 30s (last status: %s). "
+            "Running binding diagnostics...",
+            container_name,
+            port,
+            last_status,
+        )
+        diagnosis = _check_app_binding(container_name, port)
+        logger.warning(
+            "Binding diagnosis: internal=%s (HTTP %s), external=%s (HTTP %s). %s",
+            diagnosis["internal_ok"],
+            diagnosis["internal_status"],
+            diagnosis["external_ok"],
+            diagnosis["external_status"],
+            diagnosis["diagnosis"],
         )
 
     # Run cloudflared in background, capture output

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,253 @@
+"""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
+from src.services.notification_service import notification_service
+
+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)
+
+        # Create notification for instance owner (fire-and-forget)
+        # Only send warnings and errors; skip "recovered" info notifications.
+        if new_status == "error":
+            category = "instance"
+            severity = "error"
+            title = "Container failed"
+        elif new_status == "unhealthy":
+            category = "health"
+            severity = "warning"
+            title = "Container unhealthy"
+        else:
+            # Running/recovered — do not notify
+            return
+
+        try:
+            await notification_service.create_notification(
+                session=session,
+                user_id=instance.owner_id,
+                category=category,
+                severity=severity,
+                title=title,
+                message=message,
+                source_type="tool_instances",
+                source_id=instance.id,
+                metadata=metadata,
+            )
+        except Exception:
+            logger.exception(
+                "Failed to create notification for health event %s",
+                event_type,
+                extra={"correlation_id": correlation_id},
+            )

apps/api/src/services/lifecycle_hooks.py

@@ -0,0 +1,162 @@
+"""Lifecycle hook helpers for instrumenting tool instance transitions."""
+
+import logging
+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
+from src.services.notification_service import notification_service
+
+logger = logging.getLogger(__name__)
+
+
+def _derive_title(event_type: str) -> str:
+    """Map lifecycle event type to a human-readable notification title."""
+    mapping = {
+        "instance.created": "Container created",
+        "instance.started": "Container started",
+        "instance.stopped": "Container stopped",
+        "instance.restarted": "Container restarted",
+        "instance.deleted": "Container deleted",
+        "instance.error": "Container error",
+        "instance.health_changed": "Container ready",
+    }
+    return mapping.get(
+        event_type,
+        event_type.replace("instance.", "").replace("_", " ").title(),
+    )
+
+
+def _should_notify(event_type: str, status: str | None) -> bool:
+    """Determine whether a lifecycle event should generate a notification.
+
+    Only warnings, errors, and "container is ready" (health_changed running)
+    are sent to users.
+    """
+    if event_type == "instance.error":
+        return True
+    if event_type == "instance.health_changed" and status == "running":
+        return True
+    # Filter out: created, started, stopped, restarted, deleted, and any
+    # health_changed that is not "running" (unhealthy is handled by health_monitor)
+    return False
+
+
+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)
+
+    # Create notification for instance owner (fire-and-forget)
+    # Only send warnings, errors, and "container is ready" notifications.
+    effective_status = status or instance.status
+    if not _should_notify(event_type, effective_status):
+        return
+
+    severity = "error" if event_type == "instance.error" else "success"
+    title = _derive_title(event_type)
+
+    try:
+        await notification_service.create_notification(
+            session=session,
+            user_id=instance.owner_id,
+            category="instance",
+            severity=severity,
+            title=title,
+            message=message,
+            source_type="tool_instances",
+            source_id=instance.id,
+            metadata=metadata,
+        )
+    except Exception:
+        logger.exception(
+            "Failed to create notification for lifecycle event %s",
+            event_type,
+            extra={"correlation_id": payload.get("correlation_id", "unknown")},
+        )

apps/api/src/services/manifest_compiler.py

@@ -8,6 +8,8 @@ from typing import Any
 
 import yaml
 
+from src.services.docker import sort_volumes_by_specificity
+
 
 def resolve_base(manifest: dict) -> dict:
     """Merge a base definition into a tool manifest.
@@ -303,7 +305,7 @@ def compile_compose(manifest: dict, variables: dict[str, Any]) -> str:
         volumes.append(vol_str)
 
     if volumes:
-        service["volumes"] = volumes
+        service["volumes"] = sort_volumes_by_specificity(volumes)
 
     compose = {"services": {"app": service}}
     return yaml.dump(compose, default_flow_style=False)

apps/api/src/services/notification_service.py

@@ -0,0 +1,272 @@
+"""Notification persistence service."""
+
+import uuid
+from datetime import datetime, timezone
+from typing import Any
+
+from sqlalchemy import func, select, update
+from sqlalchemy.engine import CursorResult
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.models.notification import Notification
+
+
+class NotificationService:
+    """Singleton notification persistence service.
+
+    All methods filter by user_id to enforce strict ownership isolation.
+    """
+
+    async def create_notification(
+        self,
+        session: AsyncSession,
+        user_id: uuid.UUID,
+        *,
+        category: str,
+        severity: str,
+        title: str,
+        message: str | None = None,
+        source_type: str | None = None,
+        source_id: uuid.UUID | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> Notification:
+        """Insert a new notification row.
+
+        Args:
+            session: Database session.
+            user_id: Owner of the notification.
+            category: Notification category (e.g., instance, system, health).
+            severity: Severity level (e.g., info, warning, error, success).
+            title: Short notification title.
+            message: Optional longer message body.
+            source_type: Optional source entity type.
+            source_id: Optional source entity UUID.
+            metadata: Optional JSON metadata dictionary.
+
+        Returns:
+            The newly created Notification instance.
+        """
+        notification = Notification(
+            user_id=user_id,
+            category=category,
+            severity=severity,
+            title=title,
+            message=message,
+            source_type=source_type,
+            source_id=source_id,
+            notification_metadata=metadata or {},
+        )
+        session.add(notification)
+        await session.commit()
+        await session.refresh(notification)
+        return notification
+
+    async def list_notifications(
+        self,
+        session: AsyncSession,
+        user_id: uuid.UUID,
+        *,
+        limit: int = 20,
+        offset: int = 0,
+        unread_only: bool = False,
+        mute_categories: list[str] | None = None,
+    ) -> tuple[list[Notification], int]:
+        """Return paginated notifications for a user.
+
+        Excludes dismissed notifications and applies optional filtering.
+
+        Args:
+            session: Database session.
+            user_id: Owner of the notifications.
+            limit: Maximum number of items to return.
+            offset: Number of items to skip.
+            unread_only: If True, only return unread notifications.
+            mute_categories: Categories to exclude from results.
+
+        Returns:
+            A tuple of (items, total_count).
+        """
+        where_clauses = [
+            Notification.user_id == user_id,
+            Notification.dismissed_at.is_(None),
+        ]
+
+        if unread_only:
+            where_clauses.append(Notification.read_at.is_(None))
+
+        if mute_categories:
+            where_clauses.append(Notification.category.not_in(mute_categories))
+
+        total_stmt = (
+            select(func.count()).select_from(Notification).where(*where_clauses)
+        )
+        total_result = await session.execute(total_stmt)
+        total = total_result.scalar_one()
+
+        items_stmt = (
+            select(Notification)
+            .where(*where_clauses)
+            .order_by(Notification.created_at.desc())
+            .limit(limit)
+            .offset(offset)
+        )
+        items_result = await session.execute(items_stmt)
+        items = list(items_result.scalars().all())
+
+        return items, total
+
+    async def get_unread_count(
+        self,
+        session: AsyncSession,
+        user_id: uuid.UUID,
+    ) -> int:
+        """Count unread, non-dismissed notifications for a user.
+
+        Args:
+            session: Database session.
+            user_id: Owner of the notifications.
+
+        Returns:
+            Number of unread notifications.
+        """
+        stmt = (
+            select(func.count())
+            .select_from(Notification)
+            .where(
+                Notification.user_id == user_id,
+                Notification.read_at.is_(None),
+                Notification.dismissed_at.is_(None),
+            )
+        )
+        result = await session.execute(stmt)
+        return result.scalar_one()
+
+    async def mark_read(
+        self,
+        session: AsyncSession,
+        notification_id: uuid.UUID,
+        user_id: uuid.UUID,
+    ) -> Notification:
+        """Mark a single notification as read.
+
+        Args:
+            session: Database session.
+            notification_id: UUID of the notification to mark.
+            user_id: Owner of the notification.
+
+        Returns:
+            The updated Notification instance.
+
+        Raises:
+            ValueError: If the notification does not exist or is not owned by the user.
+        """
+        notification = await self._get_owned_notification(
+            session, notification_id, user_id
+        )
+        notification.read_at = datetime.now(timezone.utc)
+        await session.commit()
+        await session.refresh(notification)
+        return notification
+
+    async def mark_all_read(
+        self,
+        session: AsyncSession,
+        user_id: uuid.UUID,
+    ) -> int:
+        """Mark all unread notifications as read for a user.
+
+        Args:
+            session: Database session.
+            user_id: Owner of the notifications.
+
+        Returns:
+            Number of rows updated.
+        """
+        stmt = (
+            update(Notification)
+            .where(
+                Notification.user_id == user_id,
+                Notification.read_at.is_(None),
+                Notification.dismissed_at.is_(None),
+            )
+            .values(read_at=datetime.now(timezone.utc))
+        )
+        result: CursorResult[Any] = await session.execute(stmt)  # type: ignore[assignment]
+        await session.commit()
+        return result.rowcount or 0
+
+    async def dismiss_all(
+        self,
+        session: AsyncSession,
+        user_id: uuid.UUID,
+    ) -> int:
+        """Soft-delete all non-dismissed notifications for a user.
+
+        Args:
+            session: Database session.
+            user_id: Owner of the notifications.
+
+        Returns:
+            Number of rows updated.
+        """
+        stmt = (
+            update(Notification)
+            .where(
+                Notification.user_id == user_id,
+                Notification.dismissed_at.is_(None),
+            )
+            .values(dismissed_at=datetime.now(timezone.utc))
+        )
+        result: CursorResult[Any] = await session.execute(stmt)  # type: ignore[assignment]
+        await session.commit()
+        return result.rowcount or 0
+
+    async def dismiss(
+        self,
+        session: AsyncSession,
+        notification_id: uuid.UUID,
+        user_id: uuid.UUID,
+    ) -> None:
+        """Soft-delete a notification by setting dismissed_at.
+
+        Args:
+            session: Database session.
+            notification_id: UUID of the notification to dismiss.
+            user_id: Owner of the notification.
+
+        Raises:
+            ValueError: If the notification does not exist or is not owned by the user.
+        """
+        notification = await self._get_owned_notification(
+            session, notification_id, user_id
+        )
+        notification.dismissed_at = datetime.now(timezone.utc)
+        await session.commit()
+
+    async def _get_owned_notification(
+        self,
+        session: AsyncSession,
+        notification_id: uuid.UUID,
+        user_id: uuid.UUID,
+    ) -> Notification:
+        """Fetch a notification and verify ownership.
+
+        Args:
+            session: Database session.
+            notification_id: UUID of the notification.
+            user_id: Expected owner.
+
+        Returns:
+            The Notification instance.
+
+        Raises:
+            ValueError: If the notification does not exist or is not owned.
+        """
+        notification = await session.get(Notification, notification_id)
+        if notification is None or notification.user_id != user_id:
+            raise ValueError("Notification not found")
+        return notification
+
+
+# Module-level singleton instance
+notification_service = NotificationService()

apps/api/src/services/permission_fixer.py

@@ -40,6 +40,17 @@ def apply_mount_permissions(
             "error": None,
         }
 
+        # Skip read-only mounts — their permissions cannot be changed
+        # post-start because the bind mount is locked.
+        if mount.get("readonly", False):
+            logger.debug(
+                "Skipping permission fix for read-only mount %s (target=%s)",
+                name,
+                target,
+            )
+            results.append(result)
+            continue
+
         # Skip if no permission policy defined
         if not owner and not mode and not file_mode:
             results.append(result)
@@ -104,6 +115,141 @@ def apply_mount_permissions(
     return results
 
 
+def _exec_and_log(
+    container_id: str,
+    command: list[str],
+    timeout: int,
+    description: str,
+) -> str:
+    """Run a docker exec command and log stdout/stderr for debugging."""
+    cmd = ["docker", "exec", "--user", "root", container_id] + command
+    logger.debug("[SSH-fix] %s: %s", description, " ".join(cmd))
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except subprocess.TimeoutExpired:
+        raise PermissionFixError(
+            f"Command timed out after {timeout}s: {' '.join(command)}"
+        )
+    except FileNotFoundError:
+        raise PermissionFixError(f"Docker command not found: {' '.join(command)}")
+
+    stdout = result.stdout.strip()
+    stderr = result.stderr.strip()
+    if stdout:
+        logger.debug("[SSH-fix] %s stdout: %s", description, stdout)
+    if stderr:
+        logger.debug("[SSH-fix] %s stderr: %s", description, stderr)
+
+    if result.returncode != 0:
+        raise PermissionFixError(
+            f"Command failed (rc={result.returncode}): {stderr or '(no stderr)'}"
+        )
+    return stdout
+
+
+def apply_ssh_permissions(
+    container_id: str,
+    ssh_target: str,
+    container_user: str,
+    timeout: int = 10,
+) -> dict[str, Any]:
+    """Fix SSH directory ownership and permissions in a running container.
+
+    Runs chown and chmod on the ~/.ssh directory so the container user
+    can use the keys (SSH requires the private key to be owned by the
+    user with mode 600).
+
+    Args:
+        container_id: Docker container ID or name.
+        ssh_target: Absolute path to the .ssh directory inside the container.
+        container_user: The container user that should own the keys.
+        timeout: Max seconds per docker exec command.
+
+    Returns:
+        Result dict with keys: success, error.
+    """
+    result: dict[str, Any] = {"success": True, "error": None}
+    try:
+        # 1. Ensure directory is owned by the container user
+        _exec_and_log(
+            container_id,
+            ["chown", "-R", f"{container_user}:{container_user}", ssh_target],
+            timeout,
+            "chown",
+        )
+
+        # 2. Set directory permissions
+        _exec_and_log(
+            container_id,
+            ["chmod", "700", ssh_target],
+            timeout,
+            "chmod-dir",
+        )
+
+        # 3. Set private key permissions (id_ed25519, id_rsa, etc.)
+        _exec_and_log(
+            container_id,
+            [
+                "sh",
+                "-c",
+                f"find {ssh_target} -name 'id_*' -type f -exec chmod 600 {{}} +",
+            ],
+            timeout,
+            "chmod-keys",
+        )
+
+        # 4. Verify final state
+        ls_output = _exec_and_log(
+            container_id,
+            ["ls", "-la", ssh_target],
+            timeout,
+            "verify-ls",
+        )
+        stat_output = _exec_and_log(
+            container_id,
+            ["stat", "-c", "%U:%G %a %n", ssh_target],
+            timeout,
+            "verify-stat-dir",
+        )
+        key_stat = _exec_and_log(
+            container_id,
+            [
+                "sh",
+                "-c",
+                f"stat -c '%U:%G %a %n' {ssh_target}/id_* 2>/dev/null || echo 'no id_* files found'",
+            ],
+            timeout,
+            "verify-stat-keys",
+        )
+
+        logger.info(
+            "SSH permissions fixed for container %s (user=%s, target=%s). "
+            "ls:\n%s\nstat-dir: %s\nstat-keys: %s",
+            container_id,
+            container_user,
+            ssh_target,
+            ls_output,
+            stat_output,
+            key_stat,
+        )
+    except PermissionFixError as exc:
+        result["success"] = False
+        result["error"] = str(exc)
+        logger.warning(
+            "SSH permission fix failed for container %s (target=%s): %s",
+            container_id,
+            ssh_target,
+            exc,
+        )
+    return result
+
+
 class PermissionFixError(Exception):
     """Raised when a permission fix command fails."""
 

apps/api/src/services/ssh_keys.py

@@ -1,5 +1,6 @@
 """SSH key service utilities for preparing keys for container use."""
 
+import logging
 import os
 from pathlib import Path
 
@@ -7,6 +8,8 @@ from cryptography.fernet import Fernet
 
 from src.config import Settings
 
+logger = logging.getLogger(__name__)
+
 
 def _get_fernet() -> Fernet:
     """Generate a valid Fernet key from the session secret."""
@@ -19,17 +22,26 @@ def _get_fernet() -> Fernet:
     return Fernet(key)
 
 
-def prepare_ssh_key_files(instance_dir: str, ssh_key) -> str:
+def prepare_ssh_key_files(
+    instance_dir: str,
+    ssh_key,
+    subdir: str = ".ssh",
+    uid: int | None = None,
+    gid: int | None = None,
+) -> str:
     """Decrypt and write SSH key files to instance directory for container mounting.
 
     Args:
         instance_dir: Path to instance directory
         ssh_key: SSHKey model instance with encrypted private key
+        subdir: Subdirectory within instance_dir to write to (default: ".ssh")
+        uid: Optional UID to own the files (for bind-mount into non-root container)
+        gid: Optional GID to own the files
 
     Returns:
         Path to the .ssh directory
     """
-    ssh_dir = Path(instance_dir) / ".ssh"
+    ssh_dir = Path(instance_dir) / subdir
     ssh_dir.mkdir(parents=True, exist_ok=True)
 
     # Decrypt private key
@@ -57,6 +69,30 @@ def prepare_ssh_key_files(instance_dir: str, ssh_key) -> str:
     config_path.write_text(config_content)
     os.chmod(config_path, 0o644)
 
+    # Set ownership to target container user if requested
+    if uid is not None or gid is not None:
+        effective_uid = uid if uid is not None else -1
+        effective_gid = gid if gid is not None else -1
+        try:
+            os.chown(ssh_dir, effective_uid, effective_gid)
+            os.chown(private_key_path, effective_uid, effective_gid)
+            os.chown(public_key_path, effective_uid, effective_gid)
+            os.chown(config_path, effective_uid, effective_gid)
+            logger.debug(
+                "Set SSH key ownership to uid=%s gid=%s for %s",
+                effective_uid,
+                effective_gid,
+                ssh_dir,
+            )
+        except PermissionError as exc:
+            logger.warning(
+                "Cannot chown SSH keys to uid=%s gid=%s (running as uid=%s): %s",
+                effective_uid,
+                effective_gid,
+                os.getuid(),
+                exc,
+            )
+
     return str(ssh_dir)
 
 

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/integration/test_models.py

@@ -16,7 +16,6 @@ def test_base_metadata_collects_declared_tables() -> None:
 
 
 @pytest.mark.integration
-
 def test_shared_mixins_define_expected_columns() -> None:
     assert "id" in UUIDPrimaryKeyMixin.__dict__
     assert "created_at" in TimestampMixin.__dict__
@@ -24,20 +23,26 @@ def test_shared_mixins_define_expected_columns() -> None:
 
 
 @pytest.mark.integration
-
 def test_expected_tables_are_registered() -> None:
     assert set(Base.metadata.tables) == {
-        "refresh_tokens",
+        "config_profile_includes",
+        "config_profiles",
         "git_repositories",
+        "health_checks",
+        "instance_events",
+        "notifications",
         "projects",
         "ssh_keys",
+        "terminal_sessions",
+        "tool_definition_manifests",
+        "tool_instances",
+        "tool_types",
         "user_configs",
         "users",
     }
 
 
 @pytest.mark.integration
-
 def test_user_table_has_required_columns() -> None:
     columns = User.__table__.columns
 
@@ -56,7 +61,6 @@ def test_user_table_has_required_columns() -> None:
 
 
 @pytest.mark.integration
-
 def test_project_relationships_point_to_owner_and_default_ssh_key() -> None:
     owner_fk = next(iter(Project.__table__.c.owner_id.foreign_keys))
     ssh_fk = next(iter(Project.__table__.c.default_ssh_key_id.foreign_keys))
@@ -68,7 +72,6 @@ def test_project_relationships_point_to_owner_and_default_ssh_key() -> None:
 
 
 @pytest.mark.integration
-
 def test_repository_and_user_config_relationships_are_registered() -> None:
     project_fk = next(iter(GitRepository.__table__.c.project_id.foreign_keys))
     owner_fk = next(iter(GitRepository.__table__.c.owner_id.foreign_keys))
@@ -84,9 +87,13 @@ def test_repository_and_user_config_relationships_are_registered() -> None:
 
 @pytest.mark.asyncio
 @pytest.mark.integration
-
 async def test_async_session_can_insert_and_load_user(db_session: AsyncSession) -> None:
-    user = User(email="dev@headquarter.local", name="Dev User", authentik_id="dev-user", avatar_url=None)
+    user = User(
+        email="dev@headquarter.local",
+        name="Dev User",
+        authentik_id="dev-user",
+        avatar_url=None,
+    )
 
     db_session.add(user)
     await db_session.commit()

apps/api/tests/integration/test_notifications_api.py

@@ -0,0 +1,326 @@
+"""Integration tests for notifications API."""
+
+import uuid
+from datetime import datetime, timedelta, timezone
+
+import pytest
+from fastapi.testclient import TestClient
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.models.user import User
+from src.models.user_config import UserConfig
+from src.services.notification_service import NotificationService
+
+
+@pytest.fixture
+def notification_service() -> NotificationService:
+    return NotificationService()
+
+
+@pytest.fixture
+async def user_a(db_session: AsyncSession) -> User:
+    user = User(
+        id=uuid.uuid4(),
+        email="user-a@headquarter.local",
+        name="User A",
+        authentik_id=f"authentik-{uuid.uuid4()}",
+        avatar_url=None,
+    )
+    db_session.add(user)
+    await db_session.commit()
+    return user
+
+
+@pytest.fixture
+async def user_b(db_session: AsyncSession) -> User:
+    user = User(
+        id=uuid.uuid4(),
+        email="user-b@headquarter.local",
+        name="User B",
+        authentik_id=f"authentik-{uuid.uuid4()}",
+        avatar_url=None,
+    )
+    db_session.add(user)
+    await db_session.commit()
+    return user
+
+
+def _mint_cookie_for_user(test_client: TestClient, user_id: uuid.UUID) -> None:
+    from src.auth.session import create_session_cookie
+    from src.config import Settings
+
+    settings = Settings()
+    cookie = create_session_cookie(
+        settings=settings,
+        user_id=str(user_id),
+    )
+    test_client.cookies.set("session", cookie)
+
+
+@pytest.mark.integration
+def test_list_requires_auth(test_client: TestClient) -> None:
+    response = test_client.get("/notifications")
+    assert response.status_code == 401
+
+
+@pytest.mark.integration
+def test_list_returns_only_own_notifications(
+    authenticated_client: TestClient,
+    db_session: AsyncSession,
+    notification_service: NotificationService,
+    user_a: User,
+    user_b: User,
+) -> None:
+    async def create_notifications() -> None:
+        await notification_service.create_notification(
+            db_session, user_a.id, category="instance", severity="info", title="A"
+        )
+        await notification_service.create_notification(
+            db_session, user_b.id, category="instance", severity="info", title="B"
+        )
+
+    import asyncio
+
+    asyncio.run(create_notifications())
+
+    _mint_cookie_for_user(authenticated_client, user_a.id)
+    response = authenticated_client.get("/notifications")
+    assert response.status_code == 200
+    data = response.json()
+    assert len(data["items"]) == 1
+    assert data["items"][0]["title"] == "A"
+
+
+@pytest.mark.integration
+def test_list_pagination(
+    authenticated_client: TestClient,
+    db_session: AsyncSession,
+    notification_service: NotificationService,
+    user_a: User,
+) -> None:
+    async def create_many() -> None:
+        for i in range(25):
+            n = await notification_service.create_notification(
+                db_session,
+                user_a.id,
+                category="instance",
+                severity="info",
+                title=f"Notification {i}",
+            )
+            n.created_at = datetime.now(timezone.utc) - timedelta(seconds=i)
+            await db_session.commit()
+            await db_session.refresh(n)
+
+    import asyncio
+
+    asyncio.run(create_many())
+
+    _mint_cookie_for_user(authenticated_client, user_a.id)
+    response = authenticated_client.get("/notifications?limit=10&offset=10")
+    assert response.status_code == 200
+    data = response.json()
+    assert len(data["items"]) == 10
+    assert data["total"] == 25
+    assert data["limit"] == 10
+    assert data["offset"] == 10
+
+
+@pytest.mark.integration
+def test_unread_count_endpoint(
+    authenticated_client: TestClient,
+    db_session: AsyncSession,
+    notification_service: NotificationService,
+    user_a: User,
+) -> None:
+    async def create_unread() -> None:
+        for _ in range(3):
+            await notification_service.create_notification(
+                db_session,
+                user_a.id,
+                category="instance",
+                severity="info",
+                title="Unread",
+            )
+
+    import asyncio
+
+    asyncio.run(create_unread())
+
+    _mint_cookie_for_user(authenticated_client, user_a.id)
+    response = authenticated_client.get("/notifications/unread")
+    assert response.status_code == 200
+    data = response.json()
+    assert data["count"] == 3
+
+
+@pytest.mark.integration
+def test_mark_read_endpoint(
+    authenticated_client: TestClient,
+    db_session: AsyncSession,
+    notification_service: NotificationService,
+    user_a: User,
+) -> None:
+    async def create_and_get() -> uuid.UUID:
+        n = await notification_service.create_notification(
+            db_session, user_a.id, category="instance", severity="info", title="To read"
+        )
+        return n.id
+
+    import asyncio
+
+    nid = asyncio.run(create_and_get())
+
+    _mint_cookie_for_user(authenticated_client, user_a.id)
+    response = authenticated_client.patch(f"/notifications/{nid}/read")
+    assert response.status_code == 200
+    data = response.json()
+    assert data["read_at"] is not None
+
+
+@pytest.mark.integration
+def test_mark_read_404_for_other_user(
+    authenticated_client: TestClient,
+    db_session: AsyncSession,
+    notification_service: NotificationService,
+    user_a: User,
+    user_b: User,
+) -> None:
+    async def create_and_get() -> uuid.UUID:
+        n = await notification_service.create_notification(
+            db_session,
+            user_a.id,
+            category="instance",
+            severity="info",
+            title="Owned by A",
+        )
+        return n.id
+
+    import asyncio
+
+    nid = asyncio.run(create_and_get())
+
+    _mint_cookie_for_user(authenticated_client, user_b.id)
+    response = authenticated_client.patch(f"/notifications/{nid}/read")
+    assert response.status_code == 404
+
+
+@pytest.mark.integration
+def test_mark_all_read_endpoint(
+    authenticated_client: TestClient,
+    db_session: AsyncSession,
+    notification_service: NotificationService,
+    user_a: User,
+) -> None:
+    async def create_unread() -> None:
+        for _ in range(4):
+            await notification_service.create_notification(
+                db_session,
+                user_a.id,
+                category="instance",
+                severity="info",
+                title="Unread",
+            )
+
+    import asyncio
+
+    asyncio.run(create_unread())
+
+    _mint_cookie_for_user(authenticated_client, user_a.id)
+    response = authenticated_client.post("/notifications/mark-all-read")
+    assert response.status_code == 200
+    data = response.json()
+    assert data["marked_count"] == 4
+
+
+@pytest.mark.integration
+def test_dismiss_endpoint(
+    authenticated_client: TestClient,
+    db_session: AsyncSession,
+    notification_service: NotificationService,
+    user_a: User,
+) -> None:
+    async def create_and_get() -> uuid.UUID:
+        n = await notification_service.create_notification(
+            db_session,
+            user_a.id,
+            category="instance",
+            severity="info",
+            title="To dismiss",
+        )
+        return n.id
+
+    import asyncio
+
+    nid = asyncio.run(create_and_get())
+
+    _mint_cookie_for_user(authenticated_client, user_a.id)
+    response = authenticated_client.delete(f"/notifications/{nid}")
+    assert response.status_code == 204
+
+    response = authenticated_client.get("/notifications")
+    data = response.json()
+    assert len(data["items"]) == 0
+
+
+@pytest.mark.integration
+def test_dismiss_404_for_other_user(
+    authenticated_client: TestClient,
+    db_session: AsyncSession,
+    notification_service: NotificationService,
+    user_a: User,
+    user_b: User,
+) -> None:
+    async def create_and_get() -> uuid.UUID:
+        n = await notification_service.create_notification(
+            db_session,
+            user_a.id,
+            category="instance",
+            severity="info",
+            title="Owned by A",
+        )
+        return n.id
+
+    import asyncio
+
+    nid = asyncio.run(create_and_get())
+
+    _mint_cookie_for_user(authenticated_client, user_b.id)
+    response = authenticated_client.delete(f"/notifications/{nid}")
+    assert response.status_code == 404
+
+
+@pytest.mark.integration
+def test_mute_categories_filter_in_list(
+    authenticated_client: TestClient,
+    db_session: AsyncSession,
+    notification_service: NotificationService,
+    user_a: User,
+) -> None:
+    async def setup() -> None:
+        config = UserConfig(
+            user_id=user_a.id, config={"notification_mute_categories": ["instance"]}
+        )
+        db_session.add(config)
+        await db_session.commit()
+
+        await notification_service.create_notification(
+            db_session,
+            user_a.id,
+            category="instance",
+            severity="info",
+            title="Instance",
+        )
+        await notification_service.create_notification(
+            db_session, user_a.id, category="system", severity="info", title="System"
+        )
+
+    import asyncio
+
+    asyncio.run(setup())
+
+    _mint_cookie_for_user(authenticated_client, user_a.id)
+    response = authenticated_client.get("/notifications")
+    assert response.status_code == 200
+    data = response.json()
+    assert len(data["items"]) == 1
+    assert data["items"][0]["title"] == "System"

apps/api/tests/integration/test_notifications_lifecycle.py

@@ -0,0 +1,395 @@
+"""Integration tests for event producer → notification creation flow."""
+
+import uuid
+from collections.abc import Generator
+from unittest.mock import patch
+
+import pytest
+import pytest_asyncio
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.models.git_repository import GitRepository
+from src.models.notification import Notification
+from src.models.project import Project
+from src.models.tool_instance import ToolInstance
+from src.models.tool_type import ToolType
+from src.models.user import User
+from src.services.event_bus import InstanceEventBus, InstanceEventPayload
+from src.services.health_monitor import HealthSnapshot
+
+
+@pytest.fixture
+def event_bus() -> Generator[InstanceEventBus, None, None]:
+    """Provide a fresh EventBus instance."""
+    bus = InstanceEventBus()
+    bus._reset_for_testing()
+    yield bus
+    bus._reset_for_testing()
+
+
+@pytest_asyncio.fixture
+async def test_instance(db_session: AsyncSession) -> ToolInstance:
+    """Create a complete tool instance with all required relations."""
+    user = User(
+        id=uuid.uuid4(),
+        email="owner@headquarter.local",
+        name="Owner",
+        authentik_id=f"authentik-{uuid.uuid4()}",
+        avatar_url=None,
+    )
+    db_session.add(user)
+    await db_session.commit()
+
+    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="running",
+        compose_path="/tmp/test-compose.yml",
+        port=8080,
+    )
+    db_session.add(instance)
+    await db_session.commit()
+    return instance
+
+
+@pytest.mark.asyncio
+@pytest.mark.integration
+async def test_lifecycle_started_intermediate_skips_notification(
+    db_session: AsyncSession,
+    event_bus: InstanceEventBus,
+    test_instance: ToolInstance,
+) -> None:
+    """Intermediate 'starting' state does NOT create a notification."""
+    received: list[InstanceEventPayload] = []
+
+    def subscriber(payload: InstanceEventPayload) -> None:
+        received.append(payload)
+
+    event_bus.subscribe("instance.started", subscriber)
+
+    from src.services.lifecycle_hooks import publish_lifecycle_event
+
+    await publish_lifecycle_event(
+        event_bus=event_bus,
+        session=db_session,
+        instance=test_instance,
+        event_type="instance.started",
+        status="starting",
+        message="Container starting...",
+    )
+
+    # Event still published
+    assert len(received) == 1
+
+    # No notification created for intermediate state
+    result = await db_session.execute(
+        select(Notification).where(Notification.user_id == test_instance.owner_id)
+    )
+    notifications = list(result.scalars().all())
+    assert len(notifications) == 0
+
+
+@pytest.mark.asyncio
+@pytest.mark.integration
+async def test_lifecycle_running_creates_notification(
+    db_session: AsyncSession,
+    event_bus: InstanceEventBus,
+    test_instance: ToolInstance,
+) -> None:
+    """Successful terminal state (running) creates a notification."""
+    from src.services.lifecycle_hooks import publish_lifecycle_event
+
+    await publish_lifecycle_event(
+        event_bus=event_bus,
+        session=db_session,
+        instance=test_instance,
+        event_type="instance.health_changed",
+        status="running",
+        message="Container running",
+    )
+
+    result = await db_session.execute(
+        select(Notification).where(Notification.user_id == test_instance.owner_id)
+    )
+    notifications = list(result.scalars().all())
+    assert len(notifications) == 1
+    n = notifications[0]
+    assert n.category == "instance"
+    assert n.severity == "success"
+    assert n.title == "Container ready"
+    assert n.source_type == "tool_instances"
+    assert n.source_id == test_instance.id
+
+
+@pytest.mark.asyncio
+@pytest.mark.integration
+async def test_health_monitor_error_creates_notification(
+    db_session: AsyncSession,
+    event_bus: InstanceEventBus,
+    test_instance: ToolInstance,
+) -> None:
+    """Simulating a health monitor crash creates an error notification."""
+    from src.services.health_monitor import HealthMonitor
+
+    monitor = HealthMonitor(event_bus)
+
+    received: list[InstanceEventPayload] = []
+
+    def subscriber(payload: InstanceEventPayload) -> None:
+        received.append(payload)
+
+    event_bus.subscribe("instance.error", subscriber)
+
+    with patch(
+        "src.services.health_monitor.get_container_status",
+        return_value={"status": "exited", "exit_code": 137, "health": None},
+    ):
+        await monitor._check_instance(db_session, test_instance)
+
+    # Event published
+    assert len(received) == 1
+
+    # Notification created
+    result = await db_session.execute(
+        select(Notification).where(Notification.user_id == test_instance.owner_id)
+    )
+    notifications = list(result.scalars().all())
+    assert len(notifications) == 1
+    n = notifications[0]
+    assert n.category == "instance"
+    assert n.severity == "error"
+    assert n.source_type == "tool_instances"
+    assert n.source_id == test_instance.id
+
+
+@pytest.mark.asyncio
+@pytest.mark.integration
+async def test_notification_failure_does_not_block_event_pipeline(
+    db_session: AsyncSession,
+    event_bus: InstanceEventBus,
+    test_instance: ToolInstance,
+) -> None:
+    """If NotificationService raises, the event is still published and no exception escapes."""
+    received: list[InstanceEventPayload] = []
+
+    def subscriber(payload: InstanceEventPayload) -> None:
+        received.append(payload)
+
+    event_bus.subscribe("instance.started", subscriber)
+
+    from src.services.lifecycle_hooks import publish_lifecycle_event
+
+    with patch(
+        "src.services.lifecycle_hooks.notification_service.create_notification",
+        side_effect=RuntimeError("DB is down"),
+    ):
+        # Should not raise
+        await publish_lifecycle_event(
+            event_bus=event_bus,
+            session=db_session,
+            instance=test_instance,
+            event_type="instance.started",
+            status="starting",
+            message="Container started",
+        )
+
+    assert len(received) == 1
+    assert received[0]["event"] == "instance.started"
+
+    # No notification should have been created
+    result = await db_session.execute(
+        select(Notification).where(Notification.user_id == test_instance.owner_id)
+    )
+    assert result.scalar_one_or_none() is None
+
+
+@pytest.mark.asyncio
+@pytest.mark.integration
+async def test_notification_ownership_matches_instance_owner(
+    db_session: AsyncSession,
+    event_bus: InstanceEventBus,
+) -> None:
+    """Notification user_id matches the instance owner, not any caller."""
+    # Create a caller user (simulates the user making an API request)
+    caller = User(
+        id=uuid.uuid4(),
+        email="caller@headquarter.local",
+        name="Caller",
+        authentik_id=f"authentik-{uuid.uuid4()}",
+        avatar_url=None,
+    )
+    db_session.add(caller)
+    await db_session.commit()
+
+    # Create the actual owner
+    owner = User(
+        id=uuid.uuid4(),
+        email="owner@headquarter.local",
+        name="Owner",
+        authentik_id=f"authentik-{uuid.uuid4()}",
+        avatar_url=None,
+    )
+    db_session.add(owner)
+    await db_session.commit()
+
+    project = Project(
+        id=uuid.uuid4(),
+        name="test-project",
+        description="Test",
+        owner_id=owner.id,
+    )
+    repo = GitRepository(
+        id=uuid.uuid4(),
+        name="test-repo",
+        path="/tmp/test-repo",
+        project_id=project.id,
+        owner_id=owner.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=owner.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.health_changed",
+        status="running",
+        message="Container running",
+    )
+
+    result = await db_session.execute(
+        select(Notification).where(Notification.source_id == instance.id)
+    )
+    n = result.scalar_one()
+    assert n.user_id == owner.id
+    assert n.user_id != caller.id
+
+
+@pytest.mark.asyncio
+@pytest.mark.integration
+async def test_lifecycle_error_creates_error_notification(
+    db_session: AsyncSession,
+    event_bus: InstanceEventBus,
+    test_instance: ToolInstance,
+) -> None:
+    """An instance.error lifecycle event creates a severity=error notification."""
+    from src.services.lifecycle_hooks import publish_lifecycle_event
+
+    await publish_lifecycle_event(
+        event_bus=event_bus,
+        session=db_session,
+        instance=test_instance,
+        event_type="instance.error",
+        status="error",
+        message="Container failed",
+    )
+
+    result = await db_session.execute(
+        select(Notification).where(Notification.user_id == test_instance.owner_id)
+    )
+    n = result.scalar_one()
+    assert n.severity == "error"
+    assert n.title == "Container error"
+
+
+@pytest.mark.asyncio
+@pytest.mark.integration
+async def test_health_monitor_unhealthy_creates_warning_notification(
+    db_session: AsyncSession,
+    event_bus: InstanceEventBus,
+    test_instance: ToolInstance,
+) -> None:
+    """Health monitor marking instance unhealthy creates severity=warning notification."""
+    from src.services.health_monitor import HealthMonitor
+
+    monitor = HealthMonitor(event_bus)
+    monitor._last_known_state[test_instance.id] = HealthSnapshot(
+        container_status="running",
+        container_healthy=None,
+        tunnel_healthy=True,
+        exit_code=None,
+    )
+    test_instance.public_url = "https://example.trycloudflare.com"
+
+    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"},
+        ),
+    ):
+        await monitor._check_instance(db_session, test_instance)
+
+    result = await db_session.execute(
+        select(Notification).where(Notification.user_id == test_instance.owner_id)
+    )
+    n = result.scalar_one()
+    assert n.category == "health"
+    assert n.severity == "warning"
+    assert n.title == "Container unhealthy"

apps/api/tests/integration/test_tool_types_api_extended.py

@@ -6,7 +6,9 @@ from fastapi.testclient import TestClient
 class TestToolTypesAPIExtended:
     """Integration tests for tool types API with new fields."""
 
-    def test_create_tool_type_with_dockerfile(self, authenticated_client: TestClient) -> None:
+    def test_create_tool_type_with_dockerfile(
+        self, authenticated_client: TestClient
+    ) -> None:
         """Test creating a tool type with dockerfile definition."""
         response = authenticated_client.post(
             "/tool-types",
@@ -27,7 +29,9 @@ class TestToolTypesAPIExtended:
         assert data["definition_type"] == "dockerfile"
         assert data["dockerfile_template"] == "FROM python:3.11\nRUN pip install flask"
 
-    def test_create_tool_type_with_readiness_probe(self, authenticated_client: TestClient) -> None:
+    def test_create_tool_type_with_readiness_probe(
+        self, authenticated_client: TestClient
+    ) -> None:
         """Test creating a tool type with readiness probe."""
         response = authenticated_client.post(
             "/tool-types",
@@ -52,7 +56,9 @@ class TestToolTypesAPIExtended:
         assert data["readiness_probe"]["command"] == "curl -f http://localhost:8080"
         assert data["readiness_probe"]["timeout"] == 30
 
-    def test_create_tool_type_invalid_definition_type(self, authenticated_client: TestClient) -> None:
+    def test_create_tool_type_invalid_definition_type(
+        self, authenticated_client: TestClient
+    ) -> None:
         """Test that invalid definition types are rejected."""
         response = authenticated_client.post(
             "/tool-types",
@@ -67,7 +73,9 @@ class TestToolTypesAPIExtended:
         )
         assert response.status_code == 422
 
-    def test_create_tool_type_dockerfile_without_template(self, authenticated_client: TestClient) -> None:
+    def test_create_tool_type_dockerfile_without_template(
+        self, authenticated_client: TestClient
+    ) -> None:
         """Test that dockerfile type requires dockerfile_template."""
         response = authenticated_client.post(
             "/tool-types",
@@ -81,7 +89,9 @@ class TestToolTypesAPIExtended:
         )
         assert response.status_code == 422
 
-    def test_update_tool_type_with_new_fields(self, authenticated_client: TestClient) -> None:
+    def test_update_tool_type_with_new_fields(
+        self, authenticated_client: TestClient
+    ) -> None:
         """Test updating a tool type with new fields."""
         # Create tool type first
         create_response = authenticated_client.post(
@@ -112,7 +122,9 @@ class TestToolTypesAPIExtended:
         assert response.status_code == 200
         data = response.json()
         assert data["display_name"] == "Updated Name"
-        assert data["readiness_probe"]["command"] == "curl -f http://localhost:8080/health"
+        assert (
+            data["readiness_probe"]["command"] == "curl -f http://localhost:8080/health"
+        )
 
     def test_validate_tool_type_compose(self, authenticated_client: TestClient) -> None:
         """Test validating compose template."""
@@ -127,7 +139,9 @@ class TestToolTypesAPIExtended:
         data = response.json()
         assert data["valid"] is True
 
-    def test_validate_tool_type_invalid_compose(self, authenticated_client: TestClient) -> None:
+    def test_validate_tool_type_invalid_compose(
+        self, authenticated_client: TestClient
+    ) -> None:
         """Test validating invalid compose template."""
         response = authenticated_client.post(
             "/tool-types/validate",
@@ -141,7 +155,9 @@ class TestToolTypesAPIExtended:
         assert data["valid"] is False
         assert "errors" in data
 
-    def test_validate_tool_type_dockerfile(self, authenticated_client: TestClient) -> None:
+    def test_validate_tool_type_dockerfile(
+        self, authenticated_client: TestClient
+    ) -> None:
         """Test validating dockerfile template."""
         response = authenticated_client.post(
             "/tool-types/validate",
@@ -154,7 +170,9 @@ class TestToolTypesAPIExtended:
         data = response.json()
         assert data["valid"] is True
 
-    def test_get_tool_type_returns_new_fields(self, authenticated_client: TestClient) -> None:
+    def test_get_tool_type_returns_new_fields(
+        self, authenticated_client: TestClient
+    ) -> None:
         """Test that GET returns new fields."""
         # Create tool type with all fields
         create_response = authenticated_client.post(
@@ -166,7 +184,7 @@ class TestToolTypesAPIExtended:
                 "interfaces": ["web", "terminal"],
                 "default_port": 8443,
                 "definition_type": "compose",
-                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: code-server\n    ports:\n      - '8443:8443'\n    volumes:\n      - \"{{REPO_PATH}}:/workspace\"",
+                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: code-server\n    command: --bind-addr 0.0.0.0:8443\n    ports:\n      - '8443:8443'\n    volumes:\n      - \"{{REPO_PATH}}:/workspace\"",
                 "readiness_probe": {
                     "command": "curl -f http://localhost:8443",
                     "timeout": 30,
@@ -186,7 +204,9 @@ class TestToolTypesAPIExtended:
         assert data["interfaces"] == ["web", "terminal"]
         assert "readiness_probe" in data
 
-    def test_create_tool_type_without_port_fails(self, authenticated_client: TestClient) -> None:
+    def test_create_tool_type_without_port_fails(
+        self, authenticated_client: TestClient
+    ) -> None:
         """Test that creating a tool type without default_port fails validation."""
         response = authenticated_client.post(
             "/tool-types",
@@ -204,7 +224,9 @@ class TestToolTypesAPIExtended:
         data = response.json()
         assert "default_port" in str(data)
 
-    def test_create_tool_type_with_port_mismatch_fails(self, authenticated_client: TestClient) -> None:
+    def test_create_tool_type_with_port_mismatch_fails(
+        self, authenticated_client: TestClient
+    ) -> None:
         """Test that port mismatch between default_port and compose template fails."""
         response = authenticated_client.post(
             "/tool-types",
@@ -222,7 +244,9 @@ class TestToolTypesAPIExtended:
         assert response.status_code == 422
         _ = response.json()
 
-    def test_create_tool_type_with_startup_command(self, authenticated_client: TestClient) -> None:
+    def test_create_tool_type_with_startup_command(
+        self, authenticated_client: TestClient
+    ) -> None:
         """Test creating a tool type with startup_command."""
         response = authenticated_client.post(
             "/tool-types",
@@ -244,7 +268,9 @@ class TestToolTypesAPIExtended:
         assert data["startup_command"] == "cd /workspace && ls"
         assert data["interface_type"] == "terminal"
 
-    def test_update_tool_type_startup_command(self, authenticated_client: TestClient) -> None:
+    def test_update_tool_type_startup_command(
+        self, authenticated_client: TestClient
+    ) -> None:
         """Test updating a tool type's startup_command."""
         # Create tool type first
         create_response = authenticated_client.post(
@@ -273,7 +299,9 @@ class TestToolTypesAPIExtended:
         data = response.json()
         assert data["startup_command"] == "source /etc/profile"
 
-    def test_get_tool_type_returns_startup_command(self, authenticated_client: TestClient) -> None:
+    def test_get_tool_type_returns_startup_command(
+        self, authenticated_client: TestClient
+    ) -> None:
         """Test that GET returns startup_command."""
         create_response = authenticated_client.post(
             "/tool-types",

apps/api/tests/unit/test_config_profile_resolver.py

@@ -6,6 +6,9 @@ from src.models.config_profile import ConfigProfile, ConfigProfileInclude
 from src.services.config_profile_resolver import (
     ConfigProfileCycleError,
     ConfigProfileNotFoundError,
+    ResolvedMount,
+    ResolvedProfile,
+    apply_resolved_profile,
     check_include_cycle,
     resolve_profile,
     _merge_env_vars,
@@ -479,6 +482,82 @@ class TestResolveProfile:
             await resolve_profile(db_session, uuid.uuid4())
 
 
+class TestApplyResolvedProfile:
+    """Unit tests for apply_resolved_profile file-level mount behavior."""
+
+    def test_mounts_individual_files_not_directory(self, tmp_path) -> None:
+        """Each file in a ResolvedMount should be mounted individually, not the staging dir."""
+        resolved = ResolvedProfile(
+            profile_id=uuid.uuid4(),
+            profile_name="test",
+            mounts={
+                "/app": ResolvedMount(
+                    target="/app",
+                    mode="rw",
+                    files={
+                        "config.json": '{"key": "value"}',
+                        "nested/file.txt": "hello",
+                    },
+                )
+            },
+        )
+        env, files, volumes, hints = apply_resolved_profile(str(tmp_path), resolved)
+
+        assert len(volumes) == 2
+        targets = {v["target"] for v in volumes}
+        assert "/app/config.json" in targets
+        assert "/app/nested/file.txt" in targets
+        # No directory-level mount
+        assert "/app" not in targets
+
+    def test_file_mount_preserves_sibling_files(self, tmp_path) -> None:
+        """File-level mounts should not hide sibling files from other mounts."""
+        resolved = ResolvedProfile(
+            profile_id=uuid.uuid4(),
+            profile_name="test",
+            mounts={
+                "/workspace/x/y": ResolvedMount(
+                    target="/workspace/x/y",
+                    mode="rw",
+                    files={"z.json": "override"},
+                )
+            },
+        )
+        env, files, volumes, hints = apply_resolved_profile(str(tmp_path), resolved)
+
+        assert len(volumes) == 1
+        assert volumes[0]["target"] == "/workspace/x/y/z.json"
+        assert volumes[0]["source"].endswith("z.json")
+
+    def test_empty_mount_produces_no_volumes(self, tmp_path) -> None:
+        """A mount with no files should not produce any volume entries."""
+        resolved = ResolvedProfile(
+            profile_id=uuid.uuid4(),
+            profile_name="test",
+            mounts={"/app": ResolvedMount(target="/app", mode="rw", files={})},
+        )
+        env, files, volumes, hints = apply_resolved_profile(str(tmp_path), resolved)
+        assert volumes == []
+
+    def test_home_expansion_in_file_mount_target(self, tmp_path) -> None:
+        """~ in mount target should be expanded to home_dir for file mounts."""
+        resolved = ResolvedProfile(
+            profile_id=uuid.uuid4(),
+            profile_name="test",
+            mounts={
+                "~/.config": ResolvedMount(
+                    target="~/.config",
+                    mode="rw",
+                    files={"app.toml": "setting = 1"},
+                )
+            },
+        )
+        env, files, volumes, hints = apply_resolved_profile(
+            str(tmp_path), resolved, home_dir="/home/user"
+        )
+        assert volumes[0]["target"] == "/home/user/.config/app.toml"
+
+
 class TestCheckIncludeCycle:
     """Unit tests for include cycle checking."""
 

apps/api/tests/unit/test_docker_service.py

@@ -2,7 +2,13 @@
 
 from unittest.mock import MagicMock, patch
 
-from src.services.docker import get_container_id, get_container_name
+import logging
+
+from src.services.docker import (
+    get_container_id,
+    get_container_name,
+    sort_volumes_by_specificity,
+)
 
 
 class TestGetContainerId:
@@ -50,3 +56,57 @@ class TestGetContainerName:
         result = get_container_name("missing")
 
         assert result is None
+
+
+class TestSortVolumesBySpecificity:
+    """Tests for sort_volumes_by_specificity."""
+
+    def test_parent_before_child(self) -> None:
+        """A repo mount to /workspace/x should come before a file mount to /workspace/x/y/config.json."""
+        volumes = [
+            "/repo/x/y/config.json:/workspace/x/y/config.json",
+            "/repo/x:/workspace/x",
+        ]
+        result = sort_volumes_by_specificity(volumes)
+        assert result[0] == "/repo/x:/workspace/x"
+        assert result[1] == "/repo/x/y/config.json:/workspace/x/y/config.json"
+
+    def test_stable_sort_for_equal_depth(self) -> None:
+        """Mounts at the same depth preserve input order."""
+        volumes = [
+            "/a:/workspace/a",
+            "/b:/workspace/b",
+            "/c:/workspace/c",
+        ]
+        result = sort_volumes_by_specificity(volumes)
+        assert result == volumes
+
+    def test_with_type_suffix(self) -> None:
+        """Volume strings with :bind or :ro suffixes are parsed correctly."""
+        volumes = [
+            "/repo/x/y/config.json:/workspace/x/y/config.json:bind",
+            "/repo/x:/workspace/x:bind",
+        ]
+        result = sort_volumes_by_specificity(volumes)
+        assert result[0] == "/repo/x:/workspace/x:bind"
+        assert result[1] == "/repo/x/y/config.json:/workspace/x/y/config.json:bind"
+
+    def test_empty_list(self) -> None:
+        """Empty list returns empty list."""
+        assert sort_volumes_by_specificity([]) == []
+
+    def test_single_volume(self) -> None:
+        """Single volume returns unchanged."""
+        volumes = ["/repo:/workspace"]
+        assert sort_volumes_by_specificity(volumes) == volumes
+
+    def test_duplicate_target_warning(self, caplog) -> None:
+        """Duplicate targets trigger a warning."""
+        with caplog.at_level(logging.WARNING, logger="src.services.docker"):
+            volumes = [
+                "/a:/workspace/x",
+                "/b:/workspace/x",
+            ]
+            sort_volumes_by_specificity(volumes)
+        assert "Duplicate mount targets detected" in caplog.text
+        assert "/workspace/x" in caplog.text

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_home_path_expansion.py

@@ -12,7 +12,9 @@ class TestExpandContainerPath:
 
     def test_tilde_slash_expands(self) -> None:
         """~/foo should expand to home_dir/foo."""
-        assert expand_container_path("~/workspace", "/home/user") == "/home/user/workspace"
+        assert (
+            expand_container_path("~/workspace", "/home/user") == "/home/user/workspace"
+        )
 
     def test_tilde_alone_expands(self) -> None:
         """~ should expand to home_dir."""
@@ -20,7 +22,10 @@ class TestExpandContainerPath:
 
     def test_dollar_home_slash_expands(self) -> None:
         """$HOME/foo should expand to home_dir/foo."""
-        assert expand_container_path("$HOME/workspace", "/home/user") == "/home/user/workspace"
+        assert (
+            expand_container_path("$HOME/workspace", "/home/user")
+            == "/home/user/workspace"
+        )
 
     def test_dollar_home_alone_expands(self) -> None:
         """$HOME should expand to home_dir."""
@@ -78,7 +83,9 @@ class TestResolveGitMountMappingsExpansion:
         """Mapping with ~/repo target expands to home dir."""
         (tmp_path / "src").mkdir()
         mappings = [{"source_path": "src", "target_path": "~/repo"}]
-        result = _resolve_git_mount_mappings(str(tmp_path), mappings, None, "/home/user")
+        result = _resolve_git_mount_mappings(
+            str(tmp_path), mappings, None, "/home/user"
+        )
         assert len(result) == 1
         assert result[0]["target"] == "/home/user/repo"
 
@@ -86,7 +93,9 @@ class TestResolveGitMountMappingsExpansion:
         """Mapping with $HOME/repo target expands to home dir."""
         (tmp_path / "src").mkdir()
         mappings = [{"source_path": "src", "target_path": "$HOME/repo"}]
-        result = _resolve_git_mount_mappings(str(tmp_path), mappings, None, "/home/user")
+        result = _resolve_git_mount_mappings(
+            str(tmp_path), mappings, None, "/home/user"
+        )
         assert len(result) == 1
         assert result[0]["target"] == "/home/user/repo"
 
@@ -94,6 +103,8 @@ class TestResolveGitMountMappingsExpansion:
         """Absolute target paths are not modified."""
         (tmp_path / "src").mkdir()
         mappings = [{"source_path": "src", "target_path": "/app/src"}]
-        result = _resolve_git_mount_mappings(str(tmp_path), mappings, None, "/home/user")
+        result = _resolve_git_mount_mappings(
+            str(tmp_path), mappings, None, "/home/user"
+        )
         assert len(result) == 1
         assert result[0]["target"] == "/app/src"

apps/api/tests/unit/test_lifecycle_hooks.py

@@ -0,0 +1,49 @@
+"""Unit tests for lifecycle hook helpers."""
+
+import pytest
+
+from src.services.lifecycle_hooks import _derive_title, _should_notify
+
+
+class TestDeriveTitle:
+    """Tests for _derive_title."""
+
+    def test_known_event_types(self) -> None:
+        assert _derive_title("instance.created") == "Container created"
+        assert _derive_title("instance.started") == "Container started"
+        assert _derive_title("instance.stopped") == "Container stopped"
+        assert _derive_title("instance.restarted") == "Container restarted"
+        assert _derive_title("instance.deleted") == "Container deleted"
+        assert _derive_title("instance.error") == "Container error"
+        assert _derive_title("instance.health_changed") == "Container ready"
+
+    def test_unknown_event_type(self) -> None:
+        assert _derive_title("instance.custom_event") == "Custom Event"
+
+
+class TestShouldNotify:
+    """Tests for _should_notify filtering."""
+
+    def test_error_events_are_notified(self) -> None:
+        assert _should_notify("instance.error", "error") is True
+        assert _should_notify("instance.error", None) is True
+
+    def test_health_changed_running_is_notified(self) -> None:
+        assert _should_notify("instance.health_changed", "running") is True
+
+    def test_created_started_stopped_restarted_deleted_filtered(self) -> None:
+        for event in [
+            "instance.created",
+            "instance.started",
+            "instance.stopped",
+            "instance.restarted",
+            "instance.deleted",
+        ]:
+            assert _should_notify(event, "pending") is False
+            assert _should_notify(event, "running") is False
+            assert _should_notify(event, None) is False
+
+    def test_health_changed_non_running_filtered(self) -> None:
+        assert _should_notify("instance.health_changed", "unhealthy") is False
+        assert _should_notify("instance.health_changed", "starting") is False
+        assert _should_notify("instance.health_changed", None) is False

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/api/tests/unit/test_notification_service.py

@@ -0,0 +1,387 @@
+"""Unit tests for NotificationService."""
+
+import uuid
+from datetime import datetime, timedelta, timezone
+
+import pytest
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.models.notification import Notification
+from src.models.user import User
+from src.services.notification_service import NotificationService
+
+
+@pytest.fixture
+def notification_service() -> NotificationService:
+    return NotificationService()
+
+
+@pytest.fixture
+async def user_a(db_session: AsyncSession) -> User:
+    user = User(
+        id=uuid.uuid4(),
+        email="user-a@headquarter.local",
+        name="User A",
+        authentik_id=f"authentik-{uuid.uuid4()}",
+        avatar_url=None,
+    )
+    db_session.add(user)
+    await db_session.commit()
+    return user
+
+
+@pytest.fixture
+async def user_b(db_session: AsyncSession) -> User:
+    user = User(
+        id=uuid.uuid4(),
+        email="user-b@headquarter.local",
+        name="User B",
+        authentik_id=f"authentik-{uuid.uuid4()}",
+        avatar_url=None,
+    )
+    db_session.add(user)
+    await db_session.commit()
+    return user
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_create_notification(
+    db_session: AsyncSession,
+    notification_service: NotificationService,
+    user_a: User,
+) -> None:
+    notification = await notification_service.create_notification(
+        db_session,
+        user_a.id,
+        category="instance",
+        severity="info",
+        title="Container started",
+        message="Instance is running",
+        source_type="tool_instances",
+        source_id=uuid.uuid4(),
+        metadata={"key": "value"},
+    )
+
+    assert notification.user_id == user_a.id
+    assert notification.category == "instance"
+    assert notification.severity == "info"
+    assert notification.title == "Container started"
+    assert notification.message == "Instance is running"
+    assert notification.source_type == "tool_instances"
+    assert notification.notification_metadata == {"key": "value"}
+    assert notification.read_at is None
+    assert notification.dismissed_at is None
+    assert notification.created_at is not None
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_list_notifications_orders_by_created_at_desc(
+    db_session: AsyncSession,
+    notification_service: NotificationService,
+    user_a: User,
+) -> None:
+    n1 = await notification_service.create_notification(
+        db_session, user_a.id, category="instance", severity="info", title="First"
+    )
+    n1.created_at = datetime.now(timezone.utc) - timedelta(seconds=2)
+    await db_session.commit()
+    await db_session.refresh(n1)
+
+    n2 = await notification_service.create_notification(
+        db_session, user_a.id, category="instance", severity="info", title="Second"
+    )
+    n2.created_at = datetime.now(timezone.utc) - timedelta(seconds=1)
+    await db_session.commit()
+    await db_session.refresh(n2)
+
+    n3 = await notification_service.create_notification(
+        db_session, user_a.id, category="instance", severity="info", title="Third"
+    )
+
+    items, total = await notification_service.list_notifications(db_session, user_a.id)
+
+    assert total == 3
+    assert [item.id for item in items] == [n3.id, n2.id, n1.id]
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_list_notifications_excludes_dismissed(
+    db_session: AsyncSession,
+    notification_service: NotificationService,
+    user_a: User,
+) -> None:
+    n1 = await notification_service.create_notification(
+        db_session, user_a.id, category="instance", severity="info", title="Visible"
+    )
+    n2 = await notification_service.create_notification(
+        db_session, user_a.id, category="instance", severity="info", title="Dismissed"
+    )
+    await notification_service.dismiss(db_session, n2.id, user_a.id)
+
+    items, total = await notification_service.list_notifications(db_session, user_a.id)
+
+    assert total == 1
+    assert items[0].id == n1.id
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_list_notifications_unread_only(
+    db_session: AsyncSession,
+    notification_service: NotificationService,
+    user_a: User,
+) -> None:
+    n1 = await notification_service.create_notification(
+        db_session, user_a.id, category="instance", severity="info", title="Unread"
+    )
+    n2 = await notification_service.create_notification(
+        db_session, user_a.id, category="instance", severity="info", title="Read"
+    )
+    await notification_service.mark_read(db_session, n2.id, user_a.id)
+
+    items, total = await notification_service.list_notifications(
+        db_session, user_a.id, unread_only=True
+    )
+
+    assert total == 1
+    assert items[0].id == n1.id
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_get_unread_count(
+    db_session: AsyncSession,
+    notification_service: NotificationService,
+    user_a: User,
+) -> None:
+    for i in range(5):
+        n = await notification_service.create_notification(
+            db_session,
+            user_a.id,
+            category="instance",
+            severity="info",
+            title=f"Notification {i}",
+        )
+        if i >= 3:
+            await notification_service.mark_read(db_session, n.id, user_a.id)
+
+    count = await notification_service.get_unread_count(db_session, user_a.id)
+
+    assert count == 3
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_mark_read_sets_read_at(
+    db_session: AsyncSession,
+    notification_service: NotificationService,
+    user_a: User,
+) -> None:
+    n = await notification_service.create_notification(
+        db_session, user_a.id, category="instance", severity="info", title="Unread"
+    )
+
+    updated = await notification_service.mark_read(db_session, n.id, user_a.id)
+
+    assert updated.read_at is not None
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_mark_all_read_affects_all_unread(
+    db_session: AsyncSession,
+    notification_service: NotificationService,
+    user_a: User,
+) -> None:
+    for i in range(4):
+        await notification_service.create_notification(
+            db_session,
+            user_a.id,
+            category="instance",
+            severity="info",
+            title=f"Notification {i}",
+        )
+
+    marked = await notification_service.mark_all_read(db_session, user_a.id)
+
+    assert marked == 4
+    count = await notification_service.get_unread_count(db_session, user_a.id)
+    assert count == 0
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_dismiss_sets_dismissed_at(
+    db_session: AsyncSession,
+    notification_service: NotificationService,
+    user_a: User,
+) -> None:
+    n = await notification_service.create_notification(
+        db_session, user_a.id, category="instance", severity="info", title="To dismiss"
+    )
+
+    await notification_service.dismiss(db_session, n.id, user_a.id)
+
+    result = await db_session.execute(
+        select(Notification).where(Notification.id == n.id)
+    )
+    row = result.scalar_one()
+    assert row.dismissed_at is not None
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_mark_read_wrong_owner_raises(
+    db_session: AsyncSession,
+    notification_service: NotificationService,
+    user_a: User,
+    user_b: User,
+) -> None:
+    n = await notification_service.create_notification(
+        db_session, user_a.id, category="instance", severity="info", title="Owned by A"
+    )
+
+    with pytest.raises(ValueError, match="Notification not found"):
+        await notification_service.mark_read(db_session, n.id, user_b.id)
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_dismiss_wrong_owner_raises(
+    db_session: AsyncSession,
+    notification_service: NotificationService,
+    user_a: User,
+    user_b: User,
+) -> None:
+    n = await notification_service.create_notification(
+        db_session, user_a.id, category="instance", severity="info", title="Owned by A"
+    )
+
+    with pytest.raises(ValueError, match="Notification not found"):
+        await notification_service.dismiss(db_session, n.id, user_b.id)
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_list_notifications_mute_categories(
+    db_session: AsyncSession,
+    notification_service: NotificationService,
+    user_a: User,
+) -> None:
+    await notification_service.create_notification(
+        db_session, user_a.id, category="instance", severity="info", title="Instance"
+    )
+    n2 = await notification_service.create_notification(
+        db_session, user_a.id, category="system", severity="info", title="System"
+    )
+
+    items, total = await notification_service.list_notifications(
+        db_session, user_a.id, mute_categories=["instance"]
+    )
+
+    assert total == 1
+    assert items[0].id == n2.id
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_get_unread_count_excludes_dismissed(
+    db_session: AsyncSession,
+    notification_service: NotificationService,
+    user_a: User,
+) -> None:
+    n = await notification_service.create_notification(
+        db_session,
+        user_a.id,
+        category="instance",
+        severity="info",
+        title="Unread dismissed",
+    )
+    await notification_service.dismiss(db_session, n.id, user_a.id)
+
+    count = await notification_service.get_unread_count(db_session, user_a.id)
+
+    assert count == 0
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_dismiss_all_affects_all_non_dismissed(
+    db_session: AsyncSession,
+    notification_service: NotificationService,
+    user_a: User,
+) -> None:
+    for i in range(4):
+        await notification_service.create_notification(
+            db_session,
+            user_a.id,
+            category="instance",
+            severity="info",
+            title=f"Notification {i}",
+        )
+
+    cleared = await notification_service.dismiss_all(db_session, user_a.id)
+
+    assert cleared == 4
+    items, total = await notification_service.list_notifications(db_session, user_a.id)
+    assert total == 0
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_dismiss_all_affects_only_caller(
+    db_session: AsyncSession,
+    notification_service: NotificationService,
+    user_a: User,
+    user_b: User,
+) -> None:
+    for i in range(3):
+        await notification_service.create_notification(
+            db_session, user_a.id, category="instance", severity="info", title=f"A-{i}"
+        )
+    for i in range(2):
+        await notification_service.create_notification(
+            db_session, user_b.id, category="instance", severity="info", title=f"B-{i}"
+        )
+
+    cleared = await notification_service.dismiss_all(db_session, user_a.id)
+
+    assert cleared == 3
+    items_a, total_a = await notification_service.list_notifications(
+        db_session, user_a.id
+    )
+    items_b, total_b = await notification_service.list_notifications(
+        db_session, user_b.id
+    )
+    assert total_a == 0
+    assert total_b == 2
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_mark_all_read_affects_only_caller(
+    db_session: AsyncSession,
+    notification_service: NotificationService,
+    user_a: User,
+    user_b: User,
+) -> None:
+    for i in range(3):
+        await notification_service.create_notification(
+            db_session, user_a.id, category="instance", severity="info", title=f"A-{i}"
+        )
+    for i in range(2):
+        await notification_service.create_notification(
+            db_session, user_b.id, category="instance", severity="info", title=f"B-{i}"
+        )
+
+    marked = await notification_service.mark_all_read(db_session, user_a.id)
+
+    assert marked == 3
+    count_a = await notification_service.get_unread_count(db_session, user_a.id)
+    count_b = await notification_service.get_unread_count(db_session, user_b.id)
+    assert count_a == 0
+    assert count_b == 2

apps/api/tests/unit/test_notifications_api_routes.py

@@ -0,0 +1,34 @@
+"""Unit tests for notification API route ordering."""
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from src.api.notifications import router as notifications_router
+
+
+def test_delete_notifications_route_order() -> None:
+    """DELETE /notifications must match before DELETE /notifications/{id}.
+
+    FastAPI matches routes in declaration order. The bulk clear endpoint
+    (DELETE /notifications) must be registered before the single dismiss
+    endpoint (DELETE /notifications/{notification_id}) or the path
+    parameter route will intercept the bulk route.
+    """
+    app = FastAPI()
+    app.include_router(notifications_router)
+    client = TestClient(app)
+
+    # Verify the bulk delete route exists and returns the expected schema
+    # (it will 401 without auth, but that's fine — we just need to confirm
+    # routing doesn't hit the UUID-parameter route first)
+    response = client.delete("/notifications")
+    # Should get 401 (unauthenticated), NOT 422 (UUID parse error)
+    assert response.status_code == 401, (
+        f"Expected 401 (auth required), got {response.status_code}. "
+        f"Route order may be wrong — DELETE /notifications matched "
+        f"DELETE /notifications/{{notification_id}} instead."
+    )
+
+    # Verify the single dismiss route still works (also 401 without auth)
+    response = client.delete("/notifications/12345678-1234-1234-1234-123456789abc")
+    assert response.status_code == 401

apps/api/tests/unit/test_permission_fixer.py

@@ -7,6 +7,7 @@ import pytest
 from src.services.permission_fixer import (
     PermissionFixError,
     apply_mount_permissions,
+    apply_ssh_permissions,
     check_root_user_available,
     _run_in_container,
 )
@@ -63,6 +64,24 @@ class TestApplyMountPermissions:
             "find /home/user/.ssh -type f -exec chmod 0600" in file_mode_call[0][1][2]
         )
 
+    @patch("src.services.permission_fixer._run_in_container")
+    def test_skips_readonly_mount(self, mock_run) -> None:
+        mounts = [
+            {
+                "name": "ssh_keys",
+                "target": "/home/user/.ssh",
+                "readonly": True,
+                "mode": "0700",
+                "file_mode": "0600",
+            },
+        ]
+        results = apply_mount_permissions("abc123", mounts)
+
+        assert len(results) == 1
+        assert results[0]["mount_name"] == "ssh_keys"
+        assert results[0]["success"] is True
+        mock_run.assert_not_called()
+
     @patch("src.services.permission_fixer._run_in_container")
     def test_skips_mount_with_no_policy(self, mock_run) -> None:
         mounts = [
@@ -132,6 +151,79 @@ class TestRunInContainer:
             _run_in_container("abc123", ["chown", "x"], 10)
 
 
+class TestApplySshPermissions:
+    """Tests for apply_ssh_permissions."""
+
+    @patch("subprocess.run")
+    def test_applies_chown_chmod_and_file_mode(self, mock_run) -> None:
+        mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+        result = apply_ssh_permissions("abc123", "/home/user/.ssh", "user")
+
+        assert result["success"] is True
+        # 3 fix commands + 3 verification commands
+        assert mock_run.call_count == 6
+        chown_cmd = mock_run.call_args_list[0][0][0]
+        chmod_cmd = mock_run.call_args_list[1][0][0]
+        file_mode_cmd = mock_run.call_args_list[2][0][0]
+
+        assert chown_cmd == [
+            "docker",
+            "exec",
+            "--user",
+            "root",
+            "abc123",
+            "chown",
+            "-R",
+            "user:user",
+            "/home/user/.ssh",
+        ]
+        assert chmod_cmd == [
+            "docker",
+            "exec",
+            "--user",
+            "root",
+            "abc123",
+            "chmod",
+            "700",
+            "/home/user/.ssh",
+        ]
+        assert file_mode_cmd[0] == "docker"
+        assert (
+            "find /home/user/.ssh -name 'id_*' -type f -exec chmod 600"
+            in file_mode_cmd[-1]
+        )
+
+    @patch("subprocess.run")
+    def test_uses_root_user(self, mock_run) -> None:
+        mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+        result = apply_ssh_permissions("abc123", "/root/.ssh", "root")
+
+        assert result["success"] is True
+        chown_cmd = mock_run.call_args_list[0][0][0]
+        assert chown_cmd == [
+            "docker",
+            "exec",
+            "--user",
+            "root",
+            "abc123",
+            "chown",
+            "-R",
+            "root:root",
+            "/root/.ssh",
+        ]
+
+    @patch("subprocess.run")
+    def test_reports_failure(self, mock_run) -> None:
+        mock_run.return_value = MagicMock(
+            returncode=1, stdout="", stderr="chown failed"
+        )
+
+        result = apply_ssh_permissions("abc123", "/home/user/.ssh", "user")
+
+        assert result["success"] is False
+        assert "chown failed" in result["error"]
+
+
 class TestCheckRootUserAvailable:
     """Tests for check_root_user_available."""
 

apps/api/tests/unit/test_ssh_keys.py

@@ -0,0 +1,61 @@
+"""Unit tests for SSH key preparation."""
+
+import os
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from src.services.ssh_keys import prepare_ssh_key_files
+
+
+class TestPrepareSshKeyFiles:
+    """Tests for prepare_ssh_key_files."""
+
+    @patch("src.services.ssh_keys._get_fernet")
+    def test_creates_files_with_default_permissions(
+        self, mock_fernet, tmp_path
+    ) -> None:
+        mock_fernet.return_value.decrypt.return_value = b"private-key-content"
+        ssh_key = MagicMock()
+        ssh_key.private_key_encrypted = "enc"
+        ssh_key.public_key = "ssh-ed25519 AAA test@test"
+
+        ssh_dir = prepare_ssh_key_files(str(tmp_path), ssh_key)
+
+        assert Path(ssh_dir).exists()
+        assert (Path(ssh_dir) / "id_ed25519").exists()
+        assert (Path(ssh_dir) / "id_ed25519.pub").exists()
+        assert (Path(ssh_dir) / "config").exists()
+        assert oct(os.stat(Path(ssh_dir) / "id_ed25519").st_mode)[-3:] == "600"
+
+    @patch("src.services.ssh_keys._get_fernet")
+    def test_sets_ownership_when_uid_gid_provided(self, mock_fernet, tmp_path) -> None:
+        mock_fernet.return_value.decrypt.return_value = b"private-key-content"
+        ssh_key = MagicMock()
+        ssh_key.private_key_encrypted = "enc"
+        ssh_key.public_key = "ssh-ed25519 AAA test@test"
+
+        with patch("os.chown") as mock_chown:
+            ssh_dir = prepare_ssh_key_files(str(tmp_path), ssh_key, uid=1001, gid=1001)
+
+        # os.chown is called for the directory and each of the 3 files
+        assert mock_chown.call_count == 4
+        # First call is the directory
+        assert mock_chown.call_args_list[0][0][1] == 1001
+        assert mock_chown.call_args_list[0][0][2] == 1001
+
+    @patch("src.services.ssh_keys._get_fernet")
+    def test_gracefully_handles_permission_error_on_chown(
+        self, mock_fernet, tmp_path
+    ) -> None:
+        mock_fernet.return_value.decrypt.return_value = b"private-key-content"
+        ssh_key = MagicMock()
+        ssh_key.private_key_encrypted = "enc"
+        ssh_key.public_key = "ssh-ed25519 AAA test@test"
+
+        with patch("os.chown", side_effect=PermissionError("not allowed")):
+            # Should not raise
+            ssh_dir = prepare_ssh_key_files(str(tmp_path), ssh_key, uid=1001, gid=1001)
+
+        assert Path(ssh_dir).exists()

apps/api/tests/unit/test_tool_instances_legacy.py

@@ -77,7 +77,9 @@ def mock_session(fake_user_id, fake_project_id, fake_repo_id, fake_tool_type_id)
 
     session.get.side_effect = _get
     session.add = MagicMock(side_effect=_add)
-    session.execute.return_value = MagicMock(scalars=MagicMock(return_value=MagicMock(all=MagicMock(return_value=[]))))
+    session.execute.return_value = MagicMock(
+        scalars=MagicMock(return_value=MagicMock(all=MagicMock(return_value=[])))
+    )
     return session
 
 
@@ -409,8 +411,9 @@ class TestStartInstanceLegacyFallback:
     @patch("src.api.tool_instances.wait_for_container_running")
     @patch("src.api.tool_instances.execute_compose_command")
     @patch("src.api.tool_instances.get_container_id")
-    @patch("src.api.tool_instances.get_container_name")
     @patch("src.api.tool_instances.connect_container_to_network")
+    @patch("src.api.tool_instances._ensure_container_name_in_compose")
+    @patch("src.api.tool_instances._ensure_web_bind_address")
     @patch("src.api.tool_instances._sanitize_compose_file")
     @patch("src.api.tool_instances._prepare_manifest_instance")
     @patch("src.api.tool_instances._get_user")
@@ -421,8 +424,9 @@ class TestStartInstanceLegacyFallback:
         mock_get_user,
         mock_prepare_manifest,
         mock_sanitize,
+        mock_ensure_web_bind,
+        mock_ensure_container_name,
         mock_connect_network,
-        mock_get_container_name,
         mock_get_container_id,
         mock_execute_compose,
         mock_wait_container,
@@ -438,9 +442,12 @@ class TestStartInstanceLegacyFallback:
         mock_get_project.return_value = AsyncMock()
         mock_execute_compose.return_value = (0, "started", "")
         mock_get_container_id.return_value = "abc123"
-        mock_get_container_name.return_value = "test-container"
         mock_connect_network.return_value = True
-        mock_wait_container.return_value = {"success": True, "status": "running", "waited_seconds": 0.5}
+        mock_wait_container.return_value = {
+            "success": True,
+            "status": "running",
+            "waited_seconds": 0.5,
+        }
 
         instance = ToolInstance(
             id=fake_instance_id,
@@ -503,8 +510,9 @@ class TestStartInstanceLegacyFallback:
     @patch("src.api.tool_instances.wait_for_container_running")
     @patch("src.api.tool_instances.execute_compose_command")
     @patch("src.api.tool_instances.get_container_id")
-    @patch("src.api.tool_instances.get_container_name")
     @patch("src.api.tool_instances.connect_container_to_network")
+    @patch("src.api.tool_instances._ensure_container_name_in_compose")
+    @patch("src.api.tool_instances._ensure_web_bind_address")
     @patch("src.api.tool_instances._sanitize_compose_file")
     @patch("src.api.tool_instances._prepare_manifest_instance")
     @patch("src.api.tool_instances._get_user")
@@ -515,8 +523,9 @@ class TestStartInstanceLegacyFallback:
         mock_get_user,
         mock_prepare_manifest,
         mock_sanitize,
+        mock_ensure_web_bind,
+        mock_ensure_container_name,
         mock_connect_network,
-        mock_get_container_name,
         mock_get_container_id,
         mock_execute_compose,
         mock_wait_container,
@@ -532,9 +541,12 @@ class TestStartInstanceLegacyFallback:
         mock_get_project.return_value = AsyncMock()
         mock_execute_compose.return_value = (0, "started", "")
         mock_get_container_id.return_value = "abc123"
-        mock_get_container_name.return_value = "test-container"
         mock_connect_network.return_value = True
-        mock_wait_container.return_value = {"success": True, "status": "running", "waited_seconds": 0.5}
+        mock_wait_container.return_value = {
+            "success": True,
+            "status": "running",
+            "waited_seconds": 0.5,
+        }
 
         instance = ToolInstance(
             id=fake_instance_id,
@@ -596,8 +608,9 @@ class TestStartInstanceLegacyFallback:
     @patch("src.api.tool_instances.wait_for_container_running")
     @patch("src.api.tool_instances.execute_compose_command")
     @patch("src.api.tool_instances.get_container_id")
-    @patch("src.api.tool_instances.get_container_name")
     @patch("src.api.tool_instances.connect_container_to_network")
+    @patch("src.api.tool_instances._ensure_container_name_in_compose")
+    @patch("src.api.tool_instances._ensure_web_bind_address")
     @patch("src.api.tool_instances._sanitize_compose_file")
     @patch("src.api.tool_instances._prepare_manifest_instance")
     @patch("src.api.tool_instances._get_user")
@@ -608,8 +621,9 @@ class TestStartInstanceLegacyFallback:
         mock_get_user,
         mock_prepare_manifest,
         mock_sanitize,
+        mock_ensure_web_bind,
+        mock_ensure_container_name,
         mock_connect_network,
-        mock_get_container_name,
         mock_get_container_id,
         mock_execute_compose,
         mock_wait_container,
@@ -625,9 +639,12 @@ class TestStartInstanceLegacyFallback:
         mock_get_project.return_value = AsyncMock()
         mock_execute_compose.return_value = (0, "started", "")
         mock_get_container_id.return_value = "abc123"
-        mock_get_container_name.return_value = "test-container"
         mock_connect_network.return_value = True
-        mock_wait_container.return_value = {"success": True, "status": "running", "waited_seconds": 0.5}
+        mock_wait_container.return_value = {
+            "success": True,
+            "status": "running",
+            "waited_seconds": 0.5,
+        }
 
         instance = ToolInstance(
             id=fake_instance_id,
@@ -687,14 +704,267 @@ class TestStartInstanceLegacyFallback:
         mock_execute_compose.assert_called_once()
 
 
+class TestStartInstanceSshPermissions:
+    """SSH key mounts trigger permission fixes after container starts."""
+
+    @patch("src.api.tool_instances.write_compose_file")
+    @patch("src.api.tool_instances.prepare_ssh_key_files")
+    @patch("src.api.tool_instances.apply_ssh_permissions")
+    @patch("src.api.tool_instances.wait_for_container_running")
+    @patch("src.api.tool_instances.execute_compose_command")
+    @patch("src.api.tool_instances.get_container_id")
+    @patch("src.api.tool_instances.connect_container_to_network")
+    @patch("src.api.tool_instances._ensure_container_name_in_compose")
+    @patch("src.api.tool_instances._ensure_web_bind_address")
+    @patch("src.api.tool_instances._sanitize_compose_file")
+    @patch("src.api.tool_instances._get_user")
+    @patch("src.api.tool_instances._get_owned_project")
+    async def test_manifest_instance_applies_ssh_permissions(
+        self,
+        mock_get_project,
+        mock_get_user,
+        mock_sanitize,
+        mock_ensure_web_bind,
+        mock_ensure_container_name,
+        mock_connect_network,
+        mock_get_container_id,
+        mock_execute_compose,
+        mock_wait_container,
+        mock_apply_ssh,
+        mock_prepare_ssh,
+        mock_write_compose,
+        mock_session,
+        fake_user_id,
+        fake_project_id,
+        fake_repo_id,
+        fake_instance_id,
+        fake_tool_type_id,
+    ) -> None:
+        """Manifest instance with SSH keys calls apply_ssh_permissions."""
+        from src.models.tool_definition_manifest import ToolDefinitionManifest
+
+        manifest_id = uuid.uuid4()
+        ssh_key_id = str(uuid.uuid4())
+
+        mock_get_user.return_value = AsyncMock()
+        mock_get_project.return_value = AsyncMock()
+        mock_execute_compose.return_value = (0, "started", "")
+        mock_get_container_id.return_value = "abc123"
+        mock_connect_network.return_value = True
+        mock_wait_container.return_value = {
+            "success": True,
+            "status": "running",
+            "waited_seconds": 0.5,
+        }
+        mock_apply_ssh.return_value = {"success": True, "error": None}
+
+        instance = ToolInstance(
+            id=fake_instance_id,
+            name="manifest-instance",
+            repository_id=fake_repo_id,
+            tool_type_id=fake_tool_type_id,
+            compose_path="/data/instances/manifest-instance/docker-compose.yml",
+            status="stopped",
+            clone_mode="mount",
+            ssh_key_ids=[ssh_key_id],
+            created_at=datetime.now(),
+            updated_at=datetime.now(),
+        )
+        tool_type = ToolType(
+            id=fake_tool_type_id,
+            name="manifest-tool",
+            display_name="Manifest Tool",
+            default_port=8080,
+            definition_type="manifest",
+            manifest_id=manifest_id,
+            dockerfile_template=None,
+            compose_template=None,
+        )
+        repo = GitRepository(
+            id=fake_repo_id,
+            project_id=fake_project_id,
+            name="test-repo",
+            path="/data/repos/test-repo",
+            remote_url=None,
+            ssh_key_id=None,
+        )
+        manifest_def = ToolDefinitionManifest(
+            id=manifest_id,
+            name="test-manifest",
+            display_name="Test Manifest",
+            interface_type="web",
+            manifest={"user": {"name": "user", "uid": 1001, "gid": 1001}},
+        )
+        ssh_key = SSHKey(
+            id=uuid.UUID(ssh_key_id),
+            user_id=fake_user_id,
+            name="test-key",
+            public_key="ssh-ed25519 AAA test@test",
+            private_key_encrypted="enc",
+        )
+
+        async def _get(model, pk):
+            if model is ToolInstance and pk == fake_instance_id:
+                return instance
+            if model is ToolType and pk == fake_tool_type_id:
+                return tool_type
+            if model is GitRepository and pk == fake_repo_id:
+                return repo
+            if model is User and pk == fake_user_id:
+                return User(id=fake_user_id, email="test@example.com")
+            if model is ToolDefinitionManifest and pk == manifest_id:
+                return manifest_def
+            if model is SSHKey and pk == uuid.UUID(ssh_key_id):
+                return ssh_key
+            return None
+
+        mock_session.get.side_effect = _get
+
+        with patch("os.path.exists", return_value=True):
+            with patch(
+                "src.api.tool_instances._prepare_manifest_instance"
+            ) as mock_prepare:
+                mock_prepare.return_value = (
+                    "headquarter/test:latest",
+                    "services:\n  app:\n    image: test",
+                    {"name": "test-manifest", "user": {"name": "user"}},
+                    "/home/user",
+                )
+                result = await start_instance(
+                    project_id=fake_project_id,
+                    repo_id=fake_repo_id,
+                    instance_id=fake_instance_id,
+                    data=None,
+                    user_id=fake_user_id,
+                    session=mock_session,
+                )
+
+        assert result["status"] == "running"
+        mock_apply_ssh.assert_called_once_with("abc123", "/home/user/.ssh", "user")
+
+    @patch("src.api.tool_instances.prepare_ssh_key_files")
+    @patch("src.api.tool_instances.apply_ssh_permissions")
+    @patch("src.api.tool_instances.wait_for_container_running")
+    @patch("src.api.tool_instances.execute_compose_command")
+    @patch("src.api.tool_instances.get_container_id")
+    @patch("src.api.tool_instances.connect_container_to_network")
+    @patch("src.api.tool_instances._ensure_container_name_in_compose")
+    @patch("src.api.tool_instances._ensure_web_bind_address")
+    @patch("src.api.tool_instances._sanitize_compose_file")
+    @patch("src.api.tool_instances._get_user")
+    @patch("src.api.tool_instances._get_owned_project")
+    async def test_legacy_instance_applies_ssh_permissions(
+        self,
+        mock_get_project,
+        mock_get_user,
+        mock_sanitize,
+        mock_ensure_web_bind,
+        mock_ensure_container_name,
+        mock_connect_network,
+        mock_get_container_id,
+        mock_execute_compose,
+        mock_wait_container,
+        mock_apply_ssh,
+        mock_prepare_ssh,
+        mock_session,
+        fake_user_id,
+        fake_project_id,
+        fake_repo_id,
+        fake_instance_id,
+        fake_tool_type_id,
+    ) -> None:
+        """Legacy instance with SSH keys calls apply_ssh_permissions."""
+        ssh_key_id = str(uuid.uuid4())
+
+        mock_get_user.return_value = AsyncMock()
+        mock_get_project.return_value = AsyncMock()
+        mock_execute_compose.return_value = (0, "started", "")
+        mock_get_container_id.return_value = "abc123"
+        mock_connect_network.return_value = True
+        mock_wait_container.return_value = {
+            "success": True,
+            "status": "running",
+            "waited_seconds": 0.5,
+        }
+        mock_apply_ssh.return_value = {"success": True, "error": None}
+
+        instance = ToolInstance(
+            id=fake_instance_id,
+            name="legacy-instance",
+            repository_id=fake_repo_id,
+            tool_type_id=fake_tool_type_id,
+            compose_path="/data/instances/legacy-instance/docker-compose.yml",
+            status="stopped",
+            clone_mode="mount",
+            ssh_key_ids=[ssh_key_id],
+            created_at=datetime.now(),
+            updated_at=datetime.now(),
+        )
+        tool_type = ToolType(
+            id=fake_tool_type_id,
+            name="legacy-tool",
+            display_name="Legacy Tool",
+            default_port=8080,
+            definition_type="legacy",
+            manifest_id=None,
+            dockerfile_template=None,
+            compose_template="services:\n  app:\n    image: nginx",
+        )
+        repo = GitRepository(
+            id=fake_repo_id,
+            project_id=fake_project_id,
+            name="test-repo",
+            path="/data/repos/test-repo",
+            remote_url=None,
+            ssh_key_id=None,
+        )
+        ssh_key = SSHKey(
+            id=uuid.UUID(ssh_key_id),
+            user_id=fake_user_id,
+            name="test-key",
+            public_key="ssh-ed25519 AAA test@test",
+            private_key_encrypted="enc",
+        )
+
+        async def _get(model, pk):
+            if model is ToolInstance and pk == fake_instance_id:
+                return instance
+            if model is ToolType and pk == fake_tool_type_id:
+                return tool_type
+            if model is GitRepository and pk == fake_repo_id:
+                return repo
+            if model is User and pk == fake_user_id:
+                return User(id=fake_user_id, email="test@example.com")
+            if model is SSHKey and pk == uuid.UUID(ssh_key_id):
+                return ssh_key
+            return None
+
+        mock_session.get.side_effect = _get
+
+        with patch("os.path.exists", return_value=True):
+            with patch("src.api.tool_instances._modify_compose_file"):
+                result = await start_instance(
+                    project_id=fake_project_id,
+                    repo_id=fake_repo_id,
+                    instance_id=fake_instance_id,
+                    data=None,
+                    user_id=fake_user_id,
+                    session=mock_session,
+                )
+
+        assert result["status"] == "running"
+        mock_apply_ssh.assert_called_once_with("abc123", "/root/.ssh", "root")
+
+
 class TestStartInstanceManifestBranch:
     """Manifest branch is taken ONLY when definition_type == 'manifest'."""
 
     @patch("src.api.tool_instances.wait_for_container_running")
     @patch("src.api.tool_instances.execute_compose_command")
     @patch("src.api.tool_instances.get_container_id")
-    @patch("src.api.tool_instances.get_container_name")
     @patch("src.api.tool_instances.connect_container_to_network")
+    @patch("src.api.tool_instances._ensure_container_name_in_compose")
+    @patch("src.api.tool_instances._ensure_web_bind_address")
     @patch("src.api.tool_instances._sanitize_compose_file")
     @patch("src.api.tool_instances._prepare_manifest_instance")
     @patch("src.api.tool_instances.write_compose_file")
@@ -707,8 +977,9 @@ class TestStartInstanceManifestBranch:
         mock_write_compose,
         mock_prepare_manifest,
         mock_sanitize,
+        mock_ensure_web_bind,
+        mock_ensure_container_name,
         mock_connect_network,
-        mock_get_container_name,
         mock_get_container_id,
         mock_execute_compose,
         mock_wait_container,
@@ -728,9 +999,12 @@ class TestStartInstanceManifestBranch:
         mock_get_project.return_value = AsyncMock()
         mock_execute_compose.return_value = (0, "started", "")
         mock_get_container_id.return_value = "abc123"
-        mock_get_container_name.return_value = "test-container"
         mock_connect_network.return_value = True
-        mock_wait_container.return_value = {"success": True, "status": "running", "waited_seconds": 0.5}
+        mock_wait_container.return_value = {
+            "success": True,
+            "status": "running",
+            "waited_seconds": 0.5,
+        }
         mock_prepare_manifest.return_value = (
             "headquarter/test:latest",
             "services:\n  app:\n    image: test",

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/config_profiles.ts

@@ -167,3 +167,23 @@ export const resolveDefaultProfile = async (
 	});
 	return response.data;
 };
+
+export interface ValidateGitUrlResponse {
+	valid: boolean;
+	suggested_url?: string;
+	branches?: string[];
+	default_branch?: string;
+	error?: string;
+	error_code?: string;
+}
+
+export const validateGitUrl = async (
+	url: string,
+	sshKeyId?: string,
+): Promise<ValidateGitUrlResponse> => {
+	const response = await apiClient.post<ValidateGitUrlResponse>(
+		"/config-profiles/validate-git-url",
+		{ url, ssh_key_id: sshKeyId },
+	);
+	return response.data;
+};

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/api/notifications.ts

@@ -0,0 +1,73 @@
+import { apiClient } from "./client";
+
+export interface NotificationItem {
+	id: string;
+	user_id: string;
+	category: string;
+	severity: "info" | "warning" | "error" | "success";
+	title: string;
+	message: string | null;
+	source_type: string | null;
+	source_id: string | null;
+	metadata: Record<string, unknown>;
+	read_at: string | null;
+	dismissed_at: string | null;
+	created_at: string;
+}
+
+export interface NotificationListResponse {
+	items: NotificationItem[];
+	total: number;
+	limit: number;
+	offset: number;
+}
+
+export interface UnreadCountResponse {
+	count: number;
+}
+
+export interface MarkAllReadResponse {
+	marked_count: number;
+}
+
+export interface ClearAllResponse {
+	cleared_count: number;
+}
+
+export const getNotifications = async (): Promise<NotificationListResponse> => {
+	const response =
+		await apiClient.get<NotificationListResponse>("/notifications");
+	return response.data;
+};
+
+export const getUnreadCount = async (): Promise<number> => {
+	const response = await apiClient.get<UnreadCountResponse>(
+		"/notifications/unread",
+	);
+	return response.data.count;
+};
+
+export const markNotificationRead = async (
+	id: string,
+): Promise<NotificationItem> => {
+	const response = await apiClient.patch<NotificationItem>(
+		`/notifications/${id}/read`,
+	);
+	return response.data;
+};
+
+export const markAllNotificationsRead = async (): Promise<number> => {
+	const response = await apiClient.post<MarkAllReadResponse>(
+		"/notifications/mark-all-read",
+	);
+	return response.data.marked_count;
+};
+
+export const dismissNotification = async (id: string): Promise<void> => {
+	await apiClient.delete(`/notifications/${id}`);
+};
+
+export const clearAllNotifications = async (): Promise<number> => {
+	const response = await apiClient.delete<ClearAllResponse>("/notifications");
+	return response.data.cleared_count;
+};

apps/web/src/api/sessions.ts

@@ -12,6 +12,7 @@ export interface ToolInstance {
   url: string | null;
   port: number | null;
   selected_config_profile_id: string | null;
+  ssh_key_ids: string[];
   created_at: string;
 }
 
@@ -52,7 +53,8 @@ export async function createInstance(
   cloneMode?: string,
   branch?: string,
   newBranch?: string,
-  configProfileId?: string
+  configProfileId?: string,
+  sshKeyIds?: string[]
 ): Promise<ToolInstance> {
   const response = await apiClient.post(
     `/projects/${projectId}/repositories/${repoId}/instances`,
@@ -63,6 +65,7 @@ export async function createInstance(
       branch: branch || undefined,
       new_branch: newBranch || undefined,
       config_profile_id: configProfileId,
+      ssh_key_ids: sshKeyIds || [],
     }
   );
   return response.data;
@@ -73,12 +76,13 @@ export async function startInstance(
   repoId: string,
   instanceId: string,
   configProfileId?: string,
+  sshKeyIds?: string[],
   retries = 2
 ): Promise<{ status: string; url?: string }> {
   try {
     const response = await apiClient.post(
       `/projects/${projectId}/repositories/${repoId}/instances/${instanceId}/start`,
-      { config_profile_id: configProfileId }
+      { config_profile_id: configProfileId, ssh_key_ids: sshKeyIds || [] }
     );
     return response.data;
   } catch (error) {
@@ -86,7 +90,7 @@ export async function startInstance(
     const axiosError = error as AxiosError;
     if (retries > 0 && !axiosError.response) {
       await new Promise((r) => setTimeout(r, 1500));
-      return startInstance(projectId, repoId, instanceId, configProfileId, retries - 1);
+      return startInstance(projectId, repoId, instanceId, configProfileId, sshKeyIds, retries - 1);
     }
     throw error;
   }
@@ -108,12 +112,13 @@ export async function restartInstance(
   repoId: string,
   instanceId: string,
   configProfileId?: string,
+  sshKeyIds?: string[],
   retries = 2
 ): Promise<{ status: string; url?: string }> {
   try {
     const response = await apiClient.post(
       `/projects/${projectId}/repositories/${repoId}/instances/${instanceId}/restart`,
-      { config_profile_id: configProfileId }
+      { config_profile_id: configProfileId, ssh_key_ids: sshKeyIds || [] }
     );
     return response.data;
   } catch (error) {
@@ -121,7 +126,7 @@ export async function restartInstance(
     const axiosError = error as AxiosError;
     if (retries > 0 && !axiosError.response) {
       await new Promise((r) => setTimeout(r, 1500));
-      return restartInstance(projectId, repoId, instanceId, configProfileId, retries - 1);
+      return restartInstance(projectId, repoId, instanceId, configProfileId, sshKeyIds, retries - 1);
     }
     throw error;
   }

apps/web/src/api/settings.ts

@@ -1,27 +1,33 @@
 import { apiClient } from "./client";
 
 export interface UserConfig {
-  default_editor: string | null;
-  theme: string;
-  git_user_name: string | null;
-  git_user_email: string | null;
-  last_session_id: string | null;
+	default_editor: string | null;
+	theme: string;
+	git_user_name: string | null;
+	git_user_email: string | null;
+	last_session_id: string | null;
+	notification_toast_level?: "all" | "errors" | "none";
+	notification_mute_categories?: string[];
 }
 
 export interface UserConfigUpdate {
-  default_editor?: string | null;
-  theme?: string | null;
-  git_user_name?: string | null;
-  git_user_email?: string | null;
-  last_session_id?: string | null;
+	default_editor?: string | null;
+	theme?: string | null;
+	git_user_name?: string | null;
+	git_user_email?: string | null;
+	last_session_id?: string | null;
+	notification_toast_level?: "all" | "errors" | "none";
+	notification_mute_categories?: string[];
 }
 
 export const getUserConfig = async (): Promise<UserConfig> => {
-  const response = await apiClient.get<UserConfig>("/users/me/config");
-  return response.data;
+	const response = await apiClient.get<UserConfig>("/users/me/config");
+	return response.data;
 };
 
-export const updateUserConfig = async (data: UserConfigUpdate): Promise<UserConfig> => {
-  const response = await apiClient.patch<UserConfig>("/users/me/config", data);
-  return response.data;
+export const updateUserConfig = async (
+	data: UserConfigUpdate,
+): Promise<UserConfig> => {
+	const response = await apiClient.patch<UserConfig>("/users/me/config", data);
+	return response.data;
 };

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

@@ -7,135 +7,171 @@ 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 { NotificationProvider } from "../state/notifications";
+import { EventToastBridge } from "./event-toast-bridge";
+import { NotificationCenter } from "./notification-center";
 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>
+					<NotificationProvider>
+						<EventToastBridge />
+						<div className="shell mobile-terminal-shell">
+							<Outlet />
+						</div>
+					</NotificationProvider>
+				</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>
+				<NotificationProvider>
+					<EventToastBridge />
+					<div className="shell">
+						<header className="shell-header">
+							<Link className="brand" to="/">
+								Headquarter
+							</Link>
+							<div className="header-actions">
+								<NotificationCenter isMobileTerminal={isMobileTerminal} />
+								<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>
+				</NotificationProvider>
+			</ToastProvider>
+		</EventProvider>
+	);
 };

apps/web/src/components/create-session-form.tsx

@@ -49,6 +49,7 @@ export const CreateSessionForm = ({
   const [sshKeys, setSshKeys] = useState<SSHKey[]>([]);
   const [configProfiles, setConfigProfiles] = useState<ConfigProfile[]>([]);
   const [selectedConfigProfile, setSelectedConfigProfile] = useState("");
+  const [selectedSshKeyIds, setSelectedSshKeyIds] = useState<string[]>([]);
   
   const [branches, setBranches] = useState<Branch[]>([]);
   const [isLoadingBranches, setIsLoadingBranches] = useState(false);
@@ -60,9 +61,8 @@ export const CreateSessionForm = ({
   const [progress, setProgress] = useState("");
   const [error, setError] = useState<string | null>(null);
 
-  // Load SSH keys when clone mode is shown
+  // Load SSH keys
   useEffect(() => {
-    if (!showCloneMode) return;
     const loadKeys = async () => {
       try {
         const keys = await listSSHKeys();
@@ -72,7 +72,7 @@ export const CreateSessionForm = ({
       }
     };
     void loadKeys();
-  }, [showCloneMode]);
+  }, []);
 
   // Load config profiles when tool type is selected
   useEffect(() => {
@@ -166,11 +166,18 @@ export const CreateSessionForm = ({
         showCloneMode && cloneMode === "clone" && isCreatingNewBranch
           ? newBranchName
           : undefined,
-        selectedConfigProfile || undefined
+        selectedConfigProfile || undefined,
+        selectedSshKeyIds.length > 0 ? selectedSshKeyIds : undefined
       );
 
       setProgress("Starting container...");
-      await startInstance(projectId, repoId, instance.id);
+      await startInstance(
+        projectId,
+        repoId,
+        instance.id,
+        selectedConfigProfile || undefined,
+        selectedSshKeyIds.length > 0 ? selectedSshKeyIds : undefined
+      );
 
       // Reset form
       if (!fixedProjectId) setSelectedProject("");
@@ -182,7 +189,8 @@ export const CreateSessionForm = ({
       setIsCreatingNewBranch(false);
       setNewBranchName("");
       setBaseBranch("");
-      setBranches([]);
+        setBranches([]);
+      setSelectedSshKeyIds([]);
       setStatus("idle");
       
       onSuccess?.(instance);
@@ -344,8 +352,54 @@ export const CreateSessionForm = ({
           </label>
         )}
 
-        {/* Step 5: Clone Mode & Branch */}
-        {showCloneMode && hasToolType && renderStep("Repository Access", 5, true, false,
+        {/* Step 5: SSH Keys */}
+        {hasToolType && renderStep("SSH Keys (optional)", 5, true, false,
+          <div className="form-field">
+            <div style={{ display: "flex", flexWrap: "wrap", gap: "0.5rem" }}>
+              {sshKeys.length === 0 && (
+                <span className="muted">No SSH keys configured.</span>
+              )}
+              {sshKeys.map((key) => (
+                <label
+                  key={key.id}
+                  className="checkbox-label"
+                  style={{
+                    display: "flex",
+                    alignItems: "center",
+                    gap: "0.25rem",
+                    padding: "0.375rem 0.75rem",
+                    background: "var(--panel)",
+                    borderRadius: "0.375rem",
+                    border: "1px solid var(--border)",
+                    cursor: "pointer",
+                  }}
+                >
+                  <input
+                    type="checkbox"
+                    checked={selectedSshKeyIds.includes(key.id)}
+                    onChange={(e) => {
+                      if (e.target.checked) {
+                        setSelectedSshKeyIds((prev) => [...prev, key.id]);
+                      } else {
+                        setSelectedSshKeyIds((prev) =>
+                          prev.filter((id) => id !== key.id)
+                        );
+                      }
+                    }}
+                    disabled={isSubmitting}
+                  />
+                  {key.name}
+                </label>
+              ))}
+            </div>
+            <div className="hint" style={{ marginTop: "0.5rem" }}>
+              Selected keys will be mounted into the container at ~/.ssh
+            </div>
+          </div>
+        )}
+
+        {/* Step 6: Clone Mode & Branch */}
+        {showCloneMode && hasToolType && renderStep("Repository Access", 6, true, false,
           <div className="form-row">
             <label className="form-field">
               <div className="radio-group">
@@ -468,8 +522,8 @@ export const CreateSessionForm = ({
           </div>
         )}
 
-        {/* Step 6: Display Name */}
-        {hasToolType && renderStep("Display Name (optional)", 6, true, !!displayName,
+        {/* Step 7: Display Name */}
+        {hasToolType && renderStep("Display Name (optional)", 7, true, !!displayName,
           <label className="form-field">
             <input
               type="text"

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

@@ -0,0 +1,220 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, act } from "@testing-library/react";
+import { EventToastBridge } from "./event-toast-bridge";
+import { useEventContext } from "../state/events";
+import { getUserConfig } from "../api/settings";
+import { handleEventToast } from "./toast-rules";
+import type { InstanceEventPayload } from "../types/events";
+
+vi.mock("../state/events", () => ({
+	useEventContext: vi.fn(),
+}));
+
+vi.mock("../api/settings", () => ({
+	getUserConfig: vi.fn(),
+}));
+
+vi.mock("./toast-rules", async (importOriginal) => {
+	const actual = await importOriginal<typeof import("./toast-rules")>();
+	return {
+		...actual,
+		handleEventToast: vi.fn(),
+		clearToastDedup: vi.fn(),
+	};
+});
+
+const mockedUseEventContext = vi.mocked(useEventContext);
+const mockedGetUserConfig = vi.mocked(getUserConfig);
+const mockedHandleEventToast = vi.mocked(handleEventToast);
+
+function makeEvent(
+	eventType: string,
+	overrides?: Partial<InstanceEventPayload>,
+): InstanceEventPayload {
+	return {
+		event: eventType,
+		instance_id: "i-1",
+		status: undefined,
+		message: undefined,
+		metadata: {},
+		timestamp: "2026-05-29T10:00:00Z",
+		correlation_id: "c1",
+		...overrides,
+	};
+}
+
+async function flushPromises() {
+	await act(async () => {
+		await Promise.resolve();
+	});
+}
+
+describe("EventToastBridge preference checks", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+		mockedUseEventContext.mockReturnValue({
+			events: [],
+			connected: false,
+			reconnectCount: 0,
+		});
+		mockedGetUserConfig.mockResolvedValue({
+			theme: "system",
+			default_editor: null,
+			git_user_name: null,
+			git_user_email: null,
+			last_session_id: null,
+			notification_toast_level: "all",
+			notification_mute_categories: [],
+		} as unknown as Awaited<ReturnType<typeof getUserConfig>>);
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("shows toast when level is all and category not muted", async () => {
+		const event = makeEvent("instance.started");
+		mockedUseEventContext.mockReturnValue({
+			events: [event],
+			connected: false,
+			reconnectCount: 0,
+		});
+		render(<EventToastBridge />);
+		await flushPromises();
+		expect(mockedHandleEventToast).toHaveBeenCalledWith(event);
+	});
+
+	it("suppresses toast when level is none", async () => {
+		mockedGetUserConfig.mockResolvedValue({
+			notification_toast_level: "none",
+			notification_mute_categories: [],
+		} as unknown as Awaited<ReturnType<typeof getUserConfig>>);
+		const event = makeEvent("instance.started");
+		mockedUseEventContext.mockReturnValue({
+			events: [event],
+			connected: false,
+			reconnectCount: 0,
+		});
+		render(<EventToastBridge />);
+		await flushPromises();
+		expect(mockedHandleEventToast).not.toHaveBeenCalled();
+	});
+
+	it("suppresses info toast when level is errors", async () => {
+		mockedGetUserConfig.mockResolvedValue({
+			notification_toast_level: "errors",
+			notification_mute_categories: [],
+		} as unknown as Awaited<ReturnType<typeof getUserConfig>>);
+		const event = makeEvent("instance.started");
+		mockedUseEventContext.mockReturnValue({
+			events: [event],
+			connected: false,
+			reconnectCount: 0,
+		});
+		render(<EventToastBridge />);
+		await flushPromises();
+		expect(mockedHandleEventToast).not.toHaveBeenCalled();
+	});
+
+	it("shows error toast when level is errors", async () => {
+		mockedGetUserConfig.mockResolvedValue({
+			notification_toast_level: "errors",
+			notification_mute_categories: [],
+		} as unknown as Awaited<ReturnType<typeof getUserConfig>>);
+		const event = makeEvent("instance.error");
+		mockedUseEventContext.mockReturnValue({
+			events: [event],
+			connected: false,
+			reconnectCount: 0,
+		});
+		render(<EventToastBridge />);
+		await flushPromises();
+		expect(mockedHandleEventToast).toHaveBeenCalledWith(event);
+	});
+
+	it("suppresses toast when category is muted", async () => {
+		mockedGetUserConfig.mockResolvedValue({
+			notification_toast_level: "all",
+			notification_mute_categories: ["instance"],
+		} as unknown as Awaited<ReturnType<typeof getUserConfig>>);
+		const event = makeEvent("instance.started");
+		mockedUseEventContext.mockReturnValue({
+			events: [event],
+			connected: false,
+			reconnectCount: 0,
+		});
+		render(<EventToastBridge />);
+		await flushPromises();
+		expect(mockedHandleEventToast).not.toHaveBeenCalled();
+	});
+
+	it("applies preference change immediately via custom event", async () => {
+		const event1 = makeEvent("instance.started");
+		mockedUseEventContext.mockReturnValue({
+			events: [event1],
+			connected: false,
+			reconnectCount: 0,
+		});
+		const { rerender } = render(<EventToastBridge />);
+		await flushPromises();
+		expect(mockedHandleEventToast).toHaveBeenCalledTimes(1);
+
+		act(() => {
+			window.dispatchEvent(
+				new CustomEvent("userconfig:updated", {
+					detail: { notification_toast_level: "none" },
+				}),
+			);
+		});
+
+		const event2 = makeEvent("instance.started");
+		mockedUseEventContext.mockReturnValue({
+			events: [event1, event2],
+			connected: false,
+			reconnectCount: 0,
+		});
+		rerender(<EventToastBridge />);
+		await flushPromises();
+		expect(mockedHandleEventToast).toHaveBeenCalledTimes(1);
+	});
+
+	it("muted category overrides all level", async () => {
+		mockedGetUserConfig.mockResolvedValue({
+			notification_toast_level: "all",
+			notification_mute_categories: ["instance"],
+		} as unknown as Awaited<ReturnType<typeof getUserConfig>>);
+		const event = makeEvent("instance.error");
+		mockedUseEventContext.mockReturnValue({
+			events: [event],
+			connected: false,
+			reconnectCount: 0,
+		});
+		render(<EventToastBridge />);
+		await flushPromises();
+		expect(mockedHandleEventToast).not.toHaveBeenCalled();
+	});
+
+	it("deduplication still works with preferences", async () => {
+		const event = makeEvent("instance.started");
+		mockedUseEventContext.mockReturnValue({
+			events: [event, event],
+			connected: false,
+			reconnectCount: 0,
+		});
+		render(<EventToastBridge />);
+		await flushPromises();
+		expect(mockedHandleEventToast).toHaveBeenCalledTimes(1);
+	});
+
+	it("unmapped event defaults to system/info and shows when level is all", async () => {
+		const event = makeEvent("system.announcement");
+		mockedUseEventContext.mockReturnValue({
+			events: [event],
+			connected: false,
+			reconnectCount: 0,
+		});
+		render(<EventToastBridge />);
+		await flushPromises();
+		expect(mockedHandleEventToast).toHaveBeenCalledWith(event);
+	});
+});

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

@@ -0,0 +1,77 @@
+import { useEffect, useRef, useState } from "react";
+import { useEventContext } from "../state/events";
+import {
+	handleEventToast,
+	mapEventToCategory,
+	mapEventToSeverity,
+} from "./toast-rules";
+import { getUserConfig } from "../api/settings";
+import type { UserConfig } from "../api/settings";
+
+interface ToastConfig {
+	notification_toast_level: string;
+	notification_mute_categories: string[];
+}
+
+export function EventToastBridge(): JSX.Element | null {
+	const { events } = useEventContext();
+	const processedRef = useRef<Set<string>>(new Set());
+	const [config, setConfig] = useState<ToastConfig | null>(null);
+
+	useEffect(() => {
+		getUserConfig()
+			.then((c) => {
+				setConfig({
+					notification_toast_level: c.notification_toast_level ?? "all",
+					notification_mute_categories: c.notification_mute_categories ?? [],
+				});
+			})
+			.catch(() => {
+				setConfig({
+					notification_toast_level: "all",
+					notification_mute_categories: [],
+				});
+			});
+
+		const handler = (e: Event) => {
+			const detail = (e as CustomEvent<Partial<UserConfig>>).detail;
+			if (detail) {
+				setConfig((prev) => ({
+					notification_toast_level:
+						detail.notification_toast_level ??
+						prev?.notification_toast_level ??
+						"all",
+					notification_mute_categories:
+						detail.notification_mute_categories ??
+						prev?.notification_mute_categories ??
+						[],
+				}));
+			}
+		};
+
+		window.addEventListener("userconfig:updated", handler);
+		return () => window.removeEventListener("userconfig:updated", handler);
+	}, []);
+
+	useEffect(() => {
+		if (!config) return;
+
+		for (const event of events) {
+			const key = `${event.correlation_id}:${event.timestamp}`;
+			if (processedRef.current.has(key)) continue;
+			processedRef.current.add(key);
+
+			const category = mapEventToCategory(event);
+			const severity = mapEventToSeverity(event);
+
+			if (config.notification_toast_level === "none") continue;
+			if (config.notification_toast_level === "errors" && severity !== "error")
+				continue;
+			if (config.notification_mute_categories.includes(category)) continue;
+
+			handleEventToast(event);
+		}
+	}, [events, config]);
+
+	return null;
+}

apps/web/src/components/git-mount-editor.tsx

@@ -1,5 +1,6 @@
 import { useState, useEffect } from "react";
 import { Icon } from "./icon";
+import { validateGitUrl } from "../api/config_profiles";
 import type { GitMount, GitMountMapping } from "../api/config_profiles";
 
 interface GitMountEditorProps {
@@ -32,7 +33,10 @@ function normalizeMounts(mounts: GitMount[]): GitMount[] {
 	return mounts.map(normalizeMount);
 }
 
-export const GitMountEditor = ({ mounts, onChange }: GitMountEditorProps) => {
+export const GitMountEditor = ({
+	mounts,
+	onChange,
+}: GitMountEditorProps) => {
 	const [normalizedMounts, setNormalizedMounts] = useState<GitMount[]>(() =>
 		normalizeMounts(mounts),
 	);
@@ -204,7 +208,18 @@ interface GitMountFormProps {
 	onCancel: () => void;
 }
 
-const GitMountForm = ({ mount, onSave, onCancel }: GitMountFormProps) => {
+type ValidationState =
+	| { status: "idle" }
+	| { status: "loading" }
+	| { status: "valid"; branches: string[]; defaultBranch: string }
+	| { status: "suggestion"; suggestedUrl: string; message: string }
+	| { status: "invalid"; message: string };
+
+const GitMountForm = ({
+	mount,
+	onSave,
+	onCancel,
+}: GitMountFormProps) => {
 	const [remoteUrl, setRemoteUrl] = useState(mount.remote_url);
 	const [branch, setBranch] = useState(mount.branch || "");
 	const [mappings, setMappings] = useState<GitMountMapping[]>(
@@ -213,6 +228,65 @@ const GitMountForm = ({ mount, onSave, onCancel }: GitMountFormProps) => {
 			: [{ source_path: ".", target_path: "" }],
 	);
 	const [errors, setErrors] = useState<Record<string, string>>({});
+	const [validation, setValidation] = useState<ValidationState>({
+		status: "idle",
+	});
+
+	const isUrlValidated =
+		validation.status === "valid" ||
+		(validation.status === "idle" && mount.remote_url.length > 0);
+
+	const handleCheckUrl = async () => {
+		if (!remoteUrl.trim()) {
+			setErrors((prev) => ({ ...prev, remote_url: "Git URL is required" }));
+			return;
+		}
+		setValidation({ status: "loading" });
+		setErrors((prev) => {
+			const next = { ...prev };
+			delete next.remote_url;
+			return next;
+		});
+		try {
+			const result = await validateGitUrl(remoteUrl.trim());
+			if (result.valid && result.branches) {
+				setValidation({
+					status: "valid",
+					branches: result.branches,
+					defaultBranch: result.default_branch || "main",
+				});
+				if (!branch) {
+					setBranch(result.default_branch || "main");
+				}
+				if (result.suggested_url && result.suggested_url !== remoteUrl.trim()) {
+					setRemoteUrl(result.suggested_url);
+				}
+			} else if (result.suggested_url) {
+				setValidation({
+					status: "suggestion",
+					suggestedUrl: result.suggested_url,
+					message: result.error || "URL needs correction",
+				});
+			} else {
+				setValidation({
+					status: "invalid",
+					message: result.error || "Invalid repository URL",
+				});
+			}
+		} catch {
+			setValidation({
+				status: "invalid",
+				message: "Failed to validate URL. Please try again.",
+			});
+		}
+	};
+
+	const applySuggestion = () => {
+		if (validation.status === "suggestion") {
+			setRemoteUrl(validation.suggestedUrl);
+			setValidation({ status: "idle" });
+		}
+	};
 
 	const validate = (): boolean => {
 		const newErrors: Record<string, string> = {};
@@ -286,46 +360,117 @@ const GitMountForm = ({ mount, onSave, onCancel }: GitMountFormProps) => {
 
 	return (
 		<div style={{ display: "flex", flexDirection: "column", gap: "0.75rem" }}>
-			<div className="form-row" style={{ gap: "0.5rem" }}>
+			<div
+				className="form-row"
+				style={{ gap: "0.5rem", alignItems: "flex-start" }}
+			>
 				<div style={{ flex: 2 }}>
 					<label style={{ fontSize: "0.875rem", fontWeight: 500 }}>
 						Repository URL
 					</label>
-					<input
-						type="text"
-						value={remoteUrl}
-						onChange={(e) => {
-							setRemoteUrl(e.target.value);
-							if (errors.remote_url) {
-								setErrors((prev) => {
-									const next = { ...prev };
-									delete next.remote_url;
-									return next;
-								});
-							}
-						}}
-						placeholder="https://github.com/user/repo.git"
-						className={`form-input ${errors.remote_url ? "error" : ""}`}
-					/>
+					<div style={{ display: "flex", gap: "0.5rem" }}>
+						<input
+							type="text"
+							value={remoteUrl}
+							onChange={(e) => {
+								setRemoteUrl(e.target.value);
+								setValidation({ status: "idle" });
+								if (errors.remote_url) {
+									setErrors((prev) => {
+										const next = { ...prev };
+										delete next.remote_url;
+										return next;
+									});
+								}
+							}}
+							placeholder="https://github.com/user/repo.git"
+							className={`form-input ${errors.remote_url ? "error" : ""}`}
+							style={{ flex: 1 }}
+						/>
+						<button
+							type="button"
+							className="secondary-button small"
+							onClick={handleCheckUrl}
+							disabled={validation.status === "loading"}
+						>
+							{validation.status === "loading" ? (
+								<Icon name="loading" size="sm" />
+							) : (
+								"Check"
+							)}
+						</button>
+					</div>
 					{errors.remote_url && (
 						<span className="error-text">{errors.remote_url}</span>
 					)}
+					{validation.status === "valid" && (
+						<span className="validation-status valid">
+							Repository is accessible (
+							{
+								(validation as Extract<ValidationState, { status: "valid" }>)
+									.branches.length
+							}{" "}
+							branches)
+						</span>
+					)}
+					{validation.status === "suggestion" && (
+						<div className="url-suggestion">
+							<span>{validation.message}</span>
+							<div className="suggestion-actions">
+								<code className="suggested-url">{validation.suggestedUrl}</code>
+								<button
+									type="button"
+									className="secondary-button small"
+									onClick={applySuggestion}
+								>
+									Use this
+								</button>
+							</div>
+						</div>
+					)}
+					{validation.status === "invalid" && (
+						<span className="validation-status invalid">
+							{validation.message}
+						</span>
+					)}
 				</div>
 				<div style={{ flex: 1 }}>
 					<label style={{ fontSize: "0.875rem", fontWeight: 500 }}>
-						Branch (optional)
+						Branch
 					</label>
-					<input
-						type="text"
-						value={branch}
-						onChange={(e) => setBranch(e.target.value)}
-						placeholder="main"
-						className="form-input"
-					/>
+					{validation.status === "valid" ? (
+						<select
+							value={branch}
+							onChange={(e) => setBranch(e.target.value)}
+							className="form-input"
+						>
+							{(
+								validation as Extract<ValidationState, { status: "valid" }>
+							).branches.map((b) => (
+								<option key={b} value={b}>
+									{b}
+								</option>
+							))}
+						</select>
+					) : (
+						<input
+							type="text"
+							value={branch}
+							onChange={(e) => setBranch(e.target.value)}
+							placeholder="main"
+							className="form-input"
+							disabled={!isUrlValidated}
+						/>
+					)}
 				</div>
 			</div>
 
-			<div>
+			<div
+				style={{
+					opacity: isUrlValidated ? 1 : 0.5,
+					pointerEvents: isUrlValidated ? "auto" : "none",
+				}}
+			>
 				<label style={{ fontSize: "0.875rem", fontWeight: 500 }}>
 					Mappings
 				</label>
@@ -334,6 +479,12 @@ const GitMountForm = ({ mount, onSave, onCancel }: GitMountFormProps) => {
 					style={{ margin: "0 0 0.5rem 0", fontSize: "0.8125rem" }}
 				>
 					Source paths within the repo and where to mount them in the container.
+					{!isUrlValidated && (
+						<span style={{ color: "var(--warning)" }}>
+							{" "}
+							Validate the URL first.
+						</span>
+					)}
 				</p>
 				<div
 					style={{ display: "flex", flexDirection: "column", gap: "0.5rem" }}

apps/web/src/components/icon.tsx

@@ -1,167 +1,176 @@
 import React from "react";
 import {
-  House,
-  Folder,
-  GitBranch,
-  Gear,
-  User,
-  SignOut,
-  Plus,
-  PencilSimple,
-  Trash,
-  FloppyDisk,
-  X,
-  ArrowsClockwise,
-  Copy,
-  MagnifyingGlass,
-  List,
-  Check,
-  Warning,
-  Info,
-  Spinner,
-  GitCommit,
-  GitMerge,
-  ClockCounterClockwise,
-  ArrowDown,
-  ArrowUp,
-  File,
-  FileText,
-  Image,
-  Binary,
-  Code,
-  ArrowSquareOut,
-  Play,
-  Stop,
-  Terminal,
-  ArrowLeft,
-  DotsSixVertical,
+	House,
+	Folder,
+	GitBranch,
+	Gear,
+	User,
+	SignOut,
+	Plus,
+	PencilSimple,
+	Trash,
+	FloppyDisk,
+	X,
+	ArrowsClockwise,
+	Copy,
+	MagnifyingGlass,
+	List,
+	Check,
+	Warning,
+	Info,
+	Spinner,
+	GitCommit,
+	GitMerge,
+	ClockCounterClockwise,
+	ArrowDown,
+	ArrowUp,
+	File,
+	FileText,
+	Image,
+	Binary,
+	Code,
+	ArrowSquareOut,
+	Play,
+	Stop,
+	Terminal,
+	ArrowLeft,
+	DotsSixVertical,
+	Bell,
 } from "@phosphor-icons/react";
 
 export type IconName =
-  | "dashboard"
-  | "projects"
-  | "repositories"
-  | "settings"
-  | "profile"
-  | "logout"
-  | "add"
-  | "edit"
-  | "delete"
-  | "save"
-  | "cancel"
-  | "refresh"
-  | "copy"
-  | "search"
-  | "menu"
-  | "close"
-  | "success"
-  | "error"
-  | "warning"
-  | "info"
-  | "loading"
-  | "branch"
-  | "commit"
-  | "merge"
-  | "history"
-  | "pull"
-  | "push"
-  | "fetch"
-  | "file"
-  | "folder"
-  | "code"
-  | "document"
-  | "image"
-  | "binary"
-  | "external"
-  | "play"
-  | "stop"
-  | "terminal"
-  | "arrow-left"
-  | "drag";
+	| "dashboard"
+	| "projects"
+	| "repositories"
+	| "settings"
+	| "profile"
+	| "logout"
+	| "add"
+	| "edit"
+	| "delete"
+	| "save"
+	| "cancel"
+	| "refresh"
+	| "copy"
+	| "search"
+	| "menu"
+	| "close"
+	| "success"
+	| "error"
+	| "warning"
+	| "info"
+	| "loading"
+	| "branch"
+	| "commit"
+	| "merge"
+	| "history"
+	| "pull"
+	| "push"
+	| "fetch"
+	| "file"
+	| "folder"
+	| "code"
+	| "document"
+	| "image"
+	| "binary"
+	| "external"
+	| "play"
+	| "stop"
+	| "terminal"
+	| "arrow-left"
+	| "drag"
+	| "bell";
 
-const iconMap: Record<IconName, React.ComponentType<{ size?: number | string; weight?: "thin" | "light" | "regular" | "bold" | "fill" | "duotone" }>> = {
-  dashboard: House,
-  projects: Folder,
-  repositories: GitBranch,
-  settings: Gear,
-  profile: User,
-  logout: SignOut,
-  add: Plus,
-  edit: PencilSimple,
-  delete: Trash,
-  save: FloppyDisk,
-  cancel: X,
-  refresh: ArrowsClockwise,
-  copy: Copy,
-  search: MagnifyingGlass,
-  menu: List,
-  close: X,
-  success: Check,
-  error: X,
-  warning: Warning,
-  info: Info,
-  loading: Spinner,
-  branch: GitBranch,
-  commit: GitCommit,
-  merge: GitMerge,
-  history: ClockCounterClockwise,
-  pull: ArrowDown,
-  push: ArrowUp,
-  fetch: ArrowsClockwise,
-  file: File,
-  folder: Folder,
-  code: Code,
-  document: FileText,
-  image: Image,
-  binary: Binary,
-  external: ArrowSquareOut,
-  play: Play,
-  stop: Stop,
-  terminal: Terminal,
-  "arrow-left": ArrowLeft,
-  drag: DotsSixVertical,
+const iconMap: Record<
+	IconName,
+	React.ComponentType<{
+		size?: number | string;
+		weight?: "thin" | "light" | "regular" | "bold" | "fill" | "duotone";
+	}>
+> = {
+	dashboard: House,
+	projects: Folder,
+	repositories: GitBranch,
+	settings: Gear,
+	profile: User,
+	logout: SignOut,
+	add: Plus,
+	edit: PencilSimple,
+	delete: Trash,
+	save: FloppyDisk,
+	cancel: X,
+	refresh: ArrowsClockwise,
+	copy: Copy,
+	search: MagnifyingGlass,
+	menu: List,
+	close: X,
+	success: Check,
+	error: X,
+	warning: Warning,
+	info: Info,
+	loading: Spinner,
+	branch: GitBranch,
+	commit: GitCommit,
+	merge: GitMerge,
+	history: ClockCounterClockwise,
+	pull: ArrowDown,
+	push: ArrowUp,
+	fetch: ArrowsClockwise,
+	file: File,
+	folder: Folder,
+	code: Code,
+	document: FileText,
+	image: Image,
+	binary: Binary,
+	external: ArrowSquareOut,
+	play: Play,
+	stop: Stop,
+	terminal: Terminal,
+	"arrow-left": ArrowLeft,
+	drag: DotsSixVertical,
+	bell: Bell,
 };
 
 export interface IconProps {
-  name: IconName;
-  size?: "sm" | "md" | "lg" | "xl";
-  color?: string;
-  weight?: "thin" | "light" | "regular" | "bold" | "fill" | "duotone";
-  className?: string;
-  ariaLabel?: string;
+	name: IconName;
+	size?: "sm" | "md" | "lg" | "xl";
+	color?: string;
+	weight?: "thin" | "light" | "regular" | "bold" | "fill" | "duotone";
+	className?: string;
+	ariaLabel?: string;
 }
 
 const sizeMap: Record<NonNullable<IconProps["size"]>, number> = {
-  sm: 16,
-  md: 20,
-  lg: 24,
-  xl: 32,
+	sm: 16,
+	md: 20,
+	lg: 24,
+	xl: 32,
 };
 
 export const Icon: React.FC<IconProps> = ({
-  name,
-  size = "md",
-  color,
-  weight = "regular",
-  className,
-  ariaLabel,
+	name,
+	size = "md",
+	color,
+	weight = "regular",
+	className,
+	ariaLabel,
 }) => {
-  const IconComponent = iconMap[name];
-  const sizeValue = sizeMap[size];
+	const IconComponent = iconMap[name];
+	const sizeValue = sizeMap[size];
 
-  if (!IconComponent) {
-    return null;
-  }
+	if (!IconComponent) {
+		return null;
+	}
 
-  return (
-    <span
-      className={`icon icon-${size}${className ? ` ${className}` : ""}`}
-      style={{ color }}
-      aria-label={ariaLabel}
-      aria-hidden={!ariaLabel}
-      role="img"
-    >
-      <IconComponent size={sizeValue} weight={weight} />
-    </span>
-  );
+	return (
+		<span
+			className={`icon icon-${size}${className ? ` ${className}` : ""}`}
+			style={{ color }}
+			aria-label={ariaLabel}
+			aria-hidden={!ariaLabel}
+			role="img"
+		>
+			<IconComponent size={sizeValue} weight={weight} />
+		</span>
+	);
 };

apps/web/src/components/notification-center.test.tsx

@@ -0,0 +1,177 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, fireEvent, cleanup } from "@testing-library/react";
+import { NotificationCenter } from "./notification-center";
+import { NotificationProvider } from "../state/notifications";
+
+vi.mock("../api/notifications", () => ({
+	getNotifications: vi.fn(),
+	getUnreadCount: vi.fn(),
+	markNotificationRead: vi.fn(),
+	markAllNotificationsRead: vi.fn(),
+	dismissNotification: vi.fn(),
+	clearAllNotifications: vi.fn(),
+}));
+
+import { getNotifications, getUnreadCount } from "../api/notifications";
+
+const mockedGetNotifications = vi.mocked(getNotifications);
+const mockedGetUnreadCount = vi.mocked(getUnreadCount);
+
+const makeNotification = (id: string, overrides?: Record<string, unknown>) => ({
+	id,
+	user_id: "user-1",
+	category: "instance",
+	severity: "info" as const,
+	title: `Notification ${id}`,
+	message: null,
+	source_type: null,
+	source_id: null,
+	metadata: {},
+	read_at: null,
+	dismissed_at: null,
+	created_at: "2026-05-29T10:00:00Z",
+	...overrides,
+});
+
+function wrapper({ children }: { children: React.ReactNode }) {
+	return <NotificationProvider>{children}</NotificationProvider>;
+}
+
+describe("NotificationCenter", () => {
+	beforeEach(() => {
+		vi.useFakeTimers({ shouldAdvanceTime: true });
+		mockedGetNotifications.mockResolvedValue({
+			items: [],
+			total: 0,
+			limit: 20,
+			offset: 0,
+		});
+		mockedGetUnreadCount.mockResolvedValue(0);
+	});
+
+	afterEach(() => {
+		vi.useRealTimers();
+		vi.clearAllMocks();
+		cleanup();
+	});
+
+	it("renders bell icon", () => {
+		render(<NotificationCenter />, { wrapper });
+		expect(
+			screen.getByRole("button", { name: /notifications/i }),
+		).toBeInTheDocument();
+	});
+
+	it("shows badge when unread count > 0", async () => {
+		mockedGetUnreadCount.mockResolvedValue(3);
+		render(<NotificationCenter />, { wrapper });
+
+		await vi.advanceTimersByTimeAsync(100);
+		expect(screen.getByText("3")).toBeInTheDocument();
+	});
+
+	it("hides badge when unread count is 0", () => {
+		render(<NotificationCenter />, { wrapper });
+		expect(screen.queryByText("0")).not.toBeInTheDocument();
+	});
+
+	it("opens dropdown on bell click", () => {
+		render(<NotificationCenter />, { wrapper });
+		fireEvent.click(screen.getByRole("button", { name: /notifications/i }));
+		expect(screen.getByRole("dialog")).toBeInTheDocument();
+	});
+
+	it("closes dropdown on outside click", () => {
+		render(
+			<div>
+				<div data-testid="outside">Outside</div>
+				<NotificationCenter />
+			</div>,
+			{ wrapper },
+		);
+		fireEvent.click(screen.getByRole("button", { name: /notifications/i }));
+		expect(screen.getByRole("dialog")).toBeInTheDocument();
+
+		fireEvent.mouseDown(screen.getByTestId("outside"));
+		expect(screen.queryByRole("dialog")).not.toBeInTheDocument();
+	});
+
+	it("closes dropdown on escape", () => {
+		render(<NotificationCenter />, { wrapper });
+		fireEvent.click(screen.getByRole("button", { name: /notifications/i }));
+		expect(screen.getByRole("dialog")).toBeInTheDocument();
+
+		fireEvent.keyDown(document, { key: "Escape" });
+		expect(screen.queryByRole("dialog")).not.toBeInTheDocument();
+	});
+
+	it("renders empty state when no notifications", () => {
+		render(<NotificationCenter />, { wrapper });
+		fireEvent.click(screen.getByRole("button", { name: /notifications/i }));
+		expect(screen.getByText("No notifications")).toBeInTheDocument();
+	});
+
+	it("renders notification items", async () => {
+		mockedGetNotifications.mockResolvedValue({
+			items: [makeNotification("1"), makeNotification("2")],
+			total: 2,
+			limit: 20,
+			offset: 0,
+		});
+
+		render(<NotificationCenter />, { wrapper });
+		fireEvent.click(screen.getByRole("button", { name: /notifications/i }));
+
+		await vi.advanceTimersByTimeAsync(100);
+		expect(screen.getByText("Notification 1")).toBeInTheDocument();
+		expect(screen.getByText("Notification 2")).toBeInTheDocument();
+	});
+
+	it("calls markAllRead on footer button click", async () => {
+		mockedGetNotifications.mockResolvedValue({
+			items: [makeNotification("1")],
+			total: 1,
+			limit: 20,
+			offset: 0,
+		});
+
+		render(<NotificationCenter />, { wrapper });
+		fireEvent.click(screen.getByRole("button", { name: /notifications/i }));
+
+		await vi.advanceTimersByTimeAsync(100);
+		fireEvent.click(screen.getByRole("button", { name: /mark all as read/i }));
+
+		const { markAllNotificationsRead: mockMarkAll } = await import(
+			"../api/notifications"
+		);
+		expect(vi.mocked(mockMarkAll)).toHaveBeenCalled();
+	});
+
+	it("calls clearAll on clear-all button click", async () => {
+		mockedGetNotifications.mockResolvedValue({
+			items: [makeNotification("1")],
+			total: 1,
+			limit: 20,
+			offset: 0,
+		});
+
+		render(<NotificationCenter />, { wrapper });
+		fireEvent.click(screen.getByRole("button", { name: /notifications/i }));
+
+		await vi.advanceTimersByTimeAsync(100);
+		fireEvent.click(screen.getByRole("button", { name: /clear all/i }));
+
+		const { clearAllNotifications: mockClearAll } = await import(
+			"../api/notifications"
+		);
+		expect(vi.mocked(mockClearAll)).toHaveBeenCalled();
+	});
+
+	it("refreshes list immediately on open", async () => {
+		render(<NotificationCenter />, { wrapper });
+		fireEvent.click(screen.getByRole("button", { name: /notifications/i }));
+
+		await vi.advanceTimersByTimeAsync(100);
+		expect(mockedGetNotifications).toHaveBeenCalled();
+	});
+});

apps/web/src/components/notification-center.tsx

@@ -0,0 +1,134 @@
+import { useEffect, useRef } from "react";
+import { useNotifications } from "../hooks/use-notifications";
+import { NotificationItem } from "./notification-item";
+import { Icon } from "./icon";
+
+interface NotificationCenterProps {
+	isMobileTerminal?: boolean;
+}
+
+export function NotificationCenter({
+	isMobileTerminal = false,
+}: NotificationCenterProps) {
+	const {
+		notifications,
+		unreadCount,
+		markRead,
+		markAllRead,
+		clearAll,
+		dismiss,
+		refreshList,
+		isDropdownOpen,
+		setIsDropdownOpen,
+	} = useNotifications();
+
+	const dropdownRef = useRef<HTMLDivElement>(null);
+
+	useEffect(() => {
+		if (!isDropdownOpen) return;
+
+		const handleMouseDown = (e: MouseEvent) => {
+			if (
+				dropdownRef.current &&
+				!dropdownRef.current.contains(e.target as Node)
+			) {
+				setIsDropdownOpen(false);
+			}
+		};
+
+		const handleKeyDown = (e: KeyboardEvent) => {
+			if (e.key === "Escape") {
+				setIsDropdownOpen(false);
+			}
+		};
+
+		document.addEventListener("mousedown", handleMouseDown);
+		document.addEventListener("keydown", handleKeyDown);
+
+		return () => {
+			document.removeEventListener("mousedown", handleMouseDown);
+			document.removeEventListener("keydown", handleKeyDown);
+		};
+	}, [isDropdownOpen, setIsDropdownOpen]);
+
+	useEffect(() => {
+		if (isDropdownOpen) {
+			void refreshList();
+		}
+	}, [isDropdownOpen, refreshList]);
+
+	if (isMobileTerminal) {
+		return null;
+	}
+
+	const badgeText = unreadCount > 99 ? "99+" : String(unreadCount);
+
+	return (
+		<div className="notification-center">
+			<button
+				type="button"
+				className="notification-bell"
+				onClick={() => setIsDropdownOpen(!isDropdownOpen)}
+				aria-label="Notifications"
+				aria-haspopup="dialog"
+				aria-expanded={isDropdownOpen}
+			>
+				<Icon name="bell" size="md" />
+				{unreadCount > 0 && (
+					<span className="nav-badge notification-badge">{badgeText}</span>
+				)}
+			</button>
+
+			{isDropdownOpen && (
+				<div
+					ref={dropdownRef}
+					role="dialog"
+					aria-label="Notifications"
+					className="notification-dropdown"
+				>
+					<div className="notification-dropdown-header">
+						<span>Notifications</span>
+					</div>
+
+					<ul className="notification-list">
+						{notifications.length === 0 ? (
+							<li className="notification-empty">No notifications</li>
+						) : (
+							notifications.map((n) => (
+								<NotificationItem
+									key={n.id}
+									notification={n}
+									onMarkRead={markRead}
+									onDismiss={dismiss}
+								/>
+							))
+						)}
+					</ul>
+
+					{notifications.length > 0 && (
+						<div className="notification-dropdown-footer">
+							<button
+								type="button"
+								className="notification-mark-all"
+								onClick={() => {
+									void markAllRead();
+								}}
+							>
+								Mark all as read
+							</button>
+							<button
+								type="button"
+								className="notification-clear-all"
+								onClick={() => {
+									void clearAll();
+								}}
+							>
+								Clear all
+							</button>
+						</div>
+					)}
+				</div>
+			)}
+		</div>
+	);
+}

apps/web/src/components/notification-item.test.tsx

@@ -0,0 +1,104 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, screen, fireEvent, cleanup } from "@testing-library/react";
+import { NotificationItem } from "./notification-item";
+
+afterEach(() => {
+	cleanup();
+});
+
+const makeNotification = (overrides?: Record<string, unknown>) => ({
+	id: "1",
+	user_id: "user-1",
+	category: "instance",
+	severity: "info" as const,
+	title: "Container started",
+	message: null,
+	source_type: null,
+	source_id: null,
+	metadata: {},
+	read_at: null,
+	dismissed_at: null,
+	created_at: "2026-05-29T10:00:00Z",
+	...overrides,
+});
+
+describe("NotificationItem", () => {
+	it("displays title and relative time", () => {
+		render(
+			<NotificationItem
+				notification={makeNotification()}
+				onMarkRead={vi.fn()}
+				onDismiss={vi.fn()}
+			/>,
+		);
+
+		expect(screen.getByText("Container started")).toBeInTheDocument();
+		expect(screen.getByText(/ago|just now/)).toBeInTheDocument();
+	});
+
+	it("applies unread styling when read_at is null", () => {
+		render(
+			<NotificationItem
+				notification={makeNotification({ read_at: null })}
+				onMarkRead={vi.fn()}
+				onDismiss={vi.fn()}
+			/>,
+		);
+
+		const row = screen.getByRole("listitem");
+		expect(row.className).toContain("notification-item--unread");
+	});
+
+	it("applies read styling when read_at is set", () => {
+		render(
+			<NotificationItem
+				notification={makeNotification({ read_at: "2026-05-29T10:01:00Z" })}
+				onMarkRead={vi.fn()}
+				onDismiss={vi.fn()}
+			/>,
+		);
+
+		const row = screen.getByRole("listitem");
+		expect(row.className).toContain("notification-item--read");
+	});
+
+	it("calls onMarkRead when mark read clicked", () => {
+		const onMarkRead = vi.fn();
+		render(
+			<NotificationItem
+				notification={makeNotification()}
+				onMarkRead={onMarkRead}
+				onDismiss={vi.fn()}
+			/>,
+		);
+
+		fireEvent.click(screen.getByRole("button", { name: /mark read/i }));
+		expect(onMarkRead).toHaveBeenCalledWith("1");
+	});
+
+	it("calls onDismiss when dismiss clicked", () => {
+		const onDismiss = vi.fn();
+		render(
+			<NotificationItem
+				notification={makeNotification()}
+				onMarkRead={vi.fn()}
+				onDismiss={onDismiss}
+			/>,
+		);
+
+		fireEvent.click(screen.getByRole("button", { name: /dismiss/i }));
+		expect(onDismiss).toHaveBeenCalledWith("1");
+	});
+
+	it("displays severity icon", () => {
+		render(
+			<NotificationItem
+				notification={makeNotification({ severity: "error" })}
+				onMarkRead={vi.fn()}
+				onDismiss={vi.fn()}
+			/>,
+		);
+
+		expect(screen.getByRole("img", { hidden: true })).toBeInTheDocument();
+	});
+});

apps/web/src/components/notification-item.tsx

@@ -0,0 +1,64 @@
+import { Icon } from "./icon";
+import { formatRelativeTime } from "../utils/time";
+import type { NotificationItem as NotificationItemType } from "../api/notifications";
+
+export interface NotificationItemProps {
+	notification: NotificationItemType;
+	onMarkRead: (id: string) => void;
+	onDismiss: (id: string) => void;
+}
+
+import type { IconName } from "../utils/icons";
+
+const severityIconMap: Record<string, IconName> = {
+	info: "info",
+	warning: "warning",
+	error: "error",
+	success: "success",
+};
+
+export function NotificationItem({
+	notification,
+	onMarkRead,
+	onDismiss,
+}: NotificationItemProps) {
+	const isUnread = notification.read_at === null;
+	const iconName = severityIconMap[notification.severity] ?? "info";
+
+	return (
+		<li
+			role="listitem"
+			className={`notification-item ${isUnread ? "notification-item--unread" : "notification-item--read"}`}
+		>
+			<div className="notification-item-icon">
+				<Icon name={iconName} size="md" />
+			</div>
+			<div className="notification-item-content">
+				<div className="notification-item-title">{notification.title}</div>
+				<div className="notification-item-time">
+					{formatRelativeTime(notification.created_at)}
+				</div>
+			</div>
+			<div className="notification-item-actions">
+				{isUnread && (
+					<button
+						type="button"
+						className="notification-item-action"
+						onClick={() => onMarkRead(notification.id)}
+						aria-label="Mark read"
+					>
+						Mark read
+					</button>
+				)}
+				<button
+					type="button"
+					className="notification-item-action"
+					onClick={() => onDismiss(notification.id)}
+					aria-label="Dismiss"
+				>
+					Dismiss
+				</button>
+			</div>
+		</li>
+	);
+}

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/terminal.tsx

@@ -20,6 +20,7 @@ export interface TerminalProps {
 	sessionId?: string;
 	onClose?: () => void;
 	isMobile?: boolean;
+	showControls?: boolean;
 	activeModifier?: ModifierKey | null;
 	onModifierChange?: (modifier: ModifierKey | null) => void;
 	onTerminalReady?: (
@@ -38,6 +39,7 @@ export interface TerminalProps {
 export interface TerminalRef {
 	fit: () => void;
 	focus: () => void;
+	reset: () => void;
 }
 
 const FONT_SIZE_KEY = "terminal-font-size";
@@ -53,6 +55,7 @@ export const TerminalComponent = React.forwardRef<TerminalRef, TerminalProps>(
 			sessionId,
 			onClose,
 			isMobile = false,
+			showControls = true,
 			activeModifier,
 			onModifierChange,
 			onTerminalReady,
@@ -310,6 +313,96 @@ export const TerminalComponent = React.forwardRef<TerminalRef, TerminalProps>(
 			term.focus();
 			const ws = connectWebSocket();
 
+			// Mobile touch scroll.
+			// In normal mode xterm.js has a scrollable viewport; in alternate
+			// screen (tmux/vim) there is no scrollback and the only way to
+			// scroll is to send mouse-wheel protocol sequences to the
+			// application.  We detect which situation we're in by checking
+			// whether the viewport has scrollable height.
+			let touchCleanup: (() => void) | undefined;
+			if (isMobile) {
+				let startY = 0;
+				let startX = 0;
+				let isScrolling = false;
+
+				const onTouchStart = (e: TouchEvent) => {
+					if (e.touches.length === 1) {
+						startY = e.touches[0].clientY;
+						startX = e.touches[0].clientX;
+						isScrolling = false;
+					}
+				};
+				const onTouchMove = (e: TouchEvent) => {
+					if (e.touches.length !== 1) return;
+					const touch = e.touches[0];
+					const deltaY = startY - touch.clientY;
+					const deltaX = Math.abs(startX - touch.clientX);
+					if (!isScrolling) {
+						if (Math.abs(deltaY) > deltaX && Math.abs(deltaY) > 4) {
+							isScrolling = true;
+						}
+					}
+					if (isScrolling) {
+						e.preventDefault();
+						const viewport = container.querySelector(
+							".xterm-viewport",
+						) as HTMLElement | null;
+						if (!viewport) return;
+
+						// If the viewport is scrollable, scroll it directly.
+						// Otherwise we are in alternate screen (tmux/vim) and must
+						// send SGR 1006 mouse-wheel protocol data.
+						const hasScrollback =
+							viewport.scrollHeight > viewport.clientHeight;
+						if (hasScrollback) {
+							viewport.scrollTop += deltaY;
+						} else {
+							const ws = wsRef.current;
+							if (
+								ws?.readyState === WebSocket.OPEN &&
+								termRef.current
+							) {
+								// Use the cursor position as the wheel location so
+								// tmux knows which pane to scroll.
+								const buf = termRef.current.buffer.active;
+								const col = buf.cursorX + 1;
+								const row = buf.cursorY + 1;
+								// SGR 1006: 64 = wheel-up, 65 = wheel-down
+								const btn = deltaY > 0 ? 64 : 65;
+								ws.send(`\x1b[<${btn};${col};${row}M`);
+							}
+						}
+						startY = touch.clientY;
+					}
+				};
+				const onTouchEnd = () => {
+					isScrolling = false;
+				};
+
+				container.addEventListener("touchstart", onTouchStart, {
+					passive: true,
+					capture: true,
+				});
+				container.addEventListener("touchmove", onTouchMove, {
+					passive: false,
+					capture: true,
+				});
+				container.addEventListener("touchend", onTouchEnd, {
+					capture: true,
+				});
+				touchCleanup = () => {
+					container.removeEventListener("touchstart", onTouchStart, {
+						capture: true,
+					});
+					container.removeEventListener("touchmove", onTouchMove, {
+						capture: true,
+					});
+					container.removeEventListener("touchend", onTouchEnd, {
+						capture: true,
+					});
+				};
+			}
+
 			// Initial fit after layout settles (terminal must be opened first)
 			let fitAttempts = 0;
 			const doInitialFit = () => {
@@ -437,6 +530,7 @@ export const TerminalComponent = React.forwardRef<TerminalRef, TerminalProps>(
 					"visibilitychange",
 					handleVisibilityChange,
 				);
+				if (touchCleanup) touchCleanup();
 				if (ws) {
 					ws.close(1000, "Component unmounting");
 				}
@@ -471,6 +565,11 @@ export const TerminalComponent = React.forwardRef<TerminalRef, TerminalProps>(
 			focus: () => {
 				termRef.current?.focus();
 			},
+			reset: () => {
+				if (wsRef.current?.readyState === WebSocket.OPEN) {
+					wsRef.current.send(JSON.stringify({ type: "reset" }));
+				}
+			},
 		}));
 
 		// Update parent about status changes
@@ -560,79 +659,83 @@ export const TerminalComponent = React.forwardRef<TerminalRef, TerminalProps>(
 		};
 
 		return (
-			<div className={`terminal-wrapper ${isMobile ? "mobile" : ""}`}>
-				<div className="terminal-header">
-					<div className="terminal-header-left">
-						<div className="terminal-status">
-							<span
-								className={`status-dot ${status}`}
-								aria-label={`Terminal status: ${status}`}
-							/>
-							<span className="status-text">
-								{status === "resetting"
-									? "Resetting..."
-									: reconnectAttemptsRef.current > 0 && status !== "connected"
-										? `Reconnecting (${reconnectAttemptsRef.current}/${RECONNECT_ATTEMPTS})...`
-										: status}
-							</span>
+			<div
+				className={`terminal-wrapper ${isMobile ? "mobile" : ""} ${!showControls ? "no-controls" : ""}`}
+			>
+				{showControls && (
+					<div className="terminal-header">
+						<div className="terminal-header-left">
+							<div className="terminal-status">
+								<span
+									className={`status-dot ${status}`}
+									aria-label={`Terminal status: ${status}`}
+								/>
+								<span className="status-text">
+									{status === "resetting"
+										? "Resetting..."
+										: reconnectAttemptsRef.current > 0 && status !== "connected"
+											? `Reconnecting (${reconnectAttemptsRef.current}/${RECONNECT_ATTEMPTS})...`
+											: status}
+								</span>
+							</div>
+							{isMobile && (
+								<>
+									<button
+										className="terminal-header-button"
+										onClick={handleCopy}
+										type="button"
+										aria-label="Copy selection"
+									>
+										Copy
+									</button>
+									<button
+										className="terminal-header-button"
+										onClick={handlePaste}
+										type="button"
+										aria-label="Paste from clipboard"
+									>
+										Paste
+									</button>
+								</>
+							)}
 						</div>
-						{isMobile && (
-							<>
-								<button
-									className="terminal-header-button"
-									onClick={handleCopy}
-									type="button"
-									aria-label="Copy selection"
-								>
-									Copy
-								</button>
-								<button
-									className="terminal-header-button"
-									onClick={handlePaste}
-									type="button"
-									aria-label="Paste from clipboard"
-								>
-									Paste
-								</button>
-							</>
-						)}
-					</div>
-					<div className="terminal-header-right">
-						<button
-							className="terminal-header-button"
-							onClick={() => handleFontSizeChange(-1)}
-							type="button"
-							aria-label="Decrease font size"
-						>
-							A-
-						</button>
-						<button
-							className="terminal-header-button"
-							onClick={() => handleFontSizeChange(1)}
-							type="button"
-							aria-label="Increase font size"
-						>
-							A+
-						</button>
-						<button
-							className="terminal-header-button"
-							onClick={() => setShowResetConfirm(true)}
-							type="button"
-							aria-label="Reset terminal"
-						>
-							Reset
-						</button>
-						{onClose && (
+						<div className="terminal-header-right">
 							<button
-								className="terminal-close"
-								onClick={onClose}
+								className="terminal-header-button"
+								onClick={() => handleFontSizeChange(-1)}
 								type="button"
+								aria-label="Decrease font size"
 							>
-								Close
+								A-
 							</button>
-						)}
+							<button
+								className="terminal-header-button"
+								onClick={() => handleFontSizeChange(1)}
+								type="button"
+								aria-label="Increase font size"
+							>
+								A+
+							</button>
+							<button
+								className="terminal-header-button"
+								onClick={() => setShowResetConfirm(true)}
+								type="button"
+								aria-label="Reset terminal"
+							>
+								Reset
+							</button>
+							{onClose && (
+								<button
+									className="terminal-close"
+									onClick={onClose}
+									type="button"
+								>
+									Close
+								</button>
+							)}
+						</div>
 					</div>
-				</div>
+				)}
 				{showResetConfirm && (
 					<div className="terminal-reset-confirm">
 						<div className="terminal-reset-confirm-content">

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

@@ -0,0 +1,69 @@
+import { describe, it, expect } from "vitest";
+import { mapEventToCategory, mapEventToSeverity } from "./toast-rules";
+import type { InstanceEventPayload } from "../types/events";
+
+function makeEvent(
+	event: string,
+	overrides?: Partial<InstanceEventPayload>,
+): InstanceEventPayload {
+	return {
+		event,
+		instance_id: "i-1",
+		status: undefined,
+		message: undefined,
+		metadata: {},
+		timestamp: "2026-05-29T10:00:00Z",
+		correlation_id: "c1",
+		...overrides,
+	};
+}
+
+describe("mapEventToCategory", () => {
+	it('returns "instance" for instance.* events', () => {
+		expect(mapEventToCategory(makeEvent("instance.started"))).toBe("instance");
+		expect(mapEventToCategory(makeEvent("instance.error"))).toBe("instance");
+	});
+
+	it('returns "health" for health.* events', () => {
+		expect(mapEventToCategory(makeEvent("health.error"))).toBe("health");
+	});
+
+	it('returns "system" for unknown events', () => {
+		expect(mapEventToCategory(makeEvent("system.announcement"))).toBe("system");
+	});
+});
+
+describe("mapEventToSeverity", () => {
+	it("returns error for instance.error and health.error", () => {
+		expect(mapEventToSeverity(makeEvent("instance.error"))).toBe("error");
+		expect(mapEventToSeverity(makeEvent("health.error"))).toBe("error");
+	});
+
+	it("returns warning for unhealthy health changes", () => {
+		expect(
+			mapEventToSeverity(
+				makeEvent("instance.health_changed", { status: "unhealthy" }),
+			),
+		).toBe("warning");
+	});
+
+	it("returns success for recovery to running", () => {
+		expect(
+			mapEventToSeverity(
+				makeEvent("instance.health_changed", { status: "running" }),
+			),
+		).toBe("success");
+	});
+
+	it("returns info for lifecycle events", () => {
+		expect(mapEventToSeverity(makeEvent("instance.created"))).toBe("info");
+		expect(mapEventToSeverity(makeEvent("instance.started"))).toBe("info");
+		expect(mapEventToSeverity(makeEvent("instance.stopped"))).toBe("info");
+		expect(mapEventToSeverity(makeEvent("instance.restarted"))).toBe("info");
+		expect(mapEventToSeverity(makeEvent("instance.deleted"))).toBe("info");
+	});
+
+	it("returns info for unmapped events", () => {
+		expect(mapEventToSeverity(makeEvent("unknown.event"))).toBe("info");
+	});
+});

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

@@ -0,0 +1,83 @@
+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 mapEventToCategory(event: InstanceEventPayload): string {
+	if (event.event.startsWith("instance.")) return "instance";
+	if (event.event.startsWith("health.")) return "health";
+	return "system";
+}
+
+export function mapEventToSeverity(
+	event: InstanceEventPayload,
+): "info" | "warning" | "error" | "success" {
+	switch (event.event) {
+		case "instance.error":
+		case "health.error":
+			return "error";
+		case "instance.health_changed":
+			return event.status === "unhealthy" ? "warning" : "success";
+		case "instance.created":
+		case "instance.started":
+		case "instance.stopped":
+		case "instance.restarted":
+		case "instance.deleted":
+			return "info";
+		default:
+			return "info";
+	}
+}
+
+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/hooks/use-notifications.test.tsx

@@ -0,0 +1,337 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, waitFor, act } from "@testing-library/react";
+import { useNotifications } from "./use-notifications";
+import { NotificationProvider } from "../state/notifications";
+
+vi.mock("../api/notifications", () => ({
+	getNotifications: vi.fn(),
+	getUnreadCount: vi.fn(),
+	markNotificationRead: vi.fn(),
+	markAllNotificationsRead: vi.fn(),
+	dismissNotification: vi.fn(),
+}));
+
+import {
+	getNotifications,
+	getUnreadCount,
+	markNotificationRead,
+	markAllNotificationsRead,
+	dismissNotification,
+} from "../api/notifications";
+import type { NotificationItem } from "../api/notifications";
+
+const mockedGetNotifications = vi.mocked(getNotifications);
+const mockedGetUnreadCount = vi.mocked(getUnreadCount);
+const mockedMarkNotificationRead = vi.mocked(markNotificationRead);
+const mockedMarkAllNotificationsRead = vi.mocked(markAllNotificationsRead);
+const mockedDismissNotification = vi.mocked(dismissNotification);
+
+function wrapper({ children }: { children: React.ReactNode }) {
+	return <NotificationProvider>{children}</NotificationProvider>;
+}
+
+const makeNotification = (id: string, overrides?: Record<string, unknown>) => ({
+	id,
+	user_id: "user-1",
+	category: "instance",
+	severity: "info" as const,
+	title: "Test",
+	message: null,
+	source_type: null,
+	source_id: null,
+	metadata: {},
+	read_at: null,
+	dismissed_at: null,
+	created_at: "2026-05-29T10:00:00Z",
+	...overrides,
+});
+
+describe("useNotifications", () => {
+	beforeEach(() => {
+		vi.useFakeTimers({ shouldAdvanceTime: true });
+		mockedGetNotifications.mockResolvedValue({
+			items: [],
+			total: 0,
+			limit: 20,
+			offset: 0,
+		});
+		mockedGetUnreadCount.mockResolvedValue(0);
+		mockedMarkNotificationRead.mockResolvedValue(
+			makeNotification("1", { read_at: "2026-05-29T10:01:00Z" }),
+		);
+		mockedMarkAllNotificationsRead.mockResolvedValue(1);
+		mockedDismissNotification.mockResolvedValue(undefined);
+	});
+
+	afterEach(() => {
+		vi.useRealTimers();
+		vi.clearAllMocks();
+	});
+
+	it("returns notifications and unreadCount from provider", async () => {
+		mockedGetNotifications.mockResolvedValue({
+			items: [makeNotification("1")],
+			total: 1,
+			limit: 20,
+			offset: 0,
+		});
+		mockedGetUnreadCount.mockResolvedValue(3);
+
+		const { result } = renderHook(() => useNotifications(), { wrapper });
+
+		await act(async () => {
+			vi.advanceTimersByTime(100);
+		});
+
+		await waitFor(() => {
+			expect(result.current.notifications).toHaveLength(1);
+			expect(result.current.unreadCount).toBe(3);
+		});
+	});
+
+	it("optimistically updates on markRead", async () => {
+		mockedGetNotifications.mockResolvedValue({
+			items: [makeNotification("1"), makeNotification("2")],
+			total: 2,
+			limit: 20,
+			offset: 0,
+		});
+		mockedGetUnreadCount.mockResolvedValue(2);
+
+		const { result } = renderHook(() => useNotifications(), { wrapper });
+
+		await act(async () => {
+			vi.advanceTimersByTime(100);
+		});
+
+		await waitFor(() => expect(result.current.unreadCount).toBe(2));
+
+		let resolveApi:
+			| ((value: NotificationItem | PromiseLike<NotificationItem>) => void)
+			| undefined;
+		mockedMarkNotificationRead.mockReturnValue(
+			new Promise((resolve) => {
+				resolveApi = resolve;
+			}),
+		);
+
+		act(() => {
+			void result.current.markRead("1");
+		});
+
+		await waitFor(() => {
+			const n = result.current.notifications.find((x) => x.id === "1");
+			expect(n?.read_at).not.toBeNull();
+		});
+		expect(result.current.unreadCount).toBe(1);
+
+		act(() => {
+			resolveApi?.(makeNotification("1", { read_at: "2026-05-29T10:01:00Z" }));
+		});
+	});
+
+	it("reverts optimistic update on markRead failure", async () => {
+		mockedGetNotifications.mockResolvedValue({
+			items: [makeNotification("1")],
+			total: 1,
+			limit: 20,
+			offset: 0,
+		});
+		mockedGetUnreadCount.mockResolvedValue(1);
+
+		const { result } = renderHook(() => useNotifications(), { wrapper });
+
+		await act(async () => {
+			vi.advanceTimersByTime(100);
+		});
+		await waitFor(() => expect(result.current.unreadCount).toBe(1));
+
+		mockedMarkNotificationRead.mockRejectedValue(new Error("Network error"));
+
+		await act(async () => {
+			await result.current.markRead("1");
+		});
+
+		const n = result.current.notifications.find((x) => x.id === "1");
+		expect(n?.read_at).toBeNull();
+		expect(result.current.unreadCount).toBe(1);
+		expect(result.current.error).toBeInstanceOf(Error);
+	});
+
+	it("optimistically updates on dismiss", async () => {
+		mockedGetNotifications.mockResolvedValue({
+			items: [makeNotification("1"), makeNotification("2")],
+			total: 2,
+			limit: 20,
+			offset: 0,
+		});
+		mockedGetUnreadCount.mockResolvedValue(2);
+
+		const { result } = renderHook(() => useNotifications(), { wrapper });
+
+		await act(async () => {
+			vi.advanceTimersByTime(100);
+		});
+		await waitFor(() => expect(result.current.notifications).toHaveLength(2));
+
+		mockedDismissNotification.mockReturnValue(new Promise(() => {}));
+
+		act(() => {
+			void result.current.dismiss("1");
+		});
+
+		await waitFor(() => {
+			expect(result.current.notifications).toHaveLength(1);
+		});
+		expect(result.current.unreadCount).toBe(1);
+	});
+
+	it("reverts optimistic update on dismiss failure", async () => {
+		mockedGetNotifications.mockResolvedValue({
+			items: [makeNotification("1")],
+			total: 1,
+			limit: 20,
+			offset: 0,
+		});
+		mockedGetUnreadCount.mockResolvedValue(1);
+
+		const { result } = renderHook(() => useNotifications(), { wrapper });
+
+		await act(async () => {
+			vi.advanceTimersByTime(100);
+		});
+		await waitFor(() => expect(result.current.notifications).toHaveLength(1));
+
+		mockedDismissNotification.mockRejectedValue(new Error("Network error"));
+
+		await act(async () => {
+			await result.current.dismiss("1");
+		});
+
+		expect(result.current.notifications).toHaveLength(1);
+		expect(result.current.unreadCount).toBe(1);
+		expect(result.current.error).toBeInstanceOf(Error);
+	});
+
+	it("calls refreshList when invoked", async () => {
+		mockedGetNotifications.mockResolvedValue({
+			items: [makeNotification("1")],
+			total: 1,
+			limit: 20,
+			offset: 0,
+		});
+
+		const { result } = renderHook(() => useNotifications(), { wrapper });
+
+		await act(async () => {
+			vi.advanceTimersByTime(100);
+		});
+
+		mockedGetNotifications.mockResolvedValue({
+			items: [makeNotification("1"), makeNotification("2")],
+			total: 2,
+			limit: 20,
+			offset: 0,
+		});
+
+		await act(async () => {
+			await result.current.refreshList();
+		});
+
+		expect(mockedGetNotifications).toHaveBeenCalledTimes(2);
+		await waitFor(() => expect(result.current.notifications).toHaveLength(2));
+	});
+
+	it("stops polling on 401", async () => {
+		mockedGetUnreadCount.mockRejectedValue({ response: { status: 401 } });
+
+		renderHook(() => useNotifications(), { wrapper });
+
+		await act(async () => {
+			vi.advanceTimersByTime(100);
+		});
+
+		const callCountAfterFirst = mockedGetUnreadCount.mock.calls.length;
+
+		await act(async () => {
+			vi.advanceTimersByTime(60000);
+		});
+
+		expect(mockedGetUnreadCount.mock.calls.length).toBe(callCountAfterFirst);
+	});
+
+	it("pauses polling when document hidden", async () => {
+		renderHook(() => useNotifications(), { wrapper });
+
+		await act(async () => {
+			vi.advanceTimersByTime(100);
+		});
+
+		const callCountBefore = mockedGetUnreadCount.mock.calls.length;
+
+		act(() => {
+			Object.defineProperty(document, "hidden", {
+				value: true,
+				writable: true,
+				configurable: true,
+			});
+			document.dispatchEvent(new Event("visibilitychange"));
+		});
+
+		await act(async () => {
+			vi.advanceTimersByTime(60000);
+		});
+
+		expect(mockedGetUnreadCount.mock.calls.length).toBe(callCountBefore);
+
+		act(() => {
+			Object.defineProperty(document, "hidden", {
+				value: false,
+				writable: true,
+				configurable: true,
+			});
+			document.dispatchEvent(new Event("visibilitychange"));
+		});
+
+		await act(async () => {
+			vi.advanceTimersByTime(100);
+		});
+
+		expect(mockedGetUnreadCount.mock.calls.length).toBeGreaterThan(
+			callCountBefore,
+		);
+	});
+
+	it("multiple markRead calls decrement correctly", async () => {
+		mockedGetNotifications.mockResolvedValue({
+			items: [
+				makeNotification("1"),
+				makeNotification("2"),
+				makeNotification("3"),
+			],
+			total: 3,
+			limit: 20,
+			offset: 0,
+		});
+		mockedGetUnreadCount.mockResolvedValue(3);
+
+		const { result } = renderHook(() => useNotifications(), { wrapper });
+
+		await act(async () => {
+			vi.advanceTimersByTime(100);
+		});
+		await waitFor(() => expect(result.current.unreadCount).toBe(3));
+
+		mockedMarkNotificationRead.mockResolvedValue(
+			makeNotification("1", { read_at: "2026-05-29T10:01:00Z" }),
+		);
+
+		await act(async () => {
+			await result.current.markRead("1");
+			await result.current.markRead("2");
+			await result.current.markRead("3");
+		});
+
+		expect(result.current.unreadCount).toBe(0);
+	});
+});

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

@@ -0,0 +1,12 @@
+import { useContext } from "react";
+import { NotificationContext } from "../state/notifications";
+
+export function useNotifications() {
+	const ctx = useContext(NotificationContext);
+	if (!ctx) {
+		throw new Error(
+			"useNotifications must be used within NotificationProvider",
+		);
+	}
+	return ctx;
+}

apps/web/src/pages/settings.tsx

@@ -1,153 +1,284 @@
 import { useEffect, useState } from "react";
 import { Link, Outlet, useLocation, useOutletContext } from "react-router-dom";
 
-import { getUserConfig, updateUserConfig, type UserConfig, type UserConfigUpdate } from "../api/settings";
+import {
+	getUserConfig,
+	updateUserConfig,
+	type UserConfig,
+	type UserConfigUpdate,
+} from "../api/settings";
 import { ErrorState, LoadingState } from "../components/data-states";
 import { Icon } from "../components/icon";
 import { useAsyncData } from "../hooks/use-async-data";
 
 const TABS = [
-  { label: "General", path: "general" },
-  { label: "SSH Keys", path: "ssh-keys" },
+	{ label: "General", path: "general" },
+	{ label: "SSH Keys", path: "ssh-keys" },
 ] as const;
 
 const THEME_OPTIONS = [
-  { value: "system", label: "System" },
-  { value: "light", label: "Light" },
-  { value: "dark", label: "Dark" },
+	{ value: "system", label: "System" },
+	{ value: "light", label: "Light" },
+	{ value: "dark", label: "Dark" },
 ];
 
+const TOAST_LEVEL_OPTIONS = [
+	{ value: "all", label: "All" },
+	{ value: "errors", label: "Errors only" },
+	{ value: "none", label: "None" },
+];
+
+const MUTE_CATEGORIES = ["instance", "system", "health", "security"];
+
 type SettingsOutletContext = {
-  config: UserConfig;
-  handleChange: (key: keyof UserConfigUpdate, value: string | null) => void;
-  handleSave: () => Promise<void>;
-  saveStatus: "idle" | "saving" | "saved" | "error";
+	config: UserConfig;
+	handleChange: (
+		key: keyof UserConfigUpdate,
+		value: string | string[] | null,
+	) => void;
+	handleSave: () => Promise<void>;
+	saveStatus: "idle" | "saving" | "saved" | "error";
 };
 
 export const SettingsPage = () => {
-  const location = useLocation();
-  const { data: loadedConfig, status, reload } = useAsyncData<UserConfig>(getUserConfig, []);
-  const [config, setConfig] = useState<UserConfig>({
-    theme: "system",
-    default_editor: null,
-    git_user_name: null,
-    git_user_email: null,
-    last_session_id: null,
-  });
-  const [saveStatus, setSaveStatus] = useState<"idle" | "saving" | "saved" | "error">("idle");
+	const location = useLocation();
+	const {
+		data: loadedConfig,
+		status,
+		reload,
+	} = useAsyncData<UserConfig>(getUserConfig, []);
+	const [config, setConfig] = useState<UserConfig>({
+		theme: "system",
+		default_editor: null,
+		git_user_name: null,
+		git_user_email: null,
+		last_session_id: null,
+		notification_toast_level: "all",
+		notification_mute_categories: [],
+	});
+	const [saveStatus, setSaveStatus] = useState<
+		"idle" | "saving" | "saved" | "error"
+	>("idle");
 
-  // Sync loaded config into local editable state
-  useEffect(() => {
-    if (loadedConfig) {
-      setConfig(loadedConfig);
-    }
-  }, [loadedConfig]);
+	// Sync loaded config into local editable state
+	useEffect(() => {
+		if (loadedConfig) {
+			setConfig({
+				...loadedConfig,
+				notification_toast_level:
+					loadedConfig.notification_toast_level ?? "all",
+				notification_mute_categories:
+					loadedConfig.notification_mute_categories ?? [],
+			});
+		}
+	}, [loadedConfig]);
 
-  const handleChange = (key: keyof UserConfigUpdate, value: string | null) => {
-    setConfig((prev) => ({ ...prev, [key]: value }));
-    setSaveStatus("idle");
-  };
+	const handleChange = (
+		key: keyof UserConfigUpdate,
+		value: string | string[] | null,
+	) => {
+		setConfig((prev) => ({ ...prev, [key]: value }) as UserConfig);
+		setSaveStatus("idle");
+	};
 
-  const handleSave = async () => {
-    setSaveStatus("saving");
-    try {
-      const update: UserConfigUpdate = {
-        theme: config.theme,
-        default_editor: config.default_editor,
-        git_user_name: config.git_user_name,
-        git_user_email: config.git_user_email,
-      };
-      const updated = await updateUserConfig(update);
-      setConfig(updated);
-      setSaveStatus("saved");
-      if (updated.theme === "system") {
-        document.documentElement.removeAttribute("data-theme");
-      } else {
-        document.documentElement.setAttribute("data-theme", updated.theme);
-      }
-      window.setTimeout(() => setSaveStatus("idle"), 2000);
-    } catch {
-      setSaveStatus("error");
-    }
-  };
+	const handleSave = async () => {
+		setSaveStatus("saving");
+		try {
+			const update: UserConfigUpdate = {
+				theme: config.theme,
+				default_editor: config.default_editor,
+				git_user_name: config.git_user_name,
+				git_user_email: config.git_user_email,
+				notification_toast_level: config.notification_toast_level,
+				notification_mute_categories: config.notification_mute_categories,
+			};
+			const updated = await updateUserConfig(update);
+			setConfig(updated);
+			window.dispatchEvent(
+				new CustomEvent("userconfig:updated", { detail: updated }),
+			);
+			setSaveStatus("saved");
+			if (updated.theme === "system") {
+				document.documentElement.removeAttribute("data-theme");
+			} else {
+				document.documentElement.setAttribute("data-theme", updated.theme);
+			}
+			window.setTimeout(() => setSaveStatus("idle"), 2000);
+		} catch {
+			setSaveStatus("error");
+		}
+	};
 
-  if (status === "loading") {
-    return <section className="stack"><LoadingState message="Loading settings..." /></section>;
-  }
+	if (status === "loading") {
+		return (
+			<section className="stack">
+				<LoadingState message="Loading settings..." />
+			</section>
+		);
+	}
 
-  if (status === "error") {
-    return (
-      <section className="stack">
-        <ErrorState message="Failed to load settings" onRetry={reload} />
-      </section>
-    );
-  }
+	if (status === "error") {
+		return (
+			<section className="stack">
+				<ErrorState message="Failed to load settings" onRetry={reload} />
+			</section>
+		);
+	}
 
-  const parts = location.pathname.split("/").filter(Boolean);
-  const activePath = location.pathname.endsWith("/settings") ? "general" : (parts[parts.length - 1] ?? "general");
+	const parts = location.pathname.split("/").filter(Boolean);
+	const activePath = location.pathname.endsWith("/settings")
+		? "general"
+		: (parts[parts.length - 1] ?? "general");
 
-  return (
-    <section className="stack settings-page">
-      <header className="settings-header card stack-sm">
-        <div>
-          <p className="eyebrow">Configuration</p>
-          <h1>Settings</h1>
-        </div>
-        <p className="muted">General preferences, SSH keys, and config profiles.</p>
-      </header>
+	return (
+		<section className="stack settings-page">
+			<header className="settings-header card stack-sm">
+				<div>
+					<p className="eyebrow">Configuration</p>
+					<h1>Settings</h1>
+				</div>
+				<p className="muted">
+					General preferences, SSH keys, and config profiles.
+				</p>
+			</header>
 
-      <nav className="settings-tabs" aria-label="Settings sections">
-        {TABS.map((tab) => (
-          <Link
-            key={tab.path}
-            className={`settings-tab ${activePath === tab.path ? "active" : ""}`}
-            to={tab.path === "general" ? "/settings" : `/settings/${tab.path}`}
-          >
-            {tab.label}
-          </Link>
-        ))}
-      </nav>
+			<nav className="settings-tabs" aria-label="Settings sections">
+				{TABS.map((tab) => (
+					<Link
+						key={tab.path}
+						className={`settings-tab ${activePath === tab.path ? "active" : ""}`}
+						to={tab.path === "general" ? "/settings" : `/settings/${tab.path}`}
+					>
+						{tab.label}
+					</Link>
+				))}
+			</nav>
 
-      <div className="settings-panel card">
-        <Outlet context={{ config, handleChange, handleSave, saveStatus }} />
-      </div>
-    </section>
-  );
+			<div className="settings-panel card">
+				<Outlet context={{ config, handleChange, handleSave, saveStatus }} />
+			</div>
+		</section>
+	);
 };
 
 export const GeneralSettingsTab = () => {
-  const { config, handleChange, handleSave, saveStatus } = useOutletContext<SettingsOutletContext>();
+	const { config, handleChange, handleSave, saveStatus } =
+		useOutletContext<SettingsOutletContext>();
 
-  return (
-    <div className="stack">
-      <h2>General</h2>
-      <label className="form-field">
-        Theme
-        <select value={config.theme} onChange={(e) => handleChange("theme", e.target.value)}>
-          {THEME_OPTIONS.map((opt) => (
-            <option key={opt.value} value={opt.value}>{opt.label}</option>
-          ))}
-        </select>
-      </label>
-      <label className="form-field">
-        Git user name
-        <input type="text" value={config.git_user_name ?? ""} onChange={(e) => handleChange("git_user_name", e.target.value || null)} placeholder="Your git commit name" />
-      </label>
-      <label className="form-field">
-        Git user email
-        <input type="email" value={config.git_user_email ?? ""} onChange={(e) => handleChange("git_user_email", e.target.value || null)} placeholder="your.email@example.com" />
-      </label>
-      <label className="form-field">
-        Default editor
-        <input type="text" value={config.default_editor ?? ""} onChange={(e) => handleChange("default_editor", e.target.value || null)} placeholder="e.g., vscode, vim, cursor" />
-      </label>
-      <div className="settings-actions">
-        <button className="primary-button" onClick={() => void handleSave()} type="button">
-          {saveStatus === "saving" ? <><Icon name="loading" size="sm" /> Saving...</> : <><Icon name="save" size="sm" /> Save Settings</>}
-        </button>
-        {saveStatus === "saved" && <span className="success-text">Settings saved!</span>}
-        {saveStatus === "error" && <span className="error-text">Failed to save</span>}
-      </div>
-    </div>
-  );
+	return (
+		<div className="stack">
+			<h2>General</h2>
+			<label className="form-field">
+				Theme
+				<select
+					value={config.theme}
+					onChange={(e) => handleChange("theme", e.target.value)}
+				>
+					{THEME_OPTIONS.map((opt) => (
+						<option key={opt.value} value={opt.value}>
+							{opt.label}
+						</option>
+					))}
+				</select>
+			</label>
+			<label className="form-field">
+				Git user name
+				<input
+					type="text"
+					value={config.git_user_name ?? ""}
+					onChange={(e) =>
+						handleChange("git_user_name", e.target.value || null)
+					}
+					placeholder="Your git commit name"
+				/>
+			</label>
+			<label className="form-field">
+				Git user email
+				<input
+					type="email"
+					value={config.git_user_email ?? ""}
+					onChange={(e) =>
+						handleChange("git_user_email", e.target.value || null)
+					}
+					placeholder="your.email@example.com"
+				/>
+			</label>
+			<label className="form-field">
+				Default editor
+				<input
+					type="text"
+					value={config.default_editor ?? ""}
+					onChange={(e) =>
+						handleChange("default_editor", e.target.value || null)
+					}
+					placeholder="e.g., vscode, vim, cursor"
+				/>
+			</label>
+			<h3>Notifications</h3>
+			<label className="form-field">
+				Toast level
+				<select
+					value={config.notification_toast_level ?? "all"}
+					onChange={(e) =>
+						handleChange("notification_toast_level", e.target.value)
+					}
+				>
+					{TOAST_LEVEL_OPTIONS.map((opt) => (
+						<option key={opt.value} value={opt.value}>
+							{opt.label}
+						</option>
+					))}
+				</select>
+			</label>
+			<fieldset className="form-field">
+				<legend>Mute categories</legend>
+				<div className="stack-sm">
+					{MUTE_CATEGORIES.map((cat) => (
+						<label
+							key={cat}
+							style={{ display: "flex", alignItems: "center", gap: "0.5rem" }}
+						>
+							<input
+								type="checkbox"
+								checked={(config.notification_mute_categories ?? []).includes(
+									cat,
+								)}
+								onChange={(e) => {
+									const current = config.notification_mute_categories ?? [];
+									const next = e.target.checked
+										? [...current, cat]
+										: current.filter((c) => c !== cat);
+									handleChange("notification_mute_categories", next);
+								}}
+							/>
+							{cat}
+						</label>
+					))}
+				</div>
+			</fieldset>
+			<div className="settings-actions">
+				<button
+					className="primary-button"
+					onClick={() => void handleSave()}
+					type="button"
+				>
+					{saveStatus === "saving" ? (
+						<>
+							<Icon name="loading" size="sm" /> Saving...
+						</>
+					) : (
+						<>
+							<Icon name="save" size="sm" /> Save Settings
+						</>
+					)}
+				</button>
+				{saveStatus === "saved" && (
+					<span className="success-text">Settings saved!</span>
+				)}
+				{saveStatus === "error" && (
+					<span className="error-text">Failed to save</span>
+				)}
+			</div>
+		</div>
+	);
 };

apps/web/src/pages/terminal.tsx

@@ -5,10 +5,15 @@ import {
 	TerminalSessionTabs,
 	type TerminalSessionInfo,
 } from "../components/terminal-session-tabs";
+import { Icon } from "../components/icon";
+import { SpecialKeysStrip } from "../components/special-keys-strip";
+import { SpecialKeysPanel } from "../components/special-keys-panel";
 import { useMobileViewport } from "../hooks/use-mobile-viewport";
 import { useAutoHide } from "../hooks/use-auto-hide";
+import { useVirtualKeyboard } from "../hooks/use-virtual-keyboard";
 import { useTerminalSessions } from "../hooks/use-terminal-sessions";
 import type { TerminalSession } from "../api/terminal";
+import type { ModifierKey } from "../hooks/use-special-keys";
 
 const SESSIONS_TO_INFO = (sessions: TerminalSession[]): TerminalSessionInfo[] =>
 	sessions.map((s) => ({
@@ -17,6 +22,13 @@ const SESSIONS_TO_INFO = (sessions: TerminalSession[]): TerminalSessionInfo[] =>
 		status: s.status as TerminalSessionInfo["status"],
 	}));
 
+type TerminalStatus =
+	| "connecting"
+	| "connected"
+	| "disconnected"
+	| "error"
+	| "resetting";
+
 export const TerminalPage: React.FC = () => {
 	const { instanceId } = useParams<{
 		instanceId: string;
@@ -27,6 +39,21 @@ export const TerminalPage: React.FC = () => {
 	const terminalRefs = useRef<Record<string, React.RefObject<TerminalRef>>>({});
 	const headerAutoHide = useAutoHide({ timeout: 3000, enabled: isMobile });
 
+	// Track terminal status and callbacks for unified fullscreen header
+	const [terminalStatuses, setTerminalStatuses] = useState<
+		Record<string, TerminalStatus>
+	>({});
+	const changeFontSizeRef = useRef<((delta: number) => void) | null>(null);
+	const sendDataRef = useRef<((data: string) => void) | null>(null);
+	const focusInputRef = useRef<(() => void) | null>(null);
+	const [showResetConfirm, setShowResetConfirm] = useState(false);
+	const [showSpecialKeysPanel, setShowSpecialKeysPanel] = useState(false);
+	const [activeModifier, setActiveModifier] = useState<ModifierKey | null>(
+		null,
+	);
+	const { isOpen: isKeyboardOpen, height: keyboardHeight } =
+		useVirtualKeyboard();
+
 	const {
 		sessions,
 		activeSessionId,
@@ -66,12 +93,19 @@ export const TerminalPage: React.FC = () => {
 	useEffect(() => {
 		if (activeSessionId && terminalRefs.current[activeSessionId]) {
 			const ref = terminalRefs.current[activeSessionId];
-			// Small delay to allow display:block to apply
-			const timer = setTimeout(() => {
-				ref.current?.fit();
-				ref.current?.focus();
-			}, 50);
-			return () => clearTimeout(timer);
+			// Double rAF ensures layout has settled after the display:block switch
+			let raf1 = 0;
+			let raf2 = 0;
+			raf1 = requestAnimationFrame(() => {
+				raf2 = requestAnimationFrame(() => {
+					ref.current?.fit();
+					ref.current?.focus();
+				});
+			});
+			return () => {
+				cancelAnimationFrame(raf1);
+				cancelAnimationFrame(raf2);
+			};
 		}
 	}, [activeSessionId]);
 
@@ -141,17 +175,62 @@ export const TerminalPage: React.FC = () => {
 		setActiveSessionId,
 	]);
 
-	// Exit fullscreen on Escape
+	// Keep screen awake while terminal is open
 	useEffect(() => {
-		if (!isFullscreen) return;
-		const handleEscape = (e: KeyboardEvent) => {
-			if (e.key === "Escape") {
-				setIsFullscreen(false);
+		let wakeLock: WakeLockSentinel | null = null;
+
+		const requestWakeLock = async () => {
+			try {
+				if ("wakeLock" in navigator) {
+					wakeLock = await navigator.wakeLock.request("screen");
+				}
+			} catch {
+				// Wake lock may be denied; silently ignore
 			}
 		};
-		window.addEventListener("keydown", handleEscape);
-		return () => window.removeEventListener("keydown", handleEscape);
-	}, [isFullscreen]);
+
+		void requestWakeLock();
+
+		const handleVisibilityChange = () => {
+			if (document.visibilityState === "visible") {
+				void requestWakeLock();
+			}
+		};
+
+		document.addEventListener("visibilitychange", handleVisibilityChange);
+		return () => {
+			document.removeEventListener("visibilitychange", handleVisibilityChange);
+			wakeLock?.release().catch(() => {});
+		};
+	}, []);
+
+	// Lock page scroll on mobile terminal so swipes scroll the terminal buffer,
+	// not the page.
+	useEffect(() => {
+		if (!isMobile) return;
+		document.documentElement.classList.add("terminal-page-open");
+		document.body.classList.add("terminal-page-open");
+		return () => {
+			document.documentElement.classList.remove("terminal-page-open");
+			document.body.classList.remove("terminal-page-open");
+		};
+	}, [isMobile]);
+
+	// Click outside terminal content/header to exit fullscreen
+	const handleFullscreenClick = useCallback(
+		(e: React.MouseEvent<HTMLElement>) => {
+			if (!isFullscreen) return;
+			const target = e.target as Node;
+			const current = e.currentTarget as HTMLElement;
+			const content = current.querySelector(".terminal-page-content");
+			const header = current.querySelector(".terminal-fullscreen-header");
+			if (content?.contains(target) || header?.contains(target)) {
+				return;
+			}
+			setIsFullscreen(false);
+		},
+		[isFullscreen],
+	);
 
 	const handleSelect = useCallback(
 		(sessionId: string) => {
@@ -178,6 +257,38 @@ export const TerminalPage: React.FC = () => {
 		[renameSession],
 	);
 
+	const handleTerminalReady = useCallback(
+		(
+			sendData: (data: string) => void,
+			status: TerminalStatus,
+			focusInput: () => void,
+			changeFontSize: (delta: number) => void,
+		) => {
+			setTerminalStatuses((prev) => ({
+				...prev,
+				[activeSessionId ?? "default"]: status,
+			}));
+			sendDataRef.current = sendData;
+			focusInputRef.current = focusInput;
+			changeFontSizeRef.current = changeFontSize;
+		},
+		[activeSessionId],
+	);
+
+	const handleFontSizeChange = useCallback((delta: number) => {
+		changeFontSizeRef.current?.(delta);
+	}, []);
+
+	const handleSendKey = useCallback((data: string) => {
+		sendDataRef.current?.(data);
+	}, []);
+
+	const handleReset = useCallback(() => {
+		if (activeSessionId && terminalRefs.current[activeSessionId]) {
+			terminalRefs.current[activeSessionId].current?.reset();
+		}
+	}, [activeSessionId]);
+
 	if (!instanceId) {
 		return (
 			<section className="stack">
@@ -190,45 +301,85 @@ export const TerminalPage: React.FC = () => {
 	const sessionInfos = SESSIONS_TO_INFO(sessions);
 
 	if (isMobile) {
+		const activeSession = sessions.find((s) => s.id === activeSessionId);
+		const status =
+			terminalStatuses[activeSessionId ?? "default"] ?? "connecting";
+
 		return (
 			<section
 				className={`terminal-page mobile ${isFullscreen ? "fullscreen" : ""}`}
 			>
+				{/* Overlay status bar — floats over terminal, never resizes it */}
 				<div
-					className={`terminal-page-header mobile-header ${headerAutoHide.isVisible ? "visible" : "hidden"}`}
-					onClick={() => headerAutoHide.show()}
+					className={`mobile-terminal-overlay ${headerAutoHide.isVisible ? "visible" : "hidden"}`}
+					onClick={(e) => e.stopPropagation()}
 				>
-					<button
-						className="secondary-button"
-						onClick={() => navigate(-1)}
-						type="button"
-					>
-						Back
-					</button>
-					<h1>Terminal</h1>
-					<button
-						className="secondary-button"
-						onClick={() => setIsFullscreen((p) => !p)}
-						type="button"
-					>
-						{isFullscreen ? "Exit" : "Fullscreen"}
-					</button>
+					<div className="mobile-terminal-toolbar">
+						<div className="mobile-terminal-toolbar-left">
+							<button
+								className="mobile-terminal-toolbtn"
+								onClick={() => navigate(-1)}
+								type="button"
+								aria-label="Back"
+							>
+								<Icon name="arrow-left" size="sm" />
+							</button>
+						</div>
+						<div className="mobile-terminal-toolbar-center">
+							<span className="mobile-terminal-title">
+								{activeSession?.name || "Terminal"}
+							</span>
+							<span
+								className={`mobile-terminal-status status-dot ${status}`}
+								aria-label={`Connection status: ${status}`}
+							/>
+						</div>
+						<div className="mobile-terminal-toolbar-right">
+							<button
+								className="mobile-terminal-toolbtn"
+								onClick={() => handleFontSizeChange(-1)}
+								type="button"
+								aria-label="Decrease font size"
+							>
+								<span style={{ fontSize: "0.75rem" }}>A-</span>
+							</button>
+							<button
+								className="mobile-terminal-toolbtn"
+								onClick={() => handleFontSizeChange(1)}
+								type="button"
+								aria-label="Increase font size"
+							>
+								<span style={{ fontSize: "1rem" }}>A+</span>
+							</button>
+							<button
+								className="mobile-terminal-toolbtn"
+								onClick={() => navigate(-1)}
+								type="button"
+								aria-label="Exit terminal"
+							>
+								<Icon name="close" size="sm" />
+							</button>
+						</div>
+					</div>
+					<div className="mobile-terminal-overlay-tabs">
+						<TerminalSessionTabs
+							sessions={sessionInfos}
+							activeSessionId={activeSessionId ?? ""}
+							onSelect={handleSelect}
+							onClose={handleClose}
+							onCreate={handleCreate}
+							onRename={handleRename}
+							isMobile={true}
+						/>
+					</div>
 				</div>
+
+				{/* Terminal content — always fills full viewport */}
 				<div
-					className={`mobile-tabs-container ${headerAutoHide.isVisible ? "visible" : "hidden"}`}
-					onClick={() => headerAutoHide.show()}
+					className="terminal-page-content mobile-full"
+					style={{ paddingBottom: isKeyboardOpen ? keyboardHeight : 0 }}
+					onClick={() => headerAutoHide.toggle()}
 				>
-					<TerminalSessionTabs
-						sessions={sessionInfos}
-						activeSessionId={activeSessionId ?? ""}
-						onSelect={handleSelect}
-						onClose={handleClose}
-						onCreate={handleCreate}
-						onRename={handleRename}
-						isMobile={true}
-					/>
-				</div>
-				<div className="terminal-page-content">
 					{error && <div className="terminal-error-banner">{error}</div>}
 					{sessions
 						.filter((session) => session.id === activeSessionId)
@@ -240,6 +391,10 @@ export const TerminalPage: React.FC = () => {
 									sessionId={session.id}
 									onClose={() => handleClose(session.id)}
 									isMobile={true}
+									showControls={false}
+									activeModifier={activeModifier}
+									onModifierChange={setActiveModifier}
+									onTerminalReady={handleTerminalReady}
 								/>
 							</div>
 						))}
@@ -249,12 +404,33 @@ export const TerminalPage: React.FC = () => {
 						</div>
 					)}
 				</div>
+
+				<SpecialKeysStrip
+					onSend={handleSendKey}
+					isVisible={!showSpecialKeysPanel}
+					onMoreClick={() => setShowSpecialKeysPanel(true)}
+					onKeepFocus={() => focusInputRef.current?.()}
+					activeModifier={activeModifier}
+					onModifierChange={setActiveModifier}
+				/>
+
+				<SpecialKeysPanel
+					onSend={handleSendKey}
+					isOpen={showSpecialKeysPanel}
+					onClose={() => setShowSpecialKeysPanel(false)}
+					onKeepFocus={() => focusInputRef.current?.()}
+					activeModifier={activeModifier}
+					onModifierChange={setActiveModifier}
+				/>
 			</section>
 		);
 	}
 
 	return (
-		<section className={`terminal-page ${isFullscreen ? "fullscreen" : ""}`}>
+		<section
+			className={`terminal-page ${isFullscreen ? "fullscreen" : ""}`}
+			onClick={handleFullscreenClick}
+		>
 			{!isFullscreen && (
 				<div className="terminal-page-header">
 					<button
@@ -275,15 +451,98 @@ export const TerminalPage: React.FC = () => {
 					</button>
 				</div>
 			)}
-			<TerminalSessionTabs
-				sessions={sessionInfos}
-				activeSessionId={activeSessionId ?? ""}
-				onSelect={handleSelect}
-				onClose={handleClose}
-				onCreate={handleCreate}
-				onRename={handleRename}
-				isMobile={false}
-			/>
+			{isFullscreen ? (
+				<div className="terminal-fullscreen-header">
+					<div className="terminal-fullscreen-header-tabs">
+						<TerminalSessionTabs
+							sessions={sessionInfos}
+							activeSessionId={activeSessionId ?? ""}
+							onSelect={handleSelect}
+							onClose={handleClose}
+							onCreate={handleCreate}
+							onRename={handleRename}
+							isMobile={false}
+						/>
+					</div>
+					<div className="terminal-fullscreen-header-controls">
+						<span
+							className={`terminal-fullscreen-status status-dot ${terminalStatuses[activeSessionId ?? "default"] ?? "connecting"}`}
+							aria-label={`Terminal status: ${terminalStatuses[activeSessionId ?? "default"] ?? "connecting"}`}
+						/>
+						<button
+							className="terminal-header-button"
+							onClick={() => handleFontSizeChange(-1)}
+							type="button"
+							aria-label="Decrease font size"
+						>
+							A-
+						</button>
+						<button
+							className="terminal-header-button"
+							onClick={() => handleFontSizeChange(1)}
+							type="button"
+							aria-label="Increase font size"
+						>
+							A+
+						</button>
+						<button
+							className="terminal-header-button"
+							onClick={() => setShowResetConfirm(true)}
+							type="button"
+							aria-label="Reset terminal"
+						>
+							Reset
+						</button>
+						<button
+							className="terminal-close"
+							onClick={() => setIsFullscreen(false)}
+							type="button"
+							title="Exit fullscreen (Esc)"
+						>
+							Exit
+						</button>
+					</div>
+					{showResetConfirm && (
+						<div className="terminal-reset-confirm">
+							<div className="terminal-reset-confirm-content">
+								<p>
+									Reset terminal? This will kill the current shell session and
+									start fresh.
+								</p>
+								<div className="terminal-reset-confirm-buttons">
+									<button
+										className="terminal-reset-confirm-button cancel"
+										onClick={() => setShowResetConfirm(false)}
+										type="button"
+									>
+										Cancel
+									</button>
+									<button
+										className="terminal-reset-confirm-button confirm"
+										onClick={() => {
+											setShowResetConfirm(false);
+											handleReset();
+										}}
+										type="button"
+									>
+										Reset
+									</button>
+								</div>
+							</div>
+						</div>
+					)}
+				</div>
+			) : (
+				<TerminalSessionTabs
+					sessions={sessionInfos}
+					activeSessionId={activeSessionId ?? ""}
+					onSelect={handleSelect}
+					onClose={handleClose}
+					onCreate={handleCreate}
+					onRename={handleRename}
+					isMobile={false}
+				/>
+			)}
 			<div className="terminal-page-content">
 				{error && <div className="terminal-error-banner">{error}</div>}
 				{sessions
@@ -296,6 +555,8 @@ export const TerminalPage: React.FC = () => {
 								sessionId={session.id}
 								onClose={() => handleClose(session.id)}
 								isMobile={false}
+								showControls={!isFullscreen}
+								onTerminalReady={handleTerminalReady}
 							/>
 						</div>
 					))}

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/notifications.tsx

@@ -0,0 +1,307 @@
+import React, {
+	createContext,
+	useCallback,
+	useEffect,
+	useRef,
+	useState,
+} from "react";
+import {
+	getNotifications,
+	getUnreadCount,
+	markNotificationRead,
+	markAllNotificationsRead,
+	dismissNotification,
+	clearAllNotifications,
+} from "../api/notifications";
+import type { NotificationItem } from "../api/notifications";
+
+export interface NotificationContextValue {
+	notifications: NotificationItem[];
+	unreadCount: number;
+	isLoading: boolean;
+	error: Error | null;
+	markRead: (id: string) => Promise<void>;
+	markAllRead: () => Promise<void>;
+	clearAll: () => Promise<void>;
+	dismiss: (id: string) => Promise<void>;
+	refreshList: () => Promise<void>;
+	isDropdownOpen: boolean;
+	setIsDropdownOpen: (open: boolean) => void;
+}
+
+export const NotificationContext =
+	createContext<NotificationContextValue | null>(null);
+
+const UNREAD_POLL_MS = 15000;
+const LIST_POLL_MS = 30000;
+
+export function NotificationProvider({
+	children,
+}: {
+	children: React.ReactNode;
+}) {
+	const [notifications, setNotifications] = useState<NotificationItem[]>([]);
+	const [unreadCount, setUnreadCount] = useState(0);
+	const [isLoading, setIsLoading] = useState(false);
+	const [error, setError] = useState<Error | null>(null);
+	const [isDropdownOpen, setIsDropdownOpen] = useState(false);
+
+	const stateRef = useRef({
+		notifications,
+		unreadCount,
+		isDropdownOpen,
+		stopped: false,
+	});
+	stateRef.current = {
+		notifications,
+		unreadCount,
+		isDropdownOpen,
+		stopped: false,
+	};
+
+	const unreadIntervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+	const listIntervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+
+	const fetchUnreadCount = useCallback(async () => {
+		if (stateRef.current.stopped) return;
+		try {
+			const count = await getUnreadCount();
+			if (!stateRef.current.stopped) {
+				setUnreadCount(count);
+			}
+		} catch (err) {
+			const status = (err as { response?: { status?: number } })?.response
+				?.status;
+			if (status === 401) {
+				stateRef.current.stopped = true;
+				if (unreadIntervalRef.current) {
+					clearInterval(unreadIntervalRef.current);
+					unreadIntervalRef.current = null;
+				}
+				if (listIntervalRef.current) {
+					clearInterval(listIntervalRef.current);
+					listIntervalRef.current = null;
+				}
+			}
+			// Silently log other errors; next cycle proceeds
+			// eslint-disable-next-line no-console
+			console.error("Notification unread count poll failed", err);
+		}
+	}, []);
+
+	const fetchList = useCallback(async () => {
+		if (stateRef.current.stopped) return;
+		setIsLoading(true);
+		try {
+			const data = await getNotifications();
+			if (!stateRef.current.stopped) {
+				setNotifications(data.items);
+			}
+		} catch (err) {
+			const status = (err as { response?: { status?: number } })?.response
+				?.status;
+			if (status === 401) {
+				stateRef.current.stopped = true;
+				if (unreadIntervalRef.current) {
+					clearInterval(unreadIntervalRef.current);
+					unreadIntervalRef.current = null;
+				}
+				if (listIntervalRef.current) {
+					clearInterval(listIntervalRef.current);
+					listIntervalRef.current = null;
+				}
+			}
+			// eslint-disable-next-line no-console
+			console.error("Notification list poll failed", err);
+		} finally {
+			setIsLoading(false);
+		}
+	}, []);
+
+	const startPolling = useCallback(() => {
+		if (stateRef.current.stopped) return;
+
+		if (!unreadIntervalRef.current) {
+			void fetchUnreadCount();
+			unreadIntervalRef.current = setInterval(() => {
+				void fetchUnreadCount();
+			}, UNREAD_POLL_MS);
+		}
+
+		if (!listIntervalRef.current && !stateRef.current.isDropdownOpen) {
+			void fetchList();
+			listIntervalRef.current = setInterval(() => {
+				if (!stateRef.current.isDropdownOpen) {
+					void fetchList();
+				}
+			}, LIST_POLL_MS);
+		}
+	}, [fetchUnreadCount, fetchList]);
+
+	const stopPolling = useCallback(() => {
+		if (unreadIntervalRef.current) {
+			clearInterval(unreadIntervalRef.current);
+			unreadIntervalRef.current = null;
+		}
+		if (listIntervalRef.current) {
+			clearInterval(listIntervalRef.current);
+			listIntervalRef.current = null;
+		}
+	}, []);
+
+	// Handle visibility changes
+	useEffect(() => {
+		const handleVisibilityChange = () => {
+			if (document.hidden) {
+				stopPolling();
+			} else {
+				startPolling();
+			}
+		};
+
+		document.addEventListener("visibilitychange", handleVisibilityChange);
+		return () => {
+			document.removeEventListener("visibilitychange", handleVisibilityChange);
+		};
+	}, [startPolling, stopPolling]);
+
+	// Start/stop polling based on dropdown state
+	useEffect(() => {
+		if (isDropdownOpen) {
+			if (listIntervalRef.current) {
+				clearInterval(listIntervalRef.current);
+				listIntervalRef.current = null;
+			}
+			void fetchList();
+		} else {
+			if (
+				!listIntervalRef.current &&
+				!document.hidden &&
+				unreadIntervalRef.current
+			) {
+				listIntervalRef.current = setInterval(() => {
+					if (!stateRef.current.isDropdownOpen) {
+						void fetchList();
+					}
+				}, LIST_POLL_MS);
+			}
+		}
+	}, [isDropdownOpen, fetchList]);
+
+	// Initial start
+	useEffect(() => {
+		startPolling();
+		return () => {
+			stopPolling();
+		};
+	}, [startPolling, stopPolling]);
+
+	const markRead = useCallback(async (id: string) => {
+		const { notifications: currentNotifications, unreadCount: currentCount } =
+			stateRef.current;
+		const target = currentNotifications.find((n) => n.id === id);
+		const wasUnread = target ? target.read_at === null : false;
+
+		setNotifications(
+			currentNotifications.map((n) =>
+				n.id === id ? { ...n, read_at: new Date().toISOString() } : n,
+			),
+		);
+		if (wasUnread) {
+			setUnreadCount((c) => Math.max(0, c - 1));
+		}
+		setError(null);
+
+		try {
+			await markNotificationRead(id);
+		} catch (err) {
+			setNotifications(currentNotifications);
+			setUnreadCount(currentCount);
+			setError(err as Error);
+		}
+	}, []);
+
+	const markAllRead = useCallback(async () => {
+		const { notifications: currentNotifications, unreadCount: currentCount } =
+			stateRef.current;
+
+		setNotifications(
+			currentNotifications.map((n) =>
+				n.read_at === null ? { ...n, read_at: new Date().toISOString() } : n,
+			),
+		);
+		setUnreadCount(0);
+		setError(null);
+
+		try {
+			await markAllNotificationsRead();
+		} catch (err) {
+			setNotifications(currentNotifications);
+			setUnreadCount(currentCount);
+			setError(err as Error);
+		}
+	}, []);
+
+	const dismiss = useCallback(async (id: string) => {
+		const { notifications: currentNotifications, unreadCount: currentCount } =
+			stateRef.current;
+		const target = currentNotifications.find((n) => n.id === id);
+		const wasUnread = target ? target.read_at === null : false;
+
+		setNotifications(currentNotifications.filter((n) => n.id !== id));
+		if (wasUnread) {
+			setUnreadCount((c) => Math.max(0, c - 1));
+		}
+		setError(null);
+
+		try {
+			await dismissNotification(id);
+		} catch (err) {
+			setNotifications(currentNotifications);
+			setUnreadCount(currentCount);
+			setError(err as Error);
+		}
+	}, []);
+
+	const refreshList = useCallback(async () => {
+		await fetchList();
+	}, [fetchList]);
+
+	const clearAll = useCallback(async () => {
+		const { notifications: currentNotifications } = stateRef.current;
+		const unreadInList = currentNotifications.filter(
+			(n) => n.read_at === null,
+		).length;
+
+		setNotifications([]);
+		setUnreadCount((c) => Math.max(0, c - unreadInList));
+		setError(null);
+
+		try {
+			await clearAllNotifications();
+		} catch (err) {
+			setNotifications(currentNotifications);
+			setError(err as Error);
+		}
+	}, []);
+
+	const value: NotificationContextValue = {
+		notifications,
+		unreadCount,
+		isLoading,
+		error,
+		markRead,
+		markAllRead,
+		clearAll,
+		dismiss,
+		refreshList,
+		isDropdownOpen,
+		setIsDropdownOpen,
+	};
+
+	return (
+		<NotificationContext.Provider value={value}>
+			{children}
+		</NotificationContext.Provider>
+	);
+}

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

@@ -77,6 +77,11 @@ body {
 	color: var(--ink);
 }
 
+html.terminal-page-open,
+body.terminal-page-open {
+	overflow: hidden;
+}
+
 [data-theme="dark"] body {
 	background: radial-gradient(circle at top right, #2a2520, var(--bg));
 }
@@ -2562,6 +2567,13 @@ a.nav-item,
 	background: #1e1e1e;
 }
 
+/* When controls are hidden (fullscreen), only the container is in flow;
+   force it into the 1fr track so it fills the wrapper instead of landing
+   in the auto track and shrinking on each fit(). */
+.terminal-wrapper.no-controls {
+	grid-template-rows: 1fr;
+}
+
 .terminal-header {
 	display: flex;
 	justify-content: space-between;
@@ -2880,8 +2892,8 @@ a.nav-item,
 	right: 0;
 	bottom: 0;
 	z-index: 1000;
-	padding: 0;
-	gap: 0;
+	padding: 8px;
+	gap: 8px;
 	background: #1e1e1e;
 }
 
@@ -2890,56 +2902,201 @@ a.nav-item,
 	border-radius: 0;
 }
 
-.terminal-page.fullscreen .terminal-session-tabs {
+/* Unified fullscreen header: session tabs + terminal controls */
+.terminal-fullscreen-header {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	background: #2d2d2d;
+	border-bottom: 1px solid #3e3e3e;
+	flex-shrink: 0;
+	min-height: 0;
+}
+
+.terminal-fullscreen-header-tabs {
+	flex: 1;
+	min-width: 0;
+	overflow: hidden;
+}
+
+.terminal-fullscreen-header-tabs .terminal-session-tabs {
+	background: transparent;
+	border-bottom: none;
+}
+
+.terminal-fullscreen-header-controls {
+	display: flex;
+	align-items: center;
+	gap: var(--space-2);
+	padding: 0 var(--space-3);
+	flex-shrink: 0;
+	border-left: 1px solid #3e3e3e;
+}
+
+.terminal-fullscreen-status {
+	width: 8px;
+	height: 8px;
+	border-radius: 50%;
+	background: #666;
+	flex-shrink: 0;
+}
+
+.terminal-fullscreen-status.connecting {
+	background: #f5f543;
+	animation: pulse 1.5s infinite;
+}
+
+.terminal-fullscreen-status.connected {
+	background: #0dbc79;
+}
+
+.terminal-fullscreen-status.disconnected,
+.terminal-fullscreen-status.error {
+	background: #cd3131;
+}
+
+/* ============================================
+   Mobile Terminal Overlay
+   ============================================ */
+
+/* Mobile terminal page — no padding, terminal fills viewport */
+.terminal-page.mobile {
+	padding: 0;
+	gap: 0;
+	height: 100vh;
+	height: 100dvh;
+	position: relative;
+	overflow: hidden;
+}
+
+/* Overlay status bar — floats over terminal, never resizes it */
+.mobile-terminal-overlay {
 	position: absolute;
 	top: 0;
 	left: 0;
 	right: 0;
-	z-index: 10;
-	opacity: 0;
-	transition: opacity 0.3s;
-}
-
-.terminal-page.fullscreen .terminal-session-tabs:hover {
-	opacity: 1;
-}
-
-/* Mobile auto-hide header and tabs */
-.terminal-page.mobile .terminal-page-header,
-.mobile-tabs-container {
+	z-index: 100;
+	background: #2d2d2d;
+	border-bottom: 1px solid #3e3e3e;
 	transition:
 		transform 0.3s ease,
 		opacity 0.3s ease;
 }
 
-.terminal-page.mobile .terminal-page-header.hidden,
-.mobile-tabs-container.hidden {
+.mobile-terminal-overlay.hidden {
 	transform: translateY(-100%);
 	opacity: 0;
 	pointer-events: none;
 }
 
-.terminal-page.mobile .terminal-page-header.visible,
-.mobile-tabs-container.visible {
+.mobile-terminal-overlay.visible {
 	transform: translateY(0);
 	opacity: 1;
 }
 
+/* Toolbar row */
+.mobile-terminal-toolbar {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	padding: var(--space-2) var(--space-3);
+	gap: var(--space-2);
+}
+
+.mobile-terminal-toolbar-left,
+.mobile-terminal-toolbar-right {
+	display: flex;
+	align-items: center;
+	gap: var(--space-1);
+	flex: 0 0 auto;
+}
+
+.mobile-terminal-toolbar-center {
+	display: flex;
+	align-items: center;
+	gap: var(--space-2);
+	flex: 1;
+	justify-content: center;
+	min-width: 0;
+}
+
+.mobile-terminal-title {
+	font-size: 0.875rem;
+	font-weight: 500;
+	color: #d4d4d4;
+	white-space: nowrap;
+	overflow: hidden;
+	text-overflow: ellipsis;
+}
+
+.mobile-terminal-status {
+	width: 8px;
+	height: 8px;
+	border-radius: 50%;
+	background: #666;
+	flex-shrink: 0;
+}
+
+.mobile-terminal-status.connecting {
+	background: #f5f543;
+	animation: pulse 1.5s infinite;
+}
+
+.mobile-terminal-status.connected {
+	background: #0dbc79;
+}
+
+.mobile-terminal-status.disconnected,
+.mobile-terminal-status.error {
+	background: #cd3131;
+}
+
+.mobile-terminal-toolbtn {
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	width: 36px;
+	height: 36px;
+	padding: 0;
+	background: transparent;
+	border: 1px solid #3e3e3e;
+	border-radius: 6px;
+	color: #d4d4d4;
+	cursor: pointer;
+	font-size: 0.875rem;
+	transition: background 0.2s ease;
+}
+
+.mobile-terminal-toolbtn:hover {
+	background: #3e3e3e;
+}
+
+/* Session tabs inside overlay */
+.mobile-terminal-overlay-tabs {
+	background: #1e1e1e;
+	border-top: 1px solid #3e3e3e;
+}
+
+.mobile-terminal-overlay-tabs .terminal-session-tabs {
+	background: #1e1e1e;
+	border-bottom: none;
+}
+
+/* Terminal content — always fills full viewport on mobile */
+.terminal-page-content.mobile-full {
+	flex: 1;
+	min-height: 0;
+	border: none;
+	border-radius: 0;
+	overflow: hidden;
+}
+
 /* Mobile fullscreen */
 @media (max-width: 767px) {
 	.terminal-page.fullscreen {
 		padding: 0;
 	}
 
-	.terminal-page.mobile .terminal-page-header {
-		padding: var(--space-2);
-		gap: var(--space-2);
-	}
-
-	.terminal-page.mobile .terminal-page-header h1 {
-		font-size: 1rem;
-	}
-
 	.terminal-session-tab-name {
 		max-width: 80px;
 	}
@@ -3381,6 +3538,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
    ============================================ */
@@ -3540,6 +3708,7 @@ a.nav-item,
 	padding: 0;
 	overflow: hidden;
 	position: relative;
+	touch-action: none;
 }
 
 /* xterm.js manages its own sizing */
@@ -4452,3 +4621,249 @@ a:active,
 	gap: 0.5rem;
 	margin-top: 0.25rem;
 }
+
+/* Notification Center */
+.notification-center {
+	position: relative;
+	display: inline-flex;
+}
+
+.notification-bell {
+	position: relative;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	padding: 0.4rem;
+	background: transparent;
+	border: none;
+	border-radius: 8px;
+	color: var(--muted);
+	cursor: pointer;
+	transition:
+		background-color 0.15s ease,
+		color 0.15s ease;
+	min-height: 36px;
+	min-width: 36px;
+}
+
+.notification-bell:hover {
+	background: var(--bg);
+	color: var(--ink);
+}
+
+.notification-badge {
+	position: absolute;
+	top: -2px;
+	right: -4px;
+	min-width: 18px;
+	height: 18px;
+	padding: 0 5px;
+	background: var(--danger);
+	color: white;
+	border-radius: 9px;
+	font-size: 11px;
+	font-weight: 600;
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+}
+
+.notification-dropdown {
+	position: absolute;
+	top: calc(100% + 6px);
+	right: 0;
+	width: 360px;
+	max-width: calc(100vw - 2rem);
+	max-height: 480px;
+	background: var(--panel);
+	border: 1px solid var(--border);
+	border-radius: 12px;
+	box-shadow: 0 8px 24px rgba(0, 0, 0, 0.12);
+	z-index: 100;
+	display: flex;
+	flex-direction: column;
+	overflow: hidden;
+}
+
+.notification-dropdown-header {
+	padding: 0.75rem 1rem;
+	font-weight: 600;
+	font-size: 0.95rem;
+	border-bottom: 1px solid var(--border);
+	color: var(--ink);
+	flex-shrink: 0;
+}
+
+.notification-list {
+	list-style: none;
+	margin: 0;
+	padding: 0;
+	overflow-y: auto;
+	flex: 1;
+	min-height: 0;
+}
+
+.notification-empty {
+	padding: 2rem 1rem;
+	text-align: center;
+	color: var(--muted);
+	font-size: 0.9rem;
+}
+
+.notification-dropdown-footer {
+	padding: 0.75rem 1rem;
+	border-top: 1px solid var(--border);
+	flex-shrink: 0;
+	display: flex;
+	gap: 0.5rem;
+}
+
+.notification-mark-all {
+	flex: 1;
+	padding: 0.5rem 0.75rem;
+	background: transparent;
+	border: 1px solid var(--border);
+	border-radius: 8px;
+	color: var(--muted);
+	font: inherit;
+	font-size: 0.85rem;
+	cursor: pointer;
+	transition: all 0.15s ease;
+}
+
+.notification-mark-all:hover {
+	background: var(--bg);
+	color: var(--ink);
+	border-color: var(--brand);
+}
+
+.notification-clear-all {
+	flex: 1;
+	padding: 0.5rem 0.75rem;
+	background: transparent;
+	border: 1px solid var(--border);
+	border-radius: 8px;
+	color: var(--muted);
+	font: inherit;
+	font-size: 0.85rem;
+	cursor: pointer;
+	transition: all 0.15s ease;
+}
+
+.notification-clear-all:hover {
+	background: var(--bg);
+	color: var(--danger);
+	border-color: var(--danger);
+}
+
+/* Notification Item */
+.notification-item {
+	display: flex;
+	align-items: flex-start;
+	gap: 0.75rem;
+	padding: 0.75rem 1rem;
+	border-bottom: 1px solid var(--border);
+	transition: background-color 0.15s ease;
+}
+
+.notification-item:last-child {
+	border-bottom: none;
+}
+
+.notification-item:hover {
+	background: var(--bg);
+}
+
+.notification-item--unread {
+	font-weight: 500;
+	border-left: 3px solid var(--brand);
+	padding-left: calc(1rem - 3px);
+	background: color-mix(in srgb, var(--brand) 4%, var(--panel));
+}
+
+.notification-item--read {
+	opacity: 0.75;
+}
+
+.notification-item-icon {
+	flex-shrink: 0;
+	margin-top: 0.1rem;
+	color: var(--muted);
+}
+
+.notification-item-content {
+	flex: 1;
+	min-width: 0;
+	display: flex;
+	flex-direction: column;
+	gap: 0.2rem;
+}
+
+.notification-item-title {
+	font-size: 0.9rem;
+	line-height: 1.3;
+	color: var(--ink);
+}
+
+.notification-item--read .notification-item-title {
+	font-weight: 400;
+}
+
+.notification-item-time {
+	font-size: 0.8rem;
+	color: var(--muted);
+}
+
+.notification-item-actions {
+	display: flex;
+	gap: 0.35rem;
+	flex-shrink: 0;
+}
+
+.notification-item-action {
+	padding: 0.25rem 0.5rem;
+	background: transparent;
+	border: none;
+	border-radius: 6px;
+	color: var(--muted);
+	font: inherit;
+	font-size: 0.75rem;
+	cursor: pointer;
+	transition: all 0.15s ease;
+	white-space: nowrap;
+}
+
+.notification-item-action:hover {
+	background: var(--bg);
+	color: var(--ink);
+}
+
+@media (max-width: 767px) {
+	.notification-dropdown {
+		width: calc(100vw - 2rem);
+		max-width: 360px;
+	}
+}
+
+/* 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;
+}

apps/web/src/utils/icons.ts

@@ -1,180 +1,180 @@
 import {
-  House,
-  Folder,
-  GitBranch,
-  Gear,
-  User,
-  SignOut,
-  Plus,
-  PencilSimple,
-  Trash,
-  FloppyDisk,
-  X,
-  ArrowsClockwise,
-  Copy,
-  MagnifyingGlass,
-  List,
-  Check,
-  Warning,
-  Info,
-  Spinner,
-  GitCommit,
-  GitMerge,
-  ClockCounterClockwise,
-  ArrowDown,
-  ArrowUp,
-  File,
-  FileText,
-  Image,
-  Binary,
-  Code,
-  ArrowSquareOut,
-  Play,
-  Stop,
-  Terminal,
-  ArrowLeft,
+	House,
+	Folder,
+	GitBranch,
+	Gear,
+	User,
+	SignOut,
+	Plus,
+	PencilSimple,
+	Trash,
+	FloppyDisk,
+	X,
+	ArrowsClockwise,
+	Copy,
+	MagnifyingGlass,
+	List,
+	Check,
+	Warning,
+	Info,
+	Spinner,
+	GitCommit,
+	GitMerge,
+	ClockCounterClockwise,
+	ArrowDown,
+	ArrowUp,
+	File,
+	FileText,
+	Image,
+	Binary,
+	Code,
+	ArrowSquareOut,
+	Play,
+	Stop,
+	Terminal,
+	ArrowLeft,
+	Bell,
 } from "@phosphor-icons/react";
 
 export type IconName =
-  | "dashboard"
-  | "projects"
-  | "repositories"
-  | "settings"
-  | "profile"
-  | "logout"
-  | "add"
-  | "edit"
-  | "delete"
-  | "save"
-  | "cancel"
-  | "refresh"
-  | "copy"
-  | "search"
-  | "menu"
-  | "close"
-  | "success"
-  | "error"
-  | "warning"
-  | "info"
-  | "loading"
-  | "branch"
-  | "commit"
-  | "merge"
-  | "history"
-  | "pull"
-  | "push"
-  | "fetch"
-  | "file"
-  | "folder"
-  | "code"
-  | "document"
-  | "image"
-  | "binary"
-  | "external"
-  | "play"
-  | "stop"
-  | "terminal"
-  | "arrow-left";
+	| "dashboard"
+	| "projects"
+	| "repositories"
+	| "settings"
+	| "profile"
+	| "logout"
+	| "add"
+	| "edit"
+	| "delete"
+	| "save"
+	| "cancel"
+	| "refresh"
+	| "copy"
+	| "search"
+	| "menu"
+	| "close"
+	| "success"
+	| "error"
+	| "warning"
+	| "info"
+	| "loading"
+	| "branch"
+	| "commit"
+	| "merge"
+	| "history"
+	| "pull"
+	| "push"
+	| "fetch"
+	| "file"
+	| "folder"
+	| "code"
+	| "document"
+	| "image"
+	| "binary"
+	| "external"
+	| "play"
+	| "stop"
+	| "terminal"
+	| "arrow-left"
+	| "bell";
 
 export const iconRegistry: Record<
-  IconName,
-  React.ComponentType<{ size?: number | string; weight?: "thin" | "light" | "regular" | "bold" | "fill" | "duotone" }>
+	IconName,
+	React.ComponentType<{
+		size?: number | string;
+		weight?: "thin" | "light" | "regular" | "bold" | "fill" | "duotone";
+	}>
 > = {
-  // Navigation
-  dashboard: House,
-  projects: Folder,
-  repositories: GitBranch,
-  settings: Gear,
-  profile: User,
-  logout: SignOut,
+	// Navigation
+	dashboard: House,
+	projects: Folder,
+	repositories: GitBranch,
+	settings: Gear,
+	profile: User,
+	logout: SignOut,
 
-  // Actions
-  add: Plus,
-  edit: PencilSimple,
-  delete: Trash,
-  save: FloppyDisk,
-  cancel: X,
-  refresh: ArrowsClockwise,
-  copy: Copy,
-  search: MagnifyingGlass,
-  menu: List,
-  close: X,
+	// Actions
+	add: Plus,
+	edit: PencilSimple,
+	delete: Trash,
+	save: FloppyDisk,
+	cancel: X,
+	refresh: ArrowsClockwise,
+	copy: Copy,
+	search: MagnifyingGlass,
+	menu: List,
+	close: X,
 
-  // Status
-  success: Check,
-  error: X,
-  warning: Warning,
-  info: Info,
-  loading: Spinner,
+	// Status
+	success: Check,
+	error: X,
+	warning: Warning,
+	info: Info,
+	loading: Spinner,
 
-  // Git
-  branch: GitBranch,
-  commit: GitCommit,
-  merge: GitMerge,
-  history: ClockCounterClockwise,
-  pull: ArrowDown,
-  push: ArrowUp,
-  fetch: ArrowsClockwise,
+	// Git
+	branch: GitBranch,
+	commit: GitCommit,
+	merge: GitMerge,
+	history: ClockCounterClockwise,
+	pull: ArrowDown,
+	push: ArrowUp,
+	fetch: ArrowsClockwise,
 
-  // Files
-  file: File,
-  folder: Folder,
-  code: Code,
-  document: FileText,
-  image: Image,
-  binary: Binary,
+	// Files
+	file: File,
+	folder: Folder,
+	code: Code,
+	document: FileText,
+	image: Image,
+	binary: Binary,
 
-  // Instance actions
-  external: ArrowSquareOut,
-  play: Play,
-  stop: Stop,
-  terminal: Terminal,
-  "arrow-left": ArrowLeft,
+	// Instance actions
+	external: ArrowSquareOut,
+	play: Play,
+	stop: Stop,
+	terminal: Terminal,
+	"arrow-left": ArrowLeft,
+	bell: Bell,
 };
 
 export const iconCategories = {
-  navigation: [
-    "dashboard",
-    "projects",
-    "repositories",
-    "settings",
-    "profile",
-    "logout",
-  ] as IconName[],
-  actions: [
-    "add",
-    "edit",
-    "delete",
-    "save",
-    "cancel",
-    "refresh",
-    "copy",
-    "search",
-    "menu",
-    "close",
-  ] as IconName[],
-  status: [
-    "success",
-    "error",
-    "warning",
-    "info",
-    "loading",
-  ] as IconName[],
-  git: [
-    "branch",
-    "commit",
-    "merge",
-    "history",
-    "pull",
-    "push",
-    "fetch",
-  ] as IconName[],
-  files: [
-    "file",
-    "folder",
-    "code",
-    "document",
-    "image",
-    "binary",
-  ] as IconName[],
+	navigation: [
+		"dashboard",
+		"projects",
+		"repositories",
+		"settings",
+		"profile",
+		"logout",
+	] as IconName[],
+	actions: [
+		"add",
+		"edit",
+		"delete",
+		"save",
+		"cancel",
+		"refresh",
+		"copy",
+		"search",
+		"menu",
+		"close",
+	] as IconName[],
+	status: ["success", "error", "warning", "info", "loading"] as IconName[],
+	git: [
+		"branch",
+		"commit",
+		"merge",
+		"history",
+		"pull",
+		"push",
+		"fetch",
+	] as IconName[],
+	files: [
+		"file",
+		"folder",
+		"code",
+		"document",
+		"image",
+		"binary",
+	] as IconName[],
 };

apps/web/src/utils/time.ts

@@ -0,0 +1,29 @@
+const UNITS: { label: string; seconds: number }[] = [
+	{ label: "y", seconds: 31536000 },
+	{ label: "mo", seconds: 2592000 },
+	{ label: "w", seconds: 604800 },
+	{ label: "d", seconds: 86400 },
+	{ label: "h", seconds: 3600 },
+	{ label: "m", seconds: 60 },
+	{ label: "s", seconds: 1 },
+];
+
+export function formatRelativeTime(dateStr: string): string {
+	const date = new Date(dateStr);
+	const now = new Date();
+	const diffSeconds = Math.max(
+		0,
+		Math.floor((now.getTime() - date.getTime()) / 1000),
+	);
+
+	if (diffSeconds < 5) return "just now";
+
+	for (const unit of UNITS) {
+		const count = Math.floor(diffSeconds / unit.seconds);
+		if (count >= 1) {
+			return `${count}${unit.label} ago`;
+		}
+	}
+
+	return "just now";
+}

docker-compose.traefik.yml

@@ -13,7 +13,11 @@ services:
     volumes:
       - postgres_data:/var/lib/postgresql/data
     healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-headquarter} -d ${POSTGRES_DB:-headquarter}"]
+      test:
+        [
+          "CMD-SHELL",
+          "pg_isready -U ${POSTGRES_USER:-headquarter} -d ${POSTGRES_DB:-headquarter}",
+        ]
       interval: 10s
       timeout: 5s
       retries: 5
@@ -92,7 +96,7 @@ services:
       AUTHENTIK_AUTHORIZE_URL: ${AUTHENTIK_AUTHORIZE_URL:-}
       AUTHENTIK_TOKEN_URL: ${AUTHENTIK_TOKEN_URL:-}
     volumes:
-      - repo_data:/data/repos
+      - /data/repos:/data/repos
       - /data/instances:/data/instances
       - avatar_uploads:/app/uploads
       - /var/run/docker.sock:/var/run/docker.sock
@@ -116,7 +120,6 @@ services:
 volumes:
   postgres_data:
   redis_data:
-  repo_data:
   avatar_uploads:
 
 networks:

docker-compose.yml

@@ -1,4 +1,4 @@
-version: '3.8'
+version: "3.8"
 
 services:
   # PostgreSQL Database
@@ -14,7 +14,11 @@ services:
     ports:
       - "5432:5432"
     healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-headquarter} -d ${POSTGRES_DB:-headquarter}"]
+      test:
+        [
+          "CMD-SHELL",
+          "pg_isready -U ${POSTGRES_USER:-headquarter} -d ${POSTGRES_DB:-headquarter}",
+        ]
       interval: 10s
       timeout: 5s
       retries: 5
@@ -57,7 +61,7 @@ services:
       REPO_BASE_PATH: /data/repos
       INSTANCE_BASE_PATH: /data/instances
     volumes:
-      - repo_data:/data/repos
+      - /data/repos:/data/repos
       - /data/instances:/data/instances
     ports:
       - "8000:8000"
@@ -91,7 +95,6 @@ services:
 volumes:
   postgres_data:
   redis_data:
-  repo_data:
 
 networks:
   backend:

docs/architecture/backend.md

@@ -17,6 +17,10 @@ The Headquarter backend is built with **FastAPI** and follows a layered architec
 │  │  Auth   │ │ Projects │ │ Users  │ │   Git    │          │
 │  │ Routes  │ │ Routes   │ │ Routes │ │ Repos    │          │
 │  └────┬────┘ └────┬─────┘ └───┬────┘ └────┬─────┘          │
+│  ┌──────────┐ ┌──────────┐                                  │
+│  │ ToolInst │ │  Events  │                                  │
+│  │ Routes   │ │ Routes   │                                  │
+│  └────┬─────┘ └────┬─────┘                                  │
 ├───────┼───────────┼───────────┼───────────┼─────────────────┤
 │       │           │           │           │                  │
 │  Auth │  Project  │   User    │   Git     │                  │
@@ -41,7 +45,9 @@ src/
 │   ├── git_repositories.py # Repository endpoints
 │   ├── users.py           # User endpoints
 │   ├── tool_types.py      # Tool type endpoints
+│   ├── tool_instances.py  # Tool instance endpoints
 │   ├── ssh_keys.py        # SSH key endpoints
+│   ├── events.py          # SSE streaming endpoint
 │   └── dashboard.py       # Dashboard endpoints
 ├── auth/                   # Authentication
 │   ├── session.py         # Session management
@@ -54,7 +60,15 @@ src/
 │   ├── git_repository.py  # Repository model
 │   ├── tool_type.py       # Tool type model
 │   ├── ssh_key.py         # SSH key model
+│   ├── instance_event.py  # Instance event audit model
+│   ├── health_check.py    # Health check snapshot model
 │   └── user_config.py     # User config model
+├── services/               # Services
+│   ├── docker.py          # Docker operations
+│   ├── terminal_manager.py # Terminal session manager
+│   ├── event_bus.py       # Instance event bus (pub/sub)
+│   ├── health_monitor.py  # Background health monitoring
+│   └── lifecycle_hooks.py # Instance lifecycle events
 ├── utils/                  # Utilities
 │   ├── git_url_parser.py  # URL parsing
 │   ├── git_files.py       # Git file operations
@@ -193,6 +207,33 @@ Errors are handled at multiple levels:
 - **Integration tests**: PostgreSQL with transaction rollback
 - **Fixtures**: Shared in `conftest.py`
 
+## Monitoring & Notifications
+
+The backend includes a real-time monitoring system:
+
+### Components
+
+- **InstanceEventBus** (`services/event_bus.py`): Typed pub/sub singleton for instance lifecycle events
+- **HealthMonitor** (`services/health_monitor.py`): Asyncio background task polling container health every 15s
+- **SSE Endpoint** (`api/events.py`): Server-Sent Events streaming for real-time frontend updates
+- **Lifecycle Hooks** (`services/lifecycle_hooks.py`): Publishes events on create/start/stop/restart/delete
+
+### Event Flow
+
+```
+Container Action → Lifecycle Hook → EventBus → SSE Stream → Frontend Toast
+```
+
+### Event Types
+
+| Event | When Fired |
+|-------|-----------|
+| `instance.created` | After DB insert |
+| `instance.starting` | Before docker compose up |
+| `instance.running` | After readiness probe succeeds |
+| `instance.error` | Build fail, crash, or probe fail |
+| `instance.stopped` | After docker compose stop |
+
 ## Technology Stack
 
 | Component | Technology | Version |

docs/architecture/frontend.md

@@ -26,16 +26,21 @@ apps/web/src/
 │   ├── ssh_keys.ts      # SSH key API
 │   ├── tool_types.ts    # Tool type API
 │   ├── users.ts         # User API
+│   ├── events.ts        # SSE events API
 │   └── settings.ts      # Settings API
 ├── components/           # Reusable components
 │   ├── app-shell.tsx    # Main app layout
 │   ├── protected-route.tsx  # Auth guard
+│   ├── event-toast-bridge.tsx  # Events → toasts
 │   └── [more...]
-├── context/             # React contexts
-│   └── auth.tsx         # Auth state management
+├── state/               # Global state
+│   ├── auth.tsx         # Auth state management
+│   ├── events.tsx       # Event provider (SSE)
+│   └── toast.tsx        # Toast notifications
 ├── hooks/               # Custom hooks
 │   ├── use-auth.ts      # Auth hook
-│   └── use-theme.ts     # Theme hook
+│   ├── use-theme.ts     # Theme hook
+│   └── use-events.ts    # SSE events hook
 ├── pages/               # Page components (routes)
 │   ├── dashboard.tsx    # Dashboard
 │   ├── projects.tsx     # Project list
@@ -155,6 +160,28 @@ interface AuthState {
 }
 ```
 
+### Real-Time Events (SSE)
+
+The frontend receives real-time instance events via Server-Sent Events:
+
+```
+EventSource → useEvents() hook → EventProvider → EventToastBridge → ToastContainer
+```
+
+**Components:**
+- `useEvents()`: Manages SSE connection with auto-reconnect
+- `EventProvider`: Shares event stream across components
+- `EventToastBridge`: Maps events to toast notifications
+- `ToastContainer`: Displays and manages toast stack
+
+**Event-to-Toast Mapping:**
+| Event | Toast Severity | Auto-dismiss |
+|-------|---------------|--------------|
+| `instance.starting` | Info | 3s |
+| `instance.running` | Success | 3s |
+| `instance.error` | Error | Persistent |
+| `instance.stopped` | Info | 3s |
+
 ### 5. Routing Structure
 
 ```typescript
@@ -271,10 +298,10 @@ test('renders file list', () => {
 
 ## Future Improvements
 
+- [x] Implement real-time updates (SSE)
 - [ ] Add React Query for server state management
 - [ ] Implement virtual scrolling for large file trees
 - [ ] Add service worker for offline support
-- [ ] Implement real-time updates (WebSocket)
 - [ ] Add error boundary components
 
 ## Development Workflow

docs/features/terminal.md

@@ -50,6 +50,23 @@ Standard terminal shortcuts work as expected:
 
 Special keys can be accessed via the special keys panel on mobile or by using modifier combinations.
 
+## Container Monitoring & Notifications
+
+The platform monitors your tool instances in real-time and notifies you of important events:
+
+### What You'll See
+
+- **Starting:** When a container begins starting
+- **Running:** When a container is ready
+- **Error:** When a build fails, container crashes, or tunnel fails
+- **Stopped:** When a container stops
+
+Notifications appear as toast messages at the top of the screen. Errors persist until dismissed; other notifications auto-dismiss after a few seconds.
+
+### Real-Time Status
+
+Instance status badges update in real-time via Server-Sent Events (SSE) — no page refresh needed.
+
 ## Troubleshooting
 
 ### Connection Issues
@@ -59,6 +76,10 @@ Special keys can be accessed via the special keys panel on mobile or by using mo
 - Network issues - the client will auto-reconnect
 - Session timeout - sessions expire after 30 minutes of inactivity
 
+**"Container not found" error (4004):**
+- The Docker container no longer exists (e.g., after host restart)
+- Restart the tool instance to recreate the container
+
 **Terminal not responding:**
 - Try resetting the terminal using the Reset button
 - Check if the tool instance is still running

openspec/changes/container-monitoring-notifications/.openspec.yaml

@@ -0,0 +1,7 @@
+change: container-monitoring-notifications
+name: Container Monitoring and Notification System
+description: |
+  Monitor Docker container start, health, and lifecycle events with proper
+  logging and a real-time notification system for users.
+status: draft
+tasks: []

openspec/changes/container-monitoring-notifications/apply-pr1.md

@@ -0,0 +1,132 @@
+# PR-1 Apply Report: Backend Core for Container Monitoring & Notifications
+
+## Status: COMPLETE
+
+All 11 assigned tasks (MON-PR1-001 through MON-PR1-011) have been implemented and validated.
+
+---
+
+## Changed Files
+
+### New Files (11)
+| File | Purpose |
+|------|---------|
+| `apps/api/alembic/versions/2026_05_28_add_monitoring_tables.py` | Alembic migration creating `instance_events` + `health_checks` + 5 indexes |
+| `apps/api/src/models/instance_event.py` | SQLAlchemy `InstanceEvent` model |
+| `apps/api/src/models/health_check.py` | SQLAlchemy `HealthCheck` model |
+| `apps/api/src/services/event_bus.py` | `InstanceEventBus` singleton with typed pub/sub |
+| `apps/api/src/services/health_monitor.py` | `HealthMonitor` background polling task |
+| `apps/api/src/services/correlation.py` | Async `CORRELATION_ID` context var + `CorrelationIdMiddleware` |
+| `apps/api/src/services/lifecycle_hooks.py` | `publish_lifecycle_event` helper |
+| `apps/api/src/api/events.py` | SSE endpoint `GET /events/stream` |
+| `apps/api/tests/unit/test_event_bus.py` | Unit tests for EventBus |
+| `apps/api/tests/unit/test_health_monitor.py` | Unit tests for HealthMonitor |
+| `apps/api/tests/unit/test_monitoring_models.py` | Unit tests for new models |
+
+### Modified Files (6)
+| File | Change |
+|------|--------|
+| `apps/api/src/models/__init__.py` | Export `InstanceEvent`, `HealthCheck` |
+| `apps/api/src/api/__init__.py` | Export `events_router` |
+| `apps/api/src/api/tool_instances.py` | Lifecycle hooks at create/start/stop/restart/delete |
+| `apps/api/src/logging_config.py` | JSON formatter + `CorrelationIdFilter` |
+| `apps/api/src/main.py` | Register events router, middleware, HealthMonitor lifespan |
+
+---
+
+## Implementation Summary
+
+### MON-PR1-001/002: Database Migration
+- Single Alembic revision `2026_05_28_add_monitoring_tables` depends on current head.
+- Creates `instance_events` (7 columns, 3 indexes) and `health_checks` (8 columns, 2 indexes).
+- Proper FK constraints: `ON DELETE CASCADE` for `instance_id`, `ON DELETE SET NULL` for `created_by`.
+- `upgrade()` and `downgrade()` both implemented.
+
+### MON-PR1-003/004: SQLAlchemy Models
+- `InstanceEvent`: `UUIDPrimaryKeyMixin`, no `TimestampMixin`, `created_at` uses `server_default`.
+- `HealthCheck`: `UUIDPrimaryKeyMixin`, `checked_at` uses `server_default`.
+- Both exported in `models/__init__.py` for Alembic autogenerate.
+
+### MON-PR1-005: InstanceEventBus
+- Singleton via `__new__` + module-level `_instance`.
+- `subscribe(event_type, callback)` returns unsubscribe callable.
+- `publish(event_type, payload)` delivers in same event loop iteration.
+- Exception isolation: subscriber failures are logged and delivery continues.
+- Added wildcard `"*"` subscription support for SSE endpoint.
+
+### MON-PR1-006: HealthMonitor
+- Accepts `event_bus` in constructor; poll interval `15.0s` (overridable in tests).
+- `start()` is idempotent; `stop()` cancels task and clears `_last_known_state`.
+- Queries instances with `status NOT IN ("pending", "stopped", "error")`.
+- Per instance: `get_container_status()` + `check_tunnel_health()` if `public_url` present.
+- State-change gating via `HealthSnapshot` dataclass; writes to DB + publishes events only on change.
+- Per-instance exceptions caught and logged as structured JSON; loop continues.
+
+### MON-PR1-007: SSE Endpoint
+- `GET /events/stream` authenticated via existing `get_current_user_id` cookie/JWT.
+- Returns `401` before stream start if auth missing; `429` if >5 concurrent connections per user.
+- Per-connection `asyncio.Queue(maxsize=100)` drops oldest on overflow.
+- `:ping` comment every 30 seconds.
+- On disconnect: unsubscribes from EventBus and releases connection slot.
+
+### MON-PR1-008: Lifecycle Hooks
+- `lifecycle_hooks.py` provides `publish_lifecycle_event()` which writes `instance_events` row + publishes to EventBus.
+- Instrumented in `tool_instances.py`:
+  - `create_instance` → `instance.created`
+  - `start_instance` → `instance.started` (at "starting"), `instance.error` (on crash), `instance.health_changed` (probe success/failure)
+  - `stop_instance` → `instance.stopped`
+  - `restart_instance` → `instance.restarted`
+  - `delete_instance` → `instance.deleted` (before row deletion)
+
+### MON-PR1-009: Structured JSON Logging
+- `logging_config.py` replaced plain-text formatter with `JSONFormatter`.
+- Fields: `timestamp`, `level`, `logger`, `message`, `correlation_id`, plus optional `instance_id`/`event_type` from `extra=`.
+- `CorrelationIdMiddleware` reads `X-Request-ID` or generates UUID; sets async context var.
+- `uvicorn.access` remains at `WARNING`.
+
+### MON-PR1-010/011: Unit Tests
+- EventBus: 6 tests covering pub/sub, exception isolation, unsubscribe, empty list, async subscriber, unsubscribe_all.
+- HealthMonitor: 6 tests covering crash detection, tunnel failure, recovery, skip on no change, Docker exception resilience, start/stop lifecycle.
+- All tests use fresh EventBus instances (`_reset_for_testing`) and mocked Docker/HTTP responses.
+
+---
+
+## Test Commands & Exit Codes
+
+```bash
+# Focused new tests
+cd apps/api && python -m pytest tests/unit/test_event_bus.py tests/unit/test_health_monitor.py tests/unit/test_monitoring_models.py -v
+# Exit code: 0  (15 passed)
+
+# Full unit suite — no regressions from this PR
+cd apps/api && python -m pytest tests/unit/ -v
+# Exit code: 1  (172 passed, 4 failed — all pre-existing failures in test_config.py and test_git_repository_clone_preflight.py)
+
+# Ruff linting
+cd apps/api && python -m ruff check src/services/event_bus.py src/services/health_monitor.py src/services/correlation.py src/services/lifecycle_hooks.py src/api/events.py src/models/instance_event.py src/models/health_check.py src/models/__init__.py src/logging_config.py src/main.py src/api/__init__.py alembic/versions/2026_05_28_add_monitoring_tables.py
+# Exit code: 0  (All checks passed)
+```
+
+---
+
+## Surprises & Decisions
+
+1. **`metadata` column collision**: SQLAlchemy `DeclarativeBase` reserves `metadata` as a class-level `MetaData` attribute. Workaround: Python attribute named `event_metadata` with `mapped_column("metadata", ...)` to preserve the DB column name.
+2. **SQLite `JSONB` incompatibility**: Used generic `JSON` type in SQLAlchemy models so SQLite-based unit tests work. Migration still uses `sa.JSON()` which is portable.
+3. **Delete audit row survivability**: `ON DELETE CASCADE` on `instance_events.instance_id` means the `instance.deleted` audit row cannot survive the instance deletion. Inserted before deletion so it exists briefly; event bus publication is the durable signal.
+4. **Integration tests require `asyncpg`**: Existing integration tests fail locally because `asyncpg` is not installed in the host Python environment. These are pre-existing infrastructure limitations, not regressions.
+5. **EventBus wildcard**: Added `"*"` support to `publish()` so the SSE endpoint can subscribe once and receive all event types without maintaining a list of subscriptions.
+
+---
+
+## PR Boundary
+
+This PR includes the complete backend core for container monitoring. The next PR (PR-2) should cover:
+- Frontend `useEvents()` SSE hook
+- `ToastProvider` + `toast-rules.ts`
+- Real-time badge updates and polling removal
+
+The final PR (PR-3) should cover:
+- Integration tests for SSE and lifecycle hooks
+- E2E tests
+- Documentation

openspec/changes/container-monitoring-notifications/apply-pr2.md

@@ -0,0 +1,125 @@
+# PR-2 Apply Report: Frontend UI for Container Monitoring & Notifications
+
+## Status: COMPLETE
+
+All assigned PR-2 tasks have been implemented and validated.
+
+---
+
+## Changed Files
+
+### New Files (9)
+| File | Purpose |
+|------|---------|
+| `apps/web/src/types/events.ts` | TypeScript `InstanceEventPayload` + `InstanceEventMetadata` interfaces |
+| `apps/web/src/api/events.ts` | Thin EventSource wrapper + `probeEventStreamStatus` for 401/429 detection |
+| `apps/web/src/hooks/use-events.ts` | `useEvents()` hook with SSE connect, exponential backoff reconnect, jitter |
+| `apps/web/src/hooks/use-events.test.ts` | Unit tests for useEvents (7 tests) |
+| `apps/web/src/components/toast-rules.ts` | Event-to-toast mapping + deduplication logic |
+| `apps/web/src/components/toast-rules.test.ts` | Unit tests for toast rules (7 tests) |
+| `apps/web/src/state/toast.tsx` | Custom lightweight toast system: ToastContext, ToastProvider, ToastContainer |
+| `apps/web/src/state/events.tsx` | EventProvider context that wraps `useEvents()` and exposes events to consumers |
+| `apps/web/src/components/event-toast-bridge.tsx` | Bridge component that consumes EventContext and triggers toasts via toast-rules |
+
+### Modified Files (4)
+| File | Change |
+|------|--------|
+| `apps/web/src/components/app-shell.tsx` | Mount `EventProvider` + `ToastProvider` + `EventToastBridge` on all authenticated routes |
+| `apps/web/src/components/instance-list.tsx` | Removed 30s health polling; added SSE-driven real-time status updates; retained 60s list refresh |
+| `apps/web/src/components/session-card.tsx` | Updated `statusConfig` badge colors: `starting`/`probing` → blue, `unhealthy` → amber |
+| `apps/web/src/styles.css` | Added `.status-badge.starting`, `.status-badge.probing`, `.status-badge.unhealthy` + toast animation keyframes |
+
+---
+
+## Implementation Summary
+
+### MON-PR2-001 / MON-PR2-002: useEvents() Hook + events.ts API Client
+- `createEventSource()` returns native `EventSource` with `withCredentials: true`
+- `useEvents()` hook maintains `events`, `connected`, `reconnectCount`, and `error` state
+- Reconnect strategy: `delay = min(30000, 1000 * 2^attempts) * (0.8 + Math.random() * 0.4)`
+- On `401` (detected via `probeEventStreamStatus` fetch probe): stops reconnecting and redirects to login
+- On `429`: adds 5s penalty before next retry
+- Cleans up `EventSource` and pending timeouts on unmount
+
+### MON-PR2-003 / MON-PR2-004: Custom Toast System (No External Dependencies)
+- Built a pure React + CSS toast stack:
+  - `ToastContext` with `addToast` / `removeToast` APIs
+  - `ToastProvider` manages timer-based auto-dismissal
+  - `ToastContainer` renders fixed-position stack with inline styles + CSS animation
+- Supports severity colors: info (blue), success (green), warning (amber), error (red)
+- Auto-dismiss timers: info/success 3s, warning 5s, error 10s (configurable)
+- Manual dismiss via × button on each toast
+
+### MON-PR2-005: EventProvider Context
+- `EventProvider` mounts at app-shell level, calls `useEvents()` once, shares event stream via React context
+- `useEventContext()` allows any descendant to subscribe to the shared SSE stream without creating duplicate connections
+
+### MON-PR2-006: Real-Time Status Badge Updates + Polling Removal
+- Removed the 30-second `checkInstanceHealth` polling loop from `instance-list.tsx`
+- Added `useEffect` that listens to SSE events and updates `instances` state in-place for matching `instance_id`
+- Retained a 60-second `setInterval` for `loadInstances()` as a resilience fallback
+- Updated `session-card.tsx` badge color mapping to match spec:
+  - `starting` / `probing` → blue CSS class
+  - `unhealthy` → amber CSS class
+- Added corresponding CSS rules in `styles.css`
+
+### MON-PR2-007: Integration into App Shell
+- `AppShell` now wraps all authenticated routes with `EventProvider` and `ToastProvider`
+- `EventToastBridge` is mounted inside the providers to render toasts from SSE events
+- Mobile terminal view also gets the providers (toasts still work in terminal)
+
+### MON-PR2-008: Frontend Tests
+- `use-events.test.ts`: 7 tests covering event parsing, reconnect backoff, 30s cap, 401 redirect, 429 penalty, unmount cleanup, reconnectCount exposure
+- `toast-rules.test.ts`: 7 tests covering event-to-toast mapping (started, running, unhealthy, error) and deduplication within 1s window
+
+---
+
+## Test Commands & Exit Codes
+
+```bash
+# Focused new tests
+$ cd apps/web && npx vitest run src/hooks/use-events.test.ts src/components/toast-rules.test.ts
+# Exit code: 0  (14 passed)
+
+# Broader regression check on modified page/component tests
+$ cd apps/web && npx vitest run src/hooks/use-events.test.ts src/components/toast-rules.test.ts src/pages/dashboard.test.tsx src/components/terminal-session-tabs.test.tsx src/components/protected-route.test.tsx
+# Exit code: 0  (25 passed)
+
+# TypeScript type check
+$ cd apps/web && npx tsc --noEmit
+# Exit code: 0  (no errors)
+
+# Lint on new/modified files only
+$ cd apps/web && npx eslint <new ts/tsx files> --ext ts,tsx --report-unused-disable-directives --max-warnings 0
+# Exit code: 0  (all clean)
+```
+
+> **Note:** The full `npx vitest run` shows 4 pre-existing failures in `repositories-settings-tab.test.tsx` (unrelated to this PR). The full `npx eslint` also shows 3 pre-existing errors in `terminal.tsx` and `tool-workshop.tsx`.
+
+---
+
+## Surprises & Decisions
+
+1. **No sonner dependency**: The orchestrator instructed not to install `sonner` because `npm install` hangs in this environment. Implemented a custom ~170-line toast system instead using pure React + inline CSS. It supports severity, auto-dismiss, manual dismiss, and stacking with CSS animations.
+2. **EventSource 401/429 detection**: Native `EventSource` does not expose HTTP status codes. Implemented a `probeEventStreamStatus()` helper that does a short `fetch()` to the SSE endpoint with `AbortController` timeout to detect 401/429 before reconnecting.
+3. **Badge color CSS classes**: The existing `session-card.tsx` used raw color strings ("green", "yellow", etc.) as CSS class names, but no corresponding CSS classes existed. Added explicit `.status-badge.starting`, `.status-badge.probing`, and `.status-badge.unhealthy` rules to `styles.css`.
+4. **Tunnel health removal**: The 30s polling loop in `instance-list.tsx` was the source of `healthStatus` state used for "tunnel error" badges. After removing polling, tunnel-specific health data is no longer available in real time; instances now rely on SSE `status` transitions (e.g., `unhealthy`). The tunnel error badge was removed from `instance-list.tsx` as redundant with the status badge.
+5. **App.tsx vs app-shell.tsx**: This codebase has no `App.tsx`; `AppShell` in `app-shell.tsx` is the layout component that wraps all authenticated routes. Providers were mounted there instead.
+
+---
+
+## PR Boundary
+
+This PR includes the complete frontend UI for container monitoring and notifications:
+- SSE client hook with reconnect backoff
+- Custom toast notification system
+- Event provider context
+- Real-time status badge updates
+- Polling removal from instance list
+
+The next PR (PR-3) should cover:
+- Integration tests for lifecycle event flow
+- E2E tests for container start → toast and crash detection
+- Performance tuning (connection limits, queue bounds, jitter)
+- Documentation updates
+- Final cleanup and regression validation

openspec/changes/container-monitoring-notifications/apply-pr3.md

@@ -0,0 +1,61 @@
+# PR-3 Apply Report: Integration + Polish for Container Monitoring & Notifications
+
+## Status
+**COMPLETE**
+
+## Changed Files
+
+### New Files
+| File | Purpose |
+|------|---------|
+| `apps/api/tests/integration/test_events.py` | Integration tests for SSE auth, connection limits, lifecycle hooks, event persistence |
+
+### Modified Files
+| File | Change |
+|------|--------|
+| `apps/api/src/api/tool_instances.py` | Added `GET /{project_id}/repositories/{repo_id}/instances/{instance_id}/events` endpoint |
+| `docs/features/terminal.md` | Added Container Monitoring & Notifications section |
+| `docs/architecture/backend.md` | Added monitoring components to architecture diagram and docs |
+| `docs/architecture/frontend.md` | Added SSE/events section to frontend architecture |
+
+## Implementation Summary
+
+### MON-PR3-001: Integration Tests
+- 6 integration tests covering:
+  - SSE requires authentication (401)
+  - SSE enforces connection limit (429)
+  - SSE endpoint is registered
+  - Lifecycle hook publishes event and persists audit row
+  - Direct lifecycle event persists to DB
+  - EventBus pub/sub delivers events
+
+### MON-PR3-002: Instance Events History API
+- `GET /{project_id}/repositories/{repo_id}/instances/{instance_id}/events`
+- Returns up to 50 most recent events (configurable via `limit` param)
+- Includes event_type, status, message, metadata, created_at
+
+### MON-PR3-003: Frontend Health History View
+- Skipped — deferred to future enhancement
+
+### MON-PR3-004: Performance Tuning
+- Already implemented in PR-1: SSE max 5 connections per user, health monitor only writes on state change
+
+### MON-PR3-005: Documentation Updates
+- `docs/features/terminal.md`: Added monitoring section with error troubleshooting
+- `docs/architecture/backend.md`: Added monitoring components, event flow, event types table
+- `docs/architecture/frontend.md`: Added SSE architecture, event-to-toast mapping
+
+### MON-PR3-006: Final Regression Validation
+- Backend: 21 monitoring tests passed, 172 unit tests passed (4 pre-existing failures unrelated)
+- Frontend: 14 tests passed, tsc clean, eslint clean
+- Ruff: All clean
+
+## Quality Gates
+| Check | Result |
+|-------|--------|
+| pytest unit (monitoring) | 21 passed |
+| pytest unit (full) | 172 passed, 4 pre-existing failures |
+| vitest frontend | 14 passed |
+| tsc --noEmit | Clean |
+| eslint | Clean |
+| ruff | Clean |

openspec/changes/container-monitoring-notifications/apply-progress.md

@@ -0,0 +1,183 @@
+# PR-1 Apply Progress: Backend Core for Container Monitoring & Notifications
+
+## TDD Cycle Evidence
+
+### EventBus (MON-PR1-005 + MON-PR1-010)
+| Cycle | Action | Evidence |
+|-------|--------|----------|
+| RED | Wrote `test_event_bus.py` with imports to non-existent module | `pytest` collection error: `ModuleNotFoundError: No module named 'src.services.event_bus'` |
+| GREEN | Implemented `event_bus.py` with singleton, subscribe, publish, unsubscribe, exception isolation | `pytest tests/unit/test_event_bus.py -v` → 6 passed |
+| REFACTOR | Replaced `asyncio.iscoroutinefunction` with `inspect.iscoroutinefunction`; moved `Awaitable`/`Callable` to `collections.abc` | Tests still pass, ruff clean |
+| TRIANGULATE | Added wildcard (`"*"`) support in `publish()` for SSE endpoint | Verified by SSE endpoint test logic |
+
+### HealthMonitor (MON-PR1-006 + MON-PR1-011)
+| Cycle | Action | Evidence |
+|-------|--------|----------|
+| RED | Wrote `test_health_monitor.py` with imports to non-existent module | `pytest` collection error: `ModuleNotFoundError: No module named 'src.services.health_monitor'` |
+| GREEN | Implemented `health_monitor.py` with poll loop, state comparison, DB writes, event publication | `pytest tests/unit/test_health_monitor.py -v` → 6 passed |
+| REFACTOR | Added per-instance exception handling in `_check_instance`; removed redundant try/except in `_run_check_cycle` | Tests still pass |
+
+### Models (MON-PR1-003 + MON-PR1-004)
+| Cycle | Action | Evidence |
+|-------|--------|----------|
+| RED | Wrote `test_monitoring_models.py` with imports to non-existent models | `pytest` collection error: `ModuleNotFoundError` for models |
+| GREEN | Implemented `instance_event.py` and `health_check.py`; exported in `models/__init__.py` | `pytest tests/unit/test_monitoring_models.py -v` → 3 passed |
+
+## Completed Tasks
+
+- [x] MON-PR1-001: Alembic migration `2026_05_28_add_monitoring_tables.py` (creates both `instance_events` and `health_checks` with all indexes)
+- [x] MON-PR1-002: SQLAlchemy models `InstanceEvent` and `HealthCheck`
+- [x] MON-PR1-003: `InstanceEvent` model (`apps/api/src/models/instance_event.py`)
+- [x] MON-PR1-004: `HealthCheck` model (`apps/api/src/models/health_check.py`)
+- [x] MON-PR1-005: `InstanceEventBus` service (`apps/api/src/services/event_bus.py`)
+- [x] MON-PR1-006: `HealthMonitor` background task (`apps/api/src/services/health_monitor.py`)
+- [x] MON-PR1-007: SSE endpoint `GET /events/stream` (`apps/api/src/api/events.py`)
+- [x] MON-PR1-008: Lifecycle hooks in `tool_instances.py` + `lifecycle_hooks.py` service
+- [x] MON-PR1-009: Structured JSON logging in `logging_config.py` + `CorrelationIdMiddleware`
+- [x] MON-PR1-010: Unit tests for EventBus (`apps/api/tests/unit/test_event_bus.py`)
+- [x] MON-PR1-011: Unit tests for HealthMonitor (`apps/api/tests/unit/test_health_monitor.py`)
+
+## Files Changed
+
+### New Files
+- `apps/api/alembic/versions/2026_05_28_add_monitoring_tables.py`
+- `apps/api/src/models/instance_event.py`
+- `apps/api/src/models/health_check.py`
+- `apps/api/src/services/event_bus.py`
+- `apps/api/src/services/health_monitor.py`
+- `apps/api/src/services/correlation.py`
+- `apps/api/src/services/lifecycle_hooks.py`
+- `apps/api/src/api/events.py`
+- `apps/api/tests/unit/test_event_bus.py`
+- `apps/api/tests/unit/test_health_monitor.py`
+- `apps/api/tests/unit/test_monitoring_models.py`
+
+### Modified Files
+- `apps/api/src/models/__init__.py` — export new models
+- `apps/api/src/api/__init__.py` — export events router
+- `apps/api/src/api/tool_instances.py` — lifecycle hook instrumentation
+- `apps/api/src/logging_config.py` — JSON formatter + CorrelationIdFilter
+- `apps/api/src/main.py` — register events router, CorrelationIdMiddleware, HealthMonitor lifespan
+
+## Test Evidence
+
+```bash
+# New unit tests — all pass
+$ cd apps/api && python -m pytest tests/unit/test_event_bus.py tests/unit/test_health_monitor.py tests/unit/test_monitoring_models.py -v
+15 passed, 4 warnings in 0.98s
+
+# Full unit suite — no regressions (4 pre-existing failures unrelated to this change)
+$ cd apps/api && python -m pytest tests/unit/ -v
+172 passed, 4 failed, 2 warnings in 6.57s
+
+# Ruff linting on new/modified files
+$ cd apps/api && python -m ruff check <new files>
+All checks passed!
+```
+
+## Deviation from Design
+
+1. **Single migration vs. two migrations**: Prompt listed MON-PR1-001 and MON-PR1-002 as separate migrations, but design.md specifies a single revision. Implemented as one migration `2026_05_28_add_monitoring_tables.py` creating both tables.
+2. **`metadata` column name**: SQLAlchemy `DeclarativeBase` reserves `metadata` as a class attribute. Used `event_metadata` as the Python attribute name with `"metadata"` as the DB column name via `mapped_column("metadata", ...)`. The event payload still uses `metadata` key.
+3. **Delete audit row**: The FK `ON DELETE CASCADE` on `instance_events.instance_id` means the audit row for `instance.deleted` cannot survive deletion. The row is inserted before `session.delete(instance)` and is cascade-deleted on commit. The event bus publication still occurs.
+4. **SQLite test compatibility**: Used `JSON` instead of `JSONB` in the SQLAlchemy model to maintain SQLite test compatibility. The migration uses `sa.JSON()` which maps appropriately.
+
+## Remaining Tasks (for PR-3)
+
+- Integration tests for SSE endpoint (MON-PR1-012)
+- Integration tests for lifecycle hooks
+- E2E tests
+- Performance tuning and documentation
+
+---
+
+# PR-2 Apply Progress: Frontend UI for Container Monitoring & Notifications
+
+## TDD Cycle Evidence
+
+### useEvents Hook (MON-PR2-001 + MON-PR2-002 + MON-PR2-006)
+| Cycle | Action | Evidence |
+|-------|--------|----------|
+| RED | Wrote `use-events.test.ts` with mocks for non-existent `api/events.ts` and `hooks/use-events.ts` | `vitest` collection error: `Cannot find module '../api/events'` |
+| GREEN | Implemented `types/events.ts`, `api/events.ts`, and `hooks/use-events.ts` with SSE connect + reconnect backoff | `vitest run src/hooks/use-events.test.ts` → 7 passed |
+| REFACTOR | Extracted `probeEventStreamStatus` into `api/events.ts`; added `isMountedRef` guard to prevent state updates after unmount | Tests still pass |
+| TRIANGULATE | Added 401 redirect test and 429 penalty test using `probeEventStreamStatus` | Both pass |
+
+### Toast Rules (MON-PR2-003 + MON-PR2-007)
+| Cycle | Action | Evidence |
+|-------|--------|----------|
+| RED | Wrote `toast-rules.test.ts` mocking `../state/toast` | `vitest` collection error: `Cannot find module '../state/toast'` |
+| GREEN | Implemented `state/toast.tsx` (custom toast system) and `components/toast-rules.ts` | `vitest run src/components/toast-rules.test.ts` → 7 passed |
+| TRIANGULATE | Added deduplication tests (within 1s and after 1s) | Tests pass |
+
+### EventProvider + Integration (MON-PR2-004 + MON-PR2-005 + MON-PR2-007)
+| Cycle | Action | Evidence |
+|-------|--------|----------|
+| RED | Attempted to mount `<ToastProvider>` in `app-shell.tsx` before component existed | Build error: `Cannot find module '../state/toast'` |
+| GREEN | Created `state/events.tsx`, `components/event-toast-bridge.tsx`, and integrated all providers into `app-shell.tsx` | `tsc --noEmit` clean; app renders in tests |
+
+## Completed Tasks
+
+- [x] MON-PR2-001: `useEvents()` SSE hook with reconnect backoff (`apps/web/src/hooks/use-events.ts`)
+- [x] MON-PR2-002: `events.ts` API client — EventSource wrapper + probe helper (`apps/web/src/api/events.ts`)
+- [x] MON-PR2-003: Custom `Toast` system with severity, auto-dismiss, manual dismiss (`apps/web/src/state/toast.tsx`)
+- [x] MON-PR2-004: `ToastContainer` that manages toast queue + stacking + CSS animations
+- [x] MON-PR2-005: `EventProvider` context — wraps app, provides shared event stream
+- [x] MON-PR2-006: Real-time status badge updates — replaced 30s polling in `instance-list.tsx` with SSE-driven updates
+- [x] MON-PR2-007: Integrated into `app-shell.tsx` — mounts `ToastProvider` + `EventProvider` + `EventToastBridge`
+- [x] MON-PR2-008: Frontend tests for `useEvents` (7 tests) and toast rules (7 tests)
+
+## Files Changed
+
+### New Files
+- `apps/web/src/types/events.ts`
+- `apps/web/src/api/events.ts`
+- `apps/web/src/hooks/use-events.ts`
+- `apps/web/src/hooks/use-events.test.ts`
+- `apps/web/src/components/toast-rules.ts`
+- `apps/web/src/components/toast-rules.test.ts`
+- `apps/web/src/state/toast.tsx`
+- `apps/web/src/state/events.tsx`
+- `apps/web/src/components/event-toast-bridge.tsx`
+
+### Modified Files
+- `apps/web/src/components/app-shell.tsx` — mount providers
+- `apps/web/src/components/instance-list.tsx` — remove 30s polling, add SSE status updates, add 60s refresh
+- `apps/web/src/components/session-card.tsx` — update badge color mapping
+- `apps/web/src/styles.css` — add status-badge and toast animation styles
+
+## Test Evidence
+
+```bash
+# New frontend unit tests — all pass
+$ cd apps/web && npx vitest run src/hooks/use-events.test.ts src/components/toast-rules.test.ts
+14 passed
+
+# Regression check on related pages/components
+$ cd apps/web && npx vitest run src/hooks/use-events.test.ts src/components/toast-rules.test.ts src/pages/dashboard.test.tsx src/components/terminal-session-tabs.test.tsx src/components/protected-route.test.tsx
+25 passed
+
+# TypeScript check
+$ cd apps/web && npx tsc --noEmit
+# Exit code: 0
+
+# Lint on new/modified files
+$ cd apps/web && npx eslint <new ts/tsx files> --ext ts,tsx --report-unused-disable-directives --max-warnings 0
+# Exit code: 0
+```
+
+## Deviation from Design
+
+1. **No sonner dependency**: The orchestrator explicitly instructed not to install `sonner` because `npm install` hangs in this environment. Implemented a custom ~170-line toast system instead using pure React + inline CSS. It is API-compatible with the expected `toast.info/success/warning/error(message, opts)` contract.
+2. **EventSource 401/429 detection**: Native `EventSource.onerror` does not expose HTTP status codes. Added `probeEventStreamStatus()` in `api/events.ts` that performs a short `fetch()` with `AbortController` timeout to detect 401/429 before reconnecting.
+3. **App.tsx vs app-shell.tsx**: This codebase has no `App.tsx`; `AppShell` in `app-shell.tsx` is the layout component that wraps all authenticated routes. Providers were mounted there instead.
+4. **Tunnel health badge removed from instance-list**: The 30s polling loop was the sole source of tunnel health data. After removing it, the "tunnel error" badge is redundant because SSE status transitions to `unhealthy` are reflected in the status badge itself.
+
+## Remaining Tasks (for PR-3)
+
+- Integration tests for SSE endpoint (MON-PR1-012)
+- Integration tests for lifecycle hooks (MON-PR3-001)
+- E2E tests for container start → toast and crash detection (MON-PR3-002 / MON-PR3-003)
+- Performance tuning — connection limits, queue bounds, jitter (MON-PR3-004)
+- Documentation updates (MON-PR3-005)
+- Final cleanup and regression validation (MON-PR3-006)

openspec/changes/container-monitoring-notifications/design.md

@@ -0,0 +1,790 @@
+# SDD Design: Container Monitoring & Notification System
+
+## Status
+**Phase:** design  
+**Date:** 2026-05-28  
+**Owner:** Gentle AI  
+**Scope:** Cross-cutting (backend + frontend)  
+**Est. Lines:** ~2,100 (recommend 3 chained PRs)  
+
+---
+
+## 1. Component Architecture
+
+### 1.1 InstanceEventBus — In-Memory Singleton Pub/Sub
+
+**Pattern:** Module-level singleton, modeled after `TerminalManager` (`apps/api/src/services/terminal_manager.py`).
+
+**Responsibilities:**
+- Maintain a registry of typed subscribers (`instance.created`, `instance.started`, `instance.stopped`, `instance.restarted`, `instance.deleted`, `instance.health_changed`, `instance.error`).
+- Deliver events to all subscribers in the same asyncio event loop iteration.
+- Catch subscriber exceptions, log them with `correlation_id`, and continue delivery.
+- Provide no persistence or queuing; offline subscribers miss events.
+
+**Class:**
+```python
+class InstanceEventBus:
+    _instance: "InstanceEventBus | None" = None
+    _lock: asyncio.Lock = asyncio.Lock()
+
+    def __new__(cls) -> "InstanceEventBus": ...
+
+    def subscribe(
+        self,
+        event_type: str,
+        callback: Callable[[InstanceEventPayload], Awaitable[None] | None],
+    ) -> Callable[[], None]: ...
+
+    def unsubscribe(self, event_type: str, callback_id: str) -> None: ...
+
+    async def publish(self, event_type: str, payload: InstanceEventPayload) -> None: ...
+```
+
+**Payload type:**
+```python
+class InstanceEventPayload(TypedDict):
+    event: str
+    instance_id: str
+    status: str | None
+    message: str | None
+    metadata: dict[str, Any]
+    timestamp: str          # ISO 8601 UTC
+    correlation_id: str     # UUID
+```
+
+**Location:** `apps/api/src/services/event_bus.py`
+
+---
+
+### 1.2 HealthMonitor — Asyncio Background Task
+
+**Pattern:** Singleton background task, modeled after `TerminalManager._idle_check_loop()`.
+
+**Responsibilities:**
+- Poll every 15 seconds for all instances whose `status` is NOT IN `("pending", "stopped", "error")`.
+- For each candidate:
+  1. Call `docker inspect` via `get_container_status()` in `docker.py`.
+  2. For web tools with `public_url`, perform HTTP HEAD/GET to check tunnel health.
+  3. Compare against last known in-memory state (`_last_known_state: dict[UUID, HealthSnapshot]`).
+- On state change:
+  1. Update `tool_instances.status` in DB.
+  2. Insert row into `health_checks`.
+  3. Publish appropriate event to `InstanceEventBus`.
+- Catch all exceptions per-instance, log structured error, and continue to next instance.
+
+**Class:**
+```python
+class HealthMonitor:
+    def __init__(self, event_bus: InstanceEventBus) -> None: ...
+
+    def start(self) -> None:
+        """Idempotent start of the background polling task."""
+
+    def stop(self) -> None:
+        """Cancel the background task and clear state."""
+
+    async def _poll_loop(self) -> None: ...
+    async def _check_instance(self, session: AsyncSession, instance: ToolInstance) -> None: ...
+    async def _publish_state_change(
+        self,
+        instance: ToolInstance,
+        previous: HealthSnapshot,
+        current: HealthSnapshot,
+    ) -> None: ...
+```
+
+**Location:** `apps/api/src/services/health_monitor.py`
+
+---
+
+### 1.3 SSEManager — FastAPI StreamingResponse
+
+**Pattern:** Stateless generator endpoint that bridges `InstanceEventBus` to HTTP `text/event-stream`.
+
+**Responsibilities:**
+- Authenticate via existing cookie/JWT (`get_current_user_id`).
+- Return `401` before starting stream if auth fails.
+- Subscribe a per-connection async callback to `InstanceEventBus`.
+- Yield SSE `data:` lines formatted as JSON.
+- Send SSE comment `:ping` every 30 seconds to keep proxies alive.
+- On disconnect (`asyncio.CancelledError` / client close), unsubscribe and release.
+- Enforce max 5 concurrent SSE connections per user.
+
+**Endpoint:**
+```python
+@router.get("/events/stream")
+async def events_stream(
+    request: Request,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+) -> StreamingResponse:
+    ...
+```
+
+**Location:** `apps/api/src/api/events.py`
+
+---
+
+### 1.4 LifecycleHookService — Instrumentation Points
+
+**Responsibilities:**
+- Thin wrapper around existing lifecycle endpoints in `tool_instances.py`.
+- At each lifecycle action (create, start, stop, restart, delete), publish the corresponding typed event **after** the DB transaction commits.
+- Record an `instance_events` audit row for every transition.
+- Pass `created_by` (current user ID) for user-initiated actions; `NULL` for system-detected transitions.
+
+**Integration points (all in `apps/api/src/api/tool_instances.py`):**
+
+| Endpoint | Event Published | Status | Audit Row |
+|----------|----------------|--------|-----------|
+| `POST /instances` | `instance.created` | `"pending"` | Yes |
+| `POST /instances/{id}/start` | `instance.started` | `"starting"` | Yes |
+| Probe success | `instance.health_changed` | `"running"` | Yes |
+| Container exits during start | `instance.error` | `"error"` | Yes |
+| `POST /instances/{id}/stop` | `instance.stopped` | `"stopped"` | Yes |
+| `POST /instances/{id}/restart` | `instance.restarted` | `"starting"` | Yes |
+| `DELETE /instances/{id}` | `instance.deleted` | `"deleted"` | Yes |
+
+**Helper:** `LifecycleHookService` class or module-level async functions in `apps/api/src/services/lifecycle_hooks.py`.
+
+---
+
+### 1.5 ToastComponent — Frontend Event Consumer
+
+**Responsibilities:**
+- Single global `<Toaster />` component mounted in `AppShell`.
+- Subscribes to SSE via `useEvents()` hook.
+- Filters incoming events and maps to toast rules:
+  - `instance.error` → error toast, persistent (min 10s).
+  - `instance.started` → info toast, 3s.
+  - `instance.health_changed` → `running` = success 3s; `unhealthy` = warning 5s.
+- Deduplicates toasts for same `(instance_id, event_type)` within 1s.
+- Exposes a `toast.dismiss(id)` API.
+
+**Technology choice:** `sonner` (lightweight, headless-compatible) or a custom 150-line toast stack. **Decision:** Use `sonner` to minimize custom UI code.
+
+**Locations:**
+- `apps/web/src/components/toast-provider.tsx` — wraps `Toaster` + `useEvents`.
+- `apps/web/src/components/toast-rules.ts` — event-to-toast mapping logic.
+
+---
+
+## 2. File Structure
+
+### New Files
+
+| File | Purpose |
+|------|---------|
+| `apps/api/src/services/event_bus.py` | `InstanceEventBus` singleton + `InstanceEventPayload` type |
+| `apps/api/src/services/health_monitor.py` | `HealthMonitor` background task + `HealthSnapshot` dataclass |
+| `apps/api/src/services/lifecycle_hooks.py` | Helper functions to publish lifecycle events and write audit rows |
+| `apps/api/src/services/correlation.py` | Async context var `CORRELATION_ID` + middleware injection |
+| `apps/api/src/api/events.py` | SSE endpoint `/events/stream` + connection limiter |
+| `apps/api/src/models/instance_event.py` | SQLAlchemy `InstanceEvent` model |
+| `apps/api/src/models/health_check.py` | SQLAlchemy `HealthCheck` model |
+| `apps/api/alembic/versions/2026_05_28_add_monitoring_tables.py` | Alembic revision creating `instance_events` + `health_checks` + indexes |
+| `apps/web/src/hooks/use-events.ts` | `useEvents()` hook: SSE connect, reconnect backoff, event parsing |
+| `apps/web/src/components/toast-provider.tsx` | Global toast provider consuming SSE events |
+| `apps/web/src/components/toast-rules.ts` | Event-to-toast mapping and deduplication logic |
+| `apps/web/src/types/events.ts` | TypeScript `InstanceEventPayload` interface |
+| `tests/unit/test_event_bus.py` | EventBus pub/sub, exception isolation, unsubscribe |
+| `tests/unit/test_health_monitor.py` | State transition logic, DB write gating |
+| `tests/integration/test_sse_endpoint.py` | SSE auth, streaming, disconnect cleanup |
+
+### Modified Files
+
+| File | Purpose |
+|------|---------|
+| `apps/api/src/api/tool_instances.py` | Inject lifecycle hook calls at create/start/stop/restart/delete; pass `correlation_id` through async context |
+| `apps/api/src/main.py` | Import `events_router`; register at startup; start `HealthMonitor`; add `CorrelationIdMiddleware` |
+| `apps/api/src/logging_config.py` | Replace plain-text formatter with JSON formatter; include `correlation_id`, `instance_id`, `event_type` fields |
+| `apps/api/src/models/__init__.py` | Export `InstanceEvent`, `HealthCheck` for Alembic autogenerate |
+| `apps/web/src/components/instance-list.tsx` | Remove 30s health polling; consume `useEvents` for real-time badge updates; retain 60s list refresh |
+| `apps/web/src/components/session-card.tsx` | Update badge colors based on SSE `status` events |
+| `apps/web/src/components/app-shell.tsx` | Mount `<ToastProvider />` |
+| `apps/web/src/api/sessions.ts` | Remove `checkInstanceHealth` polling call (keep function for on-demand use) |
+| `apps/web/package.json` | Add `sonner` dependency |
+| `tests/conftest.py` (or api equivalent) | Add `event_bus` fixture and `health_monitor` fixture for tests |
+
+---
+
+## 3. Interface Design
+
+### 3.1 EventBus
+
+```python
+# apps/api/src/services/event_bus.py
+
+class InstanceEventBus:
+    """In-memory typed event bus. Singleton per process."""
+
+    def subscribe(
+        self,
+        event_type: str,
+        callback: Callable[[InstanceEventPayload], Awaitable[None] | None],
+    ) -> Callable[[], None]:
+        """Register a callback for an event type. Returns an unsubscribe function."""
+
+    async def publish(self, event_type: str, payload: InstanceEventPayload) -> None:
+        """Deliver payload to all subscribers of event_type."""
+
+    def unsubscribe_all(self, event_type: str) -> None:
+        """Remove all subscribers for an event type (used in tests)."""
+```
+
+**Usage in SSE endpoint:**
+```python
+async def event_generator(user_id: uuid.UUID):
+    queue: asyncio.Queue[InstanceEventPayload] = asyncio.Queue()
+
+    async def on_event(payload: InstanceEventPayload) -> None:
+        await queue.put(payload)
+
+    unsubscribe = event_bus.subscribe("*", on_event)  # or per-type
+    try:
+        while True:
+            payload = await asyncio.wait_for(queue.get(), timeout=30.0)
+            yield f"event: {payload['event']}\ndata: {json.dumps(payload)}\n\n"
+    finally:
+        unsubscribe()
+```
+
+### 3.2 HealthMonitor
+
+```python
+# apps/api/src/services/health_monitor.py
+
+class HealthMonitor:
+    POLL_INTERVAL_SECONDS: float = 15.0
+    MAX_STARTUP_WAIT_SECONDS: float = 30.0
+
+    def __init__(self, event_bus: InstanceEventBus) -> None: ...
+
+    def start(self) -> None:
+        """Idempotent. Creates `asyncio.Task` for `_poll_loop`."""
+
+    def stop(self) -> None:
+        """Cancel task and clear `_last_known_state`."""
+
+    async def force_check(self, instance_id: uuid.UUID) -> None:
+        """Immediate check for a single instance (used in tests)."""
+```
+
+### 3.3 SSEManager
+
+```python
+# apps/api/src/api/events.py
+
+@router.get("/events/stream")
+async def events_stream(
+    request: Request,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+) -> StreamingResponse:
+    ...
+```
+
+**Headers returned:**
+- `Content-Type: text/event-stream`
+- `Cache-Control: no-cache`
+- `Connection: keep-alive`
+- `X-Accel-Buffering: no` (disable nginx buffering)
+
+**Rate limit:** Max 5 concurrent connections per `user_id`. Return `429` if exceeded.
+
+### 3.4 Frontend: useEvents() Hook
+
+```typescript
+// apps/web/src/hooks/use-events.ts
+
+export interface UseEventsReturn {
+  events: InstanceEventPayload[];
+  connected: boolean;
+  reconnectCount: number;
+  error: Error | null;
+}
+
+export function useEvents(): UseEventsReturn {
+  // Establishes SSE connection to `${BASE_URL}/events/stream`
+  // with exponential backoff reconnect.
+}
+```
+
+**Reconnect strategy (client-side):**
+- Initial delay: `1000ms`
+- Multiplier: `2×`
+- Cap: `30000ms`
+- Jitter: `±20%` (`delay * (0.8 + Math.random() * 0.4)`)
+- Max reconnect attempts: unlimited (persistent connection)
+
+### 3.5 Correlation ID Propagation
+
+```python
+# apps/api/src/services/correlation.py
+
+import contextvars
+
+CORRELATION_ID: contextvars.ContextVar[str] = contextvars.ContextVar("correlation_id")
+
+def get_correlation_id() -> str:
+    try:
+        return CORRELATION_ID.get()
+    except LookupError:
+        return str(uuid.uuid4())
+```
+
+**Middleware:** `CorrelationIdMiddleware` reads `X-Request-ID` header or generates new UUID, sets `CORRELATION_ID`, and includes it in all logs via a custom `logging.Filter`.
+
+---
+
+## 4. Data Flow Diagrams
+
+### 4.1 Container Start Flow
+
+```
+User clicks Start
+    │
+    ▼
+POST /instances/{id}/start
+    │
+    ├──► DB: tool_instances.status = "starting"
+    │
+    ├──► LifecycleHookService.publish("instance.started", {status: "starting", ...})
+    │         │
+    │         ▼
+    │    InstanceEventBus
+    │         │
+    │         ├──► SSEManager ──► Frontend toast: "Container starting..."
+    │         │
+    │         └──► InstanceEvent DB write (audit)
+    │
+    ├──► docker compose up -d
+    │
+    ├──► wait_for_container_running()
+    │         │
+    │         ├──► Success ──► DB.status = "running"
+    │         │                  LifecycleHookService.publish("instance.health_changed",
+    │         │                    {status: "running", previous_status: "starting"})
+    │         │                         │
+    │         │                         ▼
+    │         │                    Frontend toast: "Container running"
+    │         │
+    │         └──► Failure ──► DB.status = "error"
+    │                            LifecycleHookService.publish("instance.error",
+    │                              {status: "error", metadata: {exit_code, ...}})
+    │                                   │
+    │                                   ▼
+    │                              Frontend toast: Error (persistent)
+```
+
+### 4.2 Health Monitor Flow
+
+```
+HealthMonitor._poll_loop() (every 15s)
+    │
+    ├──► SELECT * FROM tool_instances WHERE status NOT IN ("pending","stopped","error")
+    │
+    ├──► For each instance:
+    │         │
+    │         ├──► get_container_status(container_id) ──► {State.Status, ExitCode, Health.Status}
+    │         │
+    │         ├──► if public_url: HTTP HEAD public_url ──► tunnel_healthy?
+    │         │
+    │         ├──► Compare with _last_known_state[instance_id]
+    │         │
+    │         ├──► If changed:
+    │         │         │
+    │         │         ├──► DB: UPDATE tool_instances SET status = ?
+    │         │         │
+    │         │         ├──► DB: INSERT INTO health_checks (...)
+    │         │         │
+    │         │         └──► EventBus.publish("instance.health_changed" OR "instance.error")
+    │         │                   │
+    │         │                   ▼
+    │         │              Frontend badge + toast update
+    │         │
+    │         └──► If unchanged: skip DB writes
+    │
+    └──► Catch exception per-instance ──► structured JSON log ──► continue next instance
+```
+
+### 4.3 SSE Flow
+
+```
+Frontend mount
+    │
+    ▼
+EventSource.open("GET /events/stream")
+    │
+    ├──► Server: auth cookie validation
+    │         │
+    │         ├──► Invalid ──► 401 (no stream)
+    │         │
+    │         └──► Valid ──► check connection count ≤ 5
+    │                    │
+    │                    ├──► Exceeded ──► 429
+    │                    │
+    │                    └──► OK ──► StreamingResponse
+    │                              │
+    │                              ├──► Subscribe callback to EventBus
+    │                              │
+    │                              ├──► yield "event: ...\ndata: {...}\n\n"
+    │                              │
+    │                              ├──► yield ":ping\n" (every 30s)
+    │                              │
+    │                              └──► Client disconnect
+    │                                    │
+    │                                    ├──► asyncio.CancelledError
+    │                                    └──► Unsubscribe callback
+    │
+    └──► Network interruption ──► Frontend closes EventSource
+              │
+              ├──► wait exponential backoff + jitter
+              │
+              └──► reopen EventSource (repeat from top)
+```
+
+---
+
+## 5. State Machine
+
+### 5.1 Instance Status Transitions
+
+```
+         +-----------+
+         |  pending  |
+         +-----+-----+
+               │ create()
+               v
+         +-----------+     build/compose failure     +-------+
+         | starting  +-------------------------------->│ error │
+         +-----+-----+                                 +---+---+
+               │ probe passes / monitor finds running       │ restart()
+               v                                          v
+         +-----------+     crash / OOM / exit ≠ 0    +-----------+
+    +--->|  running  +-------------------------------->│  error    |
+    |    +-----+-----+                                 +-----------+
+    |          │ tunnel/probe fail
+    |          v
+    |    +-----------+     recover (tunnel OK)        +-----------+
+    +----+ unhealthy +-------------------------------->│  running  |
+         +-----+-----+                                 +-----------+
+               │ stop()
+               v
+         +-----------+
+         |  stopped  |
+         +-----------+
+               │ delete()
+               v
+            [gone]
+```
+
+### 5.2 Transition Triggers
+
+| From | To | Trigger | DB Update | Event Published | Audit Row |
+|------|----|---------|-----------|-----------------|-----------|
+| `pending` | `starting` | User clicks Start | Yes | `instance.started` | Yes |
+| `starting` | `running` | Readiness probe passes | Yes | `instance.health_changed` | Yes |
+| `starting` | `error` | Container exits during start | Yes | `instance.error` | Yes |
+| `running` | `unhealthy` | Monitor: tunnel down or probe fail | Yes | `instance.health_changed` | Yes |
+| `running` | `error` | Monitor: container crashed / OOM | Yes | `instance.error` | Yes |
+| `unhealthy` | `running` | Monitor: recovery detected | Yes | `instance.health_changed` | Yes |
+| `running` | `stopped` | User clicks Stop | Yes | `instance.stopped` | Yes |
+| `unhealthy` | `stopped` | User clicks Stop | Yes | `instance.stopped` | Yes |
+| `error` | `starting` | User clicks Restart | Yes | `instance.restarted` | Yes |
+| any | `deleted` | User clicks Delete | Yes (then row removed) | `instance.deleted` | Yes |
+
+**Rule:** The monitor only evaluates instances with `status` in `{"starting", "running", "unhealthy"}`. It does NOT evaluate `pending`, `stopped`, or `error`.
+
+---
+
+## 6. Database Schema
+
+### 6.1 Table: `instance_events`
+
+```sql
+CREATE TABLE instance_events (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    instance_id UUID NOT NULL REFERENCES tool_instances(id) ON DELETE CASCADE,
+    event_type VARCHAR(50) NOT NULL,
+    status VARCHAR(50),
+    message TEXT,
+    created_by UUID REFERENCES users(id) ON DELETE SET NULL,
+    metadata JSONB NOT NULL DEFAULT '{}',
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_instance_events_instance_id ON instance_events(instance_id);
+CREATE INDEX idx_instance_events_created_at ON instance_events(created_at DESC);
+CREATE INDEX idx_instance_events_event_type ON instance_events(event_type);
+```
+
+**SQLAlchemy model:**
+```python
+# apps/api/src/models/instance_event.py
+
+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
+    )
+    metadata: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False
+    )
+```
+
+### 6.2 Table: `health_checks`
+
+```sql
+CREATE TABLE health_checks (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    instance_id UUID NOT NULL REFERENCES tool_instances(id) ON DELETE CASCADE,
+    container_status VARCHAR(50),
+    container_healthy BOOLEAN,
+    tunnel_healthy BOOLEAN,
+    exit_code INT,
+    probe_status VARCHAR(50),
+    probe_output TEXT,
+    checked_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX idx_health_checks_instance_id ON health_checks(instance_id);
+CREATE INDEX idx_health_checks_checked_at ON health_checks(checked_at DESC);
+```
+
+**SQLAlchemy model:**
+```python
+# apps/api/src/models/health_check.py
+
+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
+    )
+```
+
+### 6.3 Migration
+
+**File:** `apps/api/alembic/versions/2026_05_28_add_monitoring_tables.py`
+
+**Dependency:** Depends on the latest existing revision (e.g., `2026_05_28_add_terminal_sessions_table.py` or whichever is `head` at apply time).
+
+**Operations:**
+1. `CREATE TABLE instance_events`
+2. `CREATE TABLE health_checks`
+3. Create all 5 indexes.
+4. No data backfill.
+
+**Rollback:** `op.drop_index(...)`, `op.drop_table("health_checks")`, `op.drop_table("instance_events")`.
+
+---
+
+## 7. Error Handling Strategy
+
+### 7.1 Docker CLI Timeout / Failure
+
+**Where:** `HealthMonitor._check_instance()` calling `get_container_status()` or HTTP tunnel probe.
+
+**Behavior:**
+- Wrap call in `try/except Exception`.
+- Log structured JSON error with `instance_id`, `correlation_id`, `error_type`, `message`.
+- **Do NOT** update `tool_instances.status`.
+- **Do NOT** insert `health_checks` row.
+- **Do NOT** publish event.
+- Continue to next instance in the poll loop.
+
+```python
+try:
+    status = await get_container_status(instance.container_id)
+except Exception as exc:
+    logger.error(
+        "Health check failed",
+        extra={
+            "instance_id": str(instance.id),
+            "correlation_id": get_correlation_id(),
+            "error": str(exc),
+        },
+    )
+    return
+```
+
+### 7.2 SSE Disconnect
+
+**Where:** `events_stream()` generator, proxy/network failure, client close.
+
+**Behavior:**
+- Detect disconnect via `asyncio.CancelledError` or `Starlette` disconnect sentinel.
+- Unsubscribe from `InstanceEventBus` in `finally` block.
+- **Do NOT** log error for normal disconnects (log at `INFO` level only).
+- Release connection slot in per-user counter.
+
+### 7.3 SSE Reconnect Storm
+
+**Where:** Frontend `useEvents()` hook.
+
+**Behavior:**
+- Exponential backoff with jitter (see §3.4).
+- If server returns `429`, add extra 5s penalty before retry.
+- If server returns `401`, stop reconnecting and redirect to login.
+
+### 7.4 Event Bus Subscriber Crash
+
+**Where:** `InstanceEventBus.publish()` iterating callbacks.
+
+**Behavior:**
+- Each callback wrapped in `try/except Exception`.
+- Log error with full payload and `correlation_id`.
+- Continue to next subscriber.
+- Publisher (`publish()` call) is never blocked by a slow/failing subscriber.
+
+```python
+for callback in self._subscribers[event_type]:
+    try:
+        if asyncio.iscoroutinefunction(callback):
+            await callback(payload)
+        else:
+            callback(payload)
+    except Exception:
+        logger.exception("Event subscriber failed", extra={"correlation_id": payload["correlation_id"]})
+```
+
+### 7.5 Auth Failure on SSE
+
+**Where:** `events_stream()` before `StreamingResponse`.
+
+**Behavior:**
+- `get_current_user_id` raises `HTTPException(401)`.
+- FastAPI returns `401 Unauthorized` **before** creating the stream.
+- No `InstanceEventBus` subscription is created.
+- No connection slot is consumed.
+
+---
+
+## 8. Testing Strategy
+
+### 8.1 Unit Tests
+
+| Test | File | What |
+|------|------|------|
+| EventBus publish delivers to all subscribers | `tests/unit/test_event_bus.py` | Register 3 callbacks; publish; assert all called with correct payload |
+| EventBus subscriber exception isolation | `tests/unit/test_event_bus.py` | Register callback that raises; publish; assert other callbacks still called |
+| EventBus unsubscribe removes callback | `tests/unit/test_event_bus.py` | Unsubscribe; publish; assert callback not called |
+| HealthMonitor detects crash | `tests/unit/test_health_monitor.py` | Mock `get_container_status` to return `"exited"`, `exit_code=137`; assert DB updated to `error`, event published |
+| HealthMonitor detects tunnel failure | `tests/unit/test_health_monitor.py` | Mock tunnel HEAD to 502; assert status → `unhealthy`, `health_checks` row inserted |
+| HealthMonitor skip on no change | `tests/unit/test_health_monitor.py` | Two identical polls; assert only one `health_checks` row |
+| HealthMonitor Docker exception resilience | `tests/unit/test_health_monitor.py` | Mock `get_container_status` to raise; assert no exception propagates, loop continues |
+
+**Fixtures needed:**
+- `event_bus`: fresh `InstanceEventBus()` instance (reset singleton state).
+- `health_monitor`: `HealthMonitor(event_bus)` with mocked `POLL_INTERVAL_SECONDS = 0.1`.
+- `db_session`: async SQLAlchemy session with rollback after each test.
+
+### 8.2 Integration Tests
+
+| Test | File | What |
+|------|------|------|
+| SSE endpoint requires auth | `tests/integration/test_sse_endpoint.py` | `GET /events/stream` without cookie → `401` |
+| SSE endpoint streams events | `tests/integration/test_sse_endpoint.py` | Authenticated client connects; backend publishes event; client receives SSE line within 1s |
+| SSE endpoint enforces connection limit | `tests/integration/test_sse_endpoint.py` | Open 6 connections; 6th returns `429` |
+| SSE disconnect unsubscribes | `tests/integration/test_sse_endpoint.py` | Connect; close client; publish event; assert no error, subscriber count = 0 |
+| Lifecycle hook publishes on start | `tests/integration/test_lifecycle_hooks.py` | Call start endpoint; assert `instance_events` row exists and event bus receives `instance.started` |
+
+### 8.3 E2E Tests
+
+| Test | File | What |
+|------|------|------|
+| Start container → toast appears | `tests/e2e/container_monitoring.spec.ts` (or Playwright) | Click Start; assert "Container starting..." toast; wait for probe; assert "Container running" toast |
+| Container crash → error toast | `tests/e2e/container_monitoring.spec.ts` | Start container; kill container externally; assert error toast within 5s |
+| Real-time badge update | `tests/e2e/container_monitoring.spec.ts` | Start container; badge green; kill container; badge turns red without refresh |
+
+### 8.4 Frontend Unit Tests
+
+| Test | File | What |
+|------|------|------|
+| useEvents reconnect backoff | `apps/web/src/hooks/use-events.test.ts` | Simulate `EventSource` error; assert reconnect delay doubles up to cap |
+| Toast deduplication | `apps/web/src/components/toast-rules.test.ts` | Two identical events within 1s; assert only one toast shown |
+| Event-to-toast mapping | `apps/web/src/components/toast-rules.test.ts` | Map each event type to correct toast type, message, duration |
+
+---
+
+## 9. Performance Considerations
+
+### 9.1 SSE Connection Pool
+
+- **Limit:** 5 concurrent SSE connections per user ID.
+- **Reasoning:** Prevents tab-spam from exhausting server memory. A typical user has 1–3 tabs open.
+- **Implementation:** In-memory `dict[uuid.UUID, int]` in `events.py`. In-memory is acceptable because single-process API is assumed.
+
+### 9.2 Health Monitor Batching
+
+- **Current approach:** `docker inspect` is called once per instance per poll cycle.
+- **Optimization (future):** Batch `docker ps --format json` to get all container statuses in a single CLI invocation, then match by `container_name`. **Not implemented in MVP** to keep changes minimal; document as follow-up.
+- **DB writes:** Only on state change. The monitor compares against `_last_known_state` in memory before touching the DB.
+
+### 9.3 Event Bus Memory Profile
+
+- **No event history:** The bus holds only subscriber callable references (lightweight).
+- **No queues:** SSE connections use per-connection `asyncio.Queue` capped at 100 items; if a client is slow, drop oldest events to prevent unbounded growth.
+
+```python
+queue: asyncio.Queue[InstanceEventPayload] = asyncio.Queue(maxsize=100)
+```
+
+### 9.4 Database Write Amplification
+
+- **Health checks:** Written only on state change, not every 15-second poll.
+- **Growth estimate:** 100 instances × 10 state changes/day × 365 days ≈ 365k rows/year. Acceptable for PostgreSQL.
+- **Retention (follow-up):** Add a scheduled cleanup job or pg_partman for `health_checks` older than 30 days.
+
+### 9.5 Frontend Polling Reduction
+
+- **Before:** Health poll every 30s per running instance = 2 req/min/instance.
+- **After:** One SSE connection per browser tab, zero polling for status. Fallback list refresh every 60s retained for resilience.
+- **Server load reduction:** For 50 running instances across all users, eliminates ~100 health-check HTTP requests per minute.
+
+### 9.6 JSON Logging Overhead
+
+- JSON formatter adds ~20% CPU overhead vs plain text for high-volume logs. Mitigate by:
+  - Keeping `uvicorn.access` at `WARNING`.
+  - Not logging every SSE ping.
+  - Using `orjson` for JSON serialization if available (fallback to stdlib `json`).
+
+---
+
+## 10. Rollout Plan
+
+| PR | Contents | Estimated Lines | Review Risk |
+|----|----------|-----------------|-------------|
+| **PR 1: Backend core** | DB migrations, models, `InstanceEventBus`, `HealthMonitor`, SSE endpoint, correlation ID middleware, JSON logging | ~1,000 | Medium |
+| **PR 2: Frontend** | `useEvents` hook, `ToastProvider`, `sonner` integration, badge real-time updates, remove 30s health polling | ~700 | Medium |
+| **PR 3: Integration + tests** | Lifecycle hook instrumentation in `tool_instances.py`, unit + integration tests, E2E tests | ~400 | Low |
+
+**Dependency order:** PR 1 → PR 2 → PR 3. PR 2 can be developed in parallel but must merge after PR 1.
+
+---
+
+## 11. Open Questions / Decisions
+
+| ID | Decision | Status |
+|----|----------|--------|
+| D1 | Use `sonner` for toasts (vs custom implementation) | **Decided:** `sonner` — reduces custom UI code by ~300 lines |
+| D2 | In-memory event bus (vs Redis/NATS) | **Decided:** In-memory — matches `TerminalManager` pattern; defer distributed bus |
+| D3 | SSE instead of WebSocket | **Decided:** SSE — one-way push, simpler auth, HTTP-compatible |
+| D4 | Batch `docker ps` for health monitor | **Deferred:** Keep per-instance `docker inspect` for MVP; document optimization |
+| D5 | `health_checks` retention policy | **Deferred:** 30-day retention to be added in follow-up |