fix(config-profiles): show Git mount refresh progress

Disable duplicate refresh requests and show in-progress feedback while Git mount sources are refreshed.

apps/api/src/api/config/config_profiles.py

@@ -1,6 +1,7 @@
 """Config profile API endpoints."""
 
 import logging
+import os
 import uuid
 
 from fastapi import APIRouter, Depends, HTTPException, Query, status
@@ -9,7 +10,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import selectinload
 
 from src.auth.dependencies import get_current_user_id, get_db_session
-from src.models import ConfigProfile, ConfigProfileInclude, UserConfig
+from src.models import ConfigProfile, ConfigProfileInclude, ToolInstance, UserConfig
 from src.schemas.config import (
     ConfigProfileCreate,
     ConfigProfileIncludeUpdate,
@@ -43,6 +44,34 @@ logger = logging.getLogger(__name__)
 router = APIRouter(prefix="/config-profiles", tags=["config-profiles"])
 
 
+async def _running_profile_outcomes(
+    session: AsyncSession, profile_id: uuid.UUID
+) -> list[dict[str, str]]:
+    """Report running instances that must restart to adopt a profile revision."""
+    result = await session.execute(
+        select(ToolInstance).where(ToolInstance.status == "running")
+    )
+    outcomes: list[dict[str, str]] = []
+    for instance in result.scalars().all():
+        if instance.selected_config_profile_id is None:
+            continue
+        resolved = await resolve_profile(session, instance.selected_config_profile_id)
+        dependencies = {resolved.profile_id} | {
+            uuid.UUID(item["id"])
+            for item in resolved.included_profiles
+            if item.get("id")
+        }
+        if profile_id in dependencies:
+            outcomes.append(
+                {
+                    "instance_id": str(instance.id),
+                    "status": "restart_required",
+                    "reason": "Existing instance must restart to adopt shared profile mounts",
+                }
+            )
+    return outcomes
+
+
 @router.get("", response_model=list[ConfigProfileResponse])
 async def list_config_profiles(
     project_id: str | None = Query(None, description="Filter by project compatibility"),
@@ -140,8 +169,51 @@ async def update_config_profile(
         )
 
     profile = await update_profile(session, profile, data)
+    response = profile_to_response(profile)
+    response["refresh_outcomes"] = await _running_profile_outcomes(session, profile.id)
     logger.debug("Updated config profile %s", profile.id)
-    return profile_to_response(profile)
+    return response
+
+
+@router.post("/{profile_id}/refresh-git-mounts")
+async def refresh_profile_git_mounts(
+    profile_id: str,
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+):
+    """Refresh canonical Git mount sources used by running profile instances."""
+    profile = await get_profile_with_includes(session, uuid.UUID(profile_id))
+    if profile is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Profile not found"
+        )
+    if profile.user_id != current_user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized"
+        )
+
+    # Import lazily: instance_service imports tool schemas that transitively
+    # load API routers, so importing it during router initialization cycles.
+    from src.services.tool.instance_service import resolve_git_mounts
+
+    outcomes = await _running_profile_outcomes(session, profile.id)
+    for outcome in outcomes:
+        instance = await session.get(ToolInstance, uuid.UUID(outcome["instance_id"]))
+        if (
+            instance is None
+            or not instance.compose_path
+            or instance.selected_config_profile_id is None
+        ):
+            continue
+        resolved = await resolve_profile(session, instance.selected_config_profile_id)
+        await resolve_git_mounts(
+            session,
+            resolved,
+            os.path.dirname(instance.compose_path),
+        )
+        outcome["status"] = "refreshed"
+        outcome["reason"] = "Canonical Git mount source refreshed in place"
+    return {"refresh_outcomes": outcomes}
 
 
 @router.delete("/{profile_id}", status_code=status.HTTP_204_NO_CONTENT)
@@ -161,6 +233,16 @@ async def delete_config_profile(
             status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized"
         )
 
+    outcomes = await _running_profile_outcomes(session, profile.id)
+    if outcomes:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail={
+                "message": "Profile is still used by running instances",
+                "outcomes": outcomes,
+            },
+        )
+
     await session.delete(profile)
     await session.commit()
 

apps/api/src/api/system/terminal.py

@@ -3,6 +3,8 @@
 import asyncio
 import json
 import logging
+from asyncio import QueueFull
+from json import JSONDecodeError
 import uuid
 from contextlib import suppress
 
@@ -31,6 +33,9 @@ from src.services.terminal.terminal_manager import (
 router = APIRouter()
 logger = logging.getLogger(__name__)
 
+MAX_PENDING_INPUT_MESSAGES = 64
+MAX_TERMINAL_INPUT_BYTES = 1024 * 1024
+
 
 class SessionRef:
     """Mutable reference to a terminal session, allowing updates during reset."""
@@ -320,8 +325,38 @@ async def _handle_terminal_websocket(
                 )
 
 
+async def _input_write_loop(input_queue: asyncio.Queue[tuple[object, bytes]]) -> None:
+    """Serialize PTY writes without blocking terminal control messages."""
+    while True:
+        session, data = await input_queue.get()
+        try:
+            await session.write_input(data)  # type: ignore[attr-defined]
+        except Exception:
+            logger.debug("Terminal input write failed", exc_info=True)
+        finally:
+            input_queue.task_done()
+
+
+def _queue_terminal_input(
+    input_queue: asyncio.Queue[tuple[object, bytes]], session: object, data: bytes
+) -> bool:
+    """Queue bounded terminal input without blocking control-message processing."""
+    if len(data) > MAX_TERMINAL_INPUT_BYTES:
+        return False
+    try:
+        input_queue.put_nowait((session, data))
+    except QueueFull:
+        return False
+    return True
+
+
 async def _write_loop(session_ref: SessionRef, websocket, instance_id: str) -> None:
-    """Read input from WebSocket and send to container."""
+    """Receive terminal messages while a dedicated worker serializes PTY input."""
+    input_queue: asyncio.Queue[tuple[object, bytes]] = asyncio.Queue(
+        maxsize=MAX_PENDING_INPUT_MESSAGES
+    )
+    input_writer = asyncio.create_task(_input_write_loop(input_queue))
+
     try:
         while True:
             session = session_ref.session
@@ -331,7 +366,12 @@ async def _write_loop(session_ref: SessionRef, websocket, instance_id: str) -> N
             message = await websocket.receive()
             if message["type"] == "websocket.receive":
                 if "bytes" in message:
-                    await session.write_input(message["bytes"])
+                    if not _queue_terminal_input(
+                        input_queue, session, message["bytes"]
+                    ):
+                        logger.warning("Terminal input buffer exceeded for %s", instance_id)
+                        await websocket.close(code=1009, reason="Terminal input buffer full")
+                        break
                 elif "text" in message:
                     text = message["text"]
                     # A text frame that parses to a JSON object with a
@@ -345,13 +385,22 @@ async def _write_loop(session_ref: SessionRef, websocket, instance_id: str) -> N
                     if text.startswith("{"):
                         try:
                             parsed = json.loads(text)
-                        except json.JSONDecodeError:
+                        except JSONDecodeError:
                             parsed = None
                         if isinstance(parsed, dict) and "type" in parsed:
                             ctrl = parsed
 
                     if ctrl is None:
-                        await session.write_input(text.encode("utf-8"))
+                        if not _queue_terminal_input(
+                            input_queue, session, text.encode("utf-8")
+                        ):
+                            logger.warning(
+                                "Terminal input buffer exceeded for %s", instance_id
+                            )
+                            await websocket.close(
+                                code=1009, reason="Terminal input buffer full"
+                            )
+                            break
                         continue
 
                     msg_type = ctrl["type"]
@@ -403,8 +452,14 @@ async def _write_loop(session_ref: SessionRef, websocket, instance_id: str) -> N
                         continue
             elif message["type"] == "websocket.disconnect":
                 break
-    except Exception:
+    except WebSocketDisconnect:
         pass
+    except (RuntimeError, TypeError, ValueError) as exc:
+        logger.debug("Terminal WebSocket receive loop ended: %s", exc)
+    finally:
+        input_writer.cancel()
+        with suppress(asyncio.CancelledError):
+            await input_writer
 
 
 async def _heartbeat_loop(websocket: WebSocket) -> None:

apps/api/src/schemas/config/config_profile.py

@@ -240,6 +240,12 @@ class ConfigProfileIncludeUpdate(BaseModel):
         return v
 
 
+class ConfigProfileRefreshOutcome(BaseModel):
+    instance_id: str
+    status: str
+    reason: str | None = None
+
+
 class ConfigProfileResponse(BaseModel):
     id: str
     user_id: str
@@ -256,6 +262,7 @@ class ConfigProfileResponse(BaseModel):
     includes: list[dict]
     created_at: str
     updated_at: str
+    refresh_outcomes: list[ConfigProfileRefreshOutcome] = Field(default_factory=list)
 
 
 class DefaultProfilesUpdate(BaseModel):

apps/api/src/seeds/builtin_tool_types.py

@@ -5,47 +5,17 @@ import logging
 from sqlalchemy import select, text
 
 from src.database import SessionLocal
-from src.models import ToolType
+from src.models import ToolDefinitionManifest, ToolType
 
 logger = logging.getLogger(__name__)
 
+# All supported built-in tools run their long-lived process with these IDs.
+# Canonical writable Config Profile mounts can therefore be shared without
+# per-instance ownership changes.
+BUILTIN_USER_UID = 1000
+BUILTIN_USER_GID = 1000
 
-async def _table_exists(session, table_name: str) -> bool:
-    """Check if a table exists in the database."""
-    try:
-        result = await session.execute(
-            text(
-                """
-                SELECT EXISTS (
-                    SELECT FROM information_schema.tables
-                    WHERE table_schema = 'public'
-                    AND table_name = :table_name
-                )
-            """
-            ),
-            {"table_name": table_name},
-        )
-        return result.scalar() or False
-    except Exception:
-        return False
-
-
-async def seed_builtin_tool_types():
-    """Create or update built-in tool types in the database.
-
-    Built-in tool types have no creator (created_by_id=None) and provide
-    out-of-the-box tools for users without requiring manual tool creation.
-    """
-    async with SessionLocal() as session:
-        # Check if tool_types table exists before attempting to seed
-        if not await _table_exists(session, "tool_types"):
-            logger.warning(
-                "tool_types table does not exist. Skipping seeding. "
-                "Migrations may not have run yet."
-            )
-            return
-
-        builtin_types = [
+BUILTIN_TOOL_TYPES = [
     {
         "name": "code-server",
         "display_name": "VS Code Server",
@@ -83,6 +53,8 @@ services:
     container_name: {{TOOL_NAME}}
     environment:
       - JUPYTER_ENABLE_LAB=yes
+      - NB_UID=1000
+      - NB_GID=1000
     volumes:
       - {{REPO_PATH}}:/home/jovyan/work
     ports:
@@ -102,31 +74,95 @@ services:
   opencode:
     image: node:20-slim
     container_name: {{TOOL_NAME}}
-    working_dir: /home/user/{{WORKSPACE_NAME}}
+    working_dir: /home/node/{{WORKSPACE_NAME}}
     volumes:
-      - {{REPO_PATH}}:/home/user/{{WORKSPACE_NAME}}
+      - {{REPO_PATH}}:/home/node/{{WORKSPACE_NAME}}
     ports:
       - "3000:3000"
     command: >
-      sh -c "set -x &&
-             apt-get update && apt-get install -y git ca-certificates &&
-             echo 'Installing opencode...' &&
-             npm install -g opencode-ai 2>&1 || echo 'ERROR: npm install failed' &&
-             which opencode || echo 'ERROR: opencode not in PATH' &&
-             npm bin -g &&
-             ls -la $(npm bin -g) || echo 'ERROR: global bin dir not found' &&
-             echo 'export PATH=\"$(npm bin -g):\\$PATH\"' >> /root/.bashrc &&
-             echo 'cd /home/user/{{WORKSPACE_NAME}}' >> /root/.bashrc &&
-             echo 'OpenCode installation complete' &&
-             exec tail -f /dev/null"
+      sh -ec "apt-get update && apt-get install -y git ca-certificates &&
+              npm install -g opencode-ai &&
+              exec setpriv --reuid=node --regid=node --init-groups opencode server"
     stdin_open: true
     tty: true
     restart: 'no'""",
         "required_variables": ["REPO_PATH", "TOOL_NAME"],
     },
-        ]
+]
 
-        for tool_data in builtin_types:
+
+def _standardize_builtin_manifest_user(manifest: dict) -> bool:
+    """Set the built-in manifest user to the shared UID/GID in place.
+
+    The helper deliberately recognizes only Headquarter's conventional
+    ``user`` account so it cannot rewrite a future custom tool definition.
+    """
+    user = manifest.get("user")
+    if not isinstance(user, dict) or user.get("name") != "user":
+        return False
+
+    changed = user.get("uid") != BUILTIN_USER_UID or user.get("gid") != BUILTIN_USER_GID
+    if changed:
+        user["uid"] = BUILTIN_USER_UID
+        user["gid"] = BUILTIN_USER_GID
+    return changed
+
+
+async def _standardize_pi_agent_manifest(session) -> None:
+    """Bring the built-in Pi Agent manifest in line with shared mount IDs."""
+    manifest_definition = await session.scalar(
+        select(ToolDefinitionManifest).where(
+            ToolDefinitionManifest.name == "pi-agent",
+            ToolDefinitionManifest.created_by_id.is_(None),
+        )
+    )
+    if manifest_definition is None:
+        return
+
+    manifest = dict(manifest_definition.manifest)
+    if _standardize_builtin_manifest_user(manifest):
+        manifest_definition.manifest = manifest
+        logger.info("Standardized built-in Pi Agent user to 1000:1000")
+
+
+async def _table_exists(session, table_name: str) -> bool:
+    """Check if a table exists in the database."""
+    try:
+        result = await session.execute(
+            text(
+                """
+                SELECT EXISTS (
+                    SELECT FROM information_schema.tables
+                    WHERE table_schema = 'public'
+                    AND table_name = :table_name
+                )
+            """
+            ),
+            {"table_name": table_name},
+        )
+        return result.scalar() or False
+    except Exception:
+        return False
+
+
+async def seed_builtin_tool_types():
+    """Create or update built-in tool types in the database.
+
+    Built-in tool types have no creator (created_by_id=None) and provide
+    out-of-the-box tools for users without requiring manual tool creation.
+    """
+    async with SessionLocal() as session:
+        # Check if tool_types table exists before attempting to seed
+        if not await _table_exists(session, "tool_types"):
+            logger.warning(
+                "tool_types table does not exist. Skipping seeding. "
+                "Migrations may not have run yet."
+            )
+            return
+
+        await _standardize_pi_agent_manifest(session)
+
+        for tool_data in BUILTIN_TOOL_TYPES:
             existing = await session.scalar(
                 select(ToolType).where(ToolType.name == tool_data["name"])
             )

apps/api/src/services/config/config_profile_resolver.py

@@ -6,6 +6,7 @@ and cycle protection.
 
 import logging
 import os
+import tempfile
 import uuid
 from dataclasses import dataclass, field
 from typing import Any
@@ -481,6 +482,7 @@ def apply_resolved_profile(
     instance_dir: str,
     resolved: ResolvedProfile,
     home_dir: str = "/root",
+    working_dir: str | None = None,
 ) -> tuple[dict[str, str], dict[str, str], list[dict], dict[str, Any]]:
     """Apply a resolved profile to an instance directory.
 
@@ -489,6 +491,8 @@ def apply_resolved_profile(
     Args:
         instance_dir: Path to the instance directory.
         resolved: The resolved profile.
+        home_dir: Container home directory used for path expansion.
+        working_dir: Container working directory for top-level profile files.
 
     Returns:
         Tuple of (env_vars, files, volume_mounts, runtime_hints).
@@ -501,49 +505,57 @@ def apply_resolved_profile(
 
     instance_path = Path(instance_dir)
     env_vars = dict(resolved.env_vars)
-    files = dict(resolved.files)
+    working_dir = working_dir or home_dir
     volume_mounts = []
 
-    # Write profile files to instance directory
-    for file_path, content in files.items():
-        full_path = instance_path / file_path
-        try:
-            full_path.resolve().relative_to(instance_path.resolve())
-        except ValueError:
-            logger.warning(
-                "Profile file path escapes instance directory: %s", file_path
-            )
-            continue
-        full_path.parent.mkdir(parents=True, exist_ok=True)
-        full_path.write_text(content)
+    # Profile content belongs to the profile, not an individual tool instance.
+    # Keeping it beside the instance root gives every compatible instance the
+    # same host source while retaining the existing instance storage setting.
+    profile_dir = instance_path.parent / "config-profiles" / str(resolved.profile_id)
+    files_dir = profile_dir / "files"
+    mounts_dir = profile_dir / "mounts"
 
-    # Stage mount directories and prepare directory-level volume mounts.
-    # Each ResolvedMount targets a container directory; we stage all of its
-    # files under a single host directory and bind-mount that directory. This
-    # keeps the target directory writable by the container user, instead of
-    # having Docker create a root-owned parent directory when only individual
-    # files are mounted.
+    def write_canonical_file(root: Path, relative_path: str, content: str) -> Path | None:
+        path = root / relative_path
+        try:
+            path.resolve().relative_to(root.resolve())
+        except ValueError:
+            logger.warning("Profile file path escapes canonical storage: %s", relative_path)
+            return None
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with tempfile.NamedTemporaryFile(
+            mode="w", encoding="utf-8", dir=path.parent, delete=False
+        ) as temporary_file:
+            temporary_file.write(content)
+            temporary_path = Path(temporary_file.name)
+        temporary_path.replace(path)
+        return path
+
+    # Top-level profile files are individual bind mounts under the working
+    # directory. They therefore cannot mask the workspace directory itself.
+    for file_path, content in resolved.files.items():
+        canonical_file = write_canonical_file(files_dir, file_path, content)
+        if canonical_file is None:
+            continue
+        volume_mounts.append(
+            {
+                "source": str(canonical_file),
+                "target": os.path.normpath(os.path.join(working_dir, file_path)),
+                "type": "bind",
+                "readonly": False,
+            }
+        )
+
+    # Explicit profile mounts remain directory-level bind mounts, but use the
+    # same profile-scoped canonical source for every instance.
     for mount in resolved.mounts.values():
         if not mount.files:
             continue
 
-        expanded_target = os.path.normpath(
-            expand_container_path(mount.target, home_dir)
-        )
-        mount_dir = (
-            instance_path / "mounts" / expanded_target.lstrip("/").replace("/", "_")
-        )
-        mount_dir.mkdir(parents=True, exist_ok=True)
-
+        expanded_target = os.path.normpath(expand_container_path(mount.target, home_dir))
+        mount_dir = mounts_dir / expanded_target.lstrip("/").replace("/", "_")
         for file_path, content in mount.files.items():
-            full_path = mount_dir / file_path
-            try:
-                full_path.resolve().relative_to(mount_dir.resolve())
-            except ValueError:
-                logger.warning("Mount file path escapes mount directory: %s", file_path)
-                continue
-            full_path.parent.mkdir(parents=True, exist_ok=True)
-            full_path.write_text(content)
+            write_canonical_file(mount_dir, file_path, content)
 
         volume_mounts.append(
             {
@@ -554,7 +566,9 @@ def apply_resolved_profile(
             }
         )
 
-    return env_vars, files, volume_mounts, resolved.runtime_hints
+    # Files are now mounted directly from canonical storage, not copied into
+    # the instance directory for write_config_files().
+    return env_vars, {}, volume_mounts, resolved.runtime_hints
 
 
 def expand_container_path(path: str, home_dir: str) -> str:

apps/api/src/services/tool/instance_service.py

@@ -2,7 +2,9 @@
 
 import asyncio
 import contextlib
+import fcntl
 import glob as glob_module
+import hashlib
 import logging
 import os
 import re
@@ -125,11 +127,11 @@ def _chown_staged_mounts(
     uid: int,
     gid: int,
 ) -> None:
-    """Recursively chown staged mount sources to the container user.
+    """Recursively chown instance-local mount sources to the container user.
 
-    Config-profile mounts, git mounts, and SSH key mounts are staged under
-    instance_dir by the API process (root). Without this, the container
-    user cannot write into bind-mounted directories such as ~/.config.
+    Profile copies, profile/Git composites, and SSH key mounts are created by
+    the API process. Their sources must be owned by the target container user
+    before Docker bind-mounts them into writable paths.
     """
     for vol in extra_volumes:
         source = vol.get("source", "")
@@ -154,61 +156,180 @@ def _relative_under(parent: str, child: str) -> str | None:
     return None
 
 
+def _stage_profile_mounts(profile_mounts: list[dict], instance_dir: str) -> list[dict]:
+    """Copy profile bind sources into an instance-local, writable staging area."""
+    staged_mounts: list[dict] = []
+    staging_root = os.path.join(instance_dir, "mounts", "profiles")
+
+    for mount in profile_mounts:
+        source = mount.get("source", "")
+        target = mount.get("target", "")
+        if not source or not target:
+            continue
+        if not os.path.exists(source):
+            logger.warning("Skipping missing config profile mount source: %s", source)
+            continue
+
+        digest = hashlib.sha256(f"{source}\0{target}".encode()).hexdigest()[:16]
+        staged_source = os.path.join(staging_root, digest)
+        try:
+            if os.path.lexists(staged_source):
+                if os.path.isdir(staged_source):
+                    shutil.rmtree(staged_source)
+                else:
+                    os.unlink(staged_source)
+            os.makedirs(os.path.dirname(staged_source), exist_ok=True)
+
+            if os.path.isdir(source):
+                shutil.copytree(source, staged_source, symlinks=True)
+            else:
+                shutil.copy2(source, staged_source, follow_symlinks=False)
+        except OSError as exc:
+            logger.error("Failed to stage config profile mount %s: %s", source, exc)
+            continue
+
+        staged_mount = dict(mount)
+        staged_mount["source"] = staged_source
+        staged_mounts.append(staged_mount)
+
+    return staged_mounts
+
+
+def _mounts_overlap(first_target: str, second_target: str) -> bool:
+    """Return whether two normalized container mount targets intersect."""
+    return (
+        _relative_under(first_target, second_target) is not None
+        or _relative_under(second_target, first_target) is not None
+    )
+
+
+def _copy_mount_source(source: str, destination: str) -> None:
+    """Copy a bind-mount source into its destination in a composite tree."""
+    try:
+        if os.path.isdir(source):
+            os.makedirs(destination, exist_ok=True)
+            for entry in os.listdir(source):
+                source_entry = os.path.join(source, entry)
+                destination_entry = os.path.join(destination, entry)
+                if os.path.isdir(source_entry):
+                    shutil.copytree(
+                        source_entry,
+                        destination_entry,
+                        dirs_exist_ok=True,
+                        symlinks=True,
+                    )
+                else:
+                    os.makedirs(os.path.dirname(destination_entry), exist_ok=True)
+                    shutil.copy2(source_entry, destination_entry, follow_symlinks=False)
+            return
+
+        os.makedirs(os.path.dirname(destination), exist_ok=True)
+        shutil.copy2(source, destination, follow_symlinks=False)
+    except OSError as exc:
+        raise RuntimeError(f"Unable to compose mount source {source}: {exc}") from exc
+
+
 def _stack_profile_mounts_with_git_mounts(
     profile_mounts: list[dict],
     git_mount_volumes: list[dict],
+    instance_dir: str,
 ) -> list[dict]:
-    """Merge profile file mounts into overlapping git-mount sources.
+    """Build instance-local composite mounts for overlapping profile and Git paths.
 
-    When a config profile mounts static files to the same directory as a
-    git-mount (e.g. ``~/.pi``), a directory-level bind mount for the profile
-    would mask the cloned repository. Instead, copy the profile files into
-    the git-mount source directory so the container sees both sets of files
-    through a single bind mount.
-
-    Profile mounts whose target is a child of a git-mount target are copied
-    into the corresponding subdirectory. Mounts that do not overlap are
-    returned unchanged.
+    Docker applies one bind mount per target; it never merges their contents.
+    A composite therefore copies shared Git content first and profile content
+    second, so profile files extend (and intentionally override) the Git tree
+    without dirtying the shared clone.
     """
-    remaining: list[dict] = []
-    for pvol in profile_mounts:
-        p_source = pvol.get("source", "")
-        p_target = pvol.get("target", "")
-        if not p_source or not os.path.exists(p_source):
-            remaining.append(pvol)
+    records: list[tuple[str, dict]] = [
+        ("profile", mount) for mount in profile_mounts
+    ] + [("git", mount) for mount in git_mount_volumes]
+    components: list[list[int]] = []
+    remaining: set[int] = set(range(len(records)))
+
+    while remaining:
+        component_indices: set[int] = {min(remaining)}
+        remaining.difference_update(component_indices)
+        pending = list(component_indices)
+        while pending:
+            current_index = pending.pop()
+            current_target = records[current_index][1].get("target", "")
+            for candidate_index in list(remaining):
+                candidate_target = records[candidate_index][1].get("target", "")
+                if _mounts_overlap(current_target, candidate_target):
+                    remaining.remove(candidate_index)
+                    component_indices.add(candidate_index)
+                    pending.append(candidate_index)
+        components.append(sorted(component_indices))
+
+    result: list[dict] = []
+    for component_indexes in components:
+        component_records = [records[index] for index in component_indexes]
+        kinds = {kind for kind, _mount in component_records}
+        if kinds != {"profile", "git"}:
+            result.extend(mount for _kind, mount in component_records)
             continue
 
-        merged = False
-        for gvol in git_mount_volumes:
-            g_source = gvol.get("source", "")
-            g_target = gvol.get("target", "")
-            if not g_source or not os.path.isdir(g_source):
-                continue
+        targets = [
+            os.path.normpath(mount["target"]) for _kind, mount in component_records
+        ]
+        composite_target = os.path.commonpath(targets)
+        if any(
+            not os.path.isdir(mount["source"])
+            and os.path.normpath(mount["target"]) == composite_target
+            for _kind, mount in component_records
+        ):
+            composite_target = os.path.dirname(composite_target)
 
-            rel = _relative_under(g_target, p_target)
-            if rel is None:
-                continue
-
-            dst = os.path.join(g_source, rel) if rel else g_source
-            if os.path.isdir(p_source):
-                shutil.copytree(p_source, dst, dirs_exist_ok=True)
-            else:
-                os.makedirs(os.path.dirname(dst), exist_ok=True)
-                shutil.copy2(p_source, dst)
-
-            logger.debug(
-                "Stacked profile mount %s into git mount %s at %s",
-                p_target,
-                g_target,
-                dst,
+        digest_input = "\0".join(
+            f"{kind}:{mount['source']}:{mount['target']}"
+            for kind, mount in component_records
         )
-            merged = True
-            break
+        composite_source = os.path.join(
+            instance_dir,
+            "mounts",
+            "composites",
+            hashlib.sha256(digest_input.encode()).hexdigest()[:16],
+        )
+        try:
+            if os.path.lexists(composite_source):
+                shutil.rmtree(composite_source)
+            os.makedirs(composite_source, exist_ok=True)
+        except OSError as exc:
+            raise RuntimeError(
+                f"Unable to prepare composite mount directory {composite_source}: {exc}"
+            ) from exc
 
-        if not merged:
-            remaining.append(pvol)
+        for kind in ("git", "profile"):
+            for record_kind, mount in component_records:
+                if record_kind != kind:
+                    continue
+                relative_target = _relative_under(composite_target, mount["target"])
+                destination = (
+                    composite_source
+                    if relative_target == ""
+                    else os.path.join(composite_source, relative_target or "")
+                )
+                _copy_mount_source(mount["source"], destination)
 
-    return remaining
+        result.append(
+            {
+                "source": composite_source,
+                "target": composite_target,
+                "type": "bind",
+                "readonly": all(
+                    mount.get("readonly", False) for _kind, mount in component_records
+                ),
+            }
+        )
+        logger.info(
+            "Composed %d profile/Git mounts at %s into %s",
+            len(component_records),
+            composite_target,
+            composite_source,
+        )
+
+    return result
 
 
 async def resolve_git_mounts(
@@ -227,12 +348,18 @@ async def resolve_git_mounts(
     if not resolved.git_mounts:
         return []
 
+    # Git mount sources are profile-scoped, not instance-scoped, so compatible
+    # instances bind the same canonical checkout.
+    clone_parent = os.path.join(
+        os.path.dirname(instance_dir or ""), "config-profiles", str(resolved.profile_id)
+    )
+
     # Process all git mounts concurrently
     tasks = []
     for git_mount in resolved.git_mounts:
         tasks.append(
             resolve_single_git_mount(
-                session, git_mount, instance_dir, working_directory, home_dir
+                session, git_mount, clone_parent, working_directory, home_dir
             )
         )
 
@@ -265,6 +392,37 @@ def normalize_git_mount(entry: dict) -> dict:
     return entry
 
 
+@contextlib.contextmanager
+def _git_mount_lock(clone_parent: str, remote_url: str, branch: str | None):
+    """Serialize clone and refresh operations for one canonical Git source."""
+    lock_dir = os.path.join(clone_parent, "git-mounts")
+    identity = f"{remote_url}:{branch or 'default'}"
+    lock_path = os.path.join(
+        lock_dir, f".{hashlib.sha256(identity.encode()).hexdigest()}.lock"
+    )
+    try:
+        os.makedirs(lock_dir, exist_ok=True)
+        with open(lock_path, "a+", encoding="utf-8") as lock_file:
+            fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX)
+            try:
+                yield
+            finally:
+                fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)
+    except OSError as exc:
+        raise RuntimeError(f"Cannot lock Git mount source: {lock_path}") from exc
+
+
+def clone_git_repo_locked(
+    remote_url: str,
+    branch: str | None,
+    clone_parent: str,
+    project_name: str | None = None,
+) -> str:
+    """Clone or refresh a canonical source while holding its process lock."""
+    with _git_mount_lock(clone_parent, remote_url, branch):
+        return clone_git_repo(remote_url, branch, clone_parent, project_name)
+
+
 def clone_git_repo(
     remote_url: str,
     branch: str | None,
@@ -283,16 +441,27 @@ def clone_git_repo(
     url_hash = hashlib.md5(f"{remote_url}:{branch_segment}".encode()).hexdigest()[:12]
     repo_name = remote_url.split("/")[-1].replace(".git", "") or "repo"
     clone_dir = os.path.join(clone_parent, "git-mounts", f"{repo_name}-{url_hash}")
-    repo_path = clone_repository(
-        remote_url,
-        None,  # No SSH key for now - can be added later
-        clone_dir,
-        branch or "main",
-        project_name=project_name,
-    )
+    clone_name = _slugify_directory_name(project_name) if project_name else "repo-clone"
+    repo_path = os.path.join(clone_dir, clone_name)
 
-    if not os.path.exists(repo_path):
+    if os.path.isdir(os.path.join(repo_path, ".git")):
+        # Reuse the deterministic per-repository cache on repeated starts.
         try:
+            pull_repository_updates(repo_path, remote_url)
+            logger.debug("Pulled updates for git mount %s", remote_url)
+        except Exception as exc:
+            logger.warning("Failed to pull updates for %s: %s", remote_url, exc)
+    else:
+        try:
+            # A failed clone can leave its destination behind. Remove only the
+            # computed clone path so the next start can retry cleanly.
+            if os.path.lexists(repo_path):
+                logger.warning("Removing incomplete git mount clone at %s", repo_path)
+                if os.path.isdir(repo_path) and not os.path.islink(repo_path):
+                    shutil.rmtree(repo_path)
+                else:
+                    os.unlink(repo_path)
+
             os.makedirs(clone_dir, exist_ok=True)
             repo_path = clone_repository(
                 remote_url,
@@ -305,13 +474,6 @@ def clone_git_repo(
         except Exception as exc:
             logger.warning("Clone failed for git mount %s: %s", remote_url, exc)
             raise
-    else:
-        # Repo exists - pull latest updates
-        try:
-            pull_repository_updates(repo_path, remote_url)
-            logger.debug("Pulled updates for git mount %s", remote_url)
-        except Exception as exc:
-            logger.warning("Failed to pull updates for %s: %s", remote_url, exc)
 
     # Handle branch checkout if specified
     if branch and repo_path:
@@ -421,7 +583,7 @@ def resolve_git_mount_mappings(
 async def resolve_single_git_mount(
     session: AsyncSession,
     git_mount: dict,
-    instance_dir: str | None = None,
+    clone_parent: str | None = None,
     working_directory: str | None = None,
     home_dir: str = "/root",
 ) -> list[dict]:
@@ -443,15 +605,15 @@ async def resolve_single_git_mount(
         logger.warning("Invalid git mount skipped: no mappings")
         return []
 
-    if not instance_dir:
-        logger.warning("Git mount skipped: no instance_dir provided for cloning")
+    if not clone_parent:
+        logger.warning("Git mount skipped: no canonical profile directory provided")
         return []
 
     # Clone or pull the repository. Git mounts are auxiliary, so they keep
     # using the repository URL basename rather than the project name.
     try:
         repo_path = await asyncio.to_thread(
-            clone_git_repo, remote_url, branch, instance_dir
+            clone_git_repo_locked, remote_url, branch, clone_parent
         )
     except Exception as exc:
         logger.warning(
@@ -464,7 +626,12 @@ async def resolve_single_git_mount(
         return []
 
     # Resolve all mappings from the cloned repo
-    return resolve_git_mount_mappings(repo_path, mappings, working_directory, home_dir)
+    volumes = resolve_git_mount_mappings(
+        repo_path, mappings, working_directory, home_dir
+    )
+    for volume in volumes:
+        volume["readonly"] = True
+    return volumes
 
 
 def checkout_branch(repo_path: str, branch: str) -> bool:
@@ -1398,17 +1565,22 @@ async def start_tool_instance(
             resolved = await resolve_profile(
                 session, instance.selected_config_profile_id
             )
+            # Profile working-directory hints determine where individual
+            # canonical profile files are bind-mounted at container creation.
+            profile_hints = resolved.runtime_hints
+            if profile_hints.get("working_directory"):
+                working_directory = expand_container_path(
+                    profile_hints["working_directory"], home_dir
+                )
             profile_env, profile_files, profile_mounts, profile_hints = (
-                apply_resolved_profile(instance_dir, resolved, home_dir)
+                apply_resolved_profile(
+                    instance_dir, resolved, home_dir, working_directory
+                )
             )
             # Profile hints override the manifest/tool defaults, and git mounts
             # need the final working directory to resolve relative target paths.
             if profile_hints.get("start_command"):
                 start_command = profile_hints["start_command"]
-            if profile_hints.get("working_directory"):
-                working_directory = expand_container_path(
-                    profile_hints["working_directory"], home_dir
-                )
             if profile_hints.get("port_override"):
                 port_override = profile_hints["port_override"]
             env_vars.update(profile_env)
@@ -1416,22 +1588,22 @@ async def start_tool_instance(
             git_mount_volumes = await resolve_git_mounts(
                 session, resolved, instance_dir, working_directory, home_dir
             )
-            # Stack static file mounts on top of git repo mounts so they do
-            # not mask each other when they target the same directory.
-            stacked_profile_mounts = _stack_profile_mounts_with_git_mounts(
-                profile_mounts, git_mount_volumes
+            staged_profile_mounts = _stage_profile_mounts(profile_mounts, instance_dir)
+            composed_mounts = _stack_profile_mounts_with_git_mounts(
+                staged_profile_mounts,
+                git_mount_volumes,
+                instance_dir,
             )
-            extra_volumes.extend(stacked_profile_mounts)
-            extra_volumes.extend(git_mount_volumes)
+            extra_volumes.extend(composed_mounts)
             logger.debug(
-                "Applied config profile %s to instance %s (env=%d, files=%d, mounts=%d, git_mounts=%d, stacked=%d)",
+                "Applied config profile %s to instance %s (env=%d, files=%d, profile_mounts=%d, git_mounts=%d, composed_mounts=%d)",
                 resolved.profile_name,
                 instance.id,
                 len(profile_env),
                 len(profile_files),
-                len(profile_mounts),
+                len(staged_profile_mounts),
                 len(git_mount_volumes),
-                len(profile_mounts) - len(stacked_profile_mounts),
+                len(composed_mounts),
             )
         except ConfigProfileCycleError as exc:
             logger.error(
@@ -1472,7 +1644,15 @@ async def start_tool_instance(
 
         if ssh_keys_to_mount:
             ssh_dir = os.path.join(instance_dir, "mounts", "ssh", ".ssh")
+            try:
                 os.makedirs(ssh_dir, exist_ok=True)
+            except OSError as exc:
+                logger.error(
+                    "Failed to create SSH mount directory for instance %s: %s",
+                    instance.id,
+                    exc,
+                )
+                ssh_keys_to_mount = []
 
             key_filenames = []
             for ssh_key in ssh_keys_to_mount:
@@ -2185,7 +2365,13 @@ async def delete_tool_instance(
         if os.path.exists(instance_dir):
             import shutil
 
+            try:
                 shutil.rmtree(instance_dir)
+            except OSError as exc:
+                logger.error(
+                    "Failed to remove instance directory %s: %s", instance_dir, exc
+                )
+                raise RuntimeError("Failed to remove instance files") from exc
 
     await publish_lifecycle_event(
         event_bus=_event_bus,

apps/api/tests/api/test_terminal_ws_multi.py

@@ -1,7 +1,15 @@
 """Integration tests for multi-session terminal WebSocket and REST API."""
 
+import asyncio
+
 import pytest
 from fastapi.testclient import TestClient
+from src.api.system.terminal import (
+    MAX_TERMINAL_INPUT_BYTES,
+    SessionRef,
+    _queue_terminal_input,
+    _write_loop,
+)
 from src.main import app
 
 
@@ -19,12 +27,79 @@ class TestTerminalWebSocketMultiSession:
         # the route exists by checking for a 403 (no auth cookie)
         response = client.get("/ws/tool-instances/test-instance/terminal/test-session")
         # WebSocket endpoint returns 403 when accessed via HTTP GET
-        assert response.status_code in (403, 404)
+        assert response.status_code == 403 or response.status_code == 404
 
     def test_default_session_alias_route_exists(self, client):
         """The default session alias route should still exist."""
         response = client.get("/ws/tool-instances/test-instance/terminal")
-        assert response.status_code in (403, 404)
+        assert response.status_code == 403 or response.status_code == 404
+
+
+def test_terminal_input_queue_rejects_excess_input_without_blocking() -> None:
+    """A stalled PTY writer cannot make the input queue grow without limit."""
+    input_queue: asyncio.Queue[tuple[object, bytes]] = asyncio.Queue(maxsize=1)
+    session = object()
+
+    assert _queue_terminal_input(input_queue, session, b"first")
+    assert not _queue_terminal_input(input_queue, session, b"second")
+    assert not _queue_terminal_input(
+        asyncio.Queue(), session, b"x" * (MAX_TERMINAL_INPUT_BYTES + 1)
+    )
+
+
+@pytest.mark.asyncio
+async def test_ack_is_processed_while_a_pty_write_is_waiting() -> None:
+    """A blocked paste writer must not block flow-control acknowledgements."""
+
+    write_started = asyncio.Event()
+
+    class Session:
+        _closed = False
+
+        def __init__(self) -> None:
+            self.acks: list[int] = []
+            self.write_finished = False
+
+        def is_alive(self) -> bool:
+            return True
+
+        async def write_input(self, _data: bytes) -> None:
+            write_started.set()
+            try:
+                await asyncio.Event().wait()
+            finally:
+                self.write_finished = True
+
+        def acknowledge_data(self, char_count: int) -> None:
+            self.acks.append(char_count)
+
+    class WebSocket:
+        def __init__(self) -> None:
+            self.messages = iter(
+                [
+                    {"type": "websocket.receive", "bytes": b"large paste"},
+                    {"type": "websocket.receive", "text": '{"type":"ack","chars":4096}'},
+                    {"type": "websocket.disconnect"},
+                ]
+            )
+            self.receive_count = 0
+
+        async def receive(self):
+            self.receive_count += 1
+            if self.receive_count > 1:
+                await write_started.wait()
+            return next(self.messages)
+
+    session = Session()
+    websocket = WebSocket()
+    task = asyncio.create_task(_write_loop(SessionRef(session), websocket, "instance"))
+
+    await asyncio.wait_for(write_started.wait(), timeout=0.1)
+    await asyncio.sleep(0)
+    assert session.acks == [4096]
+
+    await task
+    assert session.write_finished
 
 
 class TestTerminalRestApi:

apps/api/tests/unit/test_builtin_tool_users.py

@@ -0,0 +1,62 @@
+"""Tests for the shared non-root user used by built-in tools."""
+
+from pathlib import Path
+
+from src.seeds.builtin_tool_types import (
+    BUILTIN_TOOL_TYPES,
+    BUILTIN_USER_GID,
+    BUILTIN_USER_UID,
+    _standardize_builtin_manifest_user,
+)
+
+
+def test_builtin_compose_templates_use_shared_runtime_ids() -> None:
+    """Every legacy built-in Compose tool declares the shared UID/GID."""
+    templates = {
+        str(tool["name"]): str(tool["compose_template"]) for tool in BUILTIN_TOOL_TYPES
+    }
+
+    assert "- PUID=1000" in templates["code-server"]
+    assert "- PGID=1000" in templates["code-server"]
+    assert "- NB_UID=1000" in templates["jupyter-notebook"]
+    assert "- NB_GID=1000" in templates["jupyter-notebook"]
+    assert "setpriv --reuid=node --regid=node --init-groups" in templates["opencode"]
+
+
+def test_only_builtin_user_manifest_is_standardized() -> None:
+    """The startup migration cannot rewrite a future custom tool user."""
+    builtin_manifest = {"user": {"name": "user", "uid": 1001, "gid": 1001}}
+    custom_manifest = {"user": {"name": "custom", "uid": 2000, "gid": 2000}}
+
+    assert _standardize_builtin_manifest_user(builtin_manifest)
+    assert builtin_manifest["user"] == {
+        "name": "user",
+        "uid": BUILTIN_USER_UID,
+        "gid": BUILTIN_USER_GID,
+    }
+    assert not _standardize_builtin_manifest_user(custom_manifest)
+    assert custom_manifest["user"] == {"name": "custom", "uid": 2000, "gid": 2000}
+
+
+def test_tool_image_templates_define_shared_ids() -> None:
+    """Project-owned image templates explicitly create or map UID/GID 1000."""
+    root = Path(__file__).resolve().parents[4]
+    sources = {
+        name: (root / "tool-images" / name).read_text()
+        for name in (
+            "base.dockerfile",
+            "opencode.dockerfile",
+            "pi-agent.dockerfile",
+            "code-server.dockerfile",
+            "jupyter.dockerfile",
+        )
+    }
+
+    for name in ("base.dockerfile", "opencode.dockerfile", "pi-agent.dockerfile"):
+        assert "groupadd -g 1000 user" in sources[name]
+        assert "useradd -m -u 1000 -g 1000" in sources[name]
+
+    assert "PUID=1000" in sources["code-server.dockerfile"]
+    assert "PGID=1000" in sources["code-server.dockerfile"]
+    assert "NB_UID=1000" in sources["jupyter.dockerfile"]
+    assert "NB_GID=1000" in sources["jupyter.dockerfile"]

apps/api/tests/unit/test_config_profile_resolver.py

@@ -532,6 +532,54 @@ class TestApplyResolvedProfile:
         assert Path(volumes[0]["source"]).name == "workspace_x_y"
         assert (Path(volumes[0]["source"]) / "z.json").exists()
 
+    def test_top_level_files_use_profile_scoped_direct_bind_mounts(self, tmp_path) -> None:
+        """Top-level files are shared safely without mounting over a workspace."""
+        profile_id = uuid.uuid4()
+        resolved = ResolvedProfile(
+            profile_id=profile_id,
+            profile_name="test",
+            files={".tool/config.toml": "setting = true"},
+        )
+
+        instance_root = tmp_path / "instances"
+        _, files, volumes, _ = apply_resolved_profile(
+            str(instance_root / "instance-a"),
+            resolved,
+            working_dir="/workspace/project",
+        )
+
+        canonical_file = (
+            instance_root / "config-profiles" / str(profile_id) / "files" / ".tool" / "config.toml"
+        )
+        assert files == {}
+        assert volumes == [
+            {
+                "source": str(canonical_file),
+                "target": "/workspace/project/.tool/config.toml",
+                "type": "bind",
+                "readonly": False,
+            }
+        ]
+        assert canonical_file.read_text() == "setting = true"
+
+    def test_instances_share_profile_scoped_mount_sources(self, tmp_path) -> None:
+        """Different instance paths resolve a profile to one canonical source."""
+        profile_id = uuid.uuid4()
+        resolved = ResolvedProfile(
+            profile_id=profile_id,
+            profile_name="test",
+            mounts={"/app": ResolvedMount(target="/app", mode="rw", files={"config.ini": "x"})},
+        )
+
+        instance_root = tmp_path / "instances"
+        _, _, first_volumes, _ = apply_resolved_profile(str(instance_root / "instance-a"), resolved)
+        _, _, second_volumes, _ = apply_resolved_profile(str(instance_root / "instance-b"), resolved)
+
+        assert first_volumes[0]["source"] == second_volumes[0]["source"]
+        assert first_volumes[0]["source"] == str(
+            instance_root / "config-profiles" / str(profile_id) / "mounts" / "app"
+        )
+
     def test_empty_mount_produces_no_volumes(self, tmp_path) -> None:
         """A mount with no files should not produce any volume entries."""
         resolved = ResolvedProfile(
@@ -579,7 +627,7 @@ class TestApplyResolvedProfile:
 
         assert len(volumes) == 1
         assert volumes[0]["target"] == "/etc/app"
-        assert volumes[0].get("readonly") is True
+        assert volumes[0].get("readonly")
 
     def test_writable_mount_does_not_set_readonly_flag(self, tmp_path) -> None:
         """A mount with mode 'rw' should not set readonly on the volume entry."""
@@ -598,7 +646,7 @@ class TestApplyResolvedProfile:
 
         assert len(volumes) == 1
         assert volumes[0]["target"] == "/app"
-        assert volumes[0].get("readonly") is False
+        assert not volumes[0].get("readonly")
 
 
 class TestCheckIncludeCycle:

apps/api/tests/unit/test_instance_service.py

@@ -1,13 +1,18 @@
 """Unit tests for the tool instance service."""
 
+import hashlib
 import uuid
+from pathlib import Path
 from unittest.mock import MagicMock, AsyncMock
 
 import pytest
 
 from src.services.tool.instance_service import (
+    _chown_staged_mounts,
     _get_repository_mount_name,
     _stack_profile_mounts_with_git_mounts,
+    _stage_profile_mounts,
+    clone_git_repo,
     modify_compose_file,
     prepare_manifest_instance,
 )
@@ -68,154 +73,238 @@ class TestGetRepositoryMountName:
 
 
 @pytest.mark.unit
-class TestStackProfileMountsWithGitMounts:
-    """Tests for _stack_profile_mounts_with_git_mounts."""
+class TestCloneGitRepo:
+    """Regression tests for reusable config-profile git mount clones."""
 
-    def test_exact_overlap_merges_profile_files_into_git_source(self, tmp_path) -> None:
-        """When a profile mount targets the same directory as a git mount,
-        the profile files should be copied into the git-mount source so the
-        container sees both sets of files through one bind mount."""
+    def test_reuses_existing_clone(self, monkeypatch, tmp_path) -> None:
+        from src.services.tool import instance_service
+
+        remote_url = "https://gitlab.com/example/dotfiles"
+        branch = None
+        clone_parent = str(tmp_path)
+        url_hash = hashlib.md5(f"{remote_url}:default".encode()).hexdigest()[:12]
+        repo_path = tmp_path / "git-mounts" / f"dotfiles-{url_hash}" / "repo-clone"
+        (repo_path / ".git").mkdir(parents=True)
+
+        clone = MagicMock(side_effect=AssertionError("existing clone must be reused"))
+        pull = MagicMock()
+        monkeypatch.setattr(instance_service, "clone_repository", clone)
+        monkeypatch.setattr(instance_service, "pull_repository_updates", pull)
+
+        result = clone_git_repo(remote_url, branch, clone_parent)
+
+        assert result == str(repo_path)
+        clone.assert_not_called()
+        pull.assert_called_once_with(str(repo_path), remote_url)
+
+    def test_replaces_incomplete_clone_before_retry(
+        self, monkeypatch, tmp_path
+    ) -> None:
+        from src.services.tool import instance_service
+
+        remote_url = "https://gitlab.com/example/dotfiles"
+        url_hash = hashlib.md5(f"{remote_url}:main".encode()).hexdigest()[:12]
+        clone_dir = tmp_path / "git-mounts" / f"dotfiles-{url_hash}"
+        repo_path = clone_dir / "repo-clone"
+        repo_path.mkdir(parents=True)
+        (repo_path / "partial-file").write_text("incomplete")
+
+        def clone(_url, _key, destination, _branch, project_name=None):
+            assert destination == str(clone_dir)
+            assert project_name is None
+            assert not repo_path.exists()
+            (repo_path / ".git").mkdir(parents=True)
+            return str(repo_path)
+
+        monkeypatch.setattr(instance_service, "clone_repository", clone)
+
+        result = clone_git_repo(remote_url, "main", str(tmp_path))
+
+        assert result == str(repo_path)
+        assert (repo_path / ".git").is_dir()
+
+
+@pytest.mark.unit
+class TestStackProfileMountsWithGitMounts:
+    """Tests for composing profile and Git mounts without Docker masking."""
+
+    def test_stages_profile_source_under_instance_directory(self, tmp_path) -> None:
+        """Profile sources must be instance-local before ownership is fixed."""
+        instance_dir = tmp_path / "instance"
+        profile_source = tmp_path / "profile" / "settings.json"
+        profile_source.parent.mkdir(parents=True)
+        profile_source.write_text("{}")
+
+        staged = _stage_profile_mounts(
+            [{"source": str(profile_source), "target": "/home/user/.pi/settings.json"}],
+            str(instance_dir),
+        )
+
+        assert staged[0]["source"].startswith(str(instance_dir))
+        assert staged[0]["source"] != str(profile_source)
+        assert Path(staged[0]["source"]).read_text() == "{}"
+
+    def test_staged_profile_source_is_chowned_for_container_user(
+        self, monkeypatch, tmp_path
+    ) -> None:
+        """The ownership pass must include the instance-local profile copy."""
+        from src.services.tool import instance_service
+
+        instance_dir = tmp_path / "instance"
+        profile_source = tmp_path / "profile"
+        profile_source.mkdir()
+        (profile_source / "settings.json").write_text("{}")
+        staged = _stage_profile_mounts(
+            [{"source": str(profile_source), "target": "/home/user/.pi"}],
+            str(instance_dir),
+        )
+        chown = MagicMock()
+        monkeypatch.setattr(instance_service, "_chown_path", chown)
+
+        _chown_staged_mounts(staged, str(instance_dir), 1000, 1000)
+
+        chown.assert_called_once_with(staged[0]["source"], 1000, 1000)
+
+    def test_exact_overlap_creates_instance_local_composite(self, tmp_path) -> None:
+        """Profile files extend a Git root without mutating its shared clone."""
+        instance_dir = tmp_path / "instance"
         git_source = tmp_path / "git" / "repo-clone"
         git_source.mkdir(parents=True)
         (git_source / "existing.txt").write_text("from git")
-
-        profile_source = tmp_path / "profile" / "home_user_.pi"
-        profile_source.mkdir(parents=True)
+        profile_source = tmp_path / "profile"
+        profile_source.mkdir()
         (profile_source / "settings.json").write_text("{}")
 
-        profile_mounts = [
+        profile_mounts = _stage_profile_mounts(
+            [
                 {
                     "source": str(profile_source),
                     "target": "/home/user/.pi",
                     "type": "bind",
-                "readonly": False,
                 }
-        ]
-        git_mount_volumes = [
-            {"source": str(git_source), "target": "/home/user/.pi", "type": "bind"}
-        ]
-
+            ],
+            str(instance_dir),
+        )
         result = _stack_profile_mounts_with_git_mounts(
-            profile_mounts, git_mount_volumes
+            profile_mounts,
+            [{"source": str(git_source), "target": "/home/user/.pi", "type": "bind"}],
+            str(instance_dir),
         )
 
-        assert result == []
-        assert (git_source / "existing.txt").read_text() == "from git"
-        assert (git_source / "settings.json").read_text() == "{}"
+        assert len(result) == 1
+        composite = result[0]
+        assert composite["target"] == "/home/user/.pi"
+        assert composite["source"].startswith(str(instance_dir))
+        assert not (tmp_path / "git" / "repo-clone" / "settings.json").exists()
+        assert (
+            tmp_path / "git" / "repo-clone" / "existing.txt"
+        ).read_text() == "from git"
+        assert (tmp_path / "instance" / "mounts" / "composites").exists()
+        assert (Path(composite["source"]) / "existing.txt").read_text() == "from git"
+        assert (Path(composite["source"]) / "settings.json").read_text() == "{}"
 
-    def test_descendant_overlap_copies_into_subdirectory(self, tmp_path) -> None:
-        """Profile mounts targeting a child directory are copied into the
-        corresponding subdirectory of the git-mount source."""
+    def test_descendant_profile_mount_extends_git_root(self, tmp_path) -> None:
+        """Nested targets are composed at the Git root, preserving siblings."""
+        instance_dir = tmp_path / "instance"
         git_source = tmp_path / "git"
         git_source.mkdir()
         (git_source / "README").write_text("repo")
-
-        profile_source = tmp_path / "profile" / "agent"
-        profile_source.mkdir(parents=True)
+        profile_source = tmp_path / "profile"
+        profile_source.mkdir()
         (profile_source / "settings.json").write_text("x")
 
-        profile_mounts = [
-            {
-                "source": str(profile_source),
-                "target": "/home/user/.pi/agent",
-                "type": "bind",
-            }
-        ]
-        git_mount_volumes = [
-            {"source": str(git_source), "target": "/home/user/.pi", "type": "bind"}
-        ]
-
+        profile_mounts = _stage_profile_mounts(
+            [{"source": str(profile_source), "target": "/home/user/.pi/agent"}],
+            str(instance_dir),
+        )
         result = _stack_profile_mounts_with_git_mounts(
-            profile_mounts, git_mount_volumes
+            profile_mounts,
+            [{"source": str(git_source), "target": "/home/user/.pi", "type": "bind"}],
+            str(instance_dir),
         )
 
-        assert result == []
-        assert (git_source / "agent" / "settings.json").read_text() == "x"
-        assert (git_source / "README").read_text() == "repo"
+        assert len(result) == 1
+        composite = Path(result[0]["source"])
+        assert result[0]["target"] == "/home/user/.pi"
+        assert (composite / "README").read_text() == "repo"
+        assert (composite / "agent" / "settings.json").read_text() == "x"
+        assert not (git_source / "agent").exists()
 
-    def test_non_overlapping_mounts_left_untouched(self, tmp_path) -> None:
-        """Profile mounts that do not overlap a git mount are returned as-is."""
+    def test_file_profile_mount_extends_git_root(self, tmp_path) -> None:
+        """A file bind mount is composed into the Git directory, not masked."""
+        instance_dir = tmp_path / "instance"
         git_source = tmp_path / "git"
         git_source.mkdir()
-
-        profile_source = tmp_path / "profile"
-        profile_source.mkdir()
-        (profile_source / "config").write_text("c")
-
-        profile_mounts = [
-            {
-                "source": str(profile_source),
-                "target": "/home/user/.config",
-                "type": "bind",
-            }
-        ]
-        git_mount_volumes = [
-            {"source": str(git_source), "target": "/home/user/.pi", "type": "bind"}
-        ]
-
-        result = _stack_profile_mounts_with_git_mounts(
-            profile_mounts, git_mount_volumes
-        )
-
-        assert result == profile_mounts
-
-    def test_git_source_file_does_not_consume_profile_mount(self, tmp_path) -> None:
-        """If the overlapping git-mount source is a file, the profile mount
-        cannot be merged and must be kept."""
-        git_source = tmp_path / "file.txt"
-        git_source.write_text("file")
-
-        profile_source = tmp_path / "profile"
-        profile_source.mkdir()
-        (profile_source / "settings.json").write_text("{}")
-
-        profile_mounts = [
-            {
-                "source": str(profile_source),
-                "target": "/home/user/.pi",
-                "type": "bind",
-            }
-        ]
-        git_mount_volumes = [
-            {
-                "source": str(git_source),
-                "target": "/home/user/.pi/file.txt",
-                "type": "bind",
-            }
-        ]
-
-        result = _stack_profile_mounts_with_git_mounts(
-            profile_mounts, git_mount_volumes
-        )
-
-        assert result == profile_mounts
-
-    def test_profile_source_file_copied_into_git_source(self, tmp_path) -> None:
-        """A profile mount that supplies a single file is copied into the
-        git-mount source directory."""
-        git_source = tmp_path / "git"
-        git_source.mkdir()
-
+        (git_source / "README").write_text("repo")
         profile_source = tmp_path / "settings.json"
         profile_source.write_text("{}")
 
-        profile_mounts = [
+        profile_mounts = _stage_profile_mounts(
+            [
                 {
                     "source": str(profile_source),
                     "target": "/home/user/.pi/settings.json",
-                "type": "bind",
                 }
-        ]
-        git_mount_volumes = [
-            {"source": str(git_source), "target": "/home/user/.pi", "type": "bind"}
-        ]
-
+            ],
+            str(instance_dir),
+        )
         result = _stack_profile_mounts_with_git_mounts(
-            profile_mounts, git_mount_volumes
+            profile_mounts,
+            [{"source": str(git_source), "target": "/home/user/.pi", "type": "bind"}],
+            str(instance_dir),
         )
 
-        assert result == []
-        assert (git_source / "settings.json").read_text() == "{}"
+        assert len(result) == 1
+        composite = Path(result[0]["source"])
+        assert result[0]["target"] == "/home/user/.pi"
+        assert (composite / "README").read_text() == "repo"
+        assert (composite / "settings.json").read_text() == "{}"
+
+    def test_parent_profile_mount_extends_nested_git_mount(self, tmp_path) -> None:
+        """A profile parent mount keeps Git content and its own sibling files."""
+        instance_dir = tmp_path / "instance"
+        git_source = tmp_path / "git"
+        git_source.mkdir()
+        (git_source / "plugin.toml").write_text("git")
+        profile_source = tmp_path / "profile"
+        profile_source.mkdir()
+        (profile_source / "config.toml").write_text("profile")
+
+        profile_mounts = _stage_profile_mounts(
+            [{"source": str(profile_source), "target": "/home/user"}], str(instance_dir)
+        )
+        result = _stack_profile_mounts_with_git_mounts(
+            profile_mounts,
+            [{"source": str(git_source), "target": "/home/user/.pi", "type": "bind"}],
+            str(instance_dir),
+        )
+
+        assert len(result) == 1
+        composite = Path(result[0]["source"])
+        assert result[0]["target"] == "/home/user"
+        assert (composite / "config.toml").read_text() == "profile"
+        assert (composite / ".pi" / "plugin.toml").read_text() == "git"
+
+    def test_non_overlapping_mounts_remain_separate(self, tmp_path) -> None:
+        """Unrelated profile and Git mounts retain their independent sources."""
+        instance_dir = tmp_path / "instance"
+        git_source = tmp_path / "git"
+        git_source.mkdir()
+        profile_source = tmp_path / "profile"
+        profile_source.mkdir()
+
+        profile_mounts = _stage_profile_mounts(
+            [{"source": str(profile_source), "target": "/home/user/.config"}],
+            str(instance_dir),
+        )
+        git_mounts = [{"source": str(git_source), "target": "/home/user/.pi"}]
+
+        assert (
+            _stack_profile_mounts_with_git_mounts(
+                profile_mounts, git_mounts, str(instance_dir)
+            )
+            == profile_mounts + git_mounts
+        )
 
 
 @pytest.mark.unit

apps/web/index.html

@@ -3,6 +3,8 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#275d4b" />
+    <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
     <title>Headquarter</title>
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />

apps/web/public/favicon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <title>Headquarter</title>
+  <rect width="64" height="64" rx="15" fill="#275d4b"/>
+  <path fill="#fffef9" d="M17 15h8v13h14V15h8v34h-8V36H25v13h-8z"/>
+  <path fill="#9dcdb7" d="M25 28h14v8H25z"/>
+</svg>

apps/web/src/api/config-profiles.ts

@@ -1,5 +1,11 @@
 import { apiClient } from "./client";
 
+export interface ConfigProfileRefreshOutcome {
+	instance_id: string;
+	status: "compatible" | "refreshed" | "restart_required" | "incompatible_permissions";
+	reason?: string;
+}
+
 export interface ConfigProfile {
 	id: string;
 	user_id: string;
@@ -16,6 +22,7 @@ export interface ConfigProfile {
 	includes: ConfigProfileInclude[];
 	created_at: string;
 	updated_at: string;
+	refresh_outcomes?: ConfigProfileRefreshOutcome[];
 }
 
 export interface ConfigProfileMount {
@@ -138,6 +145,15 @@ export const deleteConfigProfile = async (id: string): Promise<void> => {
 	await apiClient.delete(`/config-profiles/${id}`);
 };
 
+export const refreshConfigProfileGitMounts = async (
+	id: string,
+): Promise<{ refresh_outcomes: ConfigProfileRefreshOutcome[] }> => {
+	const response = await apiClient.post<{
+		refresh_outcomes: ConfigProfileRefreshOutcome[];
+	}>(`/config-profiles/${id}/refresh-git-mounts`);
+	return response.data;
+};
+
 export const updateProfileIncludes = async (
 	id: string,
 	data: UpdateIncludesRequest,

apps/web/src/components/features/config-profiles/ConfigProfileEditorPanel.tsx

@@ -14,6 +14,7 @@ interface Props {
   saveStatus: "idle" | "saving" | "saved" | "error";
   previewData: ResolvedProfile | null;
   previewingId: string | null;
+  isRefreshingGitMounts: boolean;
   projects: ProjectWithRepos[];
   toolTypes: ToolType[];
   availableProfiles: ConfigProfile[];
@@ -23,6 +24,7 @@ interface Props {
   onSubmit: (e?: React.FormEvent) => void;
   onReset: () => void;
   onPreview: () => void;
+  onRefreshGitMounts: () => void;
   onAddInclude: (id: string) => void;
   onRemoveInclude: (index: number) => void;
   onDragStart: (e: React.DragEvent, index: number) => void;
@@ -54,6 +56,7 @@ export const ConfigProfileEditorPanel = ({
   saveStatus,
   previewData,
   previewingId,
+  isRefreshingGitMounts,
   projects,
   toolTypes,
   availableProfiles,
@@ -63,6 +66,7 @@ export const ConfigProfileEditorPanel = ({
   onSubmit,
   onReset,
   onPreview,
+  onRefreshGitMounts,
   onAddInclude,
   onRemoveInclude,
   onDragStart,
@@ -114,6 +118,17 @@ export const ConfigProfileEditorPanel = ({
             </div>
             {!isCreating && selectedProfile && (
               <div className="row row-sm">
+                <button className="btn btn-secondary" onClick={onRefreshGitMounts} disabled={isRefreshingGitMounts}>
+                  {isRefreshingGitMounts ? (
+                    <>
+                      <Icon name="loading" size="sm" /> Refreshing Git mounts...
+                    </>
+                  ) : (
+                    <>
+                      <Icon name="refresh" size="sm" /> Refresh Git mounts
+                    </>
+                  )}
+                </button>
                 <button className="btn btn-secondary" onClick={onPreview} disabled={previewingId === selectedProfile.id}>
                   {previewingId === selectedProfile.id ? (
                     <><Icon name="loading" size="sm" /> Previewing...</>

apps/web/src/components/features/config-profiles/ConfigProfilesMobileView.tsx

@@ -28,6 +28,7 @@ interface Props {
 	availableProfiles: ConfigProfile[];
 	previewData: ResolvedProfile | null;
 	previewingId: string | null;
+	isRefreshingGitMounts: boolean;
 	saveStatus: "idle" | "saving" | "saved" | "error";
 	error: string | null;
 	onViewChange: (view: MobileView) => void;
@@ -64,6 +65,7 @@ interface Props {
 	) => void;
 	onRemoveMountFile: (mountIndex: number, path: string) => void;
 	onPreview: (id: string) => void;
+	onRefreshGitMounts: (id: string) => void;
 	onClosePreview: () => void;
 }
 
@@ -79,6 +81,7 @@ export const ConfigProfilesMobileView = ({
 	availableProfiles,
 	previewData,
 	previewingId,
+	isRefreshingGitMounts,
 	saveStatus,
 	error,
 	onViewChange,
@@ -104,6 +107,7 @@ export const ConfigProfilesMobileView = ({
 	onUpdateMountFile,
 	onRemoveMountFile,
 	onPreview,
+	onRefreshGitMounts,
 	onClosePreview,
 }: Props) => {
 	const [isSaving, setIsSaving] = useState(false);
@@ -363,6 +367,23 @@ export const ConfigProfilesMobileView = ({
 				onDelete={handleDeleteClick}
 			>
 				<div className="mobile-detail-actions-extra">
+					<button
+						type="button"
+						className="secondary-button"
+						disabled={isRefreshingGitMounts}
+						onClick={() => onRefreshGitMounts(selectedProfile.id)}
+					>
+						{isRefreshingGitMounts ? (
+							<>
+								<Icon name="loading" size="sm" />
+								Refreshing Git mounts...
+							</>
+						) : (
+							<>
+								<Icon name="refresh" size="sm" /> Refresh Git mounts
+							</>
+						)}
+					</button>
 					<button
 						type="button"
 						className="secondary-button"

apps/web/src/components/features/terminal/terminal.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, it } from "vitest";
 
-import { getTerminalScrollbackLimit } from "./terminal.tsx";
+import {
+	getTerminalScrollbackLimit,
+	isCurrentWebSocket,
+	shouldRetryWebSocketClose,
+} from "./terminal.tsx";
 
 describe("getTerminalScrollbackLimit", () => {
 	it("retains normal-buffer history for custom mobile swipe scrolling", () => {
@@ -10,4 +14,19 @@ describe("getTerminalScrollbackLimit", () => {
 	it("keeps desktop scrollback disabled to prevent stale-frame wheel scrolling", () => {
 		expect(getTerminalScrollbackLimit(false)).toBe(0);
 	});
+
+	it("rejects stale WebSocket callbacks after a replacement connection", () => {
+		const current = {} as WebSocket;
+		const stale = {} as WebSocket;
+
+		expect(isCurrentWebSocket(current, current)).toBe(true);
+		expect(isCurrentWebSocket(current, stale)).toBe(false);
+	});
+
+	it("retries a heartbeat timeout but not a server socket replacement", () => {
+		expect(shouldRetryWebSocketClose(4000, "Heartbeat timeout")).toBe(true);
+		expect(shouldRetryWebSocketClose(4000, "New connection established")).toBe(
+			false,
+		);
+	});
 });

apps/web/src/components/features/terminal/terminal.tsx

@@ -57,6 +57,17 @@ export function getTerminalScrollbackLimit(isMobile: boolean): number {
 	return isMobile ? 10_000 : 0;
 }
 
+export function isCurrentWebSocket(
+	current: WebSocket | null,
+	candidate: WebSocket,
+): boolean {
+	return current === candidate;
+}
+
+export function shouldRetryWebSocketClose(code: number, reason: string): boolean {
+	return code !== 1000 && !(code === 4000 && reason === "New connection established");
+}
+
 function matchesByteSequence(
 	data: Uint8Array,
 	start: number,
@@ -87,6 +98,7 @@ export const TerminalComponent = React.forwardRef<TerminalRef, TerminalProps>(
 		const bracketedPasteEnabledRef = useRef(false);
 		const pasteTextRef = useRef<(text: string) => void>(() => {});
 		const reconnectAttemptsRef = useRef(0);
+		const reconnectTimerRef = useRef<number | null>(null);
 		const onTerminalReadyRef = useRef(onTerminalReady);
 		onTerminalReadyRef.current = onTerminalReady;
 		const handleFontSizeChangeRef = useRef<(delta: number) => void>(() => {});
@@ -115,7 +127,23 @@ export const TerminalComponent = React.forwardRef<TerminalRef, TerminalProps>(
 			return fontSize;
 		}, [fontSize]);
 
+		const clearReconnectTimer = useCallback(() => {
+			if (reconnectTimerRef.current !== null) {
+				window.clearTimeout(reconnectTimerRef.current);
+				reconnectTimerRef.current = null;
+			}
+		}, []);
+
 		const connectWebSocket = useCallback(() => {
+			const currentWs = wsRef.current;
+			if (
+				currentWs?.readyState === WebSocket.CONNECTING ||
+				currentWs?.readyState === WebSocket.OPEN
+			) {
+				return currentWs;
+			}
+			clearReconnectTimer();
+
 			const apiUrl = import.meta.env.VITE_API_BASE_URL || "";
 			const wsProtocol = window.location.protocol === "https:" ? "wss:" : "ws:";
 			const wsHost = apiUrl.replace(/^https?:\/\//, "").replace(/\/+$/, "");
@@ -165,6 +193,11 @@ export const TerminalComponent = React.forwardRef<TerminalRef, TerminalProps>(
 			};
 
 			ws.onopen = () => {
+				if (!isCurrentWebSocket(wsRef.current, ws)) {
+					ws.close(1000, "Superseded connection");
+					return;
+				}
+
 				setStatus("connected");
 				setError(null);
 				reconnectAttemptsRef.current = 0;
@@ -205,7 +238,7 @@ export const TerminalComponent = React.forwardRef<TerminalRef, TerminalProps>(
 			};
 
 			ws.onmessage = (event) => {
-				if (!termRef.current) return;
+				if (!isCurrentWebSocket(wsRef.current, ws) || !termRef.current) return;
 
 				if (event.data instanceof ArrayBuffer) {
 					const data = new Uint8Array(event.data);
@@ -264,6 +297,10 @@ export const TerminalComponent = React.forwardRef<TerminalRef, TerminalProps>(
 			};
 
 			ws.onclose = (event) => {
+				if (!isCurrentWebSocket(wsRef.current, ws)) return;
+				wsRef.current = null;
+				if (ackTimeout) window.clearTimeout(ackTimeout);
+
 				// Clean up heartbeat check
 				if (heartbeatCheckRef.current) {
 					window.clearInterval(heartbeatCheckRef.current);
@@ -279,18 +316,12 @@ export const TerminalComponent = React.forwardRef<TerminalRef, TerminalProps>(
 					return;
 				}
 
-				if (event.code === 1000) {
+				if (!shouldRetryWebSocketClose(event.code, event.reason)) {
 					setStatus("disconnected");
 					return;
 				}
 
-				if (event.code === 4000) {
-					// Server closed old connection for concurrent connection - don't reconnect
-					// The new connection is already established
-					return;
-				}
-
-				// Transient errors: attempt reconnection
+				// Transient errors: attempt reconnection.
 				setStatus("disconnected");
 				setError(`Connection closed (code: ${event.code})`);
 
@@ -299,11 +330,14 @@ export const TerminalComponent = React.forwardRef<TerminalRef, TerminalProps>(
 					const delay =
 						RECONNECT_DELAY_BASE *
 						Math.pow(2, reconnectAttemptsRef.current - 1);
-					setTimeout(() => {
-						if (isUnmountingRef.current) {
-							return;
-						}
-						if (document.visibilityState !== "hidden") {
+					clearReconnectTimer();
+					reconnectTimerRef.current = window.setTimeout(() => {
+						reconnectTimerRef.current = null;
+						if (
+							!isUnmountingRef.current &&
+							document.visibilityState !== "hidden" &&
+							wsRef.current === null
+						) {
 							connectWebSocket();
 						}
 					}, delay);
@@ -311,15 +345,18 @@ export const TerminalComponent = React.forwardRef<TerminalRef, TerminalProps>(
 			};
 
 			ws.onerror = () => {
+				if (!isCurrentWebSocket(wsRef.current, ws)) return;
 				setStatus("error");
 				setError("WebSocket error");
 			};
 
 			return ws;
-		}, [instanceId, sessionId]);
+		}, [clearReconnectTimer, instanceId, sessionId]);
 
 		useEffect(() => {
 			if (!terminalRef.current) return;
+			isUnmountingRef.current = false;
+			permanentErrorRef.current = null;
 
 			// Initialize terminal
 			const currentFontSize = calculateFontSize();
@@ -410,7 +447,7 @@ export const TerminalComponent = React.forwardRef<TerminalRef, TerminalProps>(
 			// Open xterm first (must happen before fit)
 			term.open(container);
 			term.focus();
-			const ws = connectWebSocket();
+			connectWebSocket();
 
 			pasteTextRef.current = (text: string) => {
 				const currentWs = wsRef.current;
@@ -658,14 +695,12 @@ export const TerminalComponent = React.forwardRef<TerminalRef, TerminalProps>(
 
 			// Visibility API for reconnection
 			const handleVisibilityChange = () => {
+				const currentWs = wsRef.current;
 				if (
 					document.visibilityState === "visible" &&
-					ws &&
-					ws.readyState !== WebSocket.OPEN
+					!permanentErrorRef.current &&
+					(currentWs === null || currentWs.readyState === WebSocket.CLOSED)
 				) {
-					if (permanentErrorRef.current) {
-						return;
-					}
 					reconnectAttemptsRef.current = 0;
 					connectWebSocket();
 				}
@@ -674,6 +709,7 @@ export const TerminalComponent = React.forwardRef<TerminalRef, TerminalProps>(
 
 			return () => {
 				isUnmountingRef.current = true;
+				clearReconnectTimer();
 				clearTimeout(resizeTimeout);
 				clearTimeout(windowResizeTimeout);
 				clearTimeout(headerHideTimeout);
@@ -687,8 +723,10 @@ export const TerminalComponent = React.forwardRef<TerminalRef, TerminalProps>(
 				container.removeEventListener("paste", handleBrowserPaste, true);
 				pasteTextRef.current = () => {};
 				bracketedPasteEnabledRef.current = false;
-				if (ws) {
-					ws.close(1000, "Component unmounting");
+				const currentWs = wsRef.current;
+				wsRef.current = null;
+				if (currentWs) {
+					currentWs.close(1000, "Component unmounting");
 				}
 				if (heartbeatCheckRef.current) {
 					window.clearInterval(heartbeatCheckRef.current);

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

@@ -578,7 +578,10 @@ export const InstanceList = ({
 			{showCreate && (
 				<div className="dialog-overlay" role="dialog" aria-modal="true">
 					<div className="dialog">
+						<div className="dialog-header">
 							<h2>Launch Tool</h2>
+						</div>
+						<div className="dialog-body">
 							<CreateSessionForm
 								projects={[]}
 								repositories={[]}
@@ -593,6 +596,7 @@ export const InstanceList = ({
 							/>
 						</div>
 					</div>
+				</div>
 			)}
 		</div>
 	);

apps/web/src/components/features/tool/start-tool-fab.tsx

@@ -62,6 +62,7 @@ export function StartToolFAB() {
 							</button>
 						</div>
 
+						<div className="modal-body">
 						{workspacesLoading ? (
 							<p className="muted">Loading workspaces...</p>
 						) : workspaces.length === 0 ? (
@@ -112,6 +113,7 @@ export function StartToolFAB() {
 						)}
 						</div>
 					</div>
+				</div>
 			)}
 		</>
 	);

apps/web/src/components/features/workspace/workspace-tools-panel.test.tsx

@@ -0,0 +1,47 @@
+import "@testing-library/jest-dom/vitest";
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import { WorkspaceToolsPanel } from "./workspace-tools-panel";
+import type { Workspace } from "../../../types/workspace";
+
+vi.mock("../../../hooks/use-workspace-instances", () => ({
+  useWorkspaceInstances: () => ({
+    instances: [],
+    loading: false,
+    refresh: vi.fn(),
+  }),
+}));
+
+vi.mock("../tool/tool-starter", () => ({
+  ToolStarter: () => <div data-testid="tool-starter" />,
+}));
+
+const workspace: Workspace = {
+  id: "workspace-1",
+  name: "Main",
+  repo_id: "repo-1",
+  repo_name: "repository",
+  repo_ssh_key_id: null,
+  project_id: "project-1",
+  project_name: "Project",
+  user_id: "user-1",
+  branch: "main",
+  path: "/workspace",
+  status: "ready",
+  last_sync_at: null,
+  created_at: "2026-01-01T00:00:00Z",
+  updated_at: "2026-01-01T00:00:00Z",
+  instance_count: 0,
+};
+
+describe("WorkspaceToolsPanel", () => {
+  it("places the tool launcher inside the shared scrollable dialog body", () => {
+    const { container } = render(<WorkspaceToolsPanel workspace={workspace} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Start Tool" }));
+
+    const dialogBody = container.querySelector(".dialog-body");
+    expect(dialogBody).toContainElement(screen.getByTestId("tool-starter"));
+  });
+});

apps/web/src/components/features/workspace/workspace-tools-panel.tsx

@@ -64,7 +64,10 @@ export function WorkspaceToolsPanel({ workspace }: WorkspaceToolsPanelProps) {
 			{showModal && (
 				<div className="dialog-overlay" onClick={() => setShowModal(false)}>
 					<div className="dialog" onClick={(e) => e.stopPropagation()}>
+						<div className="dialog-header">
 							<h3>Start Tool</h3>
+						</div>
+						<div className="dialog-body">
 							<ToolStarter
 								workspace={workspace}
 								onStarted={() => {
@@ -75,6 +78,7 @@ export function WorkspaceToolsPanel({ workspace }: WorkspaceToolsPanelProps) {
 							/>
 						</div>
 					</div>
+				</div>
 			)}
 		</div>
 	);

apps/web/src/hooks/use-config-profiles.ts

@@ -5,6 +5,7 @@ import {
 	deleteConfigProfile,
 	listConfigProfiles,
 	previewConfigProfile,
+	refreshConfigProfileGitMounts,
 	updateConfigProfile,
 	updateProfileIncludes,
 	type ConfigProfile,
@@ -34,17 +35,22 @@ export const useConfigProfiles = () => {
 	const [profiles, setProfiles] = useState<ConfigProfile[]>([]);
 	const [projects, setProjects] = useState<ProjectWithRepos[]>([]);
 	const [toolTypes, setToolTypes] = useState<ToolType[]>([]);
-	const [selectedProfileId, setSelectedProfileId] = useState<string | null>(null);
+	const [selectedProfileId, setSelectedProfileId] = useState<string | null>(
+		null,
+	);
 	const [isCreating, setIsCreating] = useState(false);
 	const [saveStatus, setSaveStatus] = useState<SaveStatus>("idle");
 	const [error, setError] = useState<string | null>(null);
 	const [previewData, setPreviewData] = useState<ResolvedProfile | null>(null);
 	const [previewingId, setPreviewingId] = useState<string | null>(null);
-	const [formData, setFormData] = useState<CreateConfigProfileRequest>(defaultForm);
+	const [isRefreshingGitMounts, setIsRefreshingGitMounts] = useState(false);
+	const [formData, setFormData] =
+		useState<CreateConfigProfileRequest>(defaultForm);
 	const [includedProfileIds, setIncludedProfileIds] = useState<string[]>([]);
 	const [dragOverIndex, setDragOverIndex] = useState<number | null>(null);
 
-	const selectedProfile = profiles.find((p) => p.id === selectedProfileId) || null;
+	const selectedProfile =
+		profiles.find((p) => p.id === selectedProfileId) || null;
 
 	const loadData = useCallback(async () => {
 		setStatus("loading");
@@ -89,7 +95,9 @@ export const useConfigProfiles = () => {
 			is_default: profile.is_default,
 		});
 		setIncludedProfileIds(
-			profile.includes.map((inc: { included_profile_id: string }) => inc.included_profile_id),
+			profile.includes.map(
+				(inc: { included_profile_id: string }) => inc.included_profile_id,
+			),
 		);
 		setError(null);
 		setSaveStatus("idle");
@@ -208,20 +216,39 @@ export const useConfigProfiles = () => {
 			if (isCreating) {
 				const newProfile = await createConfigProfile(formData);
 				if (includedProfileIds.length > 0) {
-					await updateProfileIncludes(newProfile.id, { includes: includedProfileIds });
+					await updateProfileIncludes(newProfile.id, {
+						includes: includedProfileIds,
+					});
 				}
 				setIsCreating(false);
 				setSelectedProfileId(newProfile.id);
 				setSaveStatus("saved");
 				await loadData();
-				const refreshed = (await listConfigProfiles()).find((p) => p.id === newProfile.id);
+				const refreshed = (await listConfigProfiles()).find(
+					(p) => p.id === newProfile.id,
+				);
 				if (refreshed) populateForm(refreshed);
 			} else if (selectedProfile) {
-				await updateConfigProfile(selectedProfile.id, formData);
-				await updateProfileIncludes(selectedProfile.id, { includes: includedProfileIds });
+				const updatedProfile = await updateConfigProfile(
+					selectedProfile.id,
+					formData,
+				);
+				await updateProfileIncludes(selectedProfile.id, {
+					includes: includedProfileIds,
+				});
+				const restartOutcomes = updatedProfile.refresh_outcomes?.filter(
+					(outcome) => outcome.status === "restart_required",
+				);
+				if (restartOutcomes?.length) {
+					setError(
+						`Profile saved. ${restartOutcomes.length} running instance${restartOutcomes.length === 1 ? "" : "s"} must restart to adopt these changes.`,
+					);
+				}
 				setSaveStatus("saved");
 				await loadData();
-				const refreshed = (await listConfigProfiles()).find((p) => p.id === selectedProfile.id);
+				const refreshed = (await listConfigProfiles()).find(
+					(p) => p.id === selectedProfile.id,
+				);
 				if (refreshed) populateForm(refreshed);
 			}
 			return true;
@@ -233,7 +260,8 @@ export const useConfigProfiles = () => {
 	};
 
 	const handleDelete = async (id: string) => {
-		if (!window.confirm("Are you sure you want to delete this config profile?")) return;
+		if (!window.confirm("Are you sure you want to delete this config profile?"))
+			return;
 		try {
 			await deleteConfigProfile(id);
 			if (selectedProfileId === id) {
@@ -242,8 +270,32 @@ export const useConfigProfiles = () => {
 				resetForm();
 			}
 			await loadData();
-		} catch {
-			alert("Failed to delete config profile");
+		} catch (err) {
+			setError(extractErrorMessage(err));
+		}
+	};
+
+	const handleRefreshGitMounts = async (id: string): Promise<boolean> => {
+		if (isRefreshingGitMounts) return false;
+
+		setError(null);
+		setIsRefreshingGitMounts(true);
+		try {
+			const result = await refreshConfigProfileGitMounts(id);
+			const refreshed = result.refresh_outcomes.filter(
+				(outcome) => outcome.status === "refreshed",
+			);
+			setError(
+				refreshed.length
+					? `Refreshed Git mounts for ${refreshed.length} running instance${refreshed.length === 1 ? "" : "s"}.`
+					: "No running instances currently use this profile's Git mounts.",
+			);
+			return true;
+		} catch (err) {
+			setError(extractErrorMessage(err));
+			return false;
+		} finally {
+			setIsRefreshingGitMounts(false);
 		}
 	};
 
@@ -268,7 +320,10 @@ export const useConfigProfiles = () => {
 	};
 
 	const addEnvVar = () => {
-		setFormData((prev) => ({ ...prev, env_vars: { ...prev.env_vars, "": "" } }));
+		setFormData((prev) => ({
+			...prev,
+			env_vars: { ...prev.env_vars, "": "" },
+		}));
 		setSaveStatus("idle");
 	};
 
@@ -323,7 +378,10 @@ export const useConfigProfiles = () => {
 		setSaveStatus("idle");
 	};
 
-	const updateMount = (index: number, updates: Partial<ConfigProfile["mounts"][0]>) => {
+	const updateMount = (
+		index: number,
+		updates: Partial<ConfigProfile["mounts"][0]>,
+	) => {
 		setFormData((prev) => {
 			const mounts = [...(prev.mounts || [])];
 			mounts[index] = { ...mounts[index], ...updates };
@@ -393,6 +451,7 @@ export const useConfigProfiles = () => {
 		error,
 		previewData,
 		previewingId,
+		isRefreshingGitMounts,
 		formData,
 		includedProfileIds,
 		dragOverIndex,
@@ -402,6 +461,7 @@ export const useConfigProfiles = () => {
 		handleSubmit,
 		handleDelete,
 		handlePreview,
+		handleRefreshGitMounts,
 		updateFormField,
 		addEnvVar,
 		updateEnvVar,

apps/web/src/pages/ConfigProfilesPage.tsx

@@ -23,6 +23,7 @@ export const ConfigProfilesPage = () => {
 		error,
 		previewData,
 		previewingId,
+		isRefreshingGitMounts,
 		formData,
 		includedProfileIds,
 		dragOverIndex,
@@ -32,6 +33,7 @@ export const ConfigProfilesPage = () => {
 		handleSubmit,
 		handleDelete,
 		handlePreview,
+		handleRefreshGitMounts,
 		updateFormField,
 		addEnvVar,
 		updateEnvVar,
@@ -110,6 +112,7 @@ export const ConfigProfilesPage = () => {
 				availableProfiles={availableProfilesForInclude()}
 				previewData={previewData}
 				previewingId={previewingId}
+				isRefreshingGitMounts={isRefreshingGitMounts}
 				saveStatus={saveStatus}
 				error={error}
 				onViewChange={setMobileView}
@@ -135,6 +138,7 @@ export const ConfigProfilesPage = () => {
 				onUpdateMountFile={updateMountFile}
 				onRemoveMountFile={removeMountFile}
 				onPreview={handlePreview}
+				onRefreshGitMounts={(id) => void handleRefreshGitMounts(id)}
 				onClosePreview={() => setPreviewData(null)}
 			/>
 		);
@@ -167,6 +171,7 @@ export const ConfigProfilesPage = () => {
 				saveStatus={saveStatus}
 				previewData={previewData}
 				previewingId={previewingId}
+				isRefreshingGitMounts={isRefreshingGitMounts}
 				projects={projects}
 				toolTypes={toolTypes}
 				availableProfiles={availableProfilesForInclude()}
@@ -176,6 +181,9 @@ export const ConfigProfilesPage = () => {
 				onSubmit={handleSubmit}
 				onReset={handleReset}
 				onPreview={() => selectedProfile && handlePreview(selectedProfile.id)}
+				onRefreshGitMounts={() =>
+					selectedProfile && handleRefreshGitMounts(selectedProfile.id)
+				}
 				onAddInclude={addInclude}
 				onRemoveInclude={removeInclude}
 				onDragStart={handleDragStart}

apps/web/src/styles/global.css

@@ -453,12 +453,16 @@
 	backdrop-filter: blur(2px);
 }
 
-.dialog {
+.dialog,
+.modal-content,
+.commit-dialog {
 	width: 100%;
 	max-width: 32rem;
 	max-height: calc(100vh - var(--space-8));
+	max-height: calc(100dvh - var(--space-8));
 	display: flex;
 	flex-direction: column;
+	min-height: 0;
 	overflow: hidden;
 	background: var(--panel);
 	border: 1px solid var(--border);
@@ -468,16 +472,6 @@
 
 .modal-content {
 	/* deprecated alias */
-	width: 100%;
-	max-width: 32rem;
-	max-height: calc(100vh - var(--space-8));
-	display: flex;
-	flex-direction: column;
-	overflow: hidden;
-	background: var(--panel);
-	border: 1px solid var(--border);
-	border-radius: var(--radius-lg);
-	box-shadow: var(--shadow-xl);
 }
 
 .dialog-lg {
@@ -500,9 +494,13 @@
 	line-height: var(--line-height-tight);
 }
 
-.dialog-body {
+.dialog-body,
+.modal-body {
 	flex: 1;
+	min-height: 0;
 	overflow: auto;
+	overscroll-behavior: contain;
+	-webkit-overflow-scrolling: touch;
 	padding: var(--space-4);
 }
 
@@ -543,9 +541,11 @@
 	}
 
 	.dialog,
-	.modal-content {
+	.modal-content,
+	.commit-dialog {
 		max-width: 100%;
 		max-height: calc(100vh - var(--space-6));
+		max-height: calc(100dvh - var(--space-6));
 		border-radius: var(--radius-lg) var(--radius-lg) 0 0;
 	}
 }

apps/web/src/styles/utilities.css

@@ -2328,8 +2328,10 @@ a.nav-item,
 	width: 100%;
 	max-width: 600px;
 	max-height: 70vh;
+	max-height: 70dvh;
 	display: flex;
 	flex-direction: column;
+	min-height: 0;
 	animation: slide-up 0.2s ease-out;
 }
 
@@ -2365,8 +2367,12 @@ a.nav-item,
 }
 
 .mobile-bottom-sheet-content {
+	flex: 1;
+	min-height: 0;
 	padding: 8px 0;
 	overflow-y: auto;
+	overscroll-behavior: contain;
+	-webkit-overflow-scrolling: touch;
 }
 
 .mobile-bottom-sheet-item {
@@ -3240,7 +3246,10 @@ a:active,
 	width: 100%;
 	max-width: 500px;
 	max-height: 80vh;
+	max-height: 80dvh;
 	overflow-y: auto;
+	overscroll-behavior: contain;
+	-webkit-overflow-scrolling: touch;
 	animation: slideUp 0.3s ease;
 	padding-bottom: env(safe-area-inset-bottom, 0);
 }
@@ -3602,6 +3611,7 @@ a:active,
 		max-width: none;
 		border-radius: 12px;
 		max-height: 70vh;
+		max-height: 70dvh;
 	}
 }
 

openspec/changes/.pi-map.index.md

@@ -10,6 +10,9 @@ map: openspec/.pi-map.md
 - openspec/changes/archive
   index: openspec/changes/archive/.pi-map.index.md
   map: openspec/changes/archive/.pi-map.md
+- openspec/changes/fix-config-profile-git-mount-clone-reuse
+  index: openspec/changes/fix-config-profile-git-mount-clone-reuse/.pi-map.index.md
+  map: openspec/changes/fix-config-profile-git-mount-clone-reuse/.pi-map.md
 - openspec/changes/fix-container-status-false-positive
   index: openspec/changes/fix-container-status-false-positive/.pi-map.index.md
   map: openspec/changes/fix-container-status-false-positive/.pi-map.md

openspec/changes/add-project-favicon/change.md

@@ -0,0 +1,21 @@
+# Add a Headquarter Favicon
+
+## Summary
+
+Add a compact, recognizable favicon for Headquarter and register it in the web document head.
+
+## Design
+
+Use a geometric cream `H` on the product's evergreen brand field. The mark remains identifiable at small browser-tab sizes, avoids font rendering dependencies, and matches both light and dark application themes.
+
+## Scope
+
+- `apps/web/public/favicon.svg`
+- `apps/web/index.html`
+
+## Acceptance Criteria
+
+- [ ] The browser uses a dedicated Headquarter favicon.
+- [ ] The mark remains legible at small sizes and on light or dark browser chrome.
+- [ ] The HTML declares the icon type and a matching browser theme color.
+- [ ] Frontend production build passes.

openspec/changes/add-project-favicon/tasks.md

@@ -0,0 +1,6 @@
+# Add a Headquarter Favicon — Tasks
+
+- [x] Create the favicon asset.
+- [x] Register the favicon and browser theme color in the web entry document.
+- [x] Run the frontend production build.
+- [x] Update project maps for changed source files.

openspec/changes/fix-config-profile-git-mount-clone-reuse/.pi-map.index.md

@@ -0,0 +1,20 @@
+# openspec/changes/fix-config-profile-git-mount-clone-reuse (index)
+dir: openspec/changes/fix-config-profile-git-mount-clone-reuse
+
+## role
+Documents and tracks a bug fix for reusing cached Config Profile git mount clones during tool instance startup.
+## parent
+index: openspec/changes/.pi-map.index.md
+map: openspec/changes/.pi-map.md
+## children
+-
+## files
+- change.md
+- tasks.md
+## links
+index: openspec/changes/fix-config-profile-git-mount-clone-reuse/.pi-map.index.md
+map: openspec/changes/fix-config-profile-git-mount-clone-reuse/.pi-map.md
+## workflows
+-
+## dirty
+-

openspec/changes/fix-config-profile-git-mount-clone-reuse/.pi-map.md

@@ -0,0 +1,20 @@
+# openspec/changes/fix-config-profile-git-mount-clone-reuse
+dir: openspec/changes/fix-config-profile-git-mount-clone-reuse
+
+index: openspec/changes/fix-config-profile-git-mount-clone-reuse/.pi-map.index.md
+
+## role
+Documents and tracks a bug fix for reusing cached Config Profile git mount clones during tool instance startup.
+## files
+- change.md | Describes the cached clone regression, required behavior, implementation scope, and verification plan.
+- tasks.md | Tracks investigation, regression testing, implementation, project-map maintenance, verification, and commit status.
+## arch
+Documentation-only OpenSpec change package with separate change rationale and implementation task checklist.
+## tags
+config, profile, git, mount, clone, cache, startup, fix
+## symbols
+-
+## workflows
+-
+## dirty
+-

openspec/changes/fix-config-profile-git-mount-clone-reuse/change.md

@@ -0,0 +1,27 @@
+# Fix config profile git mount clone reuse
+
+## Problem
+
+Starting a tool instance with a Config Profile git mount can omit the mount when the repository was already cloned into the instance cache. The startup log reports that the destination path already exists and is not an empty directory.
+
+## Root cause
+
+`clone_git_repo()` computes a deterministic cache directory but calls `clone_repository()` before checking whether that directory already contains a clone. `git clone` therefore fails on repeated starts or overlapping start requests. `resolve_single_git_mount()` treats auxiliary mount failures as non-blocking, so startup continues without the configured volume.
+
+## Required behavior
+
+1. A valid existing git mount clone must be reused and updated instead of cloned again.
+2. A missing clone must still be created normally.
+3. An incomplete clone directory must not permanently prevent a later retry.
+4. A clone/update failure remains non-blocking at the git mount resolver boundary.
+
+## Scope
+
+- Correct clone-cache handling in `apps/api/src/services/tool/instance_service.py`.
+- Add focused regression tests in `apps/api/tests/unit/test_instance_service.py`.
+- No API, database, frontend, or Docker Compose contract changes.
+
+## Verification
+
+- Targeted `pytest` for git mount clone reuse and instance service tests.
+- Ruff and mypy checks for changed backend files.

openspec/changes/fix-config-profile-git-mount-clone-reuse/tasks.md

@@ -0,0 +1,9 @@
+# Tasks: fix config profile git mount clone reuse
+
+- [x] Capture the failing runtime trace from an affected tool session.
+- [x] Add a regression test proving a valid cached clone is reused.
+- [x] Update `clone_git_repo()` to check the deterministic clone path before cloning.
+- [x] Recover safely from an incomplete clone directory.
+- [x] Run targeted backend tests and quality checks.
+- [x] Update project maps and validate map freshness.
+- [x] Commit the verified fix.

openspec/changes/fix-dialog-scroll-containment/change.md

@@ -0,0 +1,28 @@
+# Constrain and Scroll Edit Dialogs and Popups
+
+## Summary
+
+Ensure every edit dialog, form popup, and modal popup remains usable on a viewport that is shorter than its content. Dialog chrome must stay within the visible viewport while the content area scrolls independently.
+
+## Problem
+
+The shared dialog system constrains only components that follow its `dialog-header` / `dialog-body` structure. Several tool-launch and commit dialogs place form content directly inside the container or use a bespoke container, so long forms can be clipped. Existing viewport sizing also relies on `vh`, which is unreliable when mobile browser chrome changes height.
+
+## Scope
+
+- Shared dialog and modal CSS in `apps/web/src/styles/global.css`.
+- Mobile notification dropdown sizing in `apps/web/src/styles/utilities.css`.
+- Tool-launch and commit popup markup that does not currently provide a scrollable content region.
+
+## Acceptance Criteria
+
+- [ ] Dialogs and modal popups are bounded by the current visible viewport, including mobile dynamic viewport changes.
+- [ ] Headers and footer/action bars remain visible while long form content scrolls independently.
+- [ ] Tool-launch and commit popups use the shared scrollable content pattern.
+- [ ] Mobile sheets, action sheets, and notification dropdowns remain scrollable without propagating scroll gestures to the page.
+- [ ] Relevant frontend tests, typecheck, lint, and production build pass.
+
+## Non-Goals
+
+- Redesigning dialog visuals or interaction flows.
+- Changing page-level scrolling outside overlays.

openspec/changes/fix-dialog-scroll-containment/tasks.md

@@ -0,0 +1,8 @@
+# Constrain and Scroll Edit Dialogs and Popups — Tasks
+
+- [x] Audit all dialog, modal, sheet, action-sheet, and popup implementations.
+- [x] Strengthen shared dialog/modal viewport and body scrolling rules.
+- [x] Update bespoke tool-launch and commit popups to use scrollable content regions.
+- [x] Add focused coverage for the shared scrollable dialog-body markup.
+- [x] Run frontend typecheck, lint, tests (88 passed), and production build.
+- [x] Update project maps for changed source files.

openspec/changes/fix-pi-container-mount-permissions/change.md

@@ -12,6 +12,7 @@ After implementing configurable tool container home directories, new `pi-agent`
 4. `npm_global` packages are installed with `RUN npm install -g ...` as root into the system npm prefix, so the non-root container user cannot update them.
 5. Once the repo mount moves out of `/workspace`, the generated `/workspace` compatibility symlink is created in the image as root. The non-root entrypoint cannot replace it (write permission is required on `/`), so container startup fails.
 6. Older images baked a literal `{{WORKSPACE_NAME}}` directory into `/home/user`, which survives alongside the real repo-named mount directory.
+7. Config-profile file mounts use canonical profile storage owned by the API process. A non-root container user therefore cannot write to writable bind mounts. When a directory-level profile mount and a Git mount share or nest under the same target, Docker bind mounting masks the earlier source rather than merging their files.
 
 ## Fix
 
@@ -40,7 +41,9 @@ After implementing configurable tool container home directories, new `pi-agent`
 6. Remove the explicit repo mount from the built-in `pi-agent` manifest so the repo mount is synthesized by `compile_compose` rather than depending on tool config. Add a follow-up Alembic data migration that strips the `source_type: repo` mount from the manifest.
 7. Add `_get_repository_mount_name()` helper. When the instance is bound to a workspace, the helper returns the basename of `workspace.path`. For legacy repo-only instances it falls back to parsing the remote URL like `git clone` would, then to the user-provided repository name.
 8. Switch workspace storage layout to `/data/working-copies/{workspace_id}/{repo_name}/` so `git clone` creates the repo-named directory naturally, making `workspace.path.basename` the correct container mount name. This replaces the previous `/data/working-copies/{repo_id}/{workspace_name}/` layout.
-9. Update unit tests for the new behavior.
+9. Stage every config-profile bind-mount source into the instance directory before compose generation. This makes writable mounts user-owned without changing the shared canonical profile source.
+10. Replace overlapping profile and Git bind mounts with a per-instance composite source. The composite copies Git content first and profile content second, preserving Git siblings while allowing profile files to override matching paths; it is then chowned with the other staged mounts. This removes duplicate/nested Docker mounts rather than relying on mount order to merge them.
+11. Update unit tests for the new behavior.
 
 ## Affected files
 

openspec/changes/fix-pi-container-mount-permissions/tasks.md

@@ -12,5 +12,8 @@
 - [x] Remove compose-level `user: 0:0` override so entrypoint can drop privileges
 - [x] Pass manifest-declared container user to terminal sessions via `docker exec --user`
 - [x] Update unit tests for container user/terminal changes
+- [x] Stage profile bind mounts per instance so writable sources are owned by the container user
+- [x] Composite overlapping profile and Git mounts into one per-instance bind source
+- [x] Add regression tests for mount composition, ownership staging, and mount order
 - [ ] Run quality gates for container user/terminal changes
 - [ ] Commit and push

openspec/changes/fix-web-terminal-resilience/change.md

@@ -0,0 +1,35 @@
+# Fix Web Terminal Resilience
+
+## Summary
+
+Prevent large browser pastes from blocking flow-control acknowledgements, and prevent stale reconnect callbacks from replacing a healthy terminal WebSocket.
+
+## Problem
+
+The terminal WebSocket handler awaits each PTY write inline. A large paste can wait for the PTY to become writable while the same handler stops receiving acknowledgement messages. If output flow control has paused PTY reads, the acknowledgement that would resume output remains unread, leaving the terminal apparently frozen.
+
+Separately, reconnect timers and visibility callbacks can create a second socket after a connection becomes healthy. The terminal manager then closes the existing session socket, interrupting active input or rendering.
+
+## Scope
+
+- Queue bounded terminal input onto a single ordered writer so the WebSocket receive loop continues handling acknowledgements, resize, reset, and disconnect messages.
+- Make browser reconnection single-owner: stale socket callbacks and retry timers MUST NOT replace a current healthy socket.
+- Add focused regression tests for the queueing and reconnect behavior.
+
+## Non-goals
+
+- Re-enable desktop normal-buffer scrollback or mouse-wheel scrolling. Desktop continues to use zero scrollback and disabled wheel sensitivity to avoid the known stale TUI-frame regression.
+- Change terminal session persistence, authentication, PTY transport, or mobile touch scrolling behavior.
+
+## Risk and rollback
+
+The bounded input queue must preserve input ordering, reject excess input without blocking control messages, and be cancelled when the WebSocket disconnects. Socket ownership checks must not prevent a legitimate reconnect after a real disconnect. Roll back by reverting the backend queue and frontend ownership changes; existing direct PTY input and retry behavior then resumes.
+
+## Acceptance Criteria
+
+- [ ] A blocked PTY write does not prevent the WebSocket handler from processing a subsequent flow-control acknowledgement.
+- [ ] Input bytes are still written to the PTY in arrival order, and excess queued input is rejected rather than growing without limit.
+- [ ] A stale socket close event or retry callback cannot replace an open current socket.
+- [ ] Component cleanup cancels pending reconnect timers and closes the current socket.
+- [ ] Desktop scrollback and wheel settings remain unchanged.
+- [ ] Focused backend/frontend tests and relevant quality gates pass.

openspec/changes/fix-web-terminal-resilience/tasks.md

@@ -0,0 +1,27 @@
+# Fix Web Terminal Resilience — Tasks
+
+## Review Workload Forecast
+
+| Field | Value |
+| ------- | ------- |
+| Estimated changed lines | 180–280 |
+| 400-line budget risk | Low |
+| Chained PRs recommended | No |
+| Suggested split | Single focused change |
+| Delivery strategy | single-pr |
+| Chain strategy | feature-branch-chain |
+
+Decision needed before apply: No
+Chained PRs recommended: No
+Chain strategy: feature-branch-chain
+400-line budget risk: Low
+
+## Tasks
+
+- [x] **RED — backend input/control concurrency:** characterize a PTY write that waits for readiness while an acknowledgement is received; prove the acknowledgement is handled without waiting for that write to finish.
+- [x] **GREEN — ordered input writer:** move PTY writes behind one cancellable ordered queue/worker while retaining the current public WebSocket message protocol and input ordering.
+- [x] **TRIANGULATE — lifecycle:** cover worker cancellation and queued-write failure/disconnect handling.
+- [x] **RED — frontend socket ownership:** characterize stale close/retry callbacks after a newer socket has become current.
+- [x] **GREEN — reconnect ownership:** ensure only the current socket can update state or schedule a retry; cancel retry timers during cleanup.
+- [x] **REFACTOR:** keep the connection lifecycle readable and avoid changing the intentional desktop scrollback configuration.
+- [x] **Verify:** run targeted backend and frontend tests, frontend typecheck/lint/build, backend checks practical in the isolated worktree, and inspect diagnostics. (Backend pytest is unavailable locally: no pytest/uv executable; Docker test execution was explicitly declined.)

openspec/changes/live-config-profile-refresh/change.md

@@ -0,0 +1,33 @@
+# Live Config Profile Refresh
+
+## Summary
+
+Refresh profile-managed configuration for running tool instances when a Config Profile is saved, without recreating the container or terminal session.
+
+## Scope
+
+- Resolve the saved profile and refresh every running instance that selected it, including profiles that include it.
+- Store non-Git profile configuration as a canonical, host-side working copy shared by every instance using the profile.
+- Bind-mount canonical profile directories directly into their configured container targets and bind-mount canonical profile files individually under the container working directory, preserving the workspace mount.
+- Allow UI and container-side edits to the same canonical files; last writer wins, with an overwrite warning when detectable.
+- Defer Git mount refresh and Git-clone mutation to a separate commit-aware feature.
+- Standardize all supported tool containers on one shared non-root user/group so canonical writable profile mounts remain accessible across instances.
+- Return per-instance refresh results to the profile-save UI.
+
+## Constraints
+
+- Preserve running containers and terminal sessions.
+- Preserve the workspace/repository mount.
+- Docker bind-mount topology is immutable at runtime. Added, removed, retargeted, or mode-changed mounts MUST be reported as requiring restart, not partially applied.
+- Desktop and mobile profile editors use the same save/refresh behavior.
+- The standardized container user/group MUST be applied to built-in tool definitions, generated manifests, and image templates; legacy/incompatible tool images must report incompatible permissions rather than silently changing profile mount ownership.
+
+## Acceptance Criteria
+
+- [ ] Saving a profile refreshes every eligible running instance with a direct or transitive dependency on that profile.
+- [ ] Canonical non-Git profile files and mount directories are shared writable working copies across compatible running instances.
+- [ ] Container-side and UI-side changes become visible to all instances using the profile; last writer wins and detectable overwrites generate a warning.
+- [ ] Git mount refresh and Git clone mutation are not performed by this feature.
+- [ ] Built-in supported tool containers use a shared non-root user/group compatible with writable canonical profile mounts.
+- [ ] Topology changes return a restart-required result without recreating the instance.
+- [ ] Terminal WebSocket sessions remain connected throughout a successful refresh.

openspec/changes/live-config-profile-refresh/design.md

@@ -0,0 +1,17 @@
+# Design: Live Config Profile Refresh
+
+## Canonical working copies
+
+Each non-Git Config Profile owns canonical host-side storage. Directory mounts use canonical profile directories; each top-level profile file uses a canonical host file bind-mounted under the container working directory. All compatible instances selected for the profile mount the same sources, so UI and container edits are immediately shared.
+
+## Container compatibility
+
+Supported built-in tools standardize on one non-root user/group. Existing instances retain their current image/user and report `restart_required`. Custom tools are not rewritten; tools that do not opt into the shared user/group return `incompatible_permissions`.
+
+## Save behavior
+
+A profile save writes canonical profile files atomically per file. The save response reports affected compatible instances, `restart_required` topology/runtime changes, `incompatible_permissions`, and detectable overwrite warnings. Last writer wins; no merge or lock protocol is imposed.
+
+## Scope boundaries
+
+Git mount mutation is explicitly deferred. Workspace/repository mounts are never changed. Profile deletion is rejected while running instances still use the profile.

openspec/changes/live-config-profile-refresh/implementation-plan.md

@@ -0,0 +1,19 @@
+# Implementation Plan: Live Config Profile Refresh
+
+1. Standardize built-in tool user/group definitions and remove ownership-changing behavior for shared profile sources.
+2. Add canonical profile storage and bind-mount compilation for profile directories and individual working-directory files.
+3. Add compatibility/topology analysis, running-instance discovery, save-result schema, and deletion guard.
+4. Wire desktop/mobile profile save results into immediate status/warning feedback.
+5. Add unit, API, manifest/image, and frontend coverage; run quality gates and manual two-instance QA.
+
+## Delivery order
+
+1. Container-user compatibility
+2. Canonical non-Git profile mounts
+3. API and deletion semantics
+4. UI feedback
+5. Verification and commit
+
+## Deferred
+
+Git mount refresh and Git clone mutation require a commit-aware follow-up change.

openspec/changes/live-config-profile-refresh/tasks.md

@@ -0,0 +1,32 @@
+# Live Config Profile Refresh — Tasks
+
+## Review Workload Forecast
+
+| Field | Value |
+| --- | --- |
+| Estimated changed lines | 500–750 |
+| 400-line budget risk | High |
+| Chained PRs recommended | Yes |
+| Suggested split | Container-user standardization → canonical profile mounts → API/UI feedback → verification |
+| Delivery strategy | feature-branch-chain |
+| Chain strategy | feature-branch-chain |
+
+Decision needed before apply: No
+Chained PRs recommended: Yes
+Chain strategy: feature-branch-chain
+400-line budget risk: High
+
+## Tasks
+
+- [ ] **RED/GREEN — shared container user:** standardize built-in tool images, manifests, and permission handling on one shared non-root user/group; detect incompatible legacy images.
+- [ ] **RED/GREEN — canonical profile storage:** create canonical host-side directories/files per profile and mount them directly into compatible instances, without masking workspace mounts.
+- [ ] **TRIANGULATE — writable sharing:** prove UI and container edits are shared across instances, with last-writer-wins overwrite warnings.
+- [ ] **RED/GREEN — topology/API contract:** return restart-required or incompatible-permissions outcomes for paths that cannot mount live; defer Git mount mutation.
+- [ ] **RED/GREEN — UI feedback:** show shared-working-copy, warning, restart-required, and incompatible-permissions results in desktop and mobile profile editors.
+- [ ] **Verify:** run targeted backend/frontend tests, typecheck, lint, image/manifest checks, and manual multi-instance permission tests.
+
+## Verification Notes
+
+- Passed: frontend production build (`npm run build`), Python compilation for changed backend modules, and targeted LSP diagnostics.
+- Skipped: backend pytest and Ruff; this environment has no project-managed Python runner, system Python lacks those packages, and the user declined system-package installation.
+- Skipped: Docker/Compose and manual multi-instance checks; explicit Docker approval was not granted.

openspec/changes/live-config-profile-refresh/test-plan.md

@@ -0,0 +1,28 @@
+# Test Plan: Live Config Profile Refresh
+
+## Backend
+
+- Canonical file and directory paths are profile-scoped and reject traversal.
+- Two compatible instances receive the same host mount source.
+- A container-side file edit is visible through the profile read API and another instance mount.
+- A profile save updates canonical content and returns overwrite warnings when applicable.
+- Topology, environment, runtime, and legacy-instance changes return `restart_required`.
+- Incompatible users return `incompatible_permissions`.
+- Deleting a profile with running dependents is rejected with their instance identifiers.
+- Git mount content is unchanged by this feature.
+
+## Container/image compatibility
+
+- Each built-in supported image uses the common non-root UID/GID.
+- Generated manifest Dockerfiles and entrypoints retain that user and writable mount access.
+- Existing instances are not mutated until restart/recreation.
+
+## Frontend
+
+- Desktop and mobile save flows display refreshed/shared-working-copy, overwrite-warning, restart-required, and incompatible-permissions results.
+
+## Manual QA
+
+- Open two compatible instances using one profile; edit a mounted file in one terminal and verify it in the other.
+- Save a profile edit and verify both running instances see it without terminal disconnection.
+- Verify profile deletion is blocked while either instance is running.

openspec/changes/live-git-config-mount-refresh/change.md

@@ -0,0 +1,25 @@
+# Live Git Config Mount Refresh
+
+## Why
+
+Git-backed Config Profile mounts are currently cloned per instance. Their content cannot be refreshed consistently for running sessions, and writable container mounts can dirty the checkout.
+
+## Change
+
+Move Git Config Profile mounts to profile-scoped canonical host clones. Bind the already-mounted directory sources read-only into compatible instances and refresh a stable branch/ref checkout in place under a per-clone lock.
+
+## Scope
+
+- Canonical clone identity: profile, normalized remote, requested ref, and credential scope.
+- In-place refresh for existing directory mounts only.
+- Explicit outcomes for live refresh, restart-required topology changes, and refresh failures.
+- Read-only container Git config mounts.
+- An in-progress indicator that prevents duplicate refresh requests in desktop and mobile Config Profile views.
+
+## Out of scope
+
+- Writable shared Git configuration mounts.
+- Global cross-user clone sharing.
+- Live mount-topology changes, direct-file mappings, or glob match-set changes.
+- Atomic all-files revision switching for processes already reading the mount.
+- Automatic refresh of an editor buffer that has already loaded a mounted file.

openspec/changes/live-git-config-mount-refresh/design.md

@@ -0,0 +1,32 @@
+# Design: Live Git Config Mount Refresh
+
+## Canonical source
+
+Each selected Config Profile owns canonical Git clone directories beneath:
+
+```text
+<instance-root>/config-profiles/<profile-id>/git-mounts/<identity>/repo
+```
+
+`identity` is a stable hash of normalized remote URL, requested ref, and credential scope. Sources are deliberately profile-scoped; clones are never shared across users.
+
+## Runtime behavior
+
+1. Resolve Git mounts and map them to canonical sources.
+2. Acquire an exclusive lock for clone, fetch, ref resolution, and checkout.
+3. Clone into a temporary sibling, then rename on initial creation.
+4. For refresh, fetch and update the existing working tree in place.
+5. Bind directory mappings read-only. Existing containers see changed directory contents without recreation.
+6. When profile and Git mount paths overlap, the instance-local composite source must be synchronized in place during refresh; replacing its root directory would leave a running bind mount attached to the old inode.
+
+## Boundaries
+
+- URL/ref/source/target/mode changes, direct-file mappings, and changed glob result sets return `restart_required`.
+- Refresh failure is reported without mutating a known-good checkout.
+- No non-Git profile content may be copied into a Git checkout; overlapping targets are rejected or reported.
+- Containers must not write to shared Git mount sources.
+- A browser editor that already has a file open is not a filesystem watcher; the user must reload that editor buffer after the mounted source changes.
+
+## Security
+
+Host Git operations use only an authorized server-side credential source. Credentials are not part of the mounted checkout and are not exposed to containers.

openspec/changes/live-git-config-mount-refresh/tasks.md

@@ -0,0 +1,16 @@
+# Live Git Config Mount Refresh — Tasks
+
+- [x] Add canonical profile-scoped Git clone source planning and clone identity helpers.
+- [x] Make Git Config Profile mounts read-only and prevent profile-content copy into Git sources.
+- [x] Add lock-protected clone/fetch/ref checkout refresh that preserves a known-good checkout on failure.
+- [x] Add save/refresh outcomes for live refresh, restart-required topology, and failures.
+- [x] Add an in-progress desktop/mobile indicator that disables duplicate Git-mount refresh requests.
+- [ ] Synchronize affected instance-local composite mounts in place so live refresh reaches running containers.
+- [ ] Add focused resolver/service/API/frontend tests.
+- [x] Run available verification and document skipped checks.
+
+## Verification Notes
+
+- Passed: frontend production build and Python compilation for changed backend modules.
+- Skipped: backend pytest and Ruff are unavailable in this environment; Docker/manual live-session checks were not approved.
+- Known tooling limitation: project-map patching fails before execution because its runtime sends an unsupported `temperature` parameter.

tool-images/base.dockerfile

@@ -20,9 +20,10 @@ RUN apt-get update && apt-get install -y \
     sudo \
     && rm -rf /var/lib/apt/lists/*
 
-# Create a non-root user and allow passwordless sudo so the startup
-# permission fixer can adjust ownership of bind-mounted directories.
-RUN useradd -m -s /bin/bash user \
+# Use the shared built-in UID/GID so writable Config Profile mounts can be
+# shared by compatible instances without ownership changes.
+RUN groupadd -g 1000 user \
+    && useradd -m -u 1000 -g 1000 -s /bin/bash user \
     && echo "user ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/user \
     && chmod 0440 /etc/sudoers.d/user
 WORKDIR /home/user

tool-images/code-server.dockerfile

@@ -22,7 +22,11 @@ RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
 # Set up git
 RUN git config --global init.defaultBranch main
 
-# Code-server runs as abc user by default
+# The LinuxServer entrypoint maps abc to this shared UID/GID before starting
+# code-server, so writable Config Profile mounts are compatible with other
+# built-in tool containers.
+ENV PUID=1000 \
+    PGID=1000
 USER abc
 
 EXPOSE 8443

tool-images/jupyter.dockerfile

@@ -17,7 +17,10 @@ RUN apt-get update && apt-get install -y \
 # Set up git
 RUN git config --global init.defaultBranch main
 
-# Switch back to jovyan user (default for scipy-notebook)
-USER ${NB_UID}
+# start-notebook.py maps jovyan to this shared UID/GID and drops privileges.
+# Keep the image root at entrypoint time so that mapping can occur.
+ENV NB_UID=1000 \
+    NB_GID=1000
+USER root
 
 EXPOSE 8888

tool-images/opencode.dockerfile

@@ -27,8 +27,9 @@ RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
 # Install OpenCode
 RUN npm install -g opencode
 
-# Create non-root user
-RUN useradd -m -s /bin/bash user
+# Use the shared built-in UID/GID for writable Config Profile mounts.
+RUN groupadd -g 1000 user \
+    && useradd -m -u 1000 -g 1000 -s /bin/bash user
 WORKDIR /home/user
 
 # Set up git

tool-images/pi-agent.dockerfile

@@ -28,8 +28,9 @@ RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
 # Install Pi Coding Agent globally
 RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent
 
-# Create non-root user
-RUN useradd -m -s /bin/bash user
+# Use the shared built-in UID/GID for writable Config Profile mounts.
+RUN groupadd -g 1000 user \
+    && useradd -m -u 1000 -g 1000 -s /bin/bash user
 WORKDIR /home/user
 
 # Set up git
@@ -37,15 +38,11 @@ RUN git config --global init.defaultBranch main \
     && git config --global user.email "dev@headquarter.local" \
     && git config --global user.name "Developer"
 
-# Create default tmux config
-RUN printf '%s\n' 'set -g mouse on' 'set -g default-terminal "screen-256color"' > /home/user/.tmux.conf
-
-# Create default ranger config
-RUN mkdir -p /home/user/.config/ranger \
-    && printf '%s\n' 'set preview_files true' 'set use_preview_script true' > /home/user/.config/ranger/rc.conf
-
-# Set up Pi config directory
-RUN mkdir -p /home/user/.pi/agent
+# Create user-owned default configuration files.
+RUN printf '%s\n' 'set -g mouse on' 'set -g default-terminal "screen-256color"' > /home/user/.tmux.conf \
+    && mkdir -p /home/user/.config/ranger /home/user/.pi/agent \
+    && printf '%s\n' 'set preview_files true' 'set use_preview_script true' > /home/user/.config/ranger/rc.conf \
+    && chown -R user:user /home/user
 
 USER user