fix: retry start/restart on network errors

When Docker starts a container, it creates network interfaces which
triggers Chrome's ERR_NETWORK_CHANGED error, aborting the request.
The backend successfully starts the container but the frontend never
gets the response, showing 'failed to create session' even though
the session is up.

Fix: Add retry with exponential backoff for startInstance and
restartInstance when network errors occur (no HTTP response).
Retries up to 2 times with 1.5s delay between attempts.

Fixes: False 'failed to create session' errors when launching tools.

.claude/skills/sift-backlog/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: sift-backlog
+description: Triage and organize backlog tasks into actionable plans. Use when asked to review the backlog, prioritize tasks, create plans from backlog items, or move tasks from backlog to open status. Handles the full workflow of listing backlog tasks, grouping related tasks into plans, setting priorities and dependencies, activating plans, and changing task status from backlog to open.
+---
+
+# Sift Backlog
+
+Triage backlog tasks: prioritize, group into plans, set dependencies, and activate.
+
+## Overview
+
+1. List backlog tasks (`sf task backlog`)
+2. Clarify and enrich each task (titles, descriptions)
+3. Identify groupings and create draft plans
+4. Add tasks to plans and set dependencies
+5. Activate plans
+6. Set task status to open
+
+## Workflow
+
+### Step 1: List Backlog Tasks
+
+```bash
+sf task backlog
+```
+
+### Step 2: Clarify and Enrich Tasks
+
+Backlog tasks often have only a brief title with no description. Before organizing, ensure each task is well-defined.
+
+**For each task, evaluate:**
+
+- Is the title clear and actionable?
+- Is there a description? Check with `sf task describe <task-id> --show`
+- Is the scope unambiguous?
+
+**If the title is unclear**, update it:
+
+```bash
+sf update <task-id> --title "Clear, actionable title"
+```
+
+**Add a description** with context, scope, and acceptance criteria:
+
+```bash
+sf task describe <task-id> --content "Description with:
+- What needs to be done
+- Why it matters
+- Acceptance criteria
+- Any relevant context"
+```
+
+**Use your best judgment** to interpret tasks and make reasonable decisions about scope, grouping, and priority. You have context about the codebase, project patterns, and typical development practices—leverage this knowledge rather than deferring to the user for routine decisions.
+
+**Only ask the user for clarity when absolutely necessary:**
+
+- The task is fundamentally ambiguous (multiple mutually exclusive interpretations)
+- Critical business logic or user-facing behavior that could go wrong in meaningful ways
+- External dependencies or integrations you cannot verify
+
+**Do NOT ask about:**
+
+- Implementation details you can reasonably infer
+- Priority or grouping decisions—use your judgment
+- Standard development practices (testing, code style, etc.)
+- Tasks where a reasonable interpretation exists
+
+### Step 3: Create Draft Plans
+
+Group related tasks into plans using your best judgment. Plans start as drafts (tasks won't be dispatched until activated).
+
+**Grouping guidance:**
+
+- Group tasks that share a common theme, feature area, or goal
+- Consider technical dependencies when grouping (tasks that touch the same files/modules)
+- Separate unrelated work into distinct plans for parallel execution
+- Don't over-group—if tasks are truly independent, separate plans enable better parallelism
+- Don't under-group—related tasks benefit from shared context and coordinated execution
+
+```bash
+sf plan create --title "Plan Name"
+```
+
+**Example:**
+
+```bash
+sf plan create --title "Authentication Improvements"
+# Output: Created plan el-abc123
+```
+
+### Step 4: Add Tasks to Plans
+
+```bash
+sf plan add-task <plan-id> <task-id>
+```
+
+**Example:**
+
+```bash
+sf plan add-task el-abc123 el-task1
+sf plan add-task el-abc123 el-task2
+```
+
+### Step 5: Set Dependencies Between Tasks
+
+Use `blocks` dependency when one task must complete before another can start.
+
+```bash
+sf dependency add <blocked-id> <blocker-id> --type blocks
+```
+
+**Semantics:** The first ID is blocked BY the second ID. The blocker must complete first.
+
+**Example:** Task 2 can't start until Task 1 completes:
+
+```bash
+sf dependency add el-task2 el-task1 --type blocks
+```
+
+### Step 6: Update Priorities
+
+Set priorities based on your assessment of impact, urgency, and dependencies. Use your judgment—you don't need user confirmation for routine prioritization.
+
+**Priority guidance:**
+
+- **Critical (1):** Blocking issues, security vulnerabilities, production bugs
+- **High (2):** Important features with deadlines, significant user impact
+- **Medium (3):** Standard feature work, most tasks default here
+- **Low (4):** Nice-to-haves, minor improvements, tech debt
+- **Minimal (5):** Backlog cleanup, documentation, exploratory work
+
+```bash
+sf update <task-id> --priority <1-5>
+```
+
+| Value | Level    |
+| ----- | -------- |
+| 1     | Critical |
+| 2     | High     |
+| 3     | Medium   |
+| 4     | Low      |
+| 5     | Minimal  |
+
+### Step 7: Activate Plans
+
+Once tasks are organized with dependencies set, activate plans to enable dispatch.
+
+```bash
+sf plan activate <plan-id>
+```
+
+### Step 8: Set Task Status to Open
+
+Move tasks from backlog to open so they become ready for work.
+
+```bash
+sf update <id> --status open
+```
+
+## Other Actions
+
+**Close obsolete tasks:**
+
+```bash
+sf task close <id> --reason "Won't do: <reason>"
+```
+
+**Defer tasks:**
+
+```bash
+sf task defer <id> --until <date>
+```
+
+**View existing plans:**
+
+```bash
+sf plan list
+```
+
+**View tasks in a plan:**
+
+```bash
+sf plan tasks <plan-id>
+```
+
+## Tips
+
+- **Use your best judgment** for grouping, prioritization, and task interpretation—don't defer routine decisions to the user
+- **Only escalate to the user** when ambiguity is fundamental and could lead to wasted work (mutually exclusive interpretations, critical business decisions)
+- Make reasonable inferences about implementation details, scope, and priority based on codebase context
+- Create plans before setting dependencies to avoid dispatch race conditions
+- Always activate plans after dependencies are set
+- Focus on oldest backlog items first (sorted by creation date)
+- Every task should have a clear title and description before activation
+- When uncertain about a minor detail, make a reasonable choice and document it in the task description—workers can ask if needed

.gitignore

@@ -48,8 +48,4 @@ apps/web/dist/
 # OS
 .DS_Store
 Thumbs.db
-
-# Local runtime state
-.atl/
-.pi/
-swap-pane
+/.stoneforge/.worktrees/

.stoneforge/.dashboard-opened

@@ -0,0 +1,2 @@
+262629
+1779624255076

.stoneforge/.gitignore

@@ -0,0 +1,6 @@
+# Runtime data
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+daemon-state.json

.stoneforge/config.yaml

@@ -0,0 +1,20 @@
+# Stoneforge Configuration
+
+database: stoneforge.db
+sync:
+  auto_export: true
+  elements_file: elements.jsonl
+  dependencies_file: dependencies.jsonl
+playbooks:
+  paths:
+    - playbooks
+identity:
+  mode: soft
+merge:
+  auto_merge: true
+  target_branch: null
+  require_approval: false
+workflow:
+  preset: auto
+agents:
+  permission_model: unrestricted

.stoneforge/sync/dependencies.jsonl

@@ -0,0 +1,43 @@
+{"blockedId":"el-1of","blockerId":"el-258","type":"parent-child","createdAt":"2026-05-24T09:44:58.759Z","createdBy":"el-2jua"}
+{"blockedId":"el-5fe","blockerId":"el-20no","type":"parent-child","createdAt":"2026-05-24T12:44:40.892Z","createdBy":"el-2jua"}
+{"blockedId":"el-1nj","blockerId":"el-20no","type":"parent-child","createdAt":"2026-05-24T12:44:41.010Z","createdBy":"el-2jua"}
+{"blockedId":"el-1bn","blockerId":"el-20no","type":"parent-child","createdAt":"2026-05-24T12:44:41.127Z","createdBy":"el-2jua"}
+{"blockedId":"el-4hr","blockerId":"el-20no","type":"parent-child","createdAt":"2026-05-24T12:44:41.244Z","createdBy":"el-2jua"}
+{"blockedId":"el-62c","blockerId":"el-20no","type":"parent-child","createdAt":"2026-05-24T12:44:41.372Z","createdBy":"el-2jua"}
+{"blockedId":"el-5z8","blockerId":"el-20no","type":"parent-child","createdAt":"2026-05-24T12:44:41.490Z","createdBy":"el-2jua"}
+{"blockedId":"el-1t7","blockerId":"el-20no","type":"parent-child","createdAt":"2026-05-24T12:44:41.607Z","createdBy":"el-2jua"}
+{"blockedId":"el-5j5","blockerId":"el-20no","type":"parent-child","createdAt":"2026-05-24T12:44:41.726Z","createdBy":"el-2jua"}
+{"blockedId":"el-2xl","blockerId":"el-20no","type":"parent-child","createdAt":"2026-05-24T12:44:41.844Z","createdBy":"el-2jua"}
+{"blockedId":"el-4bc","blockerId":"el-20no","type":"parent-child","createdAt":"2026-05-24T12:44:41.959Z","createdBy":"el-2jua"}
+{"blockedId":"el-107","blockerId":"el-20no","type":"parent-child","createdAt":"2026-05-24T12:44:42.074Z","createdBy":"el-2jua"}
+{"blockedId":"el-32e","blockerId":"el-20no","type":"parent-child","createdAt":"2026-05-24T12:44:42.195Z","createdBy":"el-2jua"}
+{"blockedId":"el-3ou","blockerId":"el-20no","type":"parent-child","createdAt":"2026-05-24T12:44:42.311Z","createdBy":"el-2jua"}
+{"blockedId":"el-14w","blockerId":"el-20no","type":"parent-child","createdAt":"2026-05-24T12:44:42.425Z","createdBy":"el-2jua"}
+{"blockedId":"el-1ou","blockerId":"el-20no","type":"parent-child","createdAt":"2026-05-24T12:44:42.541Z","createdBy":"el-2jua"}
+{"blockedId":"el-1nj","blockerId":"el-5fe","type":"blocks","createdAt":"2026-05-24T12:44:42.651Z","createdBy":"el-2jua"}
+{"blockedId":"el-1bn","blockerId":"el-5fe","type":"blocks","createdAt":"2026-05-24T12:44:42.761Z","createdBy":"el-2jua"}
+{"blockedId":"el-4hr","blockerId":"el-5fe","type":"blocks","createdAt":"2026-05-24T12:44:42.868Z","createdBy":"el-2jua"}
+{"blockedId":"el-62c","blockerId":"el-1nj","type":"blocks","createdAt":"2026-05-24T12:44:42.979Z","createdBy":"el-2jua"}
+{"blockedId":"el-62c","blockerId":"el-1bn","type":"blocks","createdAt":"2026-05-24T12:44:43.092Z","createdBy":"el-2jua"}
+{"blockedId":"el-5z8","blockerId":"el-1nj","type":"blocks","createdAt":"2026-05-24T12:44:43.205Z","createdBy":"el-2jua"}
+{"blockedId":"el-5z8","blockerId":"el-4hr","type":"blocks","createdAt":"2026-05-24T12:44:43.313Z","createdBy":"el-2jua"}
+{"blockedId":"el-1t7","blockerId":"el-1bn","type":"blocks","createdAt":"2026-05-24T12:44:43.422Z","createdBy":"el-2jua"}
+{"blockedId":"el-1t7","blockerId":"el-4hr","type":"blocks","createdAt":"2026-05-24T12:44:43.529Z","createdBy":"el-2jua"}
+{"blockedId":"el-1t7","blockerId":"el-62c","type":"blocks","createdAt":"2026-05-24T12:44:43.647Z","createdBy":"el-2jua"}
+{"blockedId":"el-5j5","blockerId":"el-1t7","type":"blocks","createdAt":"2026-05-24T12:44:43.758Z","createdBy":"el-2jua"}
+{"blockedId":"el-2xl","blockerId":"el-1t7","type":"blocks","createdAt":"2026-05-24T12:44:43.876Z","createdBy":"el-2jua"}
+{"blockedId":"el-4bc","blockerId":"el-1nj","type":"blocks","createdAt":"2026-05-24T12:44:43.987Z","createdBy":"el-2jua"}
+{"blockedId":"el-4bc","blockerId":"el-1bn","type":"blocks","createdAt":"2026-05-24T12:44:44.096Z","createdBy":"el-2jua"}
+{"blockedId":"el-4bc","blockerId":"el-62c","type":"blocks","createdAt":"2026-05-24T12:44:44.208Z","createdBy":"el-2jua"}
+{"blockedId":"el-107","blockerId":"el-5z8","type":"blocks","createdAt":"2026-05-24T12:44:44.319Z","createdBy":"el-2jua"}
+{"blockedId":"el-32e","blockerId":"el-5j5","type":"blocks","createdAt":"2026-05-24T12:44:44.429Z","createdBy":"el-2jua"}
+{"blockedId":"el-32e","blockerId":"el-2xl","type":"blocks","createdAt":"2026-05-24T12:44:44.539Z","createdBy":"el-2jua"}
+{"blockedId":"el-3ou","blockerId":"el-4bc","type":"blocks","createdAt":"2026-05-24T12:44:44.650Z","createdBy":"el-2jua"}
+{"blockedId":"el-3ou","blockerId":"el-107","type":"blocks","createdAt":"2026-05-24T12:44:44.761Z","createdBy":"el-2jua"}
+{"blockedId":"el-14w","blockerId":"el-32e","type":"blocks","createdAt":"2026-05-24T12:44:44.873Z","createdBy":"el-2jua"}
+{"blockedId":"el-1ou","blockerId":"el-3ou","type":"blocks","createdAt":"2026-05-24T12:44:44.987Z","createdBy":"el-2jua"}
+{"blockedId":"el-1ou","blockerId":"el-14w","type":"blocks","createdAt":"2026-05-24T12:44:45.107Z","createdBy":"el-2jua"}
+{"blockedId":"el-375","blockerId":"el-26p","type":"replies-to","createdAt":"2026-05-24T13:21:42.486Z","createdBy":"el-2i1s"}
+{"blockedId":"el-3n4","blockerId":"el-31p","type":"replies-to","createdAt":"2026-05-24T13:21:46.044Z","createdBy":"el-13ju"}
+{"blockedId":"el-3jer","blockerId":"el-1xx","type":"replies-to","createdAt":"2026-05-24T13:24:47.580Z","createdBy":"el-4350"}
+{"blockedId":"el-1afv","blockerId":"el-1ozw","type":"replies-to","createdAt":"2026-05-24T13:32:42.658Z","createdBy":"el-51a8"}

AGENTS.md

@@ -87,6 +87,31 @@ Do not claim completion without verification evidence.
 
 ## Git workflow
 
+### Branching strategy
+
+For every spec change or new functionality:
+
+1. Create a new branch from `dev` with a proper prefix:
+   - `feat/` for new features (e.g., `feat/tool-workshop`)
+   - `fix/` for bug fixes (e.g., `fix/terminal-tty`)
+   - `refactor/` for refactors (e.g., `refactor/api-cleanup`)
+   - `docs/` for documentation (e.g., `docs/api-guide`)
+   - `chore/` for maintenance (e.g., `chore/update-deps`)
+2. Branch name should reference the OpenSpec change name when applicable.
+3. Do not commit directly to `main` or `dev`.
+
+### Completion and merge
+
+When implementation is complete and verified:
+
+1. Ensure all tests pass and quality gates are met.
+2. Stage all changes with `git add -A`.
+3. Create a commit with a proper conventional commit message (see below).
+4. Switch to `dev`: `git checkout dev`.
+5. Merge the feature branch: `git merge --no-ff <branch-name>`.
+6. Push to remote: `git push origin dev`.
+7. Delete the local feature branch if desired: `git branch -d <branch-name>`.
+
 ### Auto-commit on spec completion
 
 When an OpenSpec change is fully implemented and all tasks are complete:

CHANGELOG.md

@@ -21,7 +21,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **User Settings** - Theme selection, git identity, and preference management
 - **SSH Key Management** - Ed25519 key generation with secure storage
 - **Tool Types** - Built-in development tools (code-server, jupyter-notebook) with custom type support
-- **Config Profiles** - User-owned profile CRUD with includes, mounts, path validation, cycle detection, and default profile selection
 - **Comprehensive Documentation** - Architecture, API, deployment, and development guides
 
 ### Changed

apps/api/Dockerfile

@@ -27,6 +27,7 @@ WORKDIR /app
 RUN apt-get update && apt-get install -y --no-install-recommends \
     libpq5 \
     git \
+    openssh-client \
     netcat-openbsd \
     ca-certificates \
     curl \

apps/api/alembic/versions/0013_add_config_profiles.py

@@ -1,104 +0,0 @@
-"""add config profiles, includes, mounts, and tool instance profile selection
-
-Revision ID: 0013_add_config_profiles
-Revises: 0012_default_port_req
-Create Date: 2026-05-24 12:00:00.000000
-
-"""
-from typing import Sequence, Union
-
-from alembic import op
-import sqlalchemy as sa
-from sqlalchemy.dialects import postgresql
-
-# revision identifiers, used by Alembic.
-revision: str = "0013_add_config_profiles"
-down_revision: Union[str, None] = "0012_default_port_req"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    # Create config_profiles table
-    op.create_table(
-        "config_profiles",
-        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("user_id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("name", sa.String(length=255), nullable=False),
-        sa.Column("description", sa.Text(), nullable=True),
-        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
-        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
-        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
-        sa.PrimaryKeyConstraint("id"),
-        sa.UniqueConstraint("user_id", "name", name="uq_config_profiles_user_name"),
-    )
-    op.create_index("idx_config_profiles_user", "config_profiles", ["user_id"])
-
-    # Create config_includes table
-    op.create_table(
-        "config_includes",
-        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("profile_id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("included_profile_id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("order_index", sa.Integer(), nullable=False, server_default="0"),
-        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
-        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
-        sa.ForeignKeyConstraint(["profile_id"], ["config_profiles.id"], ondelete="CASCADE"),
-        sa.ForeignKeyConstraint(["included_profile_id"], ["config_profiles.id"], ondelete="CASCADE"),
-        sa.PrimaryKeyConstraint("id"),
-        sa.UniqueConstraint("profile_id", "included_profile_id", name="uq_config_includes_pair"),
-    )
-    op.create_index("idx_config_includes_profile", "config_includes", ["profile_id"])
-    op.create_index("idx_config_includes_included", "config_includes", ["included_profile_id"])
-
-    # Create config_mounts table
-    op.create_table(
-        "config_mounts",
-        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("profile_id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("mount_path", sa.String(length=1024), nullable=False),
-        sa.Column("content", sa.Text(), nullable=True),
-        sa.Column("source_profile_id", postgresql.UUID(as_uuid=True), nullable=True),
-        sa.Column("order_index", sa.Integer(), nullable=False, server_default="0"),
-        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
-        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
-        sa.ForeignKeyConstraint(["profile_id"], ["config_profiles.id"], ondelete="CASCADE"),
-        sa.ForeignKeyConstraint(["source_profile_id"], ["config_profiles.id"], ondelete="SET NULL"),
-        sa.PrimaryKeyConstraint("id"),
-    )
-    op.create_index("idx_config_mounts_profile", "config_mounts", ["profile_id"])
-
-    # Add selected_profile_id to tool_instances
-    op.add_column(
-        "tool_instances",
-        sa.Column("selected_profile_id", postgresql.UUID(as_uuid=True), nullable=True),
-    )
-    op.create_foreign_key(
-        "fk_tool_instances_selected_profile",
-        "tool_instances",
-        "config_profiles",
-        ["selected_profile_id"],
-        ["id"],
-        ondelete="SET NULL",
-    )
-    op.create_index("idx_tool_instances_selected_profile", "tool_instances", ["selected_profile_id"])
-
-
-def downgrade() -> None:
-    # Remove selected_profile_id from tool_instances
-    op.drop_index("idx_tool_instances_selected_profile", table_name="tool_instances")
-    op.drop_constraint("fk_tool_instances_selected_profile", "tool_instances", type_="foreignkey")
-    op.drop_column("tool_instances", "selected_profile_id")
-
-    # Drop config_mounts
-    op.drop_index("idx_config_mounts_profile", table_name="config_mounts")
-    op.drop_table("config_mounts")
-
-    # Drop config_includes
-    op.drop_index("idx_config_includes_included", table_name="config_includes")
-    op.drop_index("idx_config_includes_profile", table_name="config_includes")
-    op.drop_table("config_includes")
-
-    # Drop config_profiles
-    op.drop_index("idx_config_profiles_user", table_name="config_profiles")
-    op.drop_table("config_profiles")

apps/api/alembic/versions/0013_add_probe_result.py

@@ -0,0 +1,29 @@
+"""add probe_result to tool_instances
+
+Revision ID: 0013_add_probe_result
+Revises: 0012_default_port_req
+Create Date: 2026-05-22 21:45:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "0013_add_probe_result"
+down_revision: Union[str, None] = "0012_default_port_req"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "tool_instances",
+        sa.Column("probe_result", postgresql.JSON, nullable=True)
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("tool_instances", "probe_result")

apps/api/alembic/versions/0014_add_profile_resolver_fields.py

@@ -1,119 +0,0 @@
-"""add profile resolver fields to config profiles and mounts
-
-Revision ID: 0014_add_profile_resolver_fields
-Revises: 0013_add_config_profiles
-Create Date: 2026-05-24 14:00:00.000000
-
-"""
-from typing import Sequence, Union
-
-from alembic import op
-import sqlalchemy as sa
-from sqlalchemy.dialects import postgresql
-
-# revision identifiers, used by Alembic.
-revision: str = "0014_add_profile_resolver_fields"
-down_revision: Union[str, None] = "0013_add_config_profiles"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    # Add fields to config_profiles
-    op.add_column(
-        "config_profiles",
-        sa.Column("project_id", postgresql.UUID(as_uuid=True), nullable=True),
-    )
-    op.add_column(
-        "config_profiles",
-        sa.Column("tool_type_id", postgresql.UUID(as_uuid=True), nullable=True),
-    )
-    op.add_column(
-        "config_profiles",
-        sa.Column("environment_variables", sa.JSON(), nullable=True),
-    )
-    op.add_column(
-        "config_profiles",
-        sa.Column("start_command", sa.Text(), nullable=True),
-    )
-    op.add_column(
-        "config_profiles",
-        sa.Column("working_directory", sa.Text(), nullable=True),
-    )
-    op.add_column(
-        "config_profiles",
-        sa.Column("port", sa.Integer(), nullable=True),
-    )
-    op.add_column(
-        "config_profiles",
-        sa.Column("is_default", sa.Boolean(), nullable=False, server_default="false"),
-    )
-    
-    # Add foreign keys for project and tool_type
-    op.create_foreign_key(
-        "fk_config_profiles_project",
-        "config_profiles",
-        "projects",
-        ["project_id"],
-        ["id"],
-        ondelete="CASCADE",
-    )
-    op.create_foreign_key(
-        "fk_config_profiles_tool_type",
-        "config_profiles",
-        "tool_types",
-        ["tool_type_id"],
-        ["id"],
-        ondelete="CASCADE",
-    )
-    
-    # Create indices
-    op.create_index("idx_config_profiles_project", "config_profiles", ["project_id"])
-    op.create_index("idx_config_profiles_tool_type", "config_profiles", ["tool_type_id"])
-    
-    # Alter config_mounts: rename mount_path to target_path, add mode, change content to files JSON
-    op.alter_column("config_mounts", "mount_path", new_column_name="target_path")
-    op.add_column(
-        "config_mounts",
-        sa.Column("mode", sa.String(length=10), nullable=False, server_default="rw"),
-    )
-    op.add_column(
-        "config_mounts",
-        sa.Column("files", sa.JSON(), nullable=True),
-    )
-    # Drop the source_profile foreign key if it exists
-    op.drop_constraint(
-        "config_mounts_source_profile_id_fkey",
-        "config_mounts",
-        type_="foreignkey",
-    )
-    op.drop_column("config_mounts", "content")
-    op.drop_column("config_mounts", "source_profile_id")
-
-
-def downgrade() -> None:
-    # Restore config_mounts
-    op.add_column(
-        "config_mounts",
-        sa.Column("source_profile_id", postgresql.UUID(as_uuid=True), nullable=True),
-    )
-    op.add_column(
-        "config_mounts",
-        sa.Column("content", sa.Text(), nullable=True),
-    )
-    op.drop_column("config_mounts", "files")
-    op.drop_column("config_mounts", "mode")
-    op.alter_column("config_mounts", "target_path", new_column_name="mount_path")
-    
-    # Restore config_profiles
-    op.drop_index("idx_config_profiles_tool_type", table_name="config_profiles")
-    op.drop_index("idx_config_profiles_project", table_name="config_profiles")
-    op.drop_constraint("fk_config_profiles_tool_type", "config_profiles", type_="foreignkey")
-    op.drop_constraint("fk_config_profiles_project", "config_profiles", type_="foreignkey")
-    op.drop_column("config_profiles", "is_default")
-    op.drop_column("config_profiles", "port")
-    op.drop_column("config_profiles", "working_directory")
-    op.drop_column("config_profiles", "start_command")
-    op.drop_column("config_profiles", "environment_variables")
-    op.drop_column("config_profiles", "tool_type_id")
-    op.drop_column("config_profiles", "project_id")

apps/api/alembic/versions/0014_merge_heads.py

@@ -0,0 +1,25 @@
+"""merge migration heads
+
+Revision ID: 0014_merge_heads
+Revises: 0013_add_probe_result, 8ed7dd80973d
+Create Date: 2026-05-22 21:50:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "0014_merge_heads"
+down_revision: Union[str, Sequence[str], None] = ("0013_add_probe_result", "8ed7dd80973d")
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    pass
+
+
+def downgrade() -> None:
+    pass

apps/api/alembic/versions/0015_single_interface.py

@@ -0,0 +1,110 @@
+"""replace interfaces with interface_type and add requires_port
+
+Revision ID: 0015_single_interface
+Revises: 0014_merge_heads
+Create Date: 2026-05-22 22:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+from sqlalchemy import inspect
+
+# revision identifiers, used by Alembic.
+revision: str = "0015_single_interface"
+down_revision: Union[str, Sequence[str], None] = "0014_merge_heads"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def _get_dialect() -> str:
+    """Get the current database dialect name."""
+    conn = op.get_bind()
+    return conn.dialect.name
+
+
+def upgrade() -> None:
+    dialect = _get_dialect()
+    
+    # Add new columns
+    op.add_column('tool_types', sa.Column('interface_type', sa.String(20), nullable=True))
+    op.add_column('tool_types', sa.Column('requires_port', sa.Boolean(), nullable=False, server_default='true'))
+    
+    # Migrate data: take first element from interfaces JSON array
+    if dialect == 'postgresql':
+        op.execute("""
+            UPDATE tool_types 
+            SET interface_type = COALESCE(
+                (SELECT elem FROM jsonb_array_elements_text(interfaces::jsonb) AS elem LIMIT 1),
+                'web'
+            ),
+            requires_port = CASE 
+                WHEN COALESCE(
+                    (SELECT elem FROM jsonb_array_elements_text(interfaces::jsonb) AS elem LIMIT 1),
+                    'web'
+                ) = 'web' THEN true
+                ELSE false
+            END
+        """)
+    else:
+        # SQLite: interfaces is stored as JSON text, extract first array element
+        op.execute("""
+            UPDATE tool_types 
+            SET interface_type = COALESCE(
+                (SELECT json_extract(value, '$[0]') 
+                 FROM json_each(interfaces) AS value 
+                 WHERE json_valid(interfaces) 
+                 LIMIT 1),
+                'web'
+            ),
+            requires_port = CASE 
+                WHEN COALESCE(
+                    (SELECT json_extract(value, '$[0]') 
+                     FROM json_each(interfaces) AS value 
+                     WHERE json_valid(interfaces) 
+                     LIMIT 1),
+                    'web'
+                ) = 'web' THEN true
+                ELSE false
+            END
+        """)
+    
+    # Make interface_type non-nullable after data migration
+    op.alter_column('tool_types', 'interface_type', nullable=False)
+    
+    # Drop old interfaces column
+    op.drop_column('tool_types', 'interfaces')
+    
+    # Add CHECK constraint for interface_type (only on PostgreSQL; SQLite supports it too)
+    op.create_check_constraint('chk_interface_type', 'tool_types', sa.text("interface_type IN ('web', 'terminal')"))
+
+
+def downgrade() -> None:
+    dialect = _get_dialect()
+    
+    # Drop CHECK constraint
+    op.drop_constraint('chk_interface_type', 'tool_types', type_='check')
+    
+    # Add back interfaces column
+    if dialect == 'postgresql':
+        op.add_column('tool_types', sa.Column('interfaces', postgresql.JSONB(astext_type=sa.Text()), nullable=False, server_default='["web"]'))
+        
+        # Migrate data back: wrap interface_type in array
+        op.execute("""
+            UPDATE tool_types 
+            SET interfaces = jsonb_build_array(interface_type)
+        """)
+    else:
+        op.add_column('tool_types', sa.Column('interfaces', sa.JSON(), nullable=False, server_default='["web"]'))
+        
+        # Migrate data back: wrap interface_type in array for SQLite
+        op.execute("""
+            UPDATE tool_types 
+            SET interfaces = json_array(interface_type)
+        """)
+    
+    # Drop new columns
+    op.drop_column('tool_types', 'requires_port')
+    op.drop_column('tool_types', 'interface_type')

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

@@ -0,0 +1,36 @@
+"""add_clone_mode_and_ssh_key_id
+
+Revision ID: 2026_05_22_add_clone_mode
+Revises: 0014_merge_heads
+Create Date: 2026-05-22 20:30:00.000000
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision = '2026_05_22_add_clone_mode'
+down_revision = '0015_single_interface'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Add ssh_key_id to git_repositories
+    op.add_column('git_repositories', sa.Column('ssh_key_id', postgresql.UUID(), nullable=True))
+    op.create_foreign_key('fk_git_repositories_ssh_key', 'git_repositories', 'ssh_keys', ['ssh_key_id'], ['id'])
+    
+    # Add clone_mode and branch to tool_instances
+    op.add_column('tool_instances', sa.Column('clone_mode', sa.String(20), nullable=False, server_default='mount'))
+    op.add_column('tool_instances', sa.Column('branch', sa.String(255), nullable=True, server_default='main'))
+
+
+def downgrade() -> None:
+    # Drop columns from tool_instances
+    op.drop_column('tool_instances', 'branch')
+    op.drop_column('tool_instances', 'clone_mode')
+    
+    # Drop ssh_key_id from git_repositories
+    op.drop_constraint('fk_git_repositories_ssh_key', 'git_repositories', type_='foreignkey')
+    op.drop_column('git_repositories', 'ssh_key_id')

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

@@ -0,0 +1,25 @@
+"""remove_is_builtin_from_tool_types
+
+Revision ID: 2026_05_23_remove_is_builtin
+Revises: 2026_05_22_add_clone_mode
+Create Date: 2026-05-23 14:30:00.000000
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision = '2026_05_23_remove_is_builtin'
+down_revision = 'f3d2dc90ba3a'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Drop the is_builtin column from tool_types
+    op.execute("ALTER TABLE tool_types DROP COLUMN IF EXISTS is_builtin")
+
+
+def downgrade() -> None:
+    # Add the is_builtin column back to tool_types
+    op.add_column('tool_types', sa.Column('is_builtin', sa.Boolean(), nullable=False, server_default='false'))

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

@@ -0,0 +1,86 @@
+"""add_config_profiles
+
+Revision ID: 2026_05_24_add_config_profiles
+Revises: f3d2dc90ba3a
+Create Date: 2026-05-24 14:00:00.000000
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "2026_05_24_add_config_profiles"
+down_revision: Union[str, Sequence[str], None] = "f3d2dc90ba3a"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # Create config_profiles table
+    op.create_table(
+        "config_profiles",
+        sa.Column("id", postgresql.UUID(as_uuid=True), server_default=sa.text("gen_random_uuid()"), nullable=False),
+        sa.Column("user_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("name", sa.String(255), nullable=False),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column("project_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("projects.id", ondelete="CASCADE"), nullable=True),
+        sa.Column("tool_type_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("tool_types.id", ondelete="CASCADE"), nullable=True),
+        sa.Column("env_vars", postgresql.JSONB(astext_type=sa.Text()), nullable=False, server_default="{}"),
+        sa.Column("runtime_hints", postgresql.JSONB(astext_type=sa.Text()), nullable=False, server_default="{}"),
+        sa.Column("mounts", postgresql.JSONB(astext_type=sa.Text()), nullable=False, server_default="[]"),
+        sa.Column("files", postgresql.JSONB(astext_type=sa.Text()), nullable=False, server_default="{}"),
+        sa.Column("is_default", sa.Boolean(), nullable=False, server_default="false"),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("user_id", "name", name="uq_config_profiles_user_name"),
+    )
+
+    # Create indexes for config_profiles
+    op.create_index("idx_config_profiles_user", "config_profiles", ["user_id"])
+    op.create_index("idx_config_profiles_project", "config_profiles", ["project_id"])
+    op.create_index("idx_config_profiles_tool_type", "config_profiles", ["tool_type_id"])
+
+    # Create config_profile_includes table
+    op.create_table(
+        "config_profile_includes",
+        sa.Column("id", postgresql.UUID(as_uuid=True), server_default=sa.text("gen_random_uuid()"), nullable=False),
+        sa.Column("profile_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("config_profiles.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("included_profile_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("config_profiles.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("order_index", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.text("NOW()"), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("profile_id", "included_profile_id", name="uq_config_profile_includes"),
+    )
+
+    # Create indexes for config_profile_includes
+    op.create_index("idx_config_profile_includes_profile", "config_profile_includes", ["profile_id"])
+    op.create_index("idx_config_profile_includes_included", "config_profile_includes", ["included_profile_id"])
+
+    # Add selected_config_profile_id to tool_instances
+    op.add_column(
+        "tool_instances",
+        sa.Column("selected_config_profile_id", postgresql.UUID(as_uuid=True), sa.ForeignKey("config_profiles.id", ondelete="SET NULL"), nullable=True),
+    )
+    op.create_index("idx_tool_instances_config_profile", "tool_instances", ["selected_config_profile_id"])
+
+
+def downgrade() -> None:
+    # Remove selected_config_profile_id from tool_instances
+    op.drop_index("idx_tool_instances_config_profile", table_name="tool_instances")
+    op.drop_column("tool_instances", "selected_config_profile_id")
+
+    # Drop config_profile_includes table
+    op.drop_index("idx_config_profile_includes_included", table_name="config_profile_includes")
+    op.drop_index("idx_config_profile_includes_profile", table_name="config_profile_includes")
+    op.drop_table("config_profile_includes")
+
+    # Drop config_profiles table
+    op.drop_index("idx_config_profiles_tool_type", table_name="config_profiles")
+    op.drop_index("idx_config_profiles_project", table_name="config_profiles")
+    op.drop_index("idx_config_profiles_user", table_name="config_profiles")
+    op.drop_table("config_profiles")

apps/api/alembic/versions/6fc7bfcf199f_merge_remove_is_builtin_and_add_config_.py

@@ -0,0 +1,25 @@
+"""merge_remove_is_builtin_and_add_config_profiles
+
+Revision ID: 6fc7bfcf199f
+Revises: 2026_05_23_remove_is_builtin, 2026_05_24_add_config_profiles
+Create Date: 2026-05-24 18:00:43.990361
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+
+
+# revision identifiers, used by Alembic.
+revision = '6fc7bfcf199f'
+down_revision = ('2026_05_23_remove_is_builtin', '2026_05_24_add_config_profiles')
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    pass
+
+
+def downgrade() -> None:
+    pass

apps/api/alembic/versions/f3d2dc90ba3a_merge_single_interface_and_clone_mode.py

@@ -0,0 +1,25 @@
+"""merge_single_interface_and_clone_mode
+
+Revision ID: f3d2dc90ba3a
+Revises: 0015_single_interface, 2026_05_22_add_clone_mode
+Create Date: 2026-05-24 10:43:14.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "f3d2dc90ba3a"
+down_revision: Union[str, Sequence[str], None] = ("0015_single_interface", "2026_05_22_add_clone_mode")
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    pass
+
+
+def downgrade() -> None:
+    pass

apps/api/src/api/config_folders.py

@@ -4,23 +4,111 @@ import logging
 import uuid
 
 from fastapi import APIRouter, Depends, HTTPException, status
-from pydantic import Field
+from pydantic import BaseModel, Field, field_validator
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from src.auth.dependencies import get_current_user_id, get_db_session
 from src.models.config_folder import ConfigFolder
-from src.schemas.config_folder import (
-    ConfigFolderCreate,
-    ConfigFolderUpdate,
-    ConfigFolderResponse,
-    ProjectOverrideCreate,
-)
 
 logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/config-folders", tags=["config-folders"])
 
+MAX_FOLDER_SIZE_MB = 10
+MAX_FOLDER_SIZE_BYTES = MAX_FOLDER_SIZE_MB * 1024 * 1024
+
+
+class ConfigFolderCreate(BaseModel):
+    name: str = Field(description="Folder name (unique per user)")
+    description: str | None = Field(default=None, description="Optional description")
+    mount_path: str = Field(description="Default mount path in container")
+    files: dict = Field(default_factory=dict, description="Files as {path: content}")
+
+    @field_validator("mount_path")
+    @classmethod
+    def validate_mount_path(cls, v: str) -> str:
+        if not v.startswith("/"):
+            raise ValueError("Mount path must be absolute (start with /)")
+        return v
+
+    @field_validator("files")
+    @classmethod
+    def validate_files(cls, v: dict) -> dict:
+        total_size = 0
+        for path, content in v.items():
+            # Check for path traversal
+            if ".." in path or path.startswith("/"):
+                raise ValueError(f"Invalid file path: {path}")
+            total_size += len(content.encode("utf-8"))
+        
+        if total_size > MAX_FOLDER_SIZE_BYTES:
+            raise ValueError(f"Total folder size exceeds {MAX_FOLDER_SIZE_MB}MB limit")
+        
+        return v
+
+
+class ConfigFolderUpdate(BaseModel):
+    name: str | None = Field(default=None, description="Folder name")
+    description: str | None = Field(default=None, description="Optional description")
+    mount_path: str | None = Field(default=None, description="Default mount path")
+    files: dict | None = Field(default=None, description="Files as {path: content}")
+    is_active: bool | None = Field(default=None, description="Active/inactive toggle")
+
+    @field_validator("mount_path")
+    @classmethod
+    def validate_mount_path(cls, v: str | None) -> str | None:
+        if v is None:
+            return v
+        if not v.startswith("/"):
+            raise ValueError("Mount path must be absolute (start with /)")
+        return v
+
+    @field_validator("files")
+    @classmethod
+    def validate_files(cls, v: dict | None) -> dict | None:
+        if v is None:
+            return v
+        
+        total_size = 0
+        for path, content in v.items():
+            # Check for path traversal
+            if ".." in path or path.startswith("/"):
+                raise ValueError(f"Invalid file path: {path}")
+            total_size += len(content.encode("utf-8"))
+        
+        if total_size > MAX_FOLDER_SIZE_BYTES:
+            raise ValueError(f"Total folder size exceeds {MAX_FOLDER_SIZE_MB}MB limit")
+        
+        return v
+
+
+class ProjectOverrideCreate(BaseModel):
+    mount_path: str | None = Field(default=None, description="Override mount path")
+    files: dict = Field(default_factory=dict, description="Override files")
+
+    @field_validator("mount_path")
+    @classmethod
+    def validate_mount_path(cls, v: str | None) -> str | None:
+        if v is None:
+            return v
+        if not v.startswith("/"):
+            raise ValueError("Mount path must be absolute (start with /)")
+        return v
+
+
+class ConfigFolderResponse(BaseModel):
+    id: str
+    user_id: str
+    name: str
+    description: str | None
+    mount_path: str
+    files: dict
+    project_overrides: dict | None
+    is_active: bool
+    created_at: str
+    updated_at: str
+
 
 @router.get("", summary="List config folders", description="Get all config folders for the current user.")
 async def list_config_folders(

apps/api/src/api/config_profiles.py

@@ -3,297 +3,643 @@
 import logging
 import uuid
 
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from pydantic import BaseModel, Field, field_validator
 from sqlalchemy import select
 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.config_include import ConfigInclude
-from src.models.config_mount import ConfigMount
-from src.models.config_profile import ConfigProfile
+from src.models.config_profile import ConfigProfile, ConfigProfileInclude
+from src.models.project import Project
 from src.models.tool_type import ToolType
-from src.models.user_config import UserConfig
-from src.schemas.config_profile import (
-    ConfigIncludeCreate,
-    ConfigIncludeUpdate,
-    ConfigMountCreate,
-    ConfigMountUpdate,
-    ConfigProfileCreate,
-    ConfigProfileUpdate,
-    DefaultProfilesUpdate,
-)
-from src.services.config_profiles import (
-    check_duplicate_include,
-    check_duplicate_mount_path,
-    check_duplicate_name,
-    get_default_profile_for_tool_type,
-    get_default_profiles,
-    get_owned_profile,
-    include_to_dict,
-    list_includes_for_profile,
-    list_mounts_for_profile,
-    mount_to_dict,
-    profile_to_dict,
-    set_default_profiles,
-    validate_includes_no_cycle,
+from src.services.config_profile_resolver import (
+    ConfigProfileCycleError,
+    check_include_cycle,
+    resolve_profile,
+    resolved_profile_to_dict,
 )
 
 logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/config-profiles", tags=["config-profiles"])
 
+MAX_PROFILE_SIZE_MB = 10
+MAX_PROFILE_SIZE_BYTES = MAX_PROFILE_SIZE_MB * 1024 * 1024
 
 
-@router.get("")
-async def list_config_profiles(
-    tool_type_id: str | None = None,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    query = select(ConfigProfile).where(ConfigProfile.user_id == user_id)
-    if tool_type_id:
-        tool_type = await session.get(ToolType, uuid.UUID(tool_type_id))
-        if tool_type is None:
-            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found")
-    result = await session.execute(query.order_by(ConfigProfile.name))
-    return {"profiles": [profile_to_dict(p) for p in result.scalars().all()]}
+def _validate_uuid(v: str | None) -> str | None:
+    if v is None:
+        return v
+    try:
+        uuid.UUID(v)
+    except ValueError:
+        raise ValueError(f"Invalid UUID: {v}")
+    return v
 
 
-@router.post("", status_code=status.HTTP_201_CREATED)
-async def create_config_profile(
-    data: ConfigProfileCreate,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    await check_duplicate_name(session, user_id, data.name)
-    profile = ConfigProfile(user_id=user_id, name=data.name, description=data.description)
-    session.add(profile)
-    await session.commit()
-    await session.refresh(profile)
-    return profile_to_dict(profile)
+def _calculate_profile_size(data: dict) -> int:
+    """Calculate approximate serialized size of profile data."""
+    total = 0
+    for key, value in data.get("env_vars", {}).items():
+        total += len(key.encode("utf-8")) + len(str(value).encode("utf-8"))
+    for key, value in data.get("runtime_hints", {}).items():
+        total += len(key.encode("utf-8")) + len(str(value).encode("utf-8"))
+    for mount in data.get("mounts", []):
+        total += len(str(mount.get("target", "")).encode("utf-8"))
+        total += len(str(mount.get("mode", "")).encode("utf-8"))
+        for path, content in mount.get("files", {}).items():
+            total += len(path.encode("utf-8")) + len(content.encode("utf-8"))
+    for path, content in data.get("files", {}).items():
+        total += len(path.encode("utf-8")) + len(content.encode("utf-8"))
+    return total
 
 
-@router.get("/defaults")
-async def get_default_profiles_endpoint(
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    return await get_default_profiles(session, user_id)
+class MountItem(BaseModel):
+    target: str = Field(description="Absolute mount target path")
+    mode: str = Field(default="rw", description="Mount mode: ro or rw")
+    files: dict = Field(default_factory=dict, description="Files as {relative_path: content}")
+
+    @field_validator("target")
+    @classmethod
+    def validate_target(cls, v: str) -> str:
+        if not v.startswith("/"):
+            raise ValueError("Mount target must be absolute (start with /)")
+        return v
+
+    @field_validator("mode")
+    @classmethod
+    def validate_mode(cls, v: str) -> str:
+        if v not in ("ro", "rw"):
+            raise ValueError("Mount mode must be 'ro' or 'rw'")
+        return v
+
+    @field_validator("files")
+    @classmethod
+    def validate_files(cls, v: dict) -> dict:
+        for path in v.keys():
+            if ".." in path or not path:
+                raise ValueError(f"Invalid file path: {path}")
+            if path.startswith("/"):
+                raise ValueError(
+                    f"Mount file paths must be relative (got: {path}). "
+                    f"The mount target defines the absolute container path."
+                )
+        return v
 
 
-@router.put("/defaults")
-async def set_default_profiles_endpoint(
-    data: DefaultProfilesUpdate,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    return await set_default_profiles(session, user_id, data.default_profiles)
+class ConfigProfileCreate(BaseModel):
+    name: str = Field(description="Profile name (unique per user)")
+    description: str | None = Field(default=None, description="Optional description")
+    project_id: str | None = Field(default=None, description="Optional project ID")
+    tool_type_id: str | None = Field(default=None, description="Optional tool type ID")
+    env_vars: dict = Field(default_factory=dict, description="Environment variables")
+    runtime_hints: dict = Field(default_factory=dict, description="Runtime hints")
+    mounts: list[MountItem] = Field(default_factory=list, description="Mount definitions")
+    files: dict = Field(default_factory=dict, description="Files as {relative_path: content}")
+    is_default: bool = Field(default=False, description="Whether this is the default profile for its scope")
+
+    @field_validator("project_id", "tool_type_id")
+    @classmethod
+    def validate_uuids(cls, v: str | None) -> str | None:
+        return _validate_uuid(v)
+
+    @field_validator("files")
+    @classmethod
+    def validate_files(cls, v: dict) -> dict:
+        for path in v.keys():
+            if ".." in path or not path:
+                raise ValueError(f"Invalid file path: {path}")
+            if path.startswith("/"):
+                raise ValueError(
+                    f"File paths must be relative (got: {path}). "
+                    f"Use Mounts for absolute container paths."
+                )
+        return v
+
+    @field_validator("env_vars")
+    @classmethod
+    def validate_env_vars(cls, v: dict) -> dict:
+        if not isinstance(v, dict):
+            raise ValueError("env_vars must be a JSON object")
+        return v
+
+    @field_validator("runtime_hints")
+    @classmethod
+    def validate_runtime_hints(cls, v: dict) -> dict:
+        if not isinstance(v, dict):
+            raise ValueError("runtime_hints must be a JSON object")
+        return v
+
+    @field_validator("mounts")
+    @classmethod
+    def validate_mounts(cls, v: list) -> list:
+        if not isinstance(v, list):
+            raise ValueError("mounts must be a JSON array")
+        return v
 
 
-@router.get("/defaults/{tool_type_id}")
-async def get_default_profile_for_tool_type_endpoint(
-    tool_type_id: str,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    return await get_default_profile_for_tool_type(session, user_id, tool_type_id)
+class ConfigProfileUpdate(BaseModel):
+    name: str | None = Field(default=None, description="Profile name")
+    description: str | None = Field(default=None, description="Optional description")
+    project_id: str | None = Field(default=None, description="Optional project ID")
+    tool_type_id: str | None = Field(default=None, description="Optional tool type ID")
+    env_vars: dict | None = Field(default=None, description="Environment variables")
+    runtime_hints: dict | None = Field(default=None, description="Runtime hints")
+    mounts: list[MountItem] | None = Field(default=None, description="Mount definitions")
+    files: dict | None = Field(default=None, description="Files as {relative_path: content}")
+    is_default: bool | None = Field(default=None, description="Whether this is the default profile")
+
+    @field_validator("project_id", "tool_type_id")
+    @classmethod
+    def validate_uuids(cls, v: str | None) -> str | None:
+        return _validate_uuid(v)
+
+    @field_validator("files")
+    @classmethod
+    def validate_files(cls, v: dict | None) -> dict | None:
+        if v is None:
+            return v
+        for path in v.keys():
+            if ".." in path or path.startswith("/") or not path:
+                raise ValueError(f"Invalid file path: {path}")
+        return v
 
 
-@router.get("/{profile_id}")
-async def get_config_profile(
-    profile_id: uuid.UUID,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    profile = await session.get(
-        ConfigProfile,
-        profile_id,
-        options=[selectinload(ConfigProfile.includes), selectinload(ConfigProfile.mounts)],
+class ConfigProfileIncludeUpdate(BaseModel):
+    includes: list[str] = Field(description="Ordered list of included profile IDs")
+
+    @field_validator("includes")
+    @classmethod
+    def validate_includes(cls, v: list) -> list:
+        for item in v:
+            try:
+                uuid.UUID(item)
+            except ValueError:
+                raise ValueError(f"Invalid UUID in includes: {item}")
+        return v
+
+
+class ConfigProfileResponse(BaseModel):
+    id: str
+    user_id: str
+    name: str
+    description: str | None
+    project_id: str | None
+    tool_type_id: str | None
+    env_vars: dict
+    runtime_hints: dict
+    mounts: list
+    files: dict
+    is_default: bool
+    includes: list[dict]
+    created_at: str
+    updated_at: str
+
+
+async def _get_profile_with_includes(session: AsyncSession, profile_id: uuid.UUID) -> ConfigProfile | None:
+    """Fetch a profile with includes eagerly loaded."""
+    result = await session.execute(
+        select(ConfigProfile)
+        .where(ConfigProfile.id == profile_id)
+        .options(selectinload(ConfigProfile.includes))
     )
-    if profile is None or profile.user_id != user_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="config profile not found")
-    includes_data = []
-    for inc in profile.includes:
-        included_profile = await session.get(ConfigProfile, inc.included_profile_id)
-        includes_data.append(include_to_dict(inc, included_profile.name if included_profile else None))
+    return result.scalar_one_or_none()
+
+
+async def _check_access(
+    session: AsyncSession,
+    user_id: uuid.UUID,
+    project_id: uuid.UUID | None = None,
+    tool_type_id: uuid.UUID | None = None,
+) -> None:
+    """Verify user has access to referenced project and tool type."""
+    if project_id is not None:
+        project = await session.get(Project, project_id)
+        if project is None:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Project not found")
+        # Add ownership check if needed; for now just verify existence
+    if tool_type_id is not None:
+        tool_type = await session.get(ToolType, tool_type_id)
+        if tool_type is None:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Tool type not found")
+
+
+def _profile_to_response(profile: ConfigProfile, includes: list[ConfigProfileInclude] | None = None) -> dict:
     return {
-        **profile_to_dict(profile),
-        "includes": includes_data,
-        "mounts": [mount_to_dict(m) for m in profile.mounts],
+        "id": str(profile.id),
+        "user_id": str(profile.user_id),
+        "name": profile.name,
+        "description": profile.description,
+        "project_id": str(profile.project_id) if profile.project_id else None,
+        "tool_type_id": str(profile.tool_type_id) if profile.tool_type_id else None,
+        "env_vars": profile.env_vars or {},
+        "runtime_hints": profile.runtime_hints or {},
+        "mounts": profile.mounts or [],
+        "files": profile.files or {},
+        "is_default": profile.is_default,
+        "includes": [
+            {
+                "id": str(inc.id),
+                "included_profile_id": str(inc.included_profile_id),
+                "order_index": inc.order_index,
+            }
+            for inc in (includes or profile.includes)
+        ],
+        "created_at": profile.created_at.isoformat() if profile.created_at else None,
+        "updated_at": profile.updated_at.isoformat() if profile.updated_at else None,
     }
 
 
-@router.put("/{profile_id}")
-async def update_config_profile(
-    profile_id: uuid.UUID,
-    data: ConfigProfileUpdate,
-    user_id: uuid.UUID = Depends(get_current_user_id),
+@router.get("", response_model=list[ConfigProfileResponse])
+async def list_config_profiles(
+    project_id: str | None = Query(None, description="Filter by project compatibility"),
+    tool_type_id: str | None = Query(None, description="Filter by tool type compatibility"),
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    profile = await get_owned_profile(profile_id, user_id, session)
-    if data.name is not None:
-        await check_duplicate_name(session, user_id, data.name, exclude_id=profile_id)
-        profile.name = data.name
-    if data.description is not None:
-        profile.description = data.description
+):
+    """List config profiles, optionally filtered by compatibility."""
+    user_uuid = current_user_id
+    query = select(ConfigProfile).where(ConfigProfile.user_id == user_uuid).options(selectinload(ConfigProfile.includes))
+
+    if project_id or tool_type_id:
+        # Compatibility filter: include portable profiles and matching scoped profiles
+        project_uuid = uuid.UUID(project_id) if project_id else None
+        tool_uuid = uuid.UUID(tool_type_id) if tool_type_id else None
+
+        from sqlalchemy import or_
+
+        conditions: list = []
+        # Portable profiles (no project, no tool)
+        conditions.append(
+            (ConfigProfile.project_id.is_(None)) & (ConfigProfile.tool_type_id.is_(None))
+        )
+        if project_uuid:
+            # Profiles matching this project (with or without tool)
+            conditions.append(ConfigProfile.project_id == project_uuid)
+        if tool_uuid:
+            # Profiles matching this tool (with or without project)
+            conditions.append(ConfigProfile.tool_type_id == tool_uuid)
+        if project_uuid and tool_uuid:
+            # Exact match
+            conditions.append(
+                (ConfigProfile.project_id == project_uuid) & (ConfigProfile.tool_type_id == tool_uuid)
+            )
+
+        query = query.where(or_(*conditions))
+
+    result = await session.execute(query)
+    profiles = result.scalars().all()
+    return [_profile_to_response(p) for p in profiles]
+
+
+@router.post("", response_model=ConfigProfileResponse, status_code=status.HTTP_201_CREATED)
+async def create_config_profile(
+    data: ConfigProfileCreate,
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+):
+    """Create a new config profile."""
+    user_uuid = current_user_id
+
+    # Check for duplicate name
+    existing = await session.execute(
+        select(ConfigProfile).where(
+            ConfigProfile.user_id == user_uuid,
+            ConfigProfile.name == data.name,
+        ).options(selectinload(ConfigProfile.includes))
+    )
+    if existing.scalar_one_or_none() is not None:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"Profile with name '{data.name}' already exists",
+        )
+
+    # Validate references
+    project_uuid = uuid.UUID(data.project_id) if data.project_id else None
+    tool_uuid = uuid.UUID(data.tool_type_id) if data.tool_type_id else None
+    await _check_access(session, user_uuid, project_uuid, tool_uuid)
+
+    # Check size
+    size = _calculate_profile_size(data.model_dump())
+    if size > MAX_PROFILE_SIZE_BYTES:
+        raise HTTPException(
+            status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
+            detail=f"Profile size exceeds {MAX_PROFILE_SIZE_MB}MB limit",
+        )
+
+    profile = ConfigProfile(
+        user_id=user_uuid,
+        name=data.name,
+        description=data.description,
+        project_id=project_uuid,
+        tool_type_id=tool_uuid,
+        env_vars=data.env_vars,
+        runtime_hints=data.runtime_hints,
+        mounts=[m.model_dump() for m in data.mounts],
+        files=data.files,
+        is_default=data.is_default,
+    )
+    session.add(profile)
     await session.commit()
-    await session.refresh(profile)
-    return profile_to_dict(profile)
+
+    # Re-fetch with includes to avoid lazy loading issues
+    result = await session.execute(
+        select(ConfigProfile)
+        .where(ConfigProfile.id == profile.id)
+        .options(selectinload(ConfigProfile.includes))
+    )
+    profile = result.scalar_one()
+
+    logger.info("Created config profile %s for user %s", profile.id, user_uuid)
+    return _profile_to_response(profile)
+
+
+@router.get("/{profile_id}", response_model=ConfigProfileResponse)
+async def get_config_profile(
+    profile_id: str,
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+):
+    """Get a config profile by ID."""
+    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")
+    return _profile_to_response(profile)
+
+
+@router.put("/{profile_id}", response_model=ConfigProfileResponse)
+async def update_config_profile(
+    profile_id: str,
+    data: ConfigProfileUpdate,
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+):
+    """Update a config profile."""
+    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")
+
+    update_data = data.model_dump(exclude_unset=True)
+
+    # Handle name uniqueness
+    if "name" in update_data:
+        existing = await session.execute(
+            select(ConfigProfile).where(
+                ConfigProfile.user_id == profile.user_id,
+                ConfigProfile.name == update_data["name"],
+                ConfigProfile.id != profile.id,
+            )
+        )
+        if existing.scalar_one_or_none() is not None:
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail=f"Profile with name '{update_data['name']}' already exists",
+            )
+
+    # Validate references
+    project_uuid = (
+        uuid.UUID(update_data["project_id"])
+        if "project_id" in update_data and update_data["project_id"]
+        else (profile.project_id if "project_id" not in update_data else None)
+    )
+    tool_uuid = (
+        uuid.UUID(update_data["tool_type_id"])
+        if "tool_type_id" in update_data and update_data["tool_type_id"]
+        else (profile.tool_type_id if "tool_type_id" not in update_data else None)
+    )
+    await _check_access(session, profile.user_id, project_uuid, tool_uuid)
+
+    # Check size
+    current_data = _profile_to_response(profile)
+    merged = {**current_data, **update_data}
+    size = _calculate_profile_size(merged)
+    if size > MAX_PROFILE_SIZE_BYTES:
+        raise HTTPException(
+            status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
+            detail=f"Profile size exceeds {MAX_PROFILE_SIZE_MB}MB limit",
+        )
+
+    # Apply updates
+    for field_name, value in update_data.items():
+        if field_name in ("project_id", "tool_type_id"):
+            value = uuid.UUID(value) if value else None
+        elif field_name == "mounts" and value is not None:
+            value = [m.model_dump() if not isinstance(m, dict) else m for m in value]
+        setattr(profile, field_name, value)
+
+    await session.commit()
+
+    # Re-fetch with includes to avoid lazy loading issues
+    result = await session.execute(
+        select(ConfigProfile)
+        .where(ConfigProfile.id == profile.id)
+        .options(selectinload(ConfigProfile.includes))
+    )
+    profile = result.scalar_one()
+
+    logger.info("Updated config profile %s", profile.id)
+    return _profile_to_response(profile)
 
 
 @router.delete("/{profile_id}", status_code=status.HTTP_204_NO_CONTENT)
 async def delete_config_profile(
-    profile_id: uuid.UUID,
-    user_id: uuid.UUID = Depends(get_current_user_id),
+    profile_id: str,
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
-) -> None:
-    profile = await get_owned_profile(profile_id, user_id, session)
+):
+    """Delete a config profile."""
+    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")
+
     await session.delete(profile)
     await session.commit()
 
+    logger.info("Deleted config profile %s", profile_id)
+    return None
 
 
-@router.get("/{profile_id}/includes")
-async def list_profile_includes(
-    profile_id: uuid.UUID,
-    user_id: uuid.UUID = Depends(get_current_user_id),
+@router.put("/{profile_id}/includes", response_model=ConfigProfileResponse)
+async def update_profile_includes(
+    profile_id: str,
+    data: ConfigProfileIncludeUpdate,
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    await get_owned_profile(profile_id, user_id, session)
-    return await list_includes_for_profile(session, profile_id)
+):
+    """Update the ordered includes for a config profile."""
+    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")
 
+    # Validate all included profiles exist and belong to the user
+    included_uuids = [uuid.UUID(inc_id) for inc_id in data.includes]
+    for inc_uuid in included_uuids:
+        inc_profile = await session.get(ConfigProfile, inc_uuid)
+        if inc_profile is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Included profile not found: {inc_uuid}",
+            )
+        if inc_profile.user_id != current_user_id:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Not authorized to include profile: {inc_uuid}",
+            )
+        if inc_uuid == profile.id:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Profile cannot include itself",
+            )
 
-@router.post("/{profile_id}/includes", status_code=status.HTTP_201_CREATED)
-async def add_profile_include(
-    profile_id: uuid.UUID,
-    data: ConfigIncludeCreate,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    profile = await get_owned_profile(profile_id, user_id, session)
-    included_profile_id = uuid.UUID(data.included_profile_id)
-    if included_profile_id == profile_id:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="a profile cannot include itself")
-    included_profile = await session.get(ConfigProfile, included_profile_id)
-    if included_profile is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="included profile not found")
-    if included_profile.user_id != user_id:
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="included profile does not belong to user")
-    await check_duplicate_include(session, profile_id, included_profile_id)
-    await validate_includes_no_cycle(session, profile_id, included_profile_id)
-    include = ConfigInclude(
-        profile_id=profile_id,
-        included_profile_id=included_profile_id,
-        order_index=data.order_index,
+    # Check for cycles
+    cycle = await check_include_cycle(session, profile.id, None)
+    if cycle is None and included_uuids:
+        # Check each new include would not create a cycle
+        for inc_uuid in included_uuids:
+            cycle = await check_include_cycle(session, profile.id, inc_uuid)
+            if cycle is not None:
+                break
+
+    if cycle is not None:
+        cycle_str = " -> ".join(str(c) for c in cycle)
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Include cycle detected: {cycle_str}",
+        )
+
+    # Remove existing includes
+    result = await session.execute(
+        select(ConfigProfileInclude).where(ConfigProfileInclude.profile_id == profile.id)
     )
-    session.add(include)
-    await session.commit()
-    await session.refresh(include)
-    return include_to_dict(include, included_profile.name)
+    for existing in result.scalars().all():
+        await session.delete(existing)
+    await session.flush()
 
+    # Add new includes
+    for order_index, inc_uuid in enumerate(included_uuids):
+        include = ConfigProfileInclude(
+            profile_id=profile.id,
+            included_profile_id=inc_uuid,
+            order_index=order_index,
+        )
+        session.add(include)
+    await session.flush()
 
-@router.put("/{profile_id}/includes/{include_id}")
-async def update_profile_include(
-    profile_id: uuid.UUID,
-    include_id: uuid.UUID,
-    data: ConfigIncludeUpdate,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    await get_owned_profile(profile_id, user_id, session)
-    include = await session.get(ConfigInclude, include_id)
-    if include is None or include.profile_id != profile_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="include not found")
-    include.order_index = data.order_index
-    await session.commit()
-    await session.refresh(include)
-    included_profile = await session.get(ConfigProfile, include.included_profile_id)
-    return include_to_dict(include, included_profile.name if included_profile else None)
-
-
-@router.delete("/{profile_id}/includes/{include_id}", status_code=status.HTTP_204_NO_CONTENT)
-async def remove_profile_include(
-    profile_id: uuid.UUID,
-    include_id: uuid.UUID,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> None:
-    await get_owned_profile(profile_id, user_id, session)
-    include = await session.get(ConfigInclude, include_id)
-    if include is None or include.profile_id != profile_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="include not found")
-    await session.delete(include)
     await session.commit()
 
-
-
-@router.get("/{profile_id}/mounts")
-async def list_profile_mounts(
-    profile_id: uuid.UUID,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    await get_owned_profile(profile_id, user_id, session)
-    return await list_mounts_for_profile(session, profile_id)
-
-
-@router.post("/{profile_id}/mounts", status_code=status.HTTP_201_CREATED)
-async def add_profile_mount(
-    profile_id: uuid.UUID,
-    data: ConfigMountCreate,
-    user_id: uuid.UUID = Depends(get_current_user_id),
-    session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    profile = await get_owned_profile(profile_id, user_id, session)
-    await check_duplicate_mount_path(session, profile_id, data.target_path)
-    mount = ConfigMount(
-        profile_id=profile_id,
-        target_path=data.target_path,
-        mode=data.mode,
-        files=data.files,
-        order_index=data.order_index,
+    # Re-fetch profile (includes loaded separately due to SQLite async issue)
+    result = await session.execute(
+        select(ConfigProfile).where(ConfigProfile.id == profile.id)
     )
-    session.add(mount)
-    await session.commit()
-    await session.refresh(mount)
-    return mount_to_dict(mount)
+    profile = result.scalar_one()
+
+    inc_result = await session.execute(
+        select(ConfigProfileInclude).where(ConfigProfileInclude.profile_id == profile.id)
+    )
+    direct_includes = inc_result.scalars().all()
+
+    logger.info("Updated includes for config profile %s", profile.id)
+    return _profile_to_response(profile, list(direct_includes))
 
 
-@router.put("/{profile_id}/mounts/{mount_id}")
-async def update_profile_mount(
-    profile_id: uuid.UUID,
-    mount_id: uuid.UUID,
-    data: ConfigMountUpdate,
-    user_id: uuid.UUID = Depends(get_current_user_id),
+@router.get("/{profile_id}/preview")
+async def preview_config_profile(
+    profile_id: str,
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
-) -> dict:
-    await get_owned_profile(profile_id, user_id, session)
-    mount = await session.get(ConfigMount, mount_id)
-    if mount is None or mount.profile_id != profile_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="mount not found")
-    if data.target_path is not None:
-        await check_duplicate_mount_path(session, profile_id, data.target_path, exclude_id=mount_id)
-        mount.target_path = data.target_path
-    if data.files is not None:
-        mount.files = data.files
-    if data.order_index is not None:
-        mount.order_index = data.order_index
-    await session.commit()
-    await session.refresh(mount)
-    return mount_to_dict(mount)
+):
+    """Preview the resolved output of a config profile."""
+    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")
+
+    try:
+        resolved = await resolve_profile(session, profile.id)
+    except ConfigProfileCycleError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(exc),
+        )
+
+    return resolved_profile_to_dict(resolved)
 
 
-@router.delete("/{profile_id}/mounts/{mount_id}", status_code=status.HTTP_204_NO_CONTENT)
-async def remove_profile_mount(
-    profile_id: uuid.UUID,
-    mount_id: uuid.UUID,
-    user_id: uuid.UUID = Depends(get_current_user_id),
+@router.get("/defaults/resolve")
+async def resolve_default_profile(
+    project_id: str = Query(..., description="Project ID"),
+    tool_type_id: str = Query(..., description="Tool type ID"),
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
-) -> None:
-    await get_owned_profile(profile_id, user_id, session)
-    mount = await session.get(ConfigMount, mount_id)
-    if mount is None or mount.profile_id != profile_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="mount not found")
-    await session.delete(mount)
-    await session.commit()
+):
+    """Resolve the default config profile for a project/tool combination.
+
+    Selects by specificity:
+    1. project+tool explicit default
+    2. project explicit default
+    3. tool explicit default
+    4. global/user explicit default
+    5. first created compatible profile
+    6. none (returns null)
+    """
+    user_uuid = current_user_id
+    project_uuid = uuid.UUID(project_id)
+    tool_uuid = uuid.UUID(tool_type_id)
+
+    # Fetch all compatible profiles ordered by created_at
+    query = (
+        select(ConfigProfile)
+        .where(ConfigProfile.user_id == user_uuid)
+        .where(
+            (ConfigProfile.project_id.is_(None) & ConfigProfile.tool_type_id.is_(None))
+            | (ConfigProfile.project_id == project_uuid)
+            | (ConfigProfile.tool_type_id == tool_uuid)
+            | (
+                (ConfigProfile.project_id == project_uuid)
+                & (ConfigProfile.tool_type_id == tool_uuid)
+            )
+        )
+        .order_by(ConfigProfile.created_at)
+    )
+    result = await session.execute(query)
+    profiles = result.scalars().all()
+
+    if not profiles:
+        return {"profile_id": None, "profile_name": None}
+
+    # Check explicit defaults by specificity
+    explicit_defaults = [p for p in profiles if p.is_default]
+
+    # Most specific: project+tool
+    for p in explicit_defaults:
+        if p.project_id == project_uuid and p.tool_type_id == tool_uuid:
+            return {"profile_id": str(p.id), "profile_name": p.name}
+
+    # Next: project only
+    for p in explicit_defaults:
+        if p.project_id == project_uuid and p.tool_type_id is None:
+            return {"profile_id": str(p.id), "profile_name": p.name}
+
+    # Next: tool only
+    for p in explicit_defaults:
+        if p.project_id is None and p.tool_type_id == tool_uuid:
+            return {"profile_id": str(p.id), "profile_name": p.name}
+
+    # Next: global/user (no project, no tool)
+    for p in explicit_defaults:
+        if p.project_id is None and p.tool_type_id is None:
+            return {"profile_id": str(p.id), "profile_name": p.name}
+
+    # Fall back to first created compatible profile
+    first = profiles[0]
+    return {"profile_id": str(first.id), "profile_name": first.name}

apps/api/src/api/health.py

@@ -5,17 +5,11 @@ from datetime import datetime, timezone
 from typing import Any
 
 from fastapi import APIRouter, status
+from pydantic import BaseModel, Field
 from sqlalchemy import text
 
 from src.config import Settings
 from src.database import SessionLocal
-from src.schemas.health import (
-    DatabaseHealth,
-    DatabaseHealthResponse,
-    DiskHealth,
-    HealthChecks,
-    HealthResponse,
-)
 
 router = APIRouter()
 
@@ -23,6 +17,45 @@ router = APIRouter()
 _start_time = time.time()
 
 
+class DatabaseHealth(BaseModel):
+    """Database health check result."""
+
+    status: str = Field(description="Database health status", examples=["healthy"])
+    response_time_ms: float = Field(description="Query response time in milliseconds", examples=[5.2])
+
+
+class DiskHealth(BaseModel):
+    """Disk space health check result."""
+
+    status: str = Field(description="Disk health status", examples=["healthy"])
+    free_gb: float = Field(description="Free disk space in GB", examples=[45.2])
+    total_gb: float = Field(description="Total disk space in GB", examples=[100.0])
+
+
+class HealthChecks(BaseModel):
+    """Individual health checks."""
+
+    database: DatabaseHealth | None = None
+    disk: DiskHealth | None = None
+
+
+class HealthResponse(BaseModel):
+    """Overall health check response."""
+
+    status: str = Field(description="Overall health status", examples=["healthy"])
+    timestamp: str = Field(description="ISO 8601 timestamp", examples=["2026-05-19T12:00:00Z"])
+    version: str = Field(description="API version", examples=["0.1.0"])
+    checks: HealthChecks = Field(description="Individual health checks")
+    uptime_seconds: float = Field(description="Server uptime in seconds", examples=[3600.0])
+
+
+class DatabaseHealthResponse(BaseModel):
+    """Database-specific health check response."""
+
+    status: str = Field(description="Database health status", examples=["healthy"])
+    response_time_ms: float = Field(description="Query response time in milliseconds", examples=[5.2])
+
+
 @router.get(
     "/health",
     response_model=HealthResponse,

apps/api/src/api/projects.py

@@ -3,24 +3,50 @@ import shutil
 import uuid
 
 from fastapi import APIRouter, Depends, HTTPException, Response, status
+from pydantic import BaseModel, ConfigDict
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from src.auth.dependencies import get_current_user, get_db_session, get_owned_project
+from src.auth.dependencies import get_current_user_id, get_db_session
 from src.models.git_repository import GitRepository
 from src.models.project import Project
 from src.models.ssh_key import SSHKey
 from src.models.user import User
-from src.schemas.project import (
-    ProjectCreate,
-    ProjectUpdate,
-    ProjectResponse,
-    SetDefaultSSHKeyRequest,
-)
 
 router = APIRouter(prefix="/projects", tags=["projects"])
 
 
+async def _get_user(session: AsyncSession, user_id: uuid.UUID) -> User:
+    """Fetch a user by ID or raise 401 if not found."""
+    user = await session.get(User, user_id)
+    if user is None:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="user not found")
+    return user
+
+
+class ProjectCreate(BaseModel):
+    name: str
+    description: str | None = None
+
+
+class ProjectUpdate(BaseModel):
+    name: str | None = None
+    description: str | None = None
+
+
+class ProjectResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    name: str
+    description: str | None
+    owner_id: uuid.UUID
+    default_ssh_key_id: uuid.UUID | None
+
+
+class SetDefaultSSHKeyRequest(BaseModel):
+    ssh_key_id: uuid.UUID
+
 
 @router.post(
     "",
@@ -31,7 +57,7 @@ router = APIRouter(prefix="/projects", tags=["projects"])
 )
 async def create_project(
     data: ProjectCreate,
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> Project:
     """Create a new project.
@@ -44,6 +70,7 @@ async def create_project(
     Returns:
         The newly created project.
     """
+    user = await _get_user(session, user_id)
     project = Project(
         name=data.name,
         description=data.description,
@@ -63,7 +90,7 @@ async def create_project(
     description="Retrieve all projects owned by the authenticated user.",
 )
 async def list_projects(
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> list[Project]:
     """List all projects for the authenticated user.
@@ -75,6 +102,7 @@ async def list_projects(
     Returns:
         List of projects owned by the user.
     """
+    user = await _get_user(session, user_id)
     result = await session.execute(select(Project).where(Project.owner_id == user.id))
     return list(result.scalars().all())
 
@@ -87,8 +115,7 @@ async def list_projects(
 )
 async def get_project(
     project_id: uuid.UUID,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> Project:
     """Get a specific project by ID.
@@ -101,9 +128,35 @@ async def get_project(
     Returns:
         The requested project.
     """
-    return project
+    await _get_user(session, user_id)
+    return await _get_owned_project(project_id, user_id, session)
 
 
+async def _get_owned_project(
+    project_id: uuid.UUID,
+    user_id: uuid.UUID,
+    session: AsyncSession,
+) -> Project:
+    """Fetch a project and verify ownership.
+
+    Args:
+        project_id: UUID of the project.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        The project if found and owned by the user.
+
+    Raises:
+        HTTPException: If project not found or user is not the owner.
+    """
+    project = await session.get(Project, project_id)
+    if project is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="project not found")
+    if project.owner_id != user_id:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="not project owner")
+    return project
+
 
 @router.patch(
     "/{project_id}",
@@ -114,8 +167,7 @@ async def get_project(
 async def update_project(
     project_id: uuid.UUID,
     data: ProjectUpdate,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> Project:
     """Update a project.
@@ -129,6 +181,8 @@ async def update_project(
     Returns:
         The updated project.
     """
+    await _get_user(session, user_id)
+    project = await _get_owned_project(project_id, user_id, session)
 
     if data.name is not None:
         project.name = data.name
@@ -148,8 +202,7 @@ async def update_project(
 )
 async def delete_project(
     project_id: uuid.UUID,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> Response:
     """Delete a project and all its repositories.
@@ -162,6 +215,8 @@ async def delete_project(
     Returns:
         Empty response with 204 status code.
     """
+    await _get_user(session, user_id)
+    project = await _get_owned_project(project_id, user_id, session)
 
     # Delete repositories from disk and database
     result = await session.execute(select(GitRepository).where(GitRepository.project_id == project_id))
@@ -185,8 +240,7 @@ async def delete_project(
 async def set_default_ssh_key(
     project_id: uuid.UUID,
     data: SetDefaultSSHKeyRequest,
-    user: User = Depends(get_current_user),
-    project: Project = Depends(get_owned_project),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> Project:
     """Set the default SSH key for a project.
@@ -200,6 +254,8 @@ async def set_default_ssh_key(
     Returns:
         The updated project.
     """
+    user = await _get_user(session, user_id)
+    project = await _get_owned_project(project_id, user_id, session)
 
     ssh_key = await session.get(SSHKey, data.ssh_key_id)
     if ssh_key is None or ssh_key.user_id != user.id:

apps/api/src/api/ssh_keys.py

@@ -1,3 +1,4 @@
+import base64
 import uuid
 from datetime import datetime
 
@@ -5,18 +6,25 @@ from cryptography.fernet import Fernet
 from cryptography.hazmat.primitives import serialization
 from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
 from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, ConfigDict
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from src.auth.dependencies import get_current_user, get_db_session
+from src.auth.dependencies import get_current_user_id, get_db_session
 from src.config import Settings
 from src.models.ssh_key import SSHKey
 from src.models.user import User
-from src.schemas.ssh_key import SSHKeyCreate, SSHKeyResponse
 
 router = APIRouter(prefix="/ssh-keys", tags=["ssh-keys"])
 
 
+async def _get_user(session: AsyncSession, user_id: uuid.UUID) -> User:
+    """Fetch a user by ID or raise 401 if not found."""
+    user = await session.get(User, user_id)
+    if user is None:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="user not found")
+    return user
+
 
 def _get_fernet() -> Fernet:
     """Generate a valid Fernet key from the session secret."""
@@ -54,6 +62,36 @@ def generate_ssh_key_pair() -> tuple[str, str]:
     return private_bytes.decode("utf-8"), public_bytes.decode("utf-8")
 
 
+class SSHKeyCreate(BaseModel):
+    name: str
+
+
+class SSHKeyResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    name: str
+    public_key: str
+    created_at: datetime
+
+
+class SignPayloadRequest(BaseModel):
+    payload: str
+
+
+class SignatureResponse(BaseModel):
+    signature: str
+
+
+class VerifySignatureRequest(BaseModel):
+    payload: str
+    signature: str
+
+
+class VerifySignatureResponse(BaseModel):
+    valid: bool
+
+
 @router.post(
     "",
     response_model=SSHKeyResponse,
@@ -63,7 +101,7 @@ def generate_ssh_key_pair() -> tuple[str, str]:
 )
 async def create_ssh_key(
     data: SSHKeyCreate,
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> SSHKey:
     """Create a new SSH key pair.
@@ -76,6 +114,7 @@ async def create_ssh_key(
     Returns:
         The newly created SSH key with public key exposed.
     """
+    user = await _get_user(session, user_id)
     private_key, public_key = generate_ssh_key_pair()
 
     fernet = _get_fernet()
@@ -100,7 +139,7 @@ async def create_ssh_key(
     description="List all SSH keys for the authenticated user.",
 )
 async def list_ssh_keys(
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> list[SSHKey]:
     """List all SSH keys for the authenticated user.
@@ -112,6 +151,7 @@ async def list_ssh_keys(
     Returns:
         List of SSH keys owned by the user.
     """
+    user = await _get_user(session, user_id)
     result = await session.execute(select(SSHKey).where(SSHKey.user_id == user.id))
     return list(result.scalars().all())
 
@@ -124,7 +164,7 @@ async def list_ssh_keys(
 )
 async def delete_ssh_key(
     key_id: uuid.UUID,
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> None:
     """Delete an SSH key.
@@ -137,9 +177,87 @@ async def delete_ssh_key(
     Returns:
         None with 204 status code.
     """
+    user = await _get_user(session, user_id)
     ssh_key = await session.get(SSHKey, key_id)
     if ssh_key is None or ssh_key.user_id != user.id:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="ssh key not found")
 
     await session.delete(ssh_key)
     await session.commit()
+
+
+@router.post(
+    "/{key_id}/sign",
+    response_model=SignatureResponse,
+    summary="Sign payload",
+    description="Sign a payload using the SSH private key.",
+)
+async def sign_payload(
+    key_id: uuid.UUID,
+    data: SignPayloadRequest,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> SignatureResponse:
+    """Sign a payload with an SSH key.
+
+    Args:
+        key_id: UUID of the SSH key to use for signing.
+        data: Sign request containing the payload string.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Base64-encoded Ed25519 signature.
+    """
+    user = await _get_user(session, user_id)
+    ssh_key = await session.get(SSHKey, key_id)
+    if ssh_key is None or ssh_key.user_id != user.id:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="ssh key not found")
+
+    fernet = _get_fernet()
+    private_key_pem = fernet.decrypt(ssh_key.private_key_encrypted.encode()).decode()
+
+    private_key = serialization.load_ssh_private_key(
+        private_key_pem.encode(), password=None
+    )
+
+    signature = private_key.sign(data.payload.encode())
+    return SignatureResponse(signature=base64.b64encode(signature).decode())
+
+
+@router.post(
+    "/{key_id}/verify",
+    response_model=VerifySignatureResponse,
+    summary="Verify signature",
+    description="Verify a signature against a payload using the SSH public key.",
+)
+async def verify_signature(
+    key_id: uuid.UUID,
+    data: VerifySignatureRequest,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> VerifySignatureResponse:
+    """Verify a signature with an SSH key's public key.
+
+    Args:
+        key_id: UUID of the SSH key to use for verification.
+        data: Verify request containing payload and base64-encoded signature.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Whether the signature is valid.
+    """
+    user = await _get_user(session, user_id)
+    ssh_key = await session.get(SSHKey, key_id)
+    if ssh_key is None or ssh_key.user_id != user.id:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="ssh key not found")
+
+    public_key = serialization.load_ssh_public_key(ssh_key.public_key.encode())
+
+    try:
+        signature = base64.b64decode(data.signature)
+        public_key.verify(signature, data.payload.encode())
+        return VerifySignatureResponse(valid=True)
+    except Exception:
+        return VerifySignatureResponse(valid=False)

apps/api/src/api/terminal.py

@@ -4,7 +4,7 @@ import asyncio
 import logging
 import uuid
 
-from fastapi import APIRouter, Depends, WebSocket
+from fastapi import APIRouter, Depends, HTTPException, WebSocket, WebSocketDisconnect, status
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from src.auth.dependencies import get_db_session
@@ -26,11 +26,7 @@ async def terminal_websocket(
     """WebSocket endpoint for terminal access to a tool instance.
 
     Provides an interactive terminal session inside a running tool instance container.
-    Supports:
-    - Auto-reconnection (client reconnects, server spawns new session)
-    - Heartbeat ping/pong
-    - Binary and text input frames
-    - Graceful session end notifications
+    Sessions persist across WebSocket disconnections.
 
     Args:
         websocket: The WebSocket connection.
@@ -39,27 +35,26 @@ async def terminal_websocket(
 
     Returns:
         None. Communicates via WebSocket messages.
-
     """
     logger.info("Terminal WebSocket connection attempt for instance %s", instance_id)
     await websocket.accept()
 
     try:
+        # Parse instance_id
         instance_uuid = uuid.UUID(instance_id)
     except ValueError:
         logger.error("Invalid instance ID: %s", instance_id)
         await websocket.close(code=4001, reason="Invalid instance ID")
         return
 
+    # Authenticate user from session cookie
     user_id = await _get_user_from_websocket(websocket, db_session)
     if user_id is None:
-        logger.warning(
-            "Unauthorized terminal access attempt for instance %s",
-            instance_id,
-        )
+        logger.warning("Unauthorized terminal access attempt for instance %s", instance_id)
         await websocket.close(code=4003, reason="Unauthorized")
         return
 
+    # Get instance and verify ownership
     instance = await db_session.get(ToolInstance, instance_uuid)
     if instance is None:
         logger.warning("Instance %s not found", instance_id)
@@ -67,68 +62,199 @@ async def terminal_websocket(
         return
 
     if instance.owner_id != user_id:
-        logger.warning(
-            "Forbidden terminal access for instance %s by user %s",
-            instance_id,
-            user_id,
-        )
+        logger.warning("Forbidden terminal access for instance %s by user %s", instance_id, user_id)
         await websocket.close(code=4003, reason="Forbidden")
         return
 
     if instance.status != "running" or not instance.container_id:
-        logger.warning(
-            "Instance %s not running (status=%s, container_id=%s)",
-            instance_id,
-            instance.status,
-            instance.container_id,
-        )
+        logger.warning("Instance %s not running (status=%s, container_id=%s)", instance_id, instance.status, instance.container_id)
         await websocket.close(code=4004, reason="Instance not running")
         return
 
-    logger.info(
-        "Creating terminal session for instance %s (container_id=%s)",
-        instance_id,
-        instance.container_id,
-    )
+    # Get or create terminal session
     try:
-        session = await terminal_manager.create_session(
+        session = await terminal_manager.get_or_create_session(
             instance_uuid,
             instance.container_id,
-            websocket,
-        )
-        logger.info(
-            "Terminal session created successfully for instance %s",
-            instance_id,
         )
+        logger.info("Terminal session ready for instance %s (session_id=%s)", instance_id, session.session_id)
+
+        # Attach WebSocket to session
+        await terminal_manager.attach_websocket(session, websocket)
+        logger.info("WebSocket attached to session for instance %s", instance_id)
 
         # Send connected status
         await websocket.send_json({"type": "status", "status": "connected"})
 
-        # Monitor session health and echo state
-        while session.is_alive() and not session.closed:
-            # Check echo state periodically
-            new_echo_state = await session.check_echo_state()
-            if new_echo_state is not None:
-                await websocket.send_json(
-                    {"type": "set_echo_state", "enabled": new_echo_state},
-                )
-            await asyncio.sleep(1.0)
+        # Start I/O loops and heartbeat
+        read_task = asyncio.create_task(_read_loop(session, websocket))
+        write_task = asyncio.create_task(_write_loop(session, websocket, instance_id))
+        heartbeat_task = asyncio.create_task(_heartbeat_loop(websocket))
 
-        # Session ended — determine reason and notify client
-        exit_reason = session.get_exit_reason() or "process_exit"
-        await websocket.send_json({"type": "session_ended", "reason": exit_reason})
-        await websocket.close(code=1000, reason=f"Session ended: {exit_reason}")
-
-    except Exception:
-        logger.exception(
-            "Terminal session error for instance %s",
-            instance_id,
+        # Wait for either task to complete (indicating disconnect or error)
+        done, pending = await asyncio.wait(
+            [read_task, write_task, heartbeat_task],
+            return_when=asyncio.FIRST_COMPLETED,
         )
-        await websocket.close(code=4000, reason="Terminal session error")
+        
+        # Cancel remaining tasks
+        for task in pending:
+            task.cancel()
+
+    except Exception as exc:
+        logger.error("Terminal session error for instance %s: %s", instance_id, str(exc), exc_info=True)
+        await websocket.close(code=4000, reason=f"Error: {exc}")
     finally:
+        # Detach WebSocket, don't kill session
+        try:
+            if 'session' in locals():
+                await terminal_manager.detach_websocket(session, websocket)
+                logger.info("WebSocket detached from session for instance %s", instance_id)
+        except Exception:
+            pass
+
+
+async def _read_loop(session, websocket) -> None:
+    """Read output from the container and send to WebSocket."""
+    try:
+        while session.is_alive() and not session._closed:
+            data = await session.read_output()
+            if data:
+                try:
+                    await websocket.send_bytes(data)
+                except Exception:
+                    break
+            else:
+                await asyncio.sleep(0.01)
+    except Exception:
         pass
 
 
+async def _write_loop(session, websocket, instance_id: str) -> None:
+    """Read input from WebSocket and send to container."""
+    try:
+        while session.is_alive() and not session._closed:
+            message = await websocket.receive()
+            if message["type"] == "websocket.receive":
+                if "bytes" in message:
+                    await session.write_input(message["bytes"])
+                elif "text" in message:
+                    text = message["text"]
+                    if text.startswith("{"):
+                        # Control message (JSON)
+                        import json
+                        try:
+                            ctrl = json.loads(text)
+                            msg_type = ctrl.get("type")
+                            
+                            if msg_type == "resize":
+                                cols = ctrl.get("cols", 80)
+                                rows = ctrl.get("rows", 24)
+                                logger.info(f"Received resize message for instance {instance_id}: {cols}x{rows}")
+                                await session.resize(cols, rows)
+                            elif msg_type == "reset":
+                                # Reset terminal session
+                                logger.info("Resetting terminal session for instance %s", session.instance_id)
+                                await websocket.send_json({"type": "status", "status": "resetting"})
+                                
+                                # Reset the session
+                                new_session = await terminal_manager.reset_session(
+                                    session.instance_id,
+                                    session.container_id,
+                                )
+                                
+                                # Attach to new session
+                                await terminal_manager.attach_websocket(new_session, websocket)
+                                await websocket.send_json({"type": "status", "status": "connected"})
+                                
+                                # Update session reference and restart loops
+                                # Note: This will cause the current loops to exit
+                                # The WebSocket handler will create new ones
+                                return
+                                
+                        except json.JSONDecodeError:
+                            pass
+                    else:
+                        await session.write_input(text.encode("utf-8"))
+            elif message["type"] == "websocket.disconnect":
+                break
+    except Exception:
+        pass
+
+
+async def _heartbeat_loop(websocket: WebSocket) -> None:
+    """Send periodic ping messages to detect disconnections."""
+    try:
+        while True:
+            await asyncio.sleep(30)  # Ping every 30 seconds
+            try:
+                await websocket.send_json({"type": "ping"})
+            except Exception:
+                # WebSocket is closed or broken
+                break
+    except Exception:
+        pass
+
+
+@router.post(
+    "/projects/{project_id}/repositories/{repo_id}/instances/{instance_id}/terminal/reset",
+    summary="Reset terminal session",
+    description="Reset the terminal session for a tool instance, killing the current shell and starting fresh.",
+)
+async def reset_terminal_session(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    instance_id: uuid.UUID,
+    db_session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Reset the terminal session for an instance.
+
+    Args:
+        project_id: UUID of the project.
+        repo_id: UUID of the repository.
+        instance_id: UUID of the tool instance.
+        db_session: Database session.
+
+    Returns:
+        Dictionary with status message.
+    """
+    # Get instance and verify it exists and is running
+    instance = await db_session.get(ToolInstance, instance_id)
+    if instance is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Instance not found"
+        )
+
+    if instance.status != "running" or not instance.container_id:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Instance is not running"
+        )
+
+    try:
+        # Reset the session
+        new_session = await terminal_manager.reset_session(
+            instance_id,
+            instance.container_id,
+        )
+        
+        logger.info("Terminal session reset for instance %s (new session_id=%s)", instance_id, new_session.session_id)
+        
+        return {
+            "status": "success",
+            "message": "Terminal session reset successfully",
+            "instance_id": str(instance_id),
+            "session_id": new_session.session_id,
+        }
+    except Exception as exc:
+        logger.error("Failed to reset terminal session for instance %s: %s", instance_id, str(exc), exc_info=True)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to reset terminal session: {exc}"
+        )
+
+
 async def _get_user_from_websocket(
     websocket: WebSocket,
     db_session: AsyncSession,
@@ -141,7 +267,6 @@ async def _get_user_from_websocket(
 
     Returns:
         The user's UUID if authenticated, None otherwise.
-
     """
     from src.auth.session import decode_session_cookie
     from src.config import Settings

apps/api/src/api/tool_configs.py

@@ -4,19 +4,128 @@ import logging
 import uuid
 
 from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, Field, field_validator
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from src.auth.dependencies import get_current_user_id, get_db_session
 from src.models.tool_config import ToolConfig
 from src.models.tool_type import ToolType
-from src.schemas.tool_config import ToolConfigCreate, ToolConfigUpdate, ToolConfigResponse
 
 logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/tool-configs", tags=["tool-configs"])
 
 
+class ToolConfigCreate(BaseModel):
+    tool_type_id: str = Field(description="UUID of the tool type")
+    project_id: str | None = Field(default=None, description="Optional project ID for project-scoped config")
+    key: str = Field(description="Config key name")
+    value: str = Field(description="Config value")
+    config_type: str = Field(default="env", description="Type: env or file")
+    file_path: str | None = Field(default=None, description="File path for file-type configs")
+    port_override: int | None = Field(default=None, description="Port override (1-65535)")
+    start_command: str | None = Field(default=None, description="Override container start command")
+    working_directory: str | None = Field(default=None, description="Working directory inside container")
+    environment_variables: dict | None = Field(default=None, description="Environment variables as JSON object")
+    volumes: list[dict] | None = Field(default=None, description="Volume mounts as JSON array")
+
+    @field_validator("port_override")
+    @classmethod
+    def validate_port(cls, v: int | None) -> int | None:
+        if v is None:
+            return v
+        if v < 1 or v > 65535:
+            raise ValueError("Port must be between 1 and 65535")
+        return v
+
+    @field_validator("environment_variables")
+    @classmethod
+    def validate_env_vars(cls, v: dict | None) -> dict | None:
+        if v is None:
+            return v
+        if not isinstance(v, dict):
+            raise ValueError("environment_variables must be a JSON object")
+        return v
+
+    @field_validator("volumes")
+    @classmethod
+    def validate_volumes(cls, v: list | None) -> list | None:
+        if v is None:
+            return v
+        if not isinstance(v, list):
+            raise ValueError("volumes must be a JSON array")
+        for i, vol in enumerate(v):
+            if not isinstance(vol, dict):
+                raise ValueError(f"Volume at index {i} must be an object")
+            if "source" not in vol:
+                raise ValueError(f"Volume at index {i} must have 'source' field")
+            if "target" not in vol:
+                raise ValueError(f"Volume at index {i} must have 'target' field")
+        return v
+
+
+class ToolConfigUpdate(BaseModel):
+    key: str | None = Field(default=None, description="Config key name")
+    value: str | None = Field(default=None, description="Config value")
+    config_type: str | None = Field(default=None, description="Type: env or file")
+    file_path: str | None = Field(default=None, description="File path for file-type configs")
+    port_override: int | None = Field(default=None, description="Port override (1-65535)")
+    start_command: str | None = Field(default=None, description="Override container start command")
+    working_directory: str | None = Field(default=None, description="Working directory inside container")
+    environment_variables: dict | None = Field(default=None, description="Environment variables as JSON object")
+    volumes: list[dict] | None = Field(default=None, description="Volume mounts as JSON array")
+
+    @field_validator("port_override")
+    @classmethod
+    def validate_port(cls, v: int | None) -> int | None:
+        if v is None:
+            return v
+        if v < 1 or v > 65535:
+            raise ValueError("Port must be between 1 and 65535")
+        return v
+
+    @field_validator("environment_variables")
+    @classmethod
+    def validate_env_vars(cls, v: dict | None) -> dict | None:
+        if v is None:
+            return v
+        if not isinstance(v, dict):
+            raise ValueError("environment_variables must be a JSON object")
+        return v
+
+    @field_validator("volumes")
+    @classmethod
+    def validate_volumes(cls, v: list | None) -> list | None:
+        if v is None:
+            return v
+        if not isinstance(v, list):
+            raise ValueError("volumes must be a JSON array")
+        for i, vol in enumerate(v):
+            if not isinstance(vol, dict):
+                raise ValueError(f"Volume at index {i} must be an object")
+            if "source" not in vol:
+                raise ValueError(f"Volume at index {i} must have 'source' field")
+            if "target" not in vol:
+                raise ValueError(f"Volume at index {i} must have 'target' field")
+        return v
+
+
+class ToolConfigResponse(BaseModel):
+    id: str
+    tool_type_id: str
+    project_id: str | None
+    key: str
+    value: str
+    config_type: str
+    file_path: str | None
+    port_override: int | None
+    start_command: str | None
+    working_directory: str | None
+    environment_variables: dict | None
+    volumes: list[dict] | None
+
+
 @router.get("", summary="List tool configs", description="Get all tool configs for the current user.")
 async def list_configs(
     tool_type_id: str | None = None,

apps/api/src/api/tool_types.py

@@ -1,19 +1,33 @@
+import re
 import uuid
 from datetime import datetime
 
 import yaml
 from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, ConfigDict, field_validator, model_validator
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from src.auth.dependencies import get_current_user, get_db_session
+
+def _sanitize_template_vars(template: str) -> str:
+    """Replace template variables like {{VAR}} with placeholders to avoid YAML parsing errors."""
+    return re.sub(r"\{\{[A-Za-z_][A-Za-z0-9_]*\}\}", "__PLACEHOLDER__", template)
+
+from src.auth.dependencies import get_current_user_id, get_db_session
 from src.models.tool_type import ToolType
 from src.models.user import User
-from src.schemas.tool_type import ToolTypeCreate, ToolTypeResponse, ToolTypeUpdate, ToolTypeValidateRequest
 
 router = APIRouter(prefix="/tool-types", tags=["tool-types"])
 
 
+async def _get_user(session: AsyncSession, user_id: uuid.UUID) -> User:
+    """Fetch a user by ID or raise 401 if not found."""
+    user = await session.get(User, user_id)
+    if user is None:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="user not found")
+    return user
+
+
 async def _require_admin(user: User) -> None:
     """Check if user has admin privileges.
 
@@ -25,6 +39,251 @@ async def _require_admin(user: User) -> None:
     pass
 
 
+class ToolTypeCreate(BaseModel):
+    name: str
+    display_name: str
+    description: str | None = None
+    default_port: int = 0
+    definition_type: str = "compose"
+    compose_template: str | None = None
+    dockerfile_template: str | None = None
+    build_context: dict | None = None
+    readiness_probe: dict | None = None
+    required_variables: list[str] = []
+    category: str = "other"
+    interface_type: str = "web"
+    requires_port: bool = True
+
+    @field_validator("definition_type")
+    @classmethod
+    def validate_definition_type(cls, v: str) -> str:
+        if v not in ("compose", "dockerfile"):
+            raise ValueError("definition_type must be 'compose' or 'dockerfile'")
+        return v
+
+    @field_validator("compose_template")
+    @classmethod
+    def validate_compose_template(cls, v: str | None, info) -> str | None:
+        data = info.data
+        if data.get("definition_type") != "compose":
+            return v
+        
+        if v is None:
+            raise ValueError("compose_template is required when definition_type is 'compose'")
+        
+        # Replace template variables with dummy values before YAML validation
+        # to avoid YAML parsing errors with {{VAR}} syntax
+        sanitized = _sanitize_template_vars(v)
+        
+        try:
+            parsed = yaml.safe_load(sanitized)
+        except yaml.YAMLError as e:
+            raise ValueError(f"Invalid YAML: {e}")
+        
+        if not isinstance(parsed, dict):
+            raise ValueError("Compose template must be a YAML mapping")
+        
+        if "services" not in parsed:
+            raise ValueError("Compose template must contain 'services' key")
+        
+        if not parsed["services"]:
+            raise ValueError("Compose template must define at least one service")
+        
+        return v
+
+    @field_validator("dockerfile_template")
+    @classmethod
+    def validate_dockerfile_template(cls, v: str | None, info) -> str | None:
+        data = info.data
+        if data.get("definition_type") != "dockerfile":
+            return v
+        
+        if v is None:
+            raise ValueError("dockerfile_template is required when definition_type is 'dockerfile'")
+        
+        if not v.strip().startswith("FROM"):
+            raise ValueError("Dockerfile must start with a FROM instruction")
+        
+        return v
+
+    @field_validator("interface_type")
+    @classmethod
+    def validate_interface_type(cls, v: str) -> str:
+        if v not in ("web", "terminal"):
+            raise ValueError("interface_type must be 'web' or 'terminal'")
+        return v
+
+    @field_validator("default_port")
+    @classmethod
+    def validate_default_port(cls, v: int, info) -> int:
+        data = info.data
+        requires_port = data.get("requires_port", True)
+        if not requires_port:
+            return v
+        if v <= 0 or v > 65535:
+            raise ValueError("Port must be between 1 and 65535")
+        return v
+
+    @field_validator("required_variables")
+    @classmethod
+    def validate_required_variables(cls, v: list[str], info) -> list[str]:
+        if not v:
+            return v
+        
+        data = info.data
+        if data.get("definition_type") != "compose":
+            return v
+        
+        template = data.get("compose_template")
+        if not template:
+            return v
+        
+        for var in v:
+            placeholder = f"{{{{{var}}}}}"
+            if placeholder not in template:
+                raise ValueError(f"Required variable '{var}' not found in compose template")
+        
+        return v
+
+    @model_validator(mode="after")
+    def validate_templates(self) -> "ToolTypeCreate":
+        if self.definition_type == "dockerfile" and self.dockerfile_template is None:
+            raise ValueError("dockerfile_template is required when definition_type is 'dockerfile'")
+        if self.definition_type == "compose" and self.compose_template is None:
+            raise ValueError("compose_template is required when definition_type is 'compose'")
+        
+        # Validate that default_port is exposed in compose template (only if requires_port)
+        if self.requires_port and self.definition_type == "compose" and self.compose_template:
+            try:
+                sanitized = _sanitize_template_vars(self.compose_template)
+                parsed = yaml.safe_load(sanitized)
+            except yaml.YAMLError:
+                return self
+            
+            port_str = str(self.default_port)
+            port_exposed = False
+            
+            if isinstance(parsed, dict) and "services" in parsed:
+                for service_name, service_config in parsed["services"].items():
+                    if isinstance(service_config, dict) and "ports" in service_config:
+                        for port_mapping in service_config["ports"]:
+                            if isinstance(port_mapping, str):
+                                if port_str in port_mapping:
+                                    port_exposed = True
+                                    break
+                            elif isinstance(port_mapping, int) and port_mapping == self.default_port:
+                                port_exposed = True
+                                break
+                    if port_exposed:
+                        break
+            
+            if not port_exposed:
+                raise ValueError(f"Port {self.default_port} is not exposed in the compose template. Add it to the 'ports' section.")
+        
+        return self
+
+
+class ToolTypeUpdate(BaseModel):
+    display_name: str | None = None
+    description: str | None = None
+    default_port: int | None = None
+    definition_type: str | None = None
+    compose_template: str | None = None
+    dockerfile_template: str | None = None
+    build_context: dict | None = None
+    readiness_probe: dict | None = None
+    required_variables: list[str] | None = None
+    category: str | None = None
+    interface_type: str | None = None
+    requires_port: bool | None = None
+
+    @field_validator("definition_type")
+    @classmethod
+    def validate_definition_type(cls, v: str | None) -> str | None:
+        if v is None:
+            return v
+        if v not in ("compose", "dockerfile"):
+            raise ValueError("definition_type must be 'compose' or 'dockerfile'")
+        return v
+
+    @field_validator("interface_type")
+    @classmethod
+    def validate_interface_type(cls, v: str | None) -> str | None:
+        if v is None:
+            return v
+        if v not in ("web", "terminal"):
+            raise ValueError("interface_type must be 'web' or 'terminal'")
+        return v
+
+    @field_validator("compose_template")
+    @classmethod
+    def validate_compose_template(cls, v: str | None, info) -> str | None:
+        if v is None:
+            return v
+        
+        data = info.data
+        definition_type = data.get("definition_type")
+        if definition_type and definition_type != "compose":
+            return v
+        
+        # Replace template variables with dummy values before YAML validation
+        sanitized = _sanitize_template_vars(v)
+        
+        try:
+            parsed = yaml.safe_load(sanitized)
+        except yaml.YAMLError as e:
+            raise ValueError(f"Invalid YAML: {e}")
+        
+        if not isinstance(parsed, dict):
+            raise ValueError("Compose template must be a YAML mapping")
+        
+        if "services" not in parsed:
+            raise ValueError("Compose template must contain 'services' key")
+        
+        if not parsed["services"]:
+            raise ValueError("Compose template must define at least one service")
+        
+        return v
+
+    @field_validator("dockerfile_template")
+    @classmethod
+    def validate_dockerfile_template(cls, v: str | None, info) -> str | None:
+        if v is None:
+            return v
+        
+        data = info.data
+        definition_type = data.get("definition_type")
+        if definition_type and definition_type != "dockerfile":
+            return v
+        
+        if not v.strip().startswith("FROM"):
+            raise ValueError("Dockerfile must start with a FROM instruction")
+        
+        return v
+
+
+class ToolTypeResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    name: str
+    display_name: str
+    description: str | None
+    category: str
+    interface_type: str
+    requires_port: bool
+    default_port: int
+    definition_type: str
+    compose_template: str | None
+    dockerfile_template: str | None
+    build_context: dict | None
+    readiness_probe: dict | None
+    required_variables: list[str]
+    created_by_id: uuid.UUID | None
+    created_at: datetime
+    updated_at: datetime
+
+
 @router.post(
     "",
     response_model=ToolTypeResponse,
@@ -34,7 +293,7 @@ async def _require_admin(user: User) -> None:
 )
 async def create_tool_type(
     data: ToolTypeCreate,
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> ToolType:
     """Create a new tool type.
@@ -47,6 +306,7 @@ async def create_tool_type(
     Returns:
         The newly created tool type.
     """
+    user = await _get_user(session, user_id)
     await _require_admin(user)
     
     # Check for duplicate name
@@ -66,8 +326,8 @@ async def create_tool_type(
         readiness_probe=data.readiness_probe,
         required_variables=data.required_variables,
         category=data.category,
-        interfaces=data.interfaces,
-        is_builtin=False,
+        interface_type=data.interface_type,
+        requires_port=data.requires_port,
         created_by_id=user.id,
     )
     session.add(tool_type)
@@ -83,7 +343,7 @@ async def create_tool_type(
     description="List all available tool types including built-in and custom ones.",
 )
 async def list_tool_types(
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> list[ToolType]:
     """List all tool types.
@@ -95,6 +355,7 @@ async def list_tool_types(
     Returns:
         List of all tool types ordered by name.
     """
+    await _get_user(session, user_id)
     result = await session.execute(select(ToolType).order_by(ToolType.name))
     return list(result.scalars().all())
 
@@ -107,7 +368,7 @@ async def list_tool_types(
 )
 async def get_tool_type(
     tool_type_id: uuid.UUID,
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> ToolType:
     """Get a specific tool type by ID.
@@ -120,6 +381,7 @@ async def get_tool_type(
     Returns:
         The requested tool type.
     """
+    await _get_user(session, user_id)
     tool_type = await session.get(ToolType, tool_type_id)
     if tool_type is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found")
@@ -135,7 +397,7 @@ async def get_tool_type(
 async def update_tool_type(
     tool_type_id: uuid.UUID,
     data: ToolTypeUpdate,
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> ToolType:
     """Update a tool type.
@@ -149,19 +411,20 @@ async def update_tool_type(
     Returns:
         The updated tool type.
     """
+    user = await _get_user(session, user_id)
     await _require_admin(user)
     
     tool_type = await session.get(ToolType, tool_type_id)
     if tool_type is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found")
     
-    if tool_type.is_builtin:
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="cannot modify built-in tool types")
+    # Built-in tool types can now be modified
     
     update_data = data.model_dump(exclude_unset=True)
     
     # Validate port if being updated
-    if "default_port" in update_data:
+    requires_port = update_data.get("requires_port", tool_type.requires_port)
+    if "default_port" in update_data and requires_port:
         new_port = update_data["default_port"]
         if new_port <= 0 or new_port > 65535:
             raise HTTPException(
@@ -175,7 +438,8 @@ async def update_tool_type(
             template = update_data.get("compose_template", tool_type.compose_template)
             if template:
                 try:
-                    parsed = yaml.safe_load(template)
+                    sanitized = _sanitize_template_vars(template)
+                    parsed = yaml.safe_load(sanitized)
                 except yaml.YAMLError:
                     parsed = None
                 
@@ -231,6 +495,12 @@ async def update_tool_type(
     return tool_type
 
 
+class ToolTypeValidateRequest(BaseModel):
+    definition_type: str
+    compose_template: str | None = None
+    dockerfile_template: str | None = None
+
+
 @router.post(
     "/validate",
     summary="Validate tool type template",
@@ -238,7 +508,7 @@ async def update_tool_type(
 )
 async def validate_tool_type_template(
     data: ToolTypeValidateRequest,
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> dict:
     """Validate a tool type template syntax.
@@ -251,6 +521,7 @@ async def validate_tool_type_template(
     Returns:
         Validation result with success status and any errors.
     """
+    await _get_user(session, user_id)
 
     errors = []
 
@@ -259,7 +530,8 @@ async def validate_tool_type_template(
             errors.append("Compose template is required")
         else:
             try:
-                parsed = yaml.safe_load(data.compose_template)
+                sanitized = _sanitize_template_vars(data.compose_template)
+                parsed = yaml.safe_load(sanitized)
                 if not isinstance(parsed, dict):
                     errors.append("Compose template must be a YAML mapping")
                 elif "services" not in parsed:
@@ -291,7 +563,7 @@ async def validate_tool_type_template(
 )
 async def validate_tool_type(
     tool_type_id: uuid.UUID,
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> dict:
     """Validate a tool type's template syntax.
@@ -304,6 +576,7 @@ async def validate_tool_type(
     Returns:
         Validation result with success status and any errors.
     """
+    await _get_user(session, user_id)
     tool_type = await session.get(ToolType, tool_type_id)
     if tool_type is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found")
@@ -315,7 +588,8 @@ async def validate_tool_type(
             errors.append("Compose template is empty")
         else:
             try:
-                parsed = yaml.safe_load(tool_type.compose_template)
+                sanitized = _sanitize_template_vars(tool_type.compose_template)
+                parsed = yaml.safe_load(sanitized)
                 if not isinstance(parsed, dict):
                     errors.append("Compose template must be a YAML mapping")
                 elif "services" not in parsed:
@@ -345,7 +619,7 @@ async def validate_tool_type(
 )
 async def delete_tool_type(
     tool_type_id: uuid.UUID,
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> None:
     """Delete a tool type.
@@ -358,14 +632,14 @@ async def delete_tool_type(
     Returns:
         None with 204 status code.
     """
+    user = await _get_user(session, user_id)
     await _require_admin(user)
     
     tool_type = await session.get(ToolType, tool_type_id)
     if tool_type is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found")
     
-    if tool_type.is_builtin:
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="cannot delete built-in tool types")
+    # Built-in tool types can now be deleted
     
     await session.delete(tool_type)
     await session.commit()

apps/api/src/api/user_config.py

@@ -2,17 +2,26 @@ import logging
 import uuid
 
 from fastapi import APIRouter, Depends, HTTPException, status
+
+logger = logging.getLogger(__name__)
+from pydantic import BaseModel, ConfigDict
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from src.auth.dependencies import get_current_user, get_db_session
+from src.auth.dependencies import get_current_user_id, get_db_session
 from src.models.user import User
 from src.models.user_config import UserConfig
-from src.schemas.user_config import UserConfigResponse, UserConfigUpdate
 
 router = APIRouter(prefix="/users/me", tags=["user-config"])
 
 
+async def _get_user(session: AsyncSession, user_id: uuid.UUID) -> User:
+    """Fetch a user by ID or raise 401 if not found."""
+    user = await session.get(User, user_id)
+    if user is None:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="user not found")
+    return user
+
 
 async def _get_or_create_config(session: AsyncSession, user_id: uuid.UUID) -> UserConfig:
     """Get or create user config record.
@@ -24,16 +33,34 @@ async def _get_or_create_config(session: AsyncSession, user_id: uuid.UUID) -> Us
     Returns:
         The user's config, creating a new one if it doesn't exist.
     """
-    result = await session.execute(select(UserConfig).where(UserConfig.user_id == user.id))
+    result = await session.execute(select(UserConfig).where(UserConfig.user_id == user_id))
     config = result.scalar_one_or_none()
     if config is None:
-        config = UserConfig(user_id=user.id, config={})
+        config = UserConfig(user_id=user_id, config={})
         session.add(config)
         await session.commit()
         await session.refresh(config)
     return config
 
 
+class UserConfigResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    default_editor: str | None = None
+    theme: str = "system"
+    git_user_name: str | None = None
+    git_user_email: str | None = None
+    last_session_id: str | None = None
+
+
+class UserConfigUpdate(BaseModel):
+    default_editor: str | None = None
+    theme: str | None = None
+    git_user_name: str | None = None
+    git_user_email: str | None = None
+    last_session_id: str | None = None
+
+
 @router.get(
     "/config",
     response_model=UserConfigResponse,
@@ -41,7 +68,7 @@ async def _get_or_create_config(session: AsyncSession, user_id: uuid.UUID) -> Us
     description="Get the current user's configuration settings.",
 )
 async def get_user_config(
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> UserConfigResponse:
     """Get the current user's configuration.
@@ -53,7 +80,8 @@ async def get_user_config(
     Returns:
         The user's configuration settings.
     """
-    config = await _get_or_create_config(session, user.id)
+    _user = await _get_user(session, user_id)
+    config = await _get_or_create_config(session, user_id)
     return UserConfigResponse.model_validate(config.config)
 
 
@@ -65,7 +93,7 @@ async def get_user_config(
 )
 async def update_user_config(
     data: UserConfigUpdate,
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> UserConfigResponse:
     """Update the current user's configuration.
@@ -78,11 +106,12 @@ async def update_user_config(
     Returns:
         The updated user configuration.
     """
-    config = await _get_or_create_config(session, user.id)
+    _user = await _get_user(session, user_id)
+    config = await _get_or_create_config(session, user_id)
 
     # Merge updates
     update_data = data.model_dump(exclude_unset=True)
-    logger.info("Updating user config for user %s: %s", user.id, update_data)
+    logger.info("Updating user config for user %s: %s", user_id, update_data)
     # SQLAlchemy JSON doesn't track dict mutations, so we replace the whole dict
     config.config = {**config.config, **update_data}
 

apps/api/src/api/users.py

@@ -2,14 +2,11 @@ import uuid
 from pathlib import Path
 
 from fastapi import APIRouter, Depends, HTTPException, UploadFile, status
-from sqlalchemy import select
+from pydantic import BaseModel, ConfigDict
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from src.auth.dependencies import get_current_user, get_db_session
-from src.models.tool_instance import ToolInstance
+from src.auth.dependencies import get_current_user_id, get_db_session
 from src.models.user import User
-from src.schemas.tool_instance import SessionItemResponse, SessionListResponse
-from src.schemas.user import UserProfileResponse, UserProfileUpdate
 
 router = APIRouter(prefix="/users", tags=["users"])
 
@@ -19,6 +16,27 @@ ALLOWED_CONTENT_TYPES = {"image/png", "image/jpeg", "image/jpg"}
 MAX_AVATAR_SIZE = 2 * 1024 * 1024  # 2MB
 
 
+async def _get_user(session: AsyncSession, user_id: uuid.UUID) -> User:
+    """Fetch a user by ID or raise 401 if not found."""
+    user = await session.get(User, user_id)
+    if user is None:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="user not found")
+    return user
+
+
+class UserProfileResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    email: str
+    name: str
+    avatar_url: str | None
+
+
+class UserProfileUpdate(BaseModel):
+    name: str | None = None
+    email: str | None = None
+
 
 @router.get(
     "/me",
@@ -27,7 +45,7 @@ MAX_AVATAR_SIZE = 2 * 1024 * 1024  # 2MB
     description="Retrieve the profile of the currently authenticated user.",
 )
 async def get_profile(
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> User:
     """Get the current user's profile.
@@ -39,7 +57,7 @@ async def get_profile(
     Returns:
         The user's profile information.
     """
-    return user
+    return await _get_user(session, user_id)
 
 
 @router.put(
@@ -50,7 +68,7 @@ async def get_profile(
 )
 async def update_profile(
     data: UserProfileUpdate,
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> User:
     """Update the current user's profile.
@@ -63,6 +81,7 @@ async def update_profile(
     Returns:
         The updated user profile.
     """
+    user = await _get_user(session, user_id)
 
     if data.name is not None:
         if len(data.name.strip()) == 0:
@@ -87,7 +106,7 @@ async def update_profile(
 )
 async def upload_avatar(
     file: UploadFile,
-    user: User = Depends(get_current_user),
+    user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> User:
     """Upload a profile avatar image.
@@ -100,6 +119,7 @@ async def upload_avatar(
     Returns:
         The updated user profile with new avatar URL.
     """
+    user = await _get_user(session, user_id)
 
     if file.content_type not in ALLOWED_CONTENT_TYPES:
         raise HTTPException(
@@ -134,41 +154,3 @@ async def upload_avatar(
     await session.commit()
     await session.refresh(user)
     return user
-
-
-@router.get(
-    "/me/sessions",
-    response_model=SessionListResponse,
-    summary="Get current user sessions",
-    description="Retrieve all tool instances (sessions) for the authenticated user.",
-)
-async def get_user_sessions(
-    user: User = Depends(get_current_user),
-    session: AsyncSession = Depends(get_db_session),
-) -> SessionListResponse:
-    """Return all tool instances for the current user with related names."""
-    result = await session.execute(
-        select(ToolInstance)
-        .where(ToolInstance.owner_id == user.id)
-        .order_by(ToolInstance.created_at.desc())
-    )
-    instances = result.scalars().all()
-
-    sessions = [
-        SessionItemResponse(
-            id=str(inst.id),
-            display_name=inst.display_name,
-            tool_type_name=inst.tool_type.display_name if inst.tool_type else "Unknown",
-            tool_icon=inst.tool_type.icon if inst.tool_type else None,
-            tool_type_interfaces=inst.tool_type.interfaces if inst.tool_type else [],
-            repository_name=inst.repository.name if inst.repository else "Unknown",
-            repository_id=str(inst.repository_id),
-            project_name=inst.project.name if inst.project else "Unknown",
-            project_id=str(inst.project_id),
-            status=inst.status,
-            url=inst.url,
-        )
-        for inst in instances
-    ]
-
-    return SessionListResponse(sessions=sessions)

apps/api/src/auth/dependencies.py

@@ -7,7 +7,6 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from src.auth.session import decode_session_cookie
 from src.config import Settings
 from src.database import SessionLocal
-from src.models.project import Project
 from src.models.user import User
 
 
@@ -48,29 +47,3 @@ async def get_current_user(
     if user is None:
         raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="user not found")
     return user
-
-
-async def get_owned_project(
-    project_id: uuid.UUID,
-    user: User = Depends(get_current_user),
-    db_session: AsyncSession = Depends(get_db_session),
-) -> Project:
-    """Fetch a project and verify ownership.
-
-    Args:
-        project_id: UUID of the project (injected from path parameter).
-        user: The currently authenticated user.
-        db_session: Database session.
-
-    Returns:
-        The project if found and owned by the user.
-
-    Raises:
-        HTTPException: 404 if project not found, 403 if user is not the owner.
-    """
-    project = await db_session.get(Project, project_id)
-    if project is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="project not found")
-    if project.owner_id != user.id:
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="not project owner")
-    return project

apps/api/src/main.py

@@ -7,6 +7,8 @@ from fastapi.exceptions import RequestValidationError
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import JSONResponse
 from fastapi.staticfiles import StaticFiles
+from sqlalchemy import text
+
 from src.api.auth import router as auth_router
 from src.api.dashboard import router as dashboard_router
 from src.api.git_repositories import router as git_repositories_router
@@ -24,13 +26,12 @@ from src.api.tool_types import router as tool_types_router
 from src.api.user_config import router as user_config_router
 from src.api.users import router as users_router
 from src.config import Settings
-from src.database import SessionLocal, init_database
+from src.database import init_database
 from src.logging_config import (
     ExceptionLoggingMiddleware,
     RequestLoggingMiddleware,
     configure_logging,
 )
-from src.seeds.builtin_tool_types import seed_builtin_tool_types
 
 # Configure logging early
 log_level = os.getenv("LOG_LEVEL", "INFO").upper()
@@ -113,8 +114,6 @@ async def on_startup():
         import sys
         sys.exit(1)
 
-    # Seed built-in data
-    await seed_builtin_tool_types()
     logger.info("Startup complete.")
 
 app.include_router(health_router)

apps/api/src/models/__init__.py

@@ -1,8 +1,6 @@
 from src.models.base import Base
 from src.models.config_folder import ConfigFolder
-from src.models.config_include import ConfigInclude
-from src.models.config_mount import ConfigMount
-from src.models.config_profile import ConfigProfile
+from src.models.config_profile import ConfigProfile, ConfigProfileInclude
 from src.models.git_repository import GitRepository
 from src.models.project import Project
 from src.models.ssh_key import SSHKey
@@ -11,17 +9,4 @@ from src.models.tool_type import ToolType
 from src.models.user import User
 from src.models.user_config import UserConfig
 
-__all__ = [
-    "Base",
-    "ConfigFolder",
-    "ConfigInclude",
-    "ConfigMount",
-    "ConfigProfile",
-    "GitRepository",
-    "Project",
-    "SSHKey",
-    "ToolInstance",
-    "ToolType",
-    "User",
-    "UserConfig",
-]
+__all__ = ["Base", "ConfigFolder", "ConfigProfile", "ConfigProfileInclude", "GitRepository", "Project", "SSHKey", "ToolInstance", "ToolType", "User", "UserConfig"]

apps/api/src/models/config_folder.py

@@ -26,8 +26,6 @@ class ConfigFolder(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     project_overrides: Mapped[dict | None] = mapped_column(
         JSON, default=dict, nullable=True
     )  # {"project_id": {"mount_path": "...", "files": {...}}}
-    # DEPRECATED: Legacy auto-mounting flag. No longer used for launch-time
-    # auto-mounting. Use ConfigProfile and ToolInstance.selected_profile_id instead.
     is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
 
     user: Mapped["User"] = relationship()

apps/api/src/models/config_include.py

@@ -1,36 +0,0 @@
-import uuid
-from typing import TYPE_CHECKING
-
-from sqlalchemy import ForeignKey, Integer, UniqueConstraint
-from sqlalchemy import Uuid as UUID
-from sqlalchemy.orm import Mapped, mapped_column, relationship
-
-from src.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
-
-if TYPE_CHECKING:
-    from src.models.config_profile import ConfigProfile
-
-
-class ConfigInclude(UUIDPrimaryKeyMixin, TimestampMixin, Base):
-    __tablename__ = "config_includes"
-    __table_args__ = (
-        UniqueConstraint("profile_id", "included_profile_id", name="uq_config_includes_pair"),
-    )
-
-    profile_id: Mapped[uuid.UUID] = mapped_column(
-        UUID(), ForeignKey("config_profiles.id", ondelete="CASCADE"), nullable=False
-    )
-    included_profile_id: Mapped[uuid.UUID] = mapped_column(
-        UUID(), ForeignKey("config_profiles.id", ondelete="CASCADE"), nullable=False
-    )
-    order_index: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
-
-    profile: Mapped["ConfigProfile"] = relationship(
-        "ConfigProfile",
-        foreign_keys=[profile_id],
-        back_populates="includes",
-    )
-    included_profile: Mapped["ConfigProfile"] = relationship(
-        "ConfigProfile",
-        foreign_keys=[included_profile_id],
-    )

apps/api/src/models/config_mount.py

@@ -1,31 +0,0 @@
-import uuid
-from typing import TYPE_CHECKING
-
-from sqlalchemy import ForeignKey, Integer, JSON, String
-from sqlalchemy import Uuid as UUID
-from sqlalchemy.orm import Mapped, mapped_column, relationship
-
-from src.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
-
-if TYPE_CHECKING:
-    from src.models.config_profile import ConfigProfile
-
-
-class ConfigMount(UUIDPrimaryKeyMixin, TimestampMixin, Base):
-    __tablename__ = "config_mounts"
-
-    profile_id: Mapped[uuid.UUID] = mapped_column(
-        UUID(), ForeignKey("config_profiles.id", ondelete="CASCADE"), nullable=False
-    )
-    target_path: Mapped[str] = mapped_column(String(1024), nullable=False)
-    mode: Mapped[str] = mapped_column(String(10), nullable=False, default="rw")
-    files: Mapped[dict[str, str] | None] = mapped_column(
-        JSON, default=dict, nullable=True
-    )
-    order_index: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
-
-    profile: Mapped["ConfigProfile"] = relationship(
-        "ConfigProfile",
-        foreign_keys=[profile_id],
-        back_populates="mounts",
-    )

apps/api/src/models/config_profile.py

@@ -1,15 +1,13 @@
 import uuid
 from typing import TYPE_CHECKING
 
-from sqlalchemy import ForeignKey, Integer, JSON, String, Text, UniqueConstraint
+from sqlalchemy import ForeignKey, JSON, Integer, String, Text, Boolean
 from sqlalchemy import Uuid as UUID
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from src.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
 
 if TYPE_CHECKING:
-    from src.models.config_include import ConfigInclude
-    from src.models.config_mount import ConfigMount
     from src.models.project import Project
     from src.models.tool_type import ToolType
     from src.models.user import User
@@ -17,43 +15,60 @@ if TYPE_CHECKING:
 
 class ConfigProfile(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     __tablename__ = "config_profiles"
-    __table_args__ = (
-        UniqueConstraint("user_id", "name", name="uq_config_profiles_user_name"),
-    )
 
     user_id: Mapped[uuid.UUID] = mapped_column(
         UUID(), ForeignKey("users.id", ondelete="CASCADE"), nullable=False
     )
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    description: Mapped[str | None] = mapped_column(Text, nullable=True)
     project_id: Mapped[uuid.UUID | None] = mapped_column(
         UUID(), ForeignKey("projects.id", ondelete="CASCADE"), nullable=True
     )
     tool_type_id: Mapped[uuid.UUID | None] = mapped_column(
         UUID(), ForeignKey("tool_types.id", ondelete="CASCADE"), nullable=True
     )
-    name: Mapped[str] = mapped_column(String(255), nullable=False)
-    description: Mapped[str | None] = mapped_column(Text, nullable=True)
-    environment_variables: Mapped[dict[str, str] | None] = mapped_column(
-        JSON, default=dict, nullable=True
-    )
-    start_command: Mapped[str | None] = mapped_column(Text, nullable=True)
-    working_directory: Mapped[str | None] = mapped_column(Text, nullable=True)
-    port: Mapped[int | None] = mapped_column(Integer, nullable=True)
-    is_default: Mapped[bool] = mapped_column(default=False, nullable=False)
+    env_vars: Mapped[dict] = mapped_column(
+        JSON, default=dict, nullable=False
+    )  # {"VAR_NAME": "value", ...}
+    runtime_hints: Mapped[dict] = mapped_column(
+        JSON, default=dict, nullable=False
+    )  # {"start_command": "...", "working_dir": "...", ...}
+    mounts: Mapped[list] = mapped_column(
+        JSON, default=list, nullable=False
+    )  # [{"target": "/path", "mode": "rw", "files": {"rel/path": "content"}}, ...]
+    files: Mapped[dict] = mapped_column(
+        JSON, default=dict, nullable=False
+    )  # {"rel/path": "content", ...}
+    is_default: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
 
     user: Mapped["User"] = relationship()
     project: Mapped["Project | None"] = relationship()
     tool_type: Mapped["ToolType | None"] = relationship()
-    includes: Mapped[list["ConfigInclude"]] = relationship(
-        "ConfigInclude",
-        primaryjoin="ConfigProfile.id == ConfigInclude.profile_id",
-        back_populates="profile",
+    includes: Mapped[list["ConfigProfileInclude"]] = relationship(
+        "ConfigProfileInclude",
+        foreign_keys="ConfigProfileInclude.profile_id",
+        order_by="ConfigProfileInclude.order_index",
         cascade="all, delete-orphan",
-        order_by="ConfigInclude.order_index",
     )
-    mounts: Mapped[list["ConfigMount"]] = relationship(
-        "ConfigMount",
-        primaryjoin="ConfigProfile.id == ConfigMount.profile_id",
-        back_populates="profile",
-        cascade="all, delete-orphan",
-        order_by="ConfigMount.order_index",
+
+
+class ConfigProfileInclude(UUIDPrimaryKeyMixin, TimestampMixin, Base):
+    __tablename__ = "config_profile_includes"
+
+    profile_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(), ForeignKey("config_profiles.id", ondelete="CASCADE"), nullable=False
+    )
+    included_profile_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(), ForeignKey("config_profiles.id", ondelete="CASCADE"), nullable=False
+    )
+    order_index: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+
+    profile: Mapped["ConfigProfile"] = relationship(
+        "ConfigProfile",
+        foreign_keys=[profile_id],
+        back_populates="includes",
+    )
+    included_profile: Mapped["ConfigProfile"] = relationship(
+        "ConfigProfile",
+        foreign_keys=[included_profile_id],
     )

apps/api/src/models/git_repository.py

@@ -10,6 +10,7 @@ from src.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
 
 if TYPE_CHECKING:
     from src.models.project import Project
+    from src.models.ssh_key import SSHKey
     from src.models.user import User
 
 
@@ -23,6 +24,10 @@ class GitRepository(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     is_mirror: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
     remote_url: Mapped[str | None] = mapped_column(String(1024), nullable=True)
     last_push: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    ssh_key_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(), ForeignKey("ssh_keys.id"), nullable=True
+    )
 
     project: Mapped["Project"] = relationship(back_populates="repositories")
     owner: Mapped["User"] = relationship()
+    ssh_key: Mapped["SSHKey | None"] = relationship()

apps/api/src/models/tool_instance.py

@@ -2,7 +2,7 @@ import uuid
 from datetime import datetime
 from typing import TYPE_CHECKING
 
-from sqlalchemy import DateTime, ForeignKey, Integer, String
+from sqlalchemy import DateTime, ForeignKey, Integer, JSON, String
 from sqlalchemy import Uuid as UUID
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
@@ -63,7 +63,16 @@ class ToolInstance(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     last_stopped_at: Mapped[datetime | None] = mapped_column(
         DateTime(timezone=True), nullable=True
     )
-    selected_profile_id: Mapped[uuid.UUID | None] = mapped_column(
+    probe_result: Mapped[dict | None] = mapped_column(
+        JSON, nullable=True
+    )
+    clone_mode: Mapped[str] = mapped_column(
+        String(20), nullable=False, default="mount"
+    )
+    branch: Mapped[str | None] = mapped_column(
+        String(255), nullable=True, default="main"
+    )
+    selected_config_profile_id: Mapped[uuid.UUID | None] = mapped_column(
         UUID(), ForeignKey("config_profiles.id", ondelete="SET NULL"), nullable=True
     )
 
@@ -71,4 +80,4 @@ class ToolInstance(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     repository: Mapped["GitRepository"] = relationship()
     project: Mapped["Project"] = relationship()
     owner: Mapped["User"] = relationship()
-    selected_profile: Mapped["ConfigProfile | None"] = relationship()
+    selected_config_profile: Mapped["ConfigProfile | None"] = relationship()

apps/api/src/models/tool_type.py

@@ -18,7 +18,8 @@ class ToolType(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     display_name: Mapped[str] = mapped_column(String(255), nullable=False)
     description: Mapped[str | None] = mapped_column(Text, nullable=True)
     category: Mapped[str] = mapped_column(String(50), nullable=False, default="other")
-    interfaces: Mapped[list[str]] = mapped_column(JSON, default=list, nullable=False)
+    interface_type: Mapped[str] = mapped_column(String(20), nullable=False, default="web")
+    requires_port: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
     default_port: Mapped[int] = mapped_column(nullable=False)
     definition_type: Mapped[str] = mapped_column(
         String(20), nullable=False, default="compose"
@@ -30,7 +31,6 @@ class ToolType(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     )
     readiness_probe: Mapped[dict | None] = mapped_column(JSON, nullable=True)
     required_variables: Mapped[list[str]] = mapped_column(JSON, default=list, nullable=False)
-    is_builtin: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
     created_by_id: Mapped[uuid.UUID | None] = mapped_column(
         UUID(),
         ForeignKey("users.id"),

apps/api/src/models/user_config.py

@@ -18,23 +18,3 @@ class UserConfig(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     config: Mapped[dict[str, object]] = mapped_column(JSON, default=dict, nullable=False)
 
     user: Mapped["User"] = relationship(back_populates="user_config")
-
-    @property
-    def default_profile_id(self) -> uuid.UUID | None:
-        profile_id = self.config.get("default_profile_id")
-        return uuid.UUID(profile_id) if profile_id else None
-
-    @default_profile_id.setter
-    def default_profile_id(self, value: uuid.UUID | None) -> None:
-        if value is not None:
-            self.config["default_profile_id"] = str(value)
-        elif "default_profile_id" in self.config:
-            del self.config["default_profile_id"]
-
-    @property
-    def default_profiles(self) -> dict[str, str]:
-        return self.config.get("default_profiles", {})
-
-    @default_profiles.setter
-    def default_profiles(self, value: dict[str, str]) -> None:
-        self.config["default_profiles"] = value

apps/api/src/schemas/__init__.py

@@ -1 +0,0 @@
-"""Pydantic request/response schemas."""

apps/api/src/schemas/config_folder.py

@@ -1,44 +0,0 @@
-"""Config folder request/response schemas."""
-
-import uuid
-
-from pydantic import BaseModel, Field
-
-
-class ConfigFolderCreate(BaseModel):
-    name: str = Field(description="Folder name")
-    description: str | None = Field(default=None, description="Optional description")
-    mount_path: str = Field(description="Mount path in container")
-    files: dict[str, str] | None = Field(
-        default=None, description="Files as {path: content}"
-    )
-    is_active: bool = Field(default=True, description="Whether folder is active")
-
-
-class ConfigFolderUpdate(BaseModel):
-    name: str | None = None
-    description: str | None = None
-    mount_path: str | None = None
-    files: dict[str, str] | None = None
-    is_active: bool | None = None
-
-
-class ProjectOverrideCreate(BaseModel):
-    project_id: str = Field(description="Project ID to override for")
-    mount_path: str | None = Field(default=None, description="Override mount path")
-    files: dict[str, str] | None = Field(
-        default=None, description="Override files"
-    )
-    is_active: bool | None = Field(default=None, description="Override active state")
-
-
-class ConfigFolderResponse(BaseModel):
-    id: str
-    user_id: str
-    name: str
-    description: str | None
-    mount_path: str
-    files: dict[str, str] | None
-    is_active: bool
-    created_at: str
-    updated_at: str

apps/api/src/schemas/config_profile.py

@@ -1,131 +0,0 @@
-"""Config profile request/response schemas."""
-
-from typing import Any
-
-from pydantic import BaseModel, Field, field_validator
-
-MAX_MOUNT_PATH_LENGTH = 1024
-
-
-class ConfigProfileCreate(BaseModel):
-    name: str = Field(description="Profile name (unique per user)")
-    description: str | None = Field(default=None, description="Optional description")
-
-    @field_validator("name")
-    @classmethod
-    def validate_name(cls, v: str) -> str:
-        v = v.strip()
-        if not v:
-            raise ValueError("Profile name cannot be empty")
-        if len(v) > 255:
-            raise ValueError("Profile name must be 255 characters or less")
-        return v
-
-
-class ConfigProfileUpdate(BaseModel):
-    name: str | None = Field(default=None, description="Profile name")
-    description: str | None = Field(default=None, description="Optional description")
-
-    @field_validator("name")
-    @classmethod
-    def validate_name(cls, v: str | None) -> str | None:
-        if v is None:
-            return v
-        v = v.strip()
-        if not v:
-            raise ValueError("Profile name cannot be empty")
-        if len(v) > 255:
-            raise ValueError("Profile name must be 255 characters or less")
-        return v
-
-
-class ConfigProfileResponse(BaseModel):
-    id: str
-    user_id: str
-    name: str
-    description: str | None
-    created_at: str
-    updated_at: str
-
-
-class ConfigProfileDetailResponse(ConfigProfileResponse):
-    includes: list[dict[str, Any]]
-    mounts: list[dict[str, Any]]
-
-
-class ConfigIncludeCreate(BaseModel):
-    included_profile_id: str = Field(description="UUID of the profile to include")
-    order_index: int = Field(default=0, description="Order index for include resolution")
-
-
-class ConfigIncludeUpdate(BaseModel):
-    order_index: int = Field(description="Order index for include resolution")
-
-
-class ConfigIncludeResponse(BaseModel):
-    id: str
-    profile_id: str
-    included_profile_id: str
-    included_profile_name: str | None
-    order_index: int
-    created_at: str
-    updated_at: str
-
-
-class ConfigMountCreate(BaseModel):
-    target_path: str = Field(description="Absolute target path in container")
-    mode: str = Field(default="rw", description="Mount mode (rw or ro)")
-    files: dict[str, str] | None = Field(
-        default=None, description="Files as {path: content}"
-    )
-    order_index: int = Field(default=0, description="Order index for mount resolution")
-
-    @field_validator("target_path")
-    @classmethod
-    def validate_target_path(cls, v: str) -> str:
-        if not v.startswith("/"):
-            raise ValueError("Target path must be absolute (start with /)")
-        if ".." in v:
-            raise ValueError("Target path cannot contain parent directory references (..)")
-        if len(v) > MAX_MOUNT_PATH_LENGTH:
-            raise ValueError(f"Target path must be {MAX_MOUNT_PATH_LENGTH} characters or less")
-        return v
-
-
-class ConfigMountUpdate(BaseModel):
-    target_path: str | None = Field(default=None, description="Absolute target path in container")
-    mode: str | None = Field(default=None, description="Mount mode (rw or ro)")
-    files: dict[str, str] | None = Field(
-        default=None, description="Files as {path: content}"
-    )
-    order_index: int | None = Field(default=None, description="Order index for mount resolution")
-
-    @field_validator("target_path")
-    @classmethod
-    def validate_target_path(cls, v: str | None) -> str | None:
-        if v is None:
-            return v
-        if not v.startswith("/"):
-            raise ValueError("Target path must be absolute (start with /)")
-        if ".." in v:
-            raise ValueError("Target path cannot contain parent directory references (..)")
-        if len(v) > MAX_MOUNT_PATH_LENGTH:
-            raise ValueError(f"Target path must be {MAX_MOUNT_PATH_LENGTH} characters or less")
-        return v
-
-
-class ConfigMountResponse(BaseModel):
-    id: str
-    profile_id: str
-    target_path: str
-    mode: str
-    files: dict[str, str] | None
-    order_index: int
-    created_at: str
-    updated_at: str
-
-
-class DefaultProfilesUpdate(BaseModel):
-    default_profiles: dict[str, str] = Field(
-        description="Mapping of tool_type_id to profile_id"
-    )

apps/api/src/schemas/git_repository.py

@@ -1,129 +0,0 @@
-"""Git repository request/response schemas."""
-
-import uuid
-from datetime import datetime
-
-from pydantic import BaseModel, ConfigDict
-
-
-class GitRepositoryCreate(BaseModel):
-    name: str
-    remote_url: str | None = None
-    force_original_url: bool = False
-
-
-class URLParseRequest(BaseModel):
-    url: str
-
-
-class URLParseResponse(BaseModel):
-    original_url: str
-    base_url: str | None
-    is_valid_clone_url: bool
-    needs_parsing: bool
-    host: str | None
-    message: str
-    error_code: str | None
-
-
-class GitRepositoryResponse(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-
-    id: uuid.UUID
-    name: str
-    path: str
-    project_id: uuid.UUID
-    owner_id: uuid.UUID
-    is_mirror: bool
-    remote_url: str | None
-    last_push: datetime | None
-    created_at: datetime
-    updated_at: datetime
-
-
-class FileListResponse(BaseModel):
-    path: str
-    branch: str
-    entries: list[dict]
-
-
-class FileContentResponse(BaseModel):
-    path: str
-    branch: str
-    content: str
-    size: int
-    encoding: str
-    language: str | None
-    is_binary: bool
-    last_commit: dict | None
-
-
-class BranchesResponse(BaseModel):
-    branches: list[dict]
-    default_branch: str
-
-
-class FileUpdateRequest(BaseModel):
-    path: str
-    branch: str
-    content: str
-    commit_message: str
-
-
-class FileUpdateResponse(BaseModel):
-    commit_hash: str
-    message: str
-    branch: str
-
-
-class StatusResponse(BaseModel):
-    branch: str
-    modified: list[str]
-    added: list[str]
-    deleted: list[str]
-    untracked: list[str]
-    renamed: list[str]
-    ahead: int
-    behind: int
-
-
-class BranchCreateRequest(BaseModel):
-    name: str
-    base_branch: str = "HEAD"
-
-
-class CheckoutRequest(BaseModel):
-    branch: str
-
-
-class CommitRequest(BaseModel):
-    message: str
-    files: list[str] | None = None
-
-
-class CommitResponse(BaseModel):
-    commit_hash: str
-    message: str
-
-
-class FetchResponse(BaseModel):
-    message: str
-
-
-class PullResponse(BaseModel):
-    message: str
-
-
-class PushResponse(BaseModel):
-    message: str
-
-
-class MergeRequest(BaseModel):
-    source_branch: str
-    target_branch: str | None = None
-    message: str | None = None
-
-
-class MergeResponse(BaseModel):
-    commit_hash: str
-    message: str

apps/api/src/schemas/health.py

@@ -1,50 +0,0 @@
-"""Health check response schemas."""
-
-from pydantic import BaseModel, Field
-
-
-class DatabaseHealth(BaseModel):
-    """Database health check result."""
-
-    status: str = Field(description="Database health status", examples=["healthy"])
-    response_time_ms: float = Field(
-        description="Query response time in milliseconds", examples=[5.2]
-    )
-
-
-class DiskHealth(BaseModel):
-    """Disk space health check result."""
-
-    status: str = Field(description="Disk health status", examples=["healthy"])
-    free_gb: float = Field(description="Free disk space in GB", examples=[45.2])
-    total_gb: float = Field(description="Total disk space in GB", examples=[100.0])
-
-
-class HealthChecks(BaseModel):
-    """Individual health checks."""
-
-    database: DatabaseHealth | None = None
-    disk: DiskHealth | None = None
-
-
-class HealthResponse(BaseModel):
-    """Overall health check response."""
-
-    status: str = Field(description="Overall health status", examples=["healthy"])
-    timestamp: str = Field(
-        description="ISO 8601 timestamp", examples=["2026-05-19T12:00:00Z"]
-    )
-    version: str = Field(description="API version", examples=["0.1.0"])
-    checks: HealthChecks = Field(description="Individual health checks")
-    uptime_seconds: float = Field(
-        description="Server uptime in seconds", examples=[3600.0]
-    )
-
-
-class DatabaseHealthResponse(BaseModel):
-    """Database-specific health check response."""
-
-    status: str = Field(description="Database health status", examples=["healthy"])
-    response_time_ms: float = Field(
-        description="Query response time in milliseconds", examples=[5.2]
-    )

apps/api/src/schemas/project.py

@@ -1,25 +0,0 @@
-"""Project request/response schemas."""
-
-from pydantic import BaseModel
-
-
-class ProjectCreate(BaseModel):
-    name: str
-    description: str | None = None
-
-
-class ProjectUpdate(BaseModel):
-    name: str | None = None
-    description: str | None = None
-
-
-class ProjectResponse(BaseModel):
-    id: str
-    name: str
-    description: str | None
-    created_at: str
-    updated_at: str
-
-
-class SetDefaultSSHKeyRequest(BaseModel):
-    ssh_key_id: str

apps/api/src/schemas/ssh_key.py

@@ -1,16 +0,0 @@
-"""SSH key request/response schemas."""
-
-from pydantic import BaseModel
-
-
-class SSHKeyCreate(BaseModel):
-    name: str
-    public_key: str
-
-
-class SSHKeyResponse(BaseModel):
-    id: str
-    name: str
-    public_key: str
-    fingerprint: str
-    created_at: str

apps/api/src/schemas/tool_config.py

@@ -1,47 +0,0 @@
-"""Tool config request/response schemas."""
-
-from pydantic import BaseModel, Field
-
-
-class ToolConfigCreate(BaseModel):
-    tool_type_id: str = Field(description="UUID of the tool type")
-    key: str = Field(description="Configuration key")
-    value: str = Field(description="Configuration value")
-    config_type: str = Field(default="env", description="Config type: env or file")
-    file_path: str | None = Field(default=None, description="File path for file configs")
-    port_override: int | None = Field(default=None, description="Port override")
-    start_command: str | None = Field(default=None, description="Start command override")
-    working_directory: str | None = Field(default=None, description="Working directory")
-    environment_variables: dict[str, str] | None = Field(
-        default=None, description="Additional environment variables"
-    )
-    volumes: list[dict] | None = Field(default=None, description="Volume mounts")
-
-
-class ToolConfigUpdate(BaseModel):
-    value: str | None = None
-    config_type: str | None = None
-    file_path: str | None = None
-    port_override: int | None = None
-    start_command: str | None = None
-    working_directory: str | None = None
-    environment_variables: dict[str, str] | None = None
-    volumes: list[dict] | None = None
-
-
-class ToolConfigResponse(BaseModel):
-    id: str
-    tool_type_id: str
-    user_id: str
-    project_id: str | None
-    key: str
-    value: str
-    config_type: str
-    file_path: str | None
-    port_override: int | None
-    start_command: str | None
-    working_directory: str | None
-    environment_variables: dict[str, str] | None
-    volumes: list[dict] | None
-    created_at: str
-    updated_at: str

apps/api/src/schemas/tool_instance.py

@@ -1,41 +0,0 @@
-"""Tool instance request/response schemas."""
-
-from pydantic import BaseModel, Field
-
-
-class CreateInstanceRequest(BaseModel):
-    """Request body for creating a tool instance."""
-
-    model_config = {"extra": "ignore"}
-
-    tool_type_id: str = Field(description="UUID of the tool type to instantiate")
-    display_name: str | None = Field(
-        default=None, description="Optional display name for the instance"
-    )
-    config_profile_id: str | None = Field(
-        default=None, description="Optional config profile ID to apply to the instance"
-    )
-
-
-class SessionItemResponse(BaseModel):
-    """Lightweight session summary for sidebar and dashboard."""
-
-    model_config = {"extra": "ignore"}
-
-    id: str = Field(description="Session (tool instance) ID")
-    display_name: str = Field(description="Display name of the session")
-    tool_type_name: str = Field(description="Name of the tool type")
-    tool_icon: str | None = Field(default=None, description="Icon URL for the tool type")
-    tool_type_interfaces: list[str] = Field(default_factory=list, description="Supported interfaces")
-    repository_name: str = Field(description="Name of the repository")
-    repository_id: str = Field(description="Repository ID")
-    project_name: str = Field(description="Name of the project")
-    project_id: str = Field(description="Project ID")
-    status: str = Field(description="Current status")
-    url: str | None = Field(default=None, description="Access URL")
-
-
-class SessionListResponse(BaseModel):
-    """Response wrapping a list of session summaries."""
-
-    sessions: list[SessionItemResponse]

apps/api/src/schemas/tool_type.py

@@ -1,204 +0,0 @@
-"""Tool type request/response schemas."""
-
-import uuid
-from datetime import datetime
-
-import yaml
-from pydantic import BaseModel, ConfigDict, field_validator, model_validator
-
-
-class ToolTypeCreate(BaseModel):
-    name: str
-    display_name: str
-    description: str | None = None
-    default_port: int
-    definition_type: str = "compose"
-    compose_template: str | None = None
-    dockerfile_template: str | None = None
-    build_context: dict | None = None
-    readiness_probe: dict | None = None
-    required_variables: list[str] = []
-    category: str = "other"
-    interfaces: list[str] = ["web"]
-
-    @field_validator("definition_type")
-    @classmethod
-    def validate_definition_type(cls, v: str) -> str:
-        if v not in ("compose", "dockerfile"):
-            raise ValueError("definition_type must be 'compose' or 'dockerfile'")
-        return v
-
-    @field_validator("compose_template")
-    @classmethod
-    def validate_compose_template(cls, v: str | None, info) -> str | None:
-        data = info.data
-        if data.get("definition_type") != "compose":
-            return v
-        if v is None:
-            raise ValueError("compose_template is required when definition_type is 'compose'")
-        try:
-            parsed = yaml.safe_load(v)
-        except yaml.YAMLError as e:
-            raise ValueError(f"Invalid YAML: {e}")
-        if not isinstance(parsed, dict):
-            raise ValueError("Compose template must be a YAML mapping")
-        if "services" not in parsed:
-            raise ValueError("Compose template must contain 'services' key")
-        if not parsed["services"]:
-            raise ValueError("Compose template must define at least one service")
-        return v
-
-    @field_validator("dockerfile_template")
-    @classmethod
-    def validate_dockerfile_template(cls, v: str | None, info) -> str | None:
-        data = info.data
-        if data.get("definition_type") != "dockerfile":
-            return v
-        if v is None:
-            raise ValueError("dockerfile_template is required when definition_type is 'dockerfile'")
-        if not v.strip().startswith("FROM"):
-            raise ValueError("Dockerfile must start with a FROM instruction")
-        return v
-
-    @field_validator("default_port")
-    @classmethod
-    def validate_default_port(cls, v: int, info) -> int:
-        if v <= 0 or v > 65535:
-            raise ValueError("Port must be between 1 and 65535")
-        data = info.data
-        if data.get("definition_type") != "compose":
-            return v
-        template = data.get("compose_template")
-        if not template:
-            return v
-        try:
-            parsed = yaml.safe_load(template)
-        except yaml.YAMLError:
-            return v
-        port_str = str(v)
-        port_exposed = False
-        if isinstance(parsed, dict) and "services" in parsed:
-            for service_config in parsed["services"].values():
-                if isinstance(service_config, dict) and "ports" in service_config:
-                    for port_mapping in service_config["ports"]:
-                        if isinstance(port_mapping, str) and port_str in port_mapping:
-                            port_exposed = True
-                            break
-                        elif isinstance(port_mapping, int) and port_mapping == v:
-                            port_exposed = True
-                            break
-                if port_exposed:
-                    break
-        if not port_exposed:
-            raise ValueError(f"Port {v} is not exposed in the compose template. Add it to the 'ports' section.")
-        return v
-
-    @field_validator("required_variables")
-    @classmethod
-    def validate_required_variables(cls, v: list[str], info) -> list[str]:
-        if not v:
-            return v
-        data = info.data
-        if data.get("definition_type") != "compose":
-            return v
-        template = data.get("compose_template")
-        if not template:
-            return v
-        for var in v:
-            placeholder = f"{{{{{var}}}}}"
-            if placeholder not in template:
-                raise ValueError(f"Required variable '{var}' not found in compose template")
-        return v
-
-    @model_validator(mode="after")
-    def validate_templates(self) -> "ToolTypeCreate":
-        if self.definition_type == "dockerfile" and self.dockerfile_template is None:
-            raise ValueError("dockerfile_template is required when definition_type is 'dockerfile'")
-        if self.definition_type == "compose" and self.compose_template is None:
-            raise ValueError("compose_template is required when definition_type is 'compose'")
-        return self
-
-
-class ToolTypeUpdate(BaseModel):
-    display_name: str | None = None
-    description: str | None = None
-    default_port: int | None = None
-    definition_type: str | None = None
-    compose_template: str | None = None
-    dockerfile_template: str | None = None
-    build_context: dict | None = None
-    readiness_probe: dict | None = None
-    required_variables: list[str] | None = None
-    category: str | None = None
-    interfaces: list[str] | None = None
-
-    @field_validator("definition_type")
-    @classmethod
-    def validate_definition_type(cls, v: str | None) -> str | None:
-        if v is None:
-            return v
-        if v not in ("compose", "dockerfile"):
-            raise ValueError("definition_type must be 'compose' or 'dockerfile'")
-        return v
-
-    @field_validator("compose_template")
-    @classmethod
-    def validate_compose_template(cls, v: str | None, info) -> str | None:
-        if v is None:
-            return v
-        data = info.data
-        definition_type = data.get("definition_type")
-        if definition_type and definition_type != "compose":
-            return v
-        try:
-            parsed = yaml.safe_load(v)
-        except yaml.YAMLError as e:
-            raise ValueError(f"Invalid YAML: {e}")
-        if not isinstance(parsed, dict):
-            raise ValueError("Compose template must be a YAML mapping")
-        if "services" not in parsed:
-            raise ValueError("Compose template must contain 'services' key")
-        if not parsed["services"]:
-            raise ValueError("Compose template must define at least one service")
-        return v
-
-    @field_validator("dockerfile_template")
-    @classmethod
-    def validate_dockerfile_template(cls, v: str | None, info) -> str | None:
-        if v is None:
-            return v
-        data = info.data
-        definition_type = data.get("definition_type")
-        if definition_type and definition_type != "dockerfile":
-            return v
-        if not v.strip().startswith("FROM"):
-            raise ValueError("Dockerfile must start with a FROM instruction")
-        return v
-
-
-class ToolTypeResponse(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-
-    id: uuid.UUID
-    name: str
-    display_name: str
-    description: str | None
-    category: str
-    interfaces: list[str]
-    default_port: int
-    definition_type: str
-    compose_template: str | None
-    dockerfile_template: str | None
-    build_context: dict | None
-    readiness_probe: dict | None
-    required_variables: list[str]
-    is_builtin: bool
-    created_by_id: uuid.UUID | None
-    created_at: datetime
-    updated_at: datetime
-
-
-class ToolTypeValidateRequest(BaseModel):
-    definition_type: str
-    compose_template: str | None = None
-    dockerfile_template: str | None = None

apps/api/src/schemas/user.py

@@ -1,19 +0,0 @@
-"""User request/response schemas."""
-
-import uuid
-
-from pydantic import BaseModel, ConfigDict
-
-
-class UserProfileResponse(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-
-    id: uuid.UUID
-    email: str
-    name: str
-    avatar_url: str | None
-
-
-class UserProfileUpdate(BaseModel):
-    name: str | None = None
-    email: str | None = None

apps/api/src/schemas/user_config.py

@@ -1,21 +0,0 @@
-"""User config request/response schemas."""
-
-from pydantic import BaseModel, ConfigDict
-
-
-class UserConfigResponse(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-
-    default_editor: str | None = None
-    theme: str = "system"
-    git_user_name: str | None = None
-    git_user_email: str | None = None
-    last_session_id: str | None = None
-
-
-class UserConfigUpdate(BaseModel):
-    default_editor: str | None = None
-    theme: str | None = None
-    git_user_name: str | None = None
-    git_user_email: str | None = None
-    last_session_id: str | None = None

apps/api/src/seeds/builtin_tool_types.py

@@ -1,161 +0,0 @@
-import logging
-
-from sqlalchemy import select
-
-from src.database import SessionLocal
-from src.models.tool_type import ToolType
-
-logger = logging.getLogger(__name__)
-
-
-async def _table_exists(session, table_name: str) -> bool:
-    """Check if a table exists in the database."""
-    from sqlalchemy import text
-
-    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():
-    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 = [
-            {
-                "name": "code-server",
-                "display_name": "VS Code Server",
-                "description": "VS Code running in the browser via code-server",
-                "category": "editor",
-                "interfaces": ["web"],
-                "compose_template": """version: "3.8"
-services:
-  code-server:
-    image: lscr.io/linuxserver/code-server:latest
-    container_name: {{TOOL_NAME}}
-    environment:
-      - PUID=1000
-      - PGID=1000
-      - TZ=Europe/London
-    volumes:
-      - {{REPO_PATH}}:/config/workspace
-    ports:
-      - "8443:8443"
-    restart: unless-stopped""",
-                "default_port": 8443,
-                "required_variables": ["REPO_PATH", "TOOL_NAME"],
-            },
-            {
-                "name": "jupyter-notebook",
-                "display_name": "Jupyter Notebook",
-                "description": "Jupyter Lab for interactive development",
-                "category": "notebook",
-                "interfaces": ["web"],
-                "default_port": 8888,
-                "compose_template": """version: "3.8"
-services:
-  jupyter:
-    image: jupyter/scipy-notebook:latest
-    container_name: {{TOOL_NAME}}
-    environment:
-      - JUPYTER_ENABLE_LAB=yes
-    volumes:
-      - {{REPO_PATH}}:/home/jovyan/work
-    ports:
-      - "8888:8888"
-    restart: unless-stopped""",
-                "required_variables": ["REPO_PATH", "TOOL_NAME"],
-            },
-            {
-                "name": "opencode",
-                "display_name": "OpenCode",
-                "description": "AI coding assistant - run opencode in terminal",
-                "category": "ai-assistant",
-                "interfaces": ["terminal"],
-                "default_port": 3000,
-                "compose_template": """version: "3.8"
-services:
-  opencode:
-    image: node:20-slim
-    container_name: {{TOOL_NAME}}
-    working_dir: /workspace
-    environment:
-      - HOME=/tmp
-    volumes:
-      - {{REPO_PATH}}:/workspace
-      - opencode_home:/tmp
-    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 /workspace' >> /root/.bashrc &&
-             echo 'OpenCode installation complete' &&
-             cd /workspace &&
-             exec tail -f /dev/null"
-    stdin_open: true
-    tty: true
-    restart: unless-stopped
-
-volumes:
-  opencode_home:""",
-                "required_variables": ["REPO_PATH", "TOOL_NAME"],
-            },
-        ]
-
-        for tool_data in builtin_types:
-            existing = await session.scalar(select(ToolType).where(ToolType.name == tool_data["name"]))
-            if not existing:
-                tool_type = ToolType(
-                    name=tool_data["name"],
-                    display_name=tool_data["display_name"],
-                    description=tool_data["description"],
-                    category=tool_data["category"],
-                    interfaces=tool_data["interfaces"],
-                    definition_type="compose",
-                    compose_template=tool_data["compose_template"],
-                    required_variables=tool_data["required_variables"],
-                    default_port=tool_data.get("default_port"),
-                    is_builtin=True,
-                )
-                session.add(tool_type)
-                logger.info("Created built-in tool type: %s", tool_data["name"])
-            else:
-                # Update existing built-in tool types to reflect code changes
-                existing.display_name = tool_data["display_name"]
-                existing.description = tool_data["description"]
-                existing.category = tool_data["category"]
-                existing.interfaces = tool_data["interfaces"]
-                existing.definition_type = "compose"
-                existing.compose_template = tool_data["compose_template"]
-                existing.required_variables = tool_data["required_variables"]
-                existing.default_port = tool_data.get("default_port")
-                logger.info("Updated built-in tool type: %s", tool_data["name"])
-
-        await session.commit()
-        logger.info("Built-in tool types seeded successfully.")

apps/api/src/services/clone.py

@@ -0,0 +1,97 @@
+"""Clone service for repository cloning and dirty state checking."""
+
+import logging
+import os
+import subprocess
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def clone_repository(
+    remote_url: str,
+    ssh_key_path: str | None,
+    instance_dir: str,
+    branch: str = "main",
+) -> str:
+    """Clone a git repository into the instance directory.
+
+    Args:
+        remote_url: Git remote URL (SSH or HTTPS)
+        ssh_key_path: Path to SSH private key for authentication (optional)
+        instance_dir: Path to instance directory
+        branch: Branch to clone (default: main)
+
+    Returns:
+        Path to the cloned repository
+    """
+    clone_path = Path(instance_dir) / "repo-clone"
+    clone_path.mkdir(parents=True, exist_ok=True)
+
+    env = os.environ.copy()
+    if ssh_key_path:
+        # Use SSH key for cloning
+        env["GIT_SSH_COMMAND"] = f"ssh -i {ssh_key_path} -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null"
+
+    cmd = [
+        "git",
+        "clone",
+        "--branch", branch,
+        "--single-branch",
+        remote_url,
+        str(clone_path),
+    ]
+
+    logger.info("Cloning repository %s (branch: %s) into %s", remote_url, branch, clone_path)
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        env=env,
+        timeout=300,
+    )
+
+    if result.returncode != 0:
+        logger.error("Git clone failed: %s", result.stderr)
+        raise RuntimeError(f"Failed to clone repository: {result.stderr}")
+
+    logger.info("Successfully cloned repository into %s", clone_path)
+    return str(clone_path)
+
+
+def check_dirty_state(clone_path: str) -> tuple[bool, list[str]]:
+    """Check for uncommitted changes in a cloned repository.
+
+    Args:
+        clone_path: Path to the cloned repository
+
+    Returns:
+        Tuple of (is_dirty, list_of_changed_files)
+    """
+    result = subprocess.run(
+        ["git", "-C", clone_path, "status", "--short"],
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        logger.warning("Failed to check git status: %s", result.stderr)
+        return False, []
+
+    changed_files = [line.strip() for line in result.stdout.split("\n") if line.strip()]
+    is_dirty = len(changed_files) > 0
+
+    return is_dirty, changed_files
+
+
+def remove_clone_directory(instance_dir: str) -> None:
+    """Remove the cloned repository from the instance directory.
+
+    Args:
+        instance_dir: Path to instance directory
+    """
+    clone_path = Path(instance_dir) / "repo-clone"
+    if clone_path.exists():
+        import shutil
+        shutil.rmtree(clone_path)
+        logger.info("Removed clone directory: %s", clone_path)

apps/api/src/services/config_profile_resolver.py

@@ -0,0 +1,453 @@
+"""Config profile resolver service.
+
+Provides recursive ordered include resolution with deterministic merge rules
+and cycle protection.
+"""
+
+import logging
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.models.config_profile import ConfigProfile, ConfigProfileInclude
+
+logger = logging.getLogger(__name__)
+
+
+class ConfigProfileCycleError(Exception):
+    """Raised when a cycle is detected in profile includes."""
+
+    pass
+
+
+class ConfigProfileNotFoundError(Exception):
+    """Raised when a referenced profile is not found."""
+
+    pass
+
+
+@dataclass
+class ResolvedMount:
+    """A resolved mount with merged files and final mode."""
+
+    target: str
+    mode: str
+    files: dict[str, str] = field(default_factory=dict)
+    overridden_files: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class ResolvedProfile:
+    """The fully resolved output of a config profile."""
+
+    profile_id: uuid.UUID
+    profile_name: str
+    env_vars: dict[str, str] = field(default_factory=dict)
+    runtime_hints: dict[str, Any] = field(default_factory=dict)
+    mounts: dict[str, ResolvedMount] = field(default_factory=dict)
+    files: dict[str, str] = field(default_factory=dict)
+    env_overrides: dict[str, str] = field(default_factory=dict)
+    hint_overrides: dict[str, str] = field(default_factory=dict)
+    file_overrides: dict[str, str] = field(default_factory=dict)
+    mount_overrides: dict[str, str] = field(default_factory=dict)
+    included_profiles: list[dict[str, Any]] = field(default_factory=list)
+
+
+def _detect_cycle(profile_id: uuid.UUID, visited: set[uuid.UUID], path: list[uuid.UUID]) -> bool:
+    """Detect if adding profile_id to path would create a cycle.
+
+    Args:
+        profile_id: The profile ID to check.
+        visited: Set of already-visited profile IDs in current resolution.
+        path: Current resolution path for error reporting.
+
+    Returns:
+        True if a cycle would be created.
+    """
+    if profile_id in visited:
+        return True
+    return False
+
+
+def _merge_env_vars(
+    base: dict[str, str],
+    overlay: dict[str, str],
+    overrides: dict[str, str],
+    source_name: str,
+) -> dict[str, str]:
+    """Merge env vars, tracking overrides.
+
+    Later values replace earlier values.
+    """
+    result = dict(base)
+    for key, value in overlay.items():
+        if key in result and result[key] != value:
+            overrides[key] = source_name
+        result[key] = value
+    return result
+
+
+def _merge_runtime_hints(
+    base: dict[str, Any],
+    overlay: dict[str, Any],
+    overrides: dict[str, str],
+    source_name: str,
+) -> dict[str, Any]:
+    """Merge runtime hints, tracking overrides.
+
+    Later values replace earlier values.
+    """
+    result = dict(base)
+    for key, value in overlay.items():
+        if key in result and result[key] != value:
+            overrides[key] = source_name
+        result[key] = value
+    return result
+
+
+def _merge_files(
+    base: dict[str, str],
+    overlay: dict[str, str],
+    overrides: dict[str, str],
+    source_name: str,
+) -> dict[str, str]:
+    """Merge file maps, tracking overrides.
+
+    Later relative file paths win.
+    """
+    result = dict(base)
+    for path, content in overlay.items():
+        if path in result and result[path] != content:
+            overrides[path] = source_name
+        result[path] = content
+    return result
+
+
+def _merge_mounts(
+    base: dict[str, ResolvedMount],
+    overlay: list[dict[str, Any]],
+    overrides: dict[str, str],
+    source_name: str,
+) -> dict[str, ResolvedMount]:
+    """Merge mounts, tracking overrides.
+
+    Mounts with the same target path have their file maps merged and later
+    relative file paths win. Mode conflicts: later layer wins.
+    """
+    result = dict(base)
+    for mount_data in overlay:
+        target = mount_data["target"]
+        mode = mount_data.get("mode", "rw")
+        files = mount_data.get("files", {})
+
+        if target in result:
+            existing = result[target]
+            merged_files = dict(existing.files)
+            file_overrides = dict(existing.overridden_files)
+            for rel_path, content in files.items():
+                if rel_path in merged_files and merged_files[rel_path] != content:
+                    file_overrides[rel_path] = source_name
+                merged_files[rel_path] = content
+            if existing.mode != mode:
+                overrides[target] = source_name
+            result[target] = ResolvedMount(
+                target=target,
+                mode=mode,
+                files=merged_files,
+                overridden_files=file_overrides,
+            )
+        else:
+            result[target] = ResolvedMount(
+                target=target,
+                mode=mode,
+                files=dict(files),
+            )
+    return result
+
+
+async def _resolve_profile_recursive(
+    session: AsyncSession,
+    profile_id: uuid.UUID,
+    visited: set[uuid.UUID],
+    path: list[uuid.UUID],
+) -> ResolvedProfile:
+    """Recursively resolve a profile and its includes.
+
+    Args:
+        session: Database session.
+        profile_id: Profile ID to resolve.
+        visited: Set of already-visited profile IDs in current resolution chain.
+        path: Current resolution path for error reporting.
+
+    Returns:
+        ResolvedProfile with all includes merged.
+
+    Raises:
+        ConfigProfileCycleError: If a cycle is detected.
+        ConfigProfileNotFoundError: If the profile is not found.
+    """
+    if _detect_cycle(profile_id, visited, path):
+        cycle_path = " -> ".join(str(p) for p in path + [profile_id])
+        raise ConfigProfileCycleError(f"Cycle detected in profile includes: {cycle_path}")
+
+    profile = await session.get(ConfigProfile, profile_id)
+    if profile is None:
+        raise ConfigProfileNotFoundError(f"Config profile not found: {profile_id}")
+
+    new_visited = visited | {profile_id}
+    new_path = path + [profile_id]
+
+    result = ResolvedProfile(
+        profile_id=profile.id,
+        profile_name=profile.name,
+    )
+
+    # Resolve includes in order
+    include_query = (
+        select(ConfigProfileInclude)
+        .where(ConfigProfileInclude.profile_id == profile_id)
+        .order_by(ConfigProfileInclude.order_index)
+    )
+    include_result = await session.execute(include_query)
+    includes = include_result.scalars().all()
+
+    for include in includes:
+        included = await _resolve_profile_recursive(
+            session, include.included_profile_id, new_visited, new_path
+        )
+        result.included_profiles.append({
+            "id": str(included.profile_id),
+            "name": included.profile_name,
+        })
+
+        result.env_vars = _merge_env_vars(
+            result.env_vars, included.env_vars, result.env_overrides, included.profile_name
+        )
+        result.runtime_hints = _merge_runtime_hints(
+            result.runtime_hints,
+            included.runtime_hints,
+            result.hint_overrides,
+            included.profile_name,
+        )
+        result.files = _merge_files(
+            result.files, included.files, result.file_overrides, included.profile_name
+        )
+        result.mounts = _merge_mounts(
+            result.mounts,
+            [
+                {"target": m.target, "mode": m.mode, "files": m.files}
+                for m in included.mounts.values()
+            ],
+            result.mount_overrides,
+            included.profile_name,
+        )
+
+    # Apply the profile's own settings (selected profile overrides includes)
+    result.env_vars = _merge_env_vars(
+        result.env_vars,
+        profile.env_vars or {},
+        result.env_overrides,
+        profile.name,
+    )
+    result.runtime_hints = _merge_runtime_hints(
+        result.runtime_hints,
+        profile.runtime_hints or {},
+        result.hint_overrides,
+        profile.name,
+    )
+    result.files = _merge_files(
+        result.files,
+        profile.files or {},
+        result.file_overrides,
+        profile.name,
+    )
+    result.mounts = _merge_mounts(
+        result.mounts,
+        profile.mounts or [],
+        result.mount_overrides,
+        profile.name,
+    )
+
+    return result
+
+
+async def resolve_profile(
+    session: AsyncSession,
+    profile_id: uuid.UUID,
+) -> ResolvedProfile:
+    """Resolve a config profile with all includes.
+
+    Args:
+        session: Database session.
+        profile_id: Profile ID to resolve.
+
+    Returns:
+        ResolvedProfile with merged env vars, runtime hints, mounts, and files.
+
+    Raises:
+        ConfigProfileCycleError: If a cycle is detected in includes.
+        ConfigProfileNotFoundError: If the profile is not found.
+    """
+    return await _resolve_profile_recursive(session, profile_id, set(), [])
+
+
+async def check_include_cycle(
+    session: AsyncSession,
+    profile_id: uuid.UUID,
+    new_include_id: uuid.UUID | None = None,
+) -> list[uuid.UUID] | None:
+    """Check if adding an include would create a cycle.
+
+    Used at save time to validate include relationships before persisting.
+
+    Args:
+        session: Database session.
+        profile_id: The profile that would receive the new include.
+        new_include_id: Optional new profile to include. If None, checks existing includes.
+
+    Returns:
+        The cycle path as a list of UUIDs if a cycle exists, otherwise None.
+    """
+
+    async def _check_from(
+        current_id: uuid.UUID,
+        target_id: uuid.UUID,
+        visited: set[uuid.UUID],
+        path: list[uuid.UUID],
+    ) -> list[uuid.UUID] | None:
+        if current_id in visited:
+            if current_id == target_id:
+                return path + [current_id]
+            return None
+        if current_id == target_id and path:
+            return path + [current_id]
+
+        new_visited = visited | {current_id}
+        new_path = path + [current_id]
+
+        include_query = (
+            select(ConfigProfileInclude)
+            .where(ConfigProfileInclude.profile_id == current_id)
+            .order_by(ConfigProfileInclude.order_index)
+        )
+        include_result = await session.execute(include_query)
+        includes = include_result.scalars().all()
+
+        for include in includes:
+            cycle = await _check_from(
+                include.included_profile_id, target_id, new_visited, new_path
+            )
+            if cycle is not None:
+                return cycle
+        return None
+
+    # Check if new_include_id can reach profile_id (would create cycle)
+    if new_include_id is not None:
+        cycle = await _check_from(new_include_id, profile_id, set(), [])
+        if cycle is not None:
+            return cycle
+
+    # Also check existing includes for cycles
+    cycle = await _check_from(profile_id, profile_id, set(), [])
+    if cycle is not None and len(cycle) > 1:
+        return cycle
+
+    return None
+
+
+def apply_resolved_profile(
+    instance_dir: str,
+    resolved: ResolvedProfile,
+) -> tuple[dict[str, str], dict[str, str], list[dict], dict[str, Any]]:
+    """Apply a resolved profile to an instance directory.
+
+    Stages files, writes env vars, and prepares mount volumes.
+
+    Args:
+        instance_dir: Path to the instance directory.
+        resolved: The resolved profile.
+
+    Returns:
+        Tuple of (env_vars, files, volume_mounts, runtime_hints).
+        env_vars: Merged environment variables.
+        files: Relative file paths to content for the instance.
+        volume_mounts: List of Docker volume mount dicts.
+        runtime_hints: Extracted runtime hints.
+    """
+    from pathlib import Path
+
+    instance_path = Path(instance_dir)
+    env_vars = dict(resolved.env_vars)
+    files = dict(resolved.files)
+    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)
+
+    # Stage mount files and prepare volume mounts
+    for mount in resolved.mounts.values():
+        mount_dir = instance_path / "mounts" / mount.target.lstrip("/").replace("/", "_")
+        mount_dir.mkdir(parents=True, exist_ok=True)
+
+        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)
+
+        volume_mounts.append({
+            "source": str(mount_dir),
+            "target": mount.target,
+            "type": "bind",
+        })
+
+    return env_vars, files, volume_mounts, resolved.runtime_hints
+
+
+def resolved_profile_to_dict(resolved: ResolvedProfile) -> dict[str, Any]:
+    """Convert a ResolvedProfile to a plain dict for serialization.
+
+    Args:
+        resolved: The resolved profile.
+
+    Returns:
+        Dict with env_vars, runtime_hints, mounts, files, and metadata.
+    """
+    return {
+        "profile_id": str(resolved.profile_id),
+        "profile_name": resolved.profile_name,
+        "env_vars": resolved.env_vars,
+        "runtime_hints": resolved.runtime_hints,
+        "mounts": [
+            {
+                "target": m.target,
+                "mode": m.mode,
+                "files": m.files,
+                "overridden_files": m.overridden_files,
+            }
+            for m in resolved.mounts.values()
+        ],
+        "files": resolved.files,
+        "overrides": {
+            "env_vars": resolved.env_overrides,
+            "runtime_hints": resolved.hint_overrides,
+            "files": resolved.file_overrides,
+            "mounts": resolved.mount_overrides,
+        },
+        "included_profiles": resolved.included_profiles,
+    }

apps/api/src/services/config_profiles.py

@@ -1,299 +0,0 @@
-"""Config profile business logic."""
-
-import logging
-import uuid
-
-from fastapi import HTTPException, status
-from sqlalchemy import select
-from sqlalchemy.ext.asyncio import AsyncSession
-from sqlalchemy.orm import selectinload
-
-from src.models.config_include import ConfigInclude
-from src.models.config_mount import ConfigMount
-from src.models.config_profile import ConfigProfile
-from src.models.tool_type import ToolType
-from src.models.user_config import UserConfig
-
-logger = logging.getLogger(__name__)
-
-MAX_INCLUDES_DEPTH = 10
-
-
-async def get_owned_profile(
-    profile_id: uuid.UUID,
-    user_id: uuid.UUID,
-    session: AsyncSession,
-) -> ConfigProfile:
-    """Fetch a config profile and verify ownership."""
-    profile = await session.get(ConfigProfile, profile_id)
-    if profile is None or profile.user_id != user_id:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail="config profile not found",
-        )
-    return profile
-
-
-async def _detect_cycle(
-    session: AsyncSession,
-    profile_id: uuid.UUID,
-    visited: set[uuid.UUID] | None = None,
-    depth: int = 0,
-) -> bool:
-    """Detect cycles in profile includes using DFS.
-
-    Returns True if a cycle is detected.
-    """
-    if depth > MAX_INCLUDES_DEPTH:
-        return True
-
-    if visited is None:
-        visited = set()
-
-    if profile_id in visited:
-        return True
-
-    visited.add(profile_id)
-
-    result = await session.execute(
-        select(ConfigInclude.included_profile_id).where(
-            ConfigInclude.profile_id == profile_id
-        )
-    )
-    included_ids = result.scalars().all()
-
-    for included_id in included_ids:
-        if await _detect_cycle(session, included_id, visited.copy(), depth + 1):
-            return True
-
-    return False
-
-
-async def validate_includes_no_cycle(
-    session: AsyncSession,
-    profile_id: uuid.UUID,
-    new_included_id: uuid.UUID | None = None,
-) -> None:
-    """Validate that adding an include wouldn't create a cycle."""
-    if new_included_id and await _detect_cycle(session, new_included_id, {profile_id}):
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="adding this include would create a circular reference",
-        )
-
-
-# ---------------------------------------------------------------------------
-# Profile CRUD helpers
-# ---------------------------------------------------------------------------
-
-async def check_duplicate_name(
-    session: AsyncSession,
-    user_id: uuid.UUID,
-    name: str,
-    exclude_id: uuid.UUID | None = None,
-) -> None:
-    """Raise 409 if a profile with the given name already exists."""
-    query = select(ConfigProfile).where(
-        ConfigProfile.user_id == user_id,
-        ConfigProfile.name == name,
-    )
-    if exclude_id:
-        query = query.where(ConfigProfile.id != exclude_id)
-    existing = await session.scalar(query)
-    if existing:
-        raise HTTPException(
-            status_code=status.HTTP_409_CONFLICT,
-            detail=f"config profile with name '{name}' already exists",
-        )
-
-
-def profile_to_dict(profile: ConfigProfile) -> dict:
-    """Serialize a ConfigProfile to a dict."""
-    return {
-        "id": str(profile.id),
-        "user_id": str(profile.user_id),
-        "name": profile.name,
-        "description": profile.description,
-        "created_at": profile.created_at.isoformat() if profile.created_at else None,
-        "updated_at": profile.updated_at.isoformat() if profile.updated_at else None,
-    }
-
-
-# ---------------------------------------------------------------------------
-# Include helpers
-# ---------------------------------------------------------------------------
-
-async def check_duplicate_include(
-    session: AsyncSession,
-    profile_id: uuid.UUID,
-    included_profile_id: uuid.UUID,
-) -> None:
-    """Raise 409 if the include already exists."""
-    existing = await session.scalar(
-        select(ConfigInclude).where(
-            ConfigInclude.profile_id == profile_id,
-            ConfigInclude.included_profile_id == included_profile_id,
-        )
-    )
-    if existing:
-        raise HTTPException(
-            status_code=status.HTTP_409_CONFLICT,
-            detail="this include already exists",
-        )
-
-
-def include_to_dict(inc: ConfigInclude, included_name: str | None) -> dict:
-    """Serialize a ConfigInclude to a dict."""
-    return {
-        "id": str(inc.id),
-        "profile_id": str(inc.profile_id),
-        "included_profile_id": str(inc.included_profile_id),
-        "included_profile_name": included_name,
-        "order_index": inc.order_index,
-        "created_at": inc.created_at.isoformat() if inc.created_at else None,
-        "updated_at": inc.updated_at.isoformat() if inc.updated_at else None,
-    }
-
-
-# ---------------------------------------------------------------------------
-# Mount helpers
-# ---------------------------------------------------------------------------
-
-async def check_duplicate_mount_path(
-    session: AsyncSession,
-    profile_id: uuid.UUID,
-    target_path: str,
-    exclude_id: uuid.UUID | None = None,
-) -> None:
-    """Raise 409 if a mount with the given path already exists."""
-    query = select(ConfigMount).where(
-        ConfigMount.profile_id == profile_id,
-        ConfigMount.target_path == target_path,
-    )
-    if exclude_id:
-        query = query.where(ConfigMount.id != exclude_id)
-    existing = await session.scalar(query)
-    if existing:
-        raise HTTPException(
-            status_code=status.HTTP_409_CONFLICT,
-            detail=f"mount with path '{target_path}' already exists",
-        )
-
-
-def mount_to_dict(mount: ConfigMount) -> dict:
-    """Serialize a ConfigMount to a dict."""
-    return {
-        "id": str(mount.id),
-        "profile_id": str(mount.profile_id),
-        "target_path": mount.target_path,
-        "files": mount.files,
-        "mode": mount.mode,
-        "order_index": mount.order_index,
-        "created_at": mount.created_at.isoformat() if mount.created_at else None,
-        "updated_at": mount.updated_at.isoformat() if mount.updated_at else None,
-    }
-
-
-# ---------------------------------------------------------------------------
-# Default profile helpers
-# ---------------------------------------------------------------------------
-
-async def get_or_create_user_config(
-    session: AsyncSession,
-    user_id: uuid.UUID,
-) -> UserConfig:
-    """Get existing user config or create a new one."""
-    result = await session.execute(select(UserConfig).where(UserConfig.user_id == user_id))
-    user_config = result.scalar_one_or_none()
-    if user_config is None:
-        user_config = UserConfig(user_id=user_id, config={})
-        session.add(user_config)
-    return user_config
-
-
-async def validate_default_profiles(
-    session: AsyncSession,
-    user_id: uuid.UUID,
-    default_profiles: dict[str, str],
-) -> None:
-    """Validate that all profile IDs in default_profiles belong to the user."""
-    for tool_type_id, profile_id_str in default_profiles.items():
-        profile = await session.get(ConfigProfile, uuid.UUID(profile_id_str))
-        if profile is None:
-            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"profile {profile_id_str} not found")
-        if profile.user_id != user_id:
-            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=f"profile {profile_id_str} does not belong to user")
-
-
-async def get_default_profiles(
-    session: AsyncSession,
-    user_id: uuid.UUID,
-) -> dict:
-    """Get default profiles for a user."""
-    result = await session.execute(select(UserConfig).where(UserConfig.user_id == user_id))
-    user_config = result.scalar_one_or_none()
-    return {"default_profiles": user_config.default_profiles if user_config else {}}
-
-
-async def set_default_profiles(
-    session: AsyncSession,
-    user_id: uuid.UUID,
-    default_profiles: dict[str, str],
-) -> dict:
-    """Set default profiles for a user."""
-    user_config = await get_or_create_user_config(session, user_id)
-    await validate_default_profiles(session, user_id, default_profiles)
-    user_config.config = {**user_config.config, "default_profiles": default_profiles}
-    await session.commit()
-    await session.refresh(user_config)
-    return {"default_profiles": user_config.default_profiles}
-
-
-async def get_default_profile_for_tool_type(
-    session: AsyncSession,
-    user_id: uuid.UUID,
-    tool_type_id: str,
-) -> dict:
-    """Get default profile for a specific tool type."""
-    result = await session.execute(select(UserConfig).where(UserConfig.user_id == user_id))
-    user_config = result.scalar_one_or_none()
-    profile_id = user_config.default_profiles.get(tool_type_id) if user_config else None
-    return {"tool_type_id": tool_type_id, "profile_id": profile_id}
-
-
-# ---------------------------------------------------------------------------
-# Include list helper
-# ---------------------------------------------------------------------------
-
-async def list_includes_for_profile(
-    session: AsyncSession,
-    profile_id: uuid.UUID,
-) -> dict:
-    """List all includes for a profile."""
-    result = await session.execute(
-        select(ConfigInclude)
-        .where(ConfigInclude.profile_id == profile_id)
-        .order_by(ConfigInclude.order_index)
-    )
-    includes_data = []
-    for inc in result.scalars().all():
-        included_profile = await session.get(ConfigProfile, inc.included_profile_id)
-        includes_data.append(include_to_dict(inc, included_profile.name if included_profile else None))
-    return {"includes": includes_data}
-
-
-# ---------------------------------------------------------------------------
-# Mount list helper
-# ---------------------------------------------------------------------------
-
-async def list_mounts_for_profile(
-    session: AsyncSession,
-    profile_id: uuid.UUID,
-) -> dict:
-    """List all mounts for a profile."""
-    result = await session.execute(
-        select(ConfigMount)
-        .where(ConfigMount.profile_id == profile_id)
-        .order_by(ConfigMount.order_index)
-    )
-    return {"mounts": [mount_to_dict(m) for m in result.scalars().all()]}

apps/api/src/services/docker.py

@@ -0,0 +1,510 @@
+"""Docker service for managing tool instances."""
+
+import os
+import subprocess
+from pathlib import Path
+from typing import Any
+
+
+def render_compose_template(template: str, variables: dict[str, Any]) -> str:
+    """Render a Docker Compose template with variable substitution.
+
+    Args:
+        template: The compose template string
+        variables: Dictionary of variable names to values
+
+    Returns:
+        Rendered compose file content
+    """
+    result = template
+    for key, value in variables.items():
+        placeholder = f"{{{{{key}}}}}"
+        result = result.replace(placeholder, str(value))
+    return result
+
+
+def ensure_instance_directory(instance_id: str, base_path: str | None = None) -> str:
+    """Create and return the instance directory path.
+
+    Args:
+        instance_id: Unique instance identifier
+        base_path: Base directory for all instances (defaults to Settings.instance_base_path)
+
+    Returns:
+        Absolute path to instance directory
+    """
+    if base_path is None:
+        from src.config import Settings
+        base_path = Settings().instance_base_path
+    instance_dir = Path(base_path) / instance_id
+    instance_dir.mkdir(parents=True, exist_ok=True)
+    return str(instance_dir.absolute())
+
+
+def write_compose_file(instance_dir: str, content: str) -> str:
+    """Write the rendered compose file to the instance directory.
+
+    Args:
+        instance_dir: Path to instance directory
+        content: Rendered compose content
+
+    Returns:
+        Path to the compose file
+    """
+    compose_path = Path(instance_dir) / "docker-compose.yml"
+    compose_path.write_text(content)
+    return str(compose_path)
+
+
+def write_env_file(instance_dir: str, env_vars: dict[str, str]) -> str:
+    """Write environment variables to a .env file.
+
+    Args:
+        instance_dir: Path to instance directory
+        env_vars: Dictionary of env var names to values
+
+    Returns:
+        Path to the env file
+    """
+    env_path = Path(instance_dir) / ".env"
+    lines = [f'{key}="{value}"' for key, value in env_vars.items()]
+    env_path.write_text("\n".join(lines) + "\n")
+    return str(env_path)
+
+
+def write_config_files(instance_dir: str, files: dict[str, str]) -> None:
+    """Write config files to the instance directory.
+
+    Args:
+        instance_dir: Path to instance directory
+        files: Dictionary of file paths (relative to instance dir) to content
+    """
+    instance_path = Path(instance_dir)
+    for file_path, content in files.items():
+        # Ensure the path is within the instance directory (security)
+        full_path = instance_path / file_path
+        try:
+            full_path.resolve().relative_to(instance_path.resolve())
+        except ValueError:
+            raise ValueError(f"File path '{file_path}' escapes instance directory")
+        
+        full_path.parent.mkdir(parents=True, exist_ok=True)
+        full_path.write_text(content)
+
+
+def execute_compose_command(
+    compose_path: str, action: str, timeout: int = 60, env_file: str | None = None
+) -> tuple[int, str, str]:
+    """Execute a docker compose command.
+
+    Args:
+        compose_path: Path to docker-compose.yml
+        action: The compose action (up, down, start, stop, restart)
+        timeout: Command timeout in seconds
+        env_file: Optional path to .env file for environment variables
+
+    Returns:
+        Tuple of (returncode, stdout, stderr)
+    """
+    instance_dir = Path(compose_path).parent
+
+    cmd = ["docker", "compose", "-f", compose_path]
+    
+    if env_file:
+        cmd.extend(["--env-file", env_file])
+
+    if action == "up":
+        cmd.extend(["up", "-d"])
+    elif action == "down":
+        cmd.extend(["down", "-v"])
+    elif action in ("start", "stop", "restart"):
+        cmd.append(action)
+    else:
+        raise ValueError(f"Unknown compose action: {action}")
+
+    result = subprocess.run(
+        cmd,
+        cwd=str(instance_dir),
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+    )
+
+    return result.returncode, result.stdout, result.stderr
+
+
+def get_container_id(instance_name: str) -> str | None:
+    """Get the container ID for a compose service.
+
+    Args:
+        instance_name: The service name in compose
+
+    Returns:
+        Container ID or None if not found
+    """
+    result = subprocess.run(
+        ["docker", "ps", "-q", "--filter", f"name={instance_name}"],
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode == 0 and result.stdout.strip():
+        return result.stdout.strip().split("\n")[0]
+    return None
+
+
+def get_container_name(instance_name: str) -> str | None:
+    """Get the full container name for a compose service.
+
+    Args:
+        instance_name: The service name in compose
+
+    Returns:
+        Container name or None if not found
+    """
+    result = subprocess.run(
+        ["docker", "ps", "--format", "{{.Names}}", "--filter", f"name={instance_name}"],
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode == 0 and result.stdout.strip():
+        return result.stdout.strip().split("\n")[0]
+    return None
+
+
+def connect_container_to_network(container_name: str, network_name: str = "backend") -> bool:
+    """Connect a Docker container to an existing network.
+
+    Args:
+        container_name: Name or ID of the container
+        network_name: Name of the Docker network (default: backend)
+
+    Returns:
+        True if successful, False otherwise
+    """
+    result = subprocess.run(
+        ["docker", "network", "connect", network_name, container_name],
+        capture_output=True,
+        text=True,
+    )
+    return result.returncode == 0
+
+
+def get_container_status(container_id: str) -> dict[str, Any]:
+    """Get the status of a Docker container.
+
+    Args:
+        container_id: Docker container ID
+
+    Returns:
+        Dict with 'status' (running, exited, restarting, not_found), 
+        'exit_code' (int or None), and 'health' (health status or None)
+    """
+    result = subprocess.run(
+        [
+            "docker", "inspect", "-f",
+            "{{.State.Status}}|{{.State.ExitCode}}|{{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}}",
+            container_id,
+        ],
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        return {"status": "not_found", "exit_code": None, "health": None}
+    
+    parts = result.stdout.strip().split("|")
+    status = parts[0] if parts else "unknown"
+    exit_code = int(parts[1]) if len(parts) > 1 and parts[1].isdigit() else None
+    health = parts[2] if len(parts) > 2 and parts[2] != "none" else None
+    
+    return {"status": status, "exit_code": exit_code, "health": health}
+
+
+def wait_for_container_running(
+    container_id: str, timeout: int = 30, interval: float = 2.0
+) -> dict[str, Any]:
+    """Wait for a container to reach the running state.
+
+    Polls docker inspect until the container status is "running" or timeout.
+
+    Args:
+        container_id: Docker container ID
+        timeout: Maximum seconds to wait
+        interval: Seconds between polls
+
+    Returns:
+        Dict with 'success' (bool), 'status' (str), 'exit_code' (int or None),
+        and 'waited_seconds' (float)
+    """
+    import time
+
+    start_time = time.time()
+    
+    while time.time() - start_time < timeout:
+        info = get_container_status(container_id)
+        
+        if info["status"] == "running":
+            return {
+                "success": True,
+                "status": "running",
+                "exit_code": None,
+                "waited_seconds": time.time() - start_time,
+            }
+        
+        if info["status"] == "exited":
+            return {
+                "success": False,
+                "status": "exited",
+                "exit_code": info["exit_code"],
+                "waited_seconds": time.time() - start_time,
+            }
+        
+        if info["status"] == "not_found":
+            return {
+                "success": False,
+                "status": "not_found",
+                "exit_code": None,
+                "waited_seconds": time.time() - start_time,
+            }
+        
+        time.sleep(interval)
+    
+    # Timeout reached
+    info = get_container_status(container_id)
+    return {
+        "success": False,
+        "status": info["status"],
+        "exit_code": info["exit_code"],
+        "waited_seconds": time.time() - start_time,
+    }
+
+
+def get_container_logs(container_id: str, tail: int = 100) -> str:
+    """Get the logs of a Docker container.
+
+    Args:
+        container_id: Docker container ID
+        tail: Number of lines to return
+
+    Returns:
+        Container logs
+    """
+    result = subprocess.run(
+        ["docker", "logs", "--tail", str(tail), container_id],
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode == 0:
+        return result.stdout
+    return f"Failed to get logs: {result.stderr}"
+
+
+def find_free_port(start: int = 10000, end: int = 20000) -> int:
+    """Find a free TCP port in the given range.
+
+    Args:
+        start: Start of port range
+        end: End of port range
+
+    Returns:
+        Free port number
+    """
+    import socket
+
+    for port in range(start, end):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            if s.connect_ex(("localhost", port)) != 0:
+                return port
+
+    raise RuntimeError(f"No free port found in range {start}-{end}")
+
+
+import subprocess
+import time
+import re
+
+
+def start_cloudflared_tunnel(
+    container_name: str, port: int, timeout: int = 30
+) -> dict[str, str]:
+    """Start a temporary Cloudflare tunnel for a container.
+
+    Uses 'cloudflared tunnel --url' to create a temporary tunnel
+    with a random trycloudflare.com URL.
+
+    Args:
+        container_name: Name of the Docker container to tunnel to
+        port: Port number the container listens on
+        timeout: Maximum seconds to wait for tunnel URL
+
+    Returns:
+        Dict with 'url' (the public tunnel URL) and 'pid' (process ID)
+    """
+    import subprocess
+    import time
+    import re
+    import logging
+
+    logger = logging.getLogger(__name__)
+
+    # First verify the container is accessible
+    logger.info("Checking connectivity to %s:%d...", container_name, port)
+    for attempt in range(10):
+        check = subprocess.run(
+            ["curl", "-s", "-o", "/dev/null", "-w", "%{http_code}", 
+             f"http://{container_name}:{port}"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        logger.info("Connectivity check %d: http_code=%s", attempt + 1, check.stdout.strip())
+        if check.returncode == 0:
+            break
+        time.sleep(1)
+    else:
+        logger.warning("Container %s:%d not responding to curl checks", container_name, port)
+
+    # Run cloudflared in background, capture output
+    logger.info("Starting cloudflared tunnel to http://%s:%d", container_name, port)
+    proc = subprocess.Popen(
+        ["cloudflared", "tunnel", "--url", f"http://{container_name}:{port}"],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+    )
+
+    # Wait for the URL to appear in output
+    url_pattern = re.compile(r"https://[a-z0-9-]+\.trycloudflare\.com")
+    start_time = time.time()
+    url = None
+
+    while time.time() - start_time < timeout:
+        # Read available output
+        import select
+        readable, _, _ = select.select([proc.stdout], [], [], 1.0)
+        if readable:
+            line = proc.stdout.readline()
+            if line:
+                match = url_pattern.search(line)
+                if match:
+                    url = match.group(0)
+                    break
+
+    if not url:
+        proc.terminate()
+        proc.wait(timeout=5)
+        raise RuntimeError(
+            f"Failed to get tunnel URL within {timeout}s. "
+            f"cloudflared output may contain errors."
+        )
+
+    return {"url": url, "pid": str(proc.pid)}
+
+
+def stop_cloudflared_tunnel(pid: str) -> None:
+    """Stop a cloudflared tunnel process.
+
+    Args:
+        pid: Process ID of the cloudflared tunnel
+    """
+    import os
+    import signal
+
+    try:
+        os.kill(int(pid), signal.SIGTERM)
+    except ProcessLookupError:
+        pass  # Already stopped
+
+
+def recreate_tunnel(
+    container_name: str, port: int, old_pid: str | None = None
+) -> dict[str, str]:
+    """Recreate a temporary Cloudflare tunnel.
+
+    Stops the old tunnel (if pid provided) and starts a new one.
+
+    Args:
+        container_name: Name of the Docker container to tunnel to
+        port: Port number the container listens on
+        old_pid: Optional PID of the old tunnel process to stop
+
+    Returns:
+        Dict with 'url' and 'pid' for the new tunnel
+    """
+    if old_pid:
+        stop_cloudflared_tunnel(old_pid)
+
+    return start_cloudflared_tunnel(container_name, port)
+
+
+def check_tunnel_health(url: str, timeout: int = 10) -> dict[str, Any]:
+    """Check if a tunnel URL is healthy with smart error classification.
+
+    Args:
+        url: The tunnel URL to check
+        timeout: Request timeout in seconds
+
+    Returns:
+        Dict with 'tunnel_status' (healthy, unreachable, error_response, not_applicable),
+        'status_code' (int or None), 'healthy' (bool), and 'error' (str or None)
+    """
+    import subprocess
+
+    try:
+        result = subprocess.run(
+            ["curl", "-s", "-o", "/dev/null", "-w", "%{http_code}",
+             "--max-time", str(timeout), url],
+            capture_output=True,
+            text=True,
+            timeout=timeout + 5,
+        )
+        status_code = int(result.stdout.strip())
+        
+        if 200 <= status_code < 400:
+            return {
+                "tunnel_status": "healthy",
+                "status_code": status_code,
+                "healthy": True,
+                "error": None,
+            }
+        elif status_code in (502, 503, 504):
+            # Application error, not tunnel error
+            return {
+                "tunnel_status": "error_response",
+                "status_code": status_code,
+                "healthy": False,
+                "error": f"Application returned HTTP {status_code}",
+            }
+        else:
+            return {
+                "tunnel_status": "error_response",
+                "status_code": status_code,
+                "healthy": False,
+                "error": f"HTTP {status_code}",
+            }
+    except subprocess.TimeoutExpired:
+        return {
+            "tunnel_status": "unreachable",
+            "status_code": None,
+            "healthy": False,
+            "error": "Tunnel request timed out",
+        }
+    except (ValueError, Exception) as e:
+        error_str = str(e).lower()
+        # Classify connection errors
+        if any(err in error_str for err in ["connection refused", "econnrefused", "could not resolve", "nodename"]):
+            return {
+                "tunnel_status": "unreachable",
+                "status_code": None,
+                "healthy": False,
+                "error": f"Tunnel unreachable: {e}",
+            }
+        return {
+            "tunnel_status": "unreachable",
+            "status_code": None,
+            "healthy": False,
+            "error": str(e),
+        }

apps/api/src/services/docker/__init__.py

@@ -1,44 +0,0 @@
-"""Docker services for container and tunnel management."""
-
-from .compose import (
-    ensure_instance_directory,
-    execute_compose_command,
-    render_compose_template,
-    write_compose_file,
-    write_env_file,
-)
-from .config_staging import write_config_files, write_config_folder_files
-from .container import (
-    connect_container_to_network,
-    find_free_port,
-    get_container_id,
-    get_container_logs,
-    get_container_name,
-    get_container_status,
-)
-from .tunnel import (
-    check_tunnel_health,
-    recreate_tunnel,
-    start_cloudflared_tunnel,
-    stop_cloudflared_tunnel,
-)
-
-__all__ = [
-    "render_compose_template",
-    "ensure_instance_directory",
-    "write_compose_file",
-    "write_env_file",
-    "execute_compose_command",
-    "write_config_files",
-    "write_config_folder_files",
-    "get_container_id",
-    "get_container_name",
-    "connect_container_to_network",
-    "get_container_status",
-    "get_container_logs",
-    "find_free_port",
-    "start_cloudflared_tunnel",
-    "stop_cloudflared_tunnel",
-    "recreate_tunnel",
-    "check_tunnel_health",
-]

apps/api/src/services/docker/compose.py

@@ -1,237 +0,0 @@
-"""Docker Compose file generation and command execution."""
-
-import re
-import subprocess
-import uuid
-from pathlib import Path
-from typing import Any
-
-from sqlalchemy import select
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from src.models.config_profile import ConfigProfile
-from src.models.tool_instance import ToolInstance
-from src.services.profile_resolver import resolve_profile
-
-
-def _sanitize_name(name: str) -> str:
-    """Sanitize a string for use in Docker/container names."""
-    sanitized = re.sub(r"[^a-z0-9-]", "-", name.lower())
-    sanitized = re.sub(r"-+", "-", sanitized)
-    return sanitized.strip("-")
-
-
-async def _generate_instance_name(
-    session: AsyncSession,
-    project_name: str,
-    tool_type_name: str,
-) -> str:
-    """Generate a unique instance name: project-tool-NUM."""
-    base = f"{_sanitize_name(project_name)}-{_sanitize_name(tool_type_name)}"
-    base = base.strip("-") or "instance"
-    result = await session.execute(
-        select(ToolInstance.name).where(ToolInstance.name.like(f"{base}-%"))
-    )
-    names = result.scalars().all()
-    max_num = 0
-    for name in names:
-        parts = name.rsplit("-", 1)
-        if len(parts) == 2 and parts[0] == base and parts[1].isdigit():
-            max_num = max(max_num, int(parts[1]))
-    return f"{base}-{max_num + 1:03d}"
-
-
-def _modify_compose_file(
-    compose_path: str,
-    port_override: int | None = None,
-    start_command: str | None = None,
-    working_directory: str | None = None,
-    extra_volumes: list[dict] | None = None,
-) -> None:
-    """Modify compose file with runtime overrides."""
-    import yaml
-
-    compose_file = Path(compose_path)
-    content = compose_file.read_text()
-    compose_data = yaml.safe_load(content)
-
-    if not compose_data or "services" not in compose_data:
-        return
-
-    for service_name, service_config in compose_data["services"].items():
-        if port_override and "ports" in service_config:
-            for i, port_mapping in enumerate(service_config["ports"]):
-                if isinstance(port_mapping, str) and ":" in port_mapping:
-                    _host_port, container_port = port_mapping.split(":", 1)
-                    service_config["ports"][i] = f"{port_override}:{container_port}"
-                    break
-
-        if start_command:
-            service_config["command"] = start_command
-
-        if working_directory:
-            service_config["working_dir"] = working_directory
-
-        if extra_volumes:
-            if "volumes" not in service_config:
-                service_config["volumes"] = []
-            for vol in extra_volumes:
-                source = vol.get("source", "")
-                target = vol.get("target", "")
-                vol_type = vol.get("type", "bind")
-                if vol_type == "bind":
-                    service_config["volumes"].append(f"{source}:{target}")
-                else:
-                    service_config["volumes"].append(f"{source}:{target}:{vol_type}")
-
-        break
-
-    compose_file.write_text(yaml.dump(compose_data, default_flow_style=False))
-
-
-async def _apply_resolved_profile(
-    profile: ConfigProfile,
-    instance_dir: str,
-    env_vars: dict[str, str],
-    port_override: int | None,
-    start_command: str | None,
-    working_directory: str | None,
-    extra_volumes: list[dict],
-) -> tuple[dict[str, str], int | None, str | None, str | None, list[dict]]:
-    """Resolve a profile and apply its output to instance configuration."""
-    resolved = resolve_profile(profile)
-
-    if resolved.environment_variables:
-        env_vars.update(resolved.environment_variables)
-
-    if resolved.runtime_hints.start_command is not None:
-        start_command = resolved.runtime_hints.start_command
-    if resolved.runtime_hints.working_directory is not None:
-        working_directory = resolved.runtime_hints.working_directory
-    if resolved.runtime_hints.port is not None:
-        port_override = resolved.runtime_hints.port
-
-    for target_path, mount in resolved.mounts.items():
-        safe_name = target_path.strip("/").replace("/", "_")
-        mount_dir = Path(instance_dir) / "mounts" / safe_name
-        mount_dir.mkdir(parents=True, exist_ok=True)
-
-        for rel_path, content in mount.files.items():
-            file_path = mount_dir / rel_path
-            file_path.parent.mkdir(parents=True, exist_ok=True)
-            file_path.write_text(content)
-
-        extra_volumes.append({
-            "source": str(mount_dir),
-            "target": target_path,
-            "type": mount.mode,
-        })
-
-    return env_vars, port_override, start_command, working_directory, extra_volumes
-
-
-def render_compose_template(template: str, variables: dict[str, Any]) -> str:
-    """Render a Docker Compose template with variable substitution.
-
-    Args:
-        template: The compose template string
-        variables: Dictionary of variable names to values
-
-    Returns:
-        Rendered compose file content
-    """
-    result = template
-    for key, value in variables.items():
-        placeholder = f"{{{{{key}}}}}"
-        result = result.replace(placeholder, str(value))
-    return result
-
-
-def ensure_instance_directory(instance_id: str, base_path: str | None = None) -> str:
-    """Create and return the instance directory path.
-
-    Args:
-        instance_id: Unique instance identifier
-        base_path: Base directory for all instances (defaults to Settings.instance_base_path)
-
-    Returns:
-        Absolute path to instance directory
-    """
-    if base_path is None:
-        from src.config import Settings
-        base_path = Settings().instance_base_path
-    instance_dir = Path(base_path) / instance_id
-    instance_dir.mkdir(parents=True, exist_ok=True)
-    return str(instance_dir.absolute())
-
-
-def write_compose_file(instance_dir: str, content: str) -> str:
-    """Write the rendered compose file to the instance directory.
-
-    Args:
-        instance_dir: Path to instance directory
-        content: Rendered compose content
-
-    Returns:
-        Path to the compose file
-    """
-    compose_path = Path(instance_dir) / "docker-compose.yml"
-    compose_path.write_text(content)
-    return str(compose_path)
-
-
-def write_env_file(instance_dir: str, env_vars: dict[str, str]) -> str:
-    """Write environment variables to a .env file.
-
-    Args:
-        instance_dir: Path to instance directory
-        env_vars: Dictionary of env var names to values
-
-    Returns:
-        Path to the env file
-    """
-    env_path = Path(instance_dir) / ".env"
-    lines = [f'{key}="{value}"' for key, value in env_vars.items()]
-    env_path.write_text("\n".join(lines) + "\n")
-    return str(env_path)
-
-
-def execute_compose_command(
-    compose_path: str, action: str, timeout: int = 60, env_file: str | None = None
-) -> tuple[int, str, str]:
-    """Execute a docker compose command.
-
-    Args:
-        compose_path: Path to docker-compose.yml
-        action: The compose action (up, down, start, stop, restart)
-        timeout: Command timeout in seconds
-        env_file: Optional path to .env file for environment variables
-
-    Returns:
-        Tuple of (returncode, stdout, stderr)
-    """
-    instance_dir = Path(compose_path).parent
-
-    cmd = ["docker", "compose", "-f", compose_path]
-
-    if env_file:
-        cmd.extend(["--env-file", env_file])
-
-    if action == "up":
-        cmd.extend(["up", "-d"])
-    elif action == "down":
-        cmd.extend(["down", "-v"])
-    elif action in ("start", "stop", "restart"):
-        cmd.append(action)
-    else:
-        raise ValueError(f"Unknown compose action: {action}")
-
-    result = subprocess.run(
-        cmd,
-        cwd=str(instance_dir),
-        capture_output=True,
-        text=True,
-        timeout=timeout,
-    )
-
-    return result.returncode, result.stdout, result.stderr

apps/api/src/services/docker/config_staging.py

@@ -1,79 +0,0 @@
-"""Config folder file staging for Docker instances."""
-
-import logging
-from pathlib import Path
-
-logger = logging.getLogger(__name__)
-
-
-def write_config_files(instance_dir: str, files: dict[str, str]) -> None:
-    """Write config files to the instance directory.
-
-    Args:
-        instance_dir: Path to instance directory
-        files: Dictionary of file paths (relative to instance dir) to content
-    """
-    instance_path = Path(instance_dir)
-    for file_path, content in files.items():
-        # Ensure the path is within the instance directory (security)
-        full_path = instance_path / file_path
-        try:
-            full_path.resolve().relative_to(instance_path.resolve())
-        except ValueError:
-            raise ValueError(f"File path '{file_path}' escapes instance directory")
-
-        full_path.parent.mkdir(parents=True, exist_ok=True)
-        full_path.write_text(content)
-
-
-def write_config_folder_files(instance_dir: str, folders: list, project_id: str | None = None) -> list[dict]:
-    """Write config folder files to the instance directory and return volume mounts.
-
-    Args:
-        instance_dir: Path to instance directory
-        folders: List of ConfigFolder objects
-        project_id: Optional project ID for applying overrides
-
-    Returns:
-        List of volume mount dicts [{"source": "...", "target": "...", "type": "..."}]
-    """
-    instance_path = Path(instance_dir)
-    volume_mounts = []
-
-    for folder in folders:
-        # Determine mount path (with project override if applicable)
-        mount_path = folder.mount_path
-        files = folder.files.copy()
-
-        if project_id and folder.project_overrides:
-            override = folder.project_overrides.get(str(project_id))
-            if override:
-                if override.get("mount_path"):
-                    mount_path = override["mount_path"]
-                if override.get("files"):
-                    files.update(override["files"])
-
-        # Write files to instance directory
-        folder_dir = instance_path / "volumes" / folder.name
-        folder_dir.mkdir(parents=True, exist_ok=True)
-
-        for file_path, content in files.items():
-            # Security: ensure path doesn't escape folder_dir
-            full_path = folder_dir / file_path
-            try:
-                full_path.resolve().relative_to(folder_dir.resolve())
-            except ValueError:
-                logger.warning("Config folder file path escapes directory: %s", file_path)
-                continue
-
-            full_path.parent.mkdir(parents=True, exist_ok=True)
-            full_path.write_text(content)
-
-        # Add volume mount
-        volume_mounts.append({
-            "source": str(folder_dir),
-            "target": mount_path,
-            "type": "bind",
-        })
-
-    return volume_mounts

apps/api/src/services/docker/container.py

@@ -1,121 +0,0 @@
-"""Docker container lifecycle and query operations."""
-
-import socket
-import subprocess
-
-
-def get_container_id(instance_name: str) -> str | None:
-    """Get the container ID for a compose service.
-
-    Args:
-        instance_name: The service name in compose
-
-    Returns:
-        Container ID or None if not found
-    """
-    result = subprocess.run(
-        ["docker", "ps", "-q", "--filter", f"name={instance_name}"],
-        capture_output=True,
-        text=True,
-    )
-
-    if result.returncode == 0 and result.stdout.strip():
-        return result.stdout.strip().split("\n")[0]
-    return None
-
-
-def get_container_name(instance_name: str) -> str | None:
-    """Get the full container name for a compose service.
-
-    Args:
-        instance_name: The service name in compose
-
-    Returns:
-        Container name or None if not found
-    """
-    result = subprocess.run(
-        ["docker", "ps", "--format", "{{.Names}}", "--filter", f"name={instance_name}"],
-        capture_output=True,
-        text=True,
-    )
-
-    if result.returncode == 0 and result.stdout.strip():
-        return result.stdout.strip().split("\n")[0]
-    return None
-
-
-def connect_container_to_network(container_name: str, network_name: str = "backend") -> bool:
-    """Connect a Docker container to an existing network.
-
-    Args:
-        container_name: Name or ID of the container
-        network_name: Name of the Docker network (default: backend)
-
-    Returns:
-        True if successful, False otherwise
-    """
-    result = subprocess.run(
-        ["docker", "network", "connect", network_name, container_name],
-        capture_output=True,
-        text=True,
-    )
-    return result.returncode == 0
-
-
-def get_container_status(container_id: str) -> str:
-    """Get the status of a Docker container.
-
-    Args:
-        container_id: Docker container ID
-
-    Returns:
-        Container status string (running, exited, etc.)
-    """
-    result = subprocess.run(
-        ["docker", "inspect", "-f", "{{.State.Status}}", container_id],
-        capture_output=True,
-        text=True,
-    )
-
-    if result.returncode == 0:
-        return result.stdout.strip()
-    return "unknown"
-
-
-def get_container_logs(container_id: str, tail: int = 100) -> str:
-    """Get the logs of a Docker container.
-
-    Args:
-        container_id: Docker container ID
-        tail: Number of lines to return
-
-    Returns:
-        Container logs
-    """
-    result = subprocess.run(
-        ["docker", "logs", "--tail", str(tail), container_id],
-        capture_output=True,
-        text=True,
-    )
-
-    if result.returncode == 0:
-        return result.stdout
-    return f"Failed to get logs: {result.stderr}"
-
-
-def find_free_port(start: int = 10000, end: int = 20000) -> int:
-    """Find a free TCP port in the given range.
-
-    Args:
-        start: Start of port range
-        end: End of port range
-
-    Returns:
-        Free port number
-    """
-    for port in range(start, end):
-        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-            if s.connect_ex(("localhost", port)) != 0:
-                return port
-
-    raise RuntimeError(f"No free port found in range {start}-{end}")

apps/api/src/services/docker/tunnel.py

@@ -1,146 +0,0 @@
-"""Cloudflare tunnel management for Docker instances."""
-
-import logging
-import os
-import re
-import signal
-import subprocess
-import time
-from typing import Any
-
-logger = logging.getLogger(__name__)
-
-
-def start_cloudflared_tunnel(
-    container_name: str, port: int, timeout: int = 30
-) -> dict[str, str]:
-    """Start a temporary Cloudflare tunnel for a container.
-
-    Uses 'cloudflared tunnel --url' to create a temporary tunnel
-    with a random trycloudflare.com URL.
-
-    Args:
-        container_name: Name of the Docker container to tunnel to
-        port: Port number the container listens on
-        timeout: Maximum seconds to wait for tunnel URL
-
-    Returns:
-        Dict with 'url' (the public tunnel URL) and 'pid' (process ID)
-    """
-    import select as sel
-
-    # First verify the container is accessible
-    logger.info("Checking connectivity to %s:%d...", container_name, port)
-    for attempt in range(10):
-        check = subprocess.run(
-            ["curl", "-s", "-o", "/dev/null", "-w", "%{http_code}",
-             f"http://{container_name}:{port}"],
-            capture_output=True,
-            text=True,
-            timeout=5,
-        )
-        logger.info("Connectivity check %d: http_code=%s", attempt + 1, check.stdout.strip())
-        if check.returncode == 0:
-            break
-        time.sleep(1)
-    else:
-        logger.warning("Container %s:%d not responding to curl checks", container_name, port)
-
-    # Run cloudflared in background, capture output
-    logger.info("Starting cloudflared tunnel to http://%s:%d", container_name, port)
-    proc = subprocess.Popen(
-        ["cloudflared", "tunnel", "--url", f"http://{container_name}:{port}"],
-        stdout=subprocess.PIPE,
-        stderr=subprocess.STDOUT,
-        text=True,
-    )
-
-    # Wait for the URL to appear in output
-    url_pattern = re.compile(r"https://[a-z0-9-]+\.trycloudflare\.com")
-    start_time = time.time()
-    url = None
-
-    while time.time() - start_time < timeout:
-        # Read available output
-        readable, _, _ = sel.select([proc.stdout], [], [], 1.0)
-        if readable:
-            line = proc.stdout.readline()
-            if line:
-                match = url_pattern.search(line)
-                if match:
-                    url = match.group(0)
-                    break
-
-    if not url:
-        proc.terminate()
-        proc.wait(timeout=5)
-        raise RuntimeError(
-            f"Failed to get tunnel URL within {timeout}s. "
-            f"cloudflared output may contain errors."
-        )
-
-    return {"url": url, "pid": str(proc.pid)}
-
-
-def stop_cloudflared_tunnel(pid: str) -> None:
-    """Stop a cloudflared tunnel process.
-
-    Args:
-        pid: Process ID of the cloudflared tunnel
-    """
-    try:
-        os.kill(int(pid), signal.SIGTERM)
-    except ProcessLookupError:
-        pass  # Already stopped
-
-
-def recreate_tunnel(
-    container_name: str, port: int, old_pid: str | None = None
-) -> dict[str, str]:
-    """Recreate a temporary Cloudflare tunnel.
-
-    Stops the old tunnel (if pid provided) and starts a new one.
-
-    Args:
-        container_name: Name of the Docker container to tunnel to
-        port: Port number the container listens on
-        old_pid: Optional PID of the old tunnel process to stop
-
-    Returns:
-        Dict with 'url' and 'pid' for the new tunnel
-    """
-    if old_pid:
-        stop_cloudflared_tunnel(old_pid)
-
-    return start_cloudflared_tunnel(container_name, port)
-
-
-def check_tunnel_health(url: str, timeout: int = 10) -> dict[str, Any]:
-    """Check if a tunnel URL is healthy.
-
-    Args:
-        url: The tunnel URL to check
-        timeout: Request timeout in seconds
-
-    Returns:
-        Dict with 'healthy' (bool) and 'status_code' (int or None)
-    """
-    try:
-        result = subprocess.run(
-            ["curl", "-s", "-o", "/dev/null", "-w", "%{http_code}",
-             "--max-time", str(timeout), url],
-            capture_output=True,
-            text=True,
-            timeout=timeout + 5,
-        )
-        status_code = int(result.stdout.strip())
-        return {
-            "healthy": 200 <= status_code < 400,
-            "status_code": status_code,
-        }
-    except (ValueError, subprocess.TimeoutExpired, Exception) as e:
-        return {
-            "healthy": False,
-            "status_code": None,
-            "error": str(e),
-        }

apps/api/src/services/git/__init__.py

@@ -1 +0,0 @@
-"""Git services package."""

apps/api/src/services/git/control.py

@@ -1,196 +0,0 @@
-"""Git control operations with repo validation."""
-
-import logging
-import os
-import uuid
-
-from fastapi import HTTPException, status
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from src.models.git_repository import GitRepository
-from src.models.user import User
-from src.schemas.git_repository import (
-    BranchCreateRequest,
-    CheckoutRequest,
-    CommitRequest,
-    FetchResponse,
-    MergeRequest,
-    MergeResponse,
-    PullResponse,
-    PushResponse,
-    StatusResponse,
-)
-from src.services.git.repository import ensure_repo_on_disk, get_repo_and_validate
-from src.utils.git_control import (
-    checkout_branch,
-    commit_changes,
-    create_branch,
-    delete_branch,
-    fetch,
-    get_status,
-    merge,
-    pull,
-    push,
-)
-
-logger = logging.getLogger(__name__)
-
-
-async def get_status_with_validation(
-    session: AsyncSession,
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-) -> StatusResponse:
-    repo = await get_repo_and_validate(session, repo_id, project_id)
-    ensure_repo_on_disk(repo)
-    try:
-        result = get_status(repo.path)
-        return StatusResponse(
-            branch=result.branch,
-            modified=result.modified,
-            added=result.added,
-            deleted=result.deleted,
-            untracked=result.untracked,
-            renamed=result.renamed,
-            ahead=result.ahead,
-            behind=result.behind,
-        )
-    except RuntimeError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
-
-
-async def create_branch_with_validation(
-    session: AsyncSession,
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    data: BranchCreateRequest,
-) -> dict:
-    repo = await get_repo_and_validate(session, repo_id, project_id)
-    ensure_repo_on_disk(repo)
-    try:
-        create_branch(repo.path, data.name, data.base_branch)
-        return {"message": f"Branch '{data.name}' created", "branch": data.name}
-    except RuntimeError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
-
-
-async def delete_branch_with_validation(
-    session: AsyncSession,
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    branch_name: str,
-    force: bool = False,
-) -> dict:
-    repo = await get_repo_and_validate(session, repo_id, project_id)
-    ensure_repo_on_disk(repo)
-    try:
-        delete_branch(repo.path, branch_name, force)
-        return {"message": f"Branch '{branch_name}' deleted"}
-    except RuntimeError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
-
-
-async def checkout_branch_with_validation(
-    session: AsyncSession,
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    data: CheckoutRequest,
-) -> dict:
-    repo = await get_repo_and_validate(session, repo_id, project_id)
-    ensure_repo_on_disk(repo)
-    try:
-        checkout_branch(repo.path, data.branch)
-        return {"message": f"Checked out branch '{data.branch}'", "branch": data.branch}
-    except RuntimeError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
-
-
-async def commit_changes_with_validation(
-    session: AsyncSession,
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    data: CommitRequest,
-    user: User,
-) -> dict:
-    repo = await get_repo_and_validate(session, repo_id, project_id)
-    ensure_repo_on_disk(repo)
-    author_name = user.name or "Unknown"
-    author_email = user.email or "unknown@example.com"
-    try:
-        commit_hash = commit_changes(
-            repo_path=repo.path,
-            message=data.message,
-            author_name=author_name,
-            author_email=author_email,
-            files=data.files,
-        )
-        return {"commit_hash": commit_hash, "message": data.message}
-    except RuntimeError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
-
-
-async def fetch_with_validation(
-    session: AsyncSession,
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-) -> FetchResponse:
-    repo = await get_repo_and_validate(session, repo_id, project_id)
-    ensure_repo_on_disk(repo)
-    try:
-        fetch(repo.path)
-        return FetchResponse(message="Fetched from remote")
-    except RuntimeError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
-
-
-async def pull_with_validation(
-    session: AsyncSession,
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    branch: str | None = None,
-) -> PullResponse:
-    repo = await get_repo_and_validate(session, repo_id, project_id)
-    ensure_repo_on_disk(repo)
-    try:
-        pull(repo.path, branch)
-        return PullResponse(message="Pulled from remote")
-    except RuntimeError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
-
-
-async def push_with_validation(
-    session: AsyncSession,
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    branch: str | None = None,
-) -> PushResponse:
-    repo = await get_repo_and_validate(session, repo_id, project_id)
-    ensure_repo_on_disk(repo)
-    try:
-        push(repo.path, branch)
-        return PushResponse(message="Pushed to remote")
-    except RuntimeError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
-
-
-async def merge_with_validation(
-    session: AsyncSession,
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    data: MergeRequest,
-) -> MergeResponse:
-    repo = await get_repo_and_validate(session, repo_id, project_id)
-    ensure_repo_on_disk(repo)
-    try:
-        commit_hash = merge(
-            repo_path=repo.path,
-            source_branch=data.source_branch,
-            target_branch=data.target_branch,
-            message=data.message,
-        )
-        return MergeResponse(
-            commit_hash=commit_hash,
-            message=data.message or f"Merge {data.source_branch}",
-        )
-    except RuntimeError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))

apps/api/src/services/git/files.py

@@ -1,150 +0,0 @@
-"""Git file operations with repo validation."""
-
-import logging
-import uuid
-
-from fastapi import HTTPException, status
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from src.models.git_repository import GitRepository
-from src.models.user import User
-from src.schemas.git_repository import (
-    FileContentResponse,
-    FileListResponse,
-    FileUpdateRequest,
-    FileUpdateResponse,
-)
-from src.services.git.repository import ensure_repo_on_disk, get_repo_and_validate
-from src.utils.git_files import (
-    commit_file,
-    get_file_content,
-    list_branches,
-    list_tree,
-)
-
-logger = logging.getLogger(__name__)
-
-
-async def list_files(
-    session: AsyncSession,
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    branch: str = "main",
-    path: str = "",
-) -> FileListResponse:
-    repo = await get_repo_and_validate(session, repo_id, project_id)
-    ensure_repo_on_disk(repo)
-    try:
-        entries = list_tree(repo.path, branch=branch, path=path)
-        return FileListResponse(
-            path=path,
-            branch=branch,
-            entries=[
-                {
-                    "name": e.name,
-                    "type": e.type,
-                    "path": e.path,
-                    "size": e.size,
-                    "mode": e.mode,
-                    "last_commit": e.last_commit,
-                }
-                for e in entries
-            ],
-        )
-    except RuntimeError as e:
-        logger.error(
-            "Failed to list files for repo %s (path=%s, branch=%s): %s",
-            repo_id,
-            path,
-            branch,
-            str(e),
-            exc_info=True,
-        )
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
-
-
-async def get_file(
-    session: AsyncSession,
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    branch: str,
-    path: str,
-) -> FileContentResponse:
-    repo = await get_repo_and_validate(session, repo_id, project_id)
-    ensure_repo_on_disk(repo)
-    try:
-        file_content = get_file_content(repo.path, branch=branch, path=path)
-        return FileContentResponse(
-            path=file_content.path,
-            branch=file_content.branch,
-            content=file_content.content,
-            size=file_content.size,
-            encoding=file_content.encoding,
-            language=file_content.language,
-            is_binary=file_content.is_binary,
-            last_commit=file_content.last_commit,
-        )
-    except FileNotFoundError:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="file not found")
-    except RuntimeError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
-
-
-async def update_file(
-    session: AsyncSession,
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-    data: FileUpdateRequest,
-    user: User,
-) -> FileUpdateResponse:
-    repo = await get_repo_and_validate(session, repo_id, project_id)
-    ensure_repo_on_disk(repo)
-    author_name = user.name or "Unknown"
-    author_email = user.email or "unknown@example.com"
-    try:
-        commit_hash = commit_file(
-            repo_path=repo.path,
-            branch=data.branch,
-            path=data.path,
-            content=data.content,
-            commit_message=data.commit_message,
-            author_name=author_name,
-            author_email=author_email,
-        )
-        return FileUpdateResponse(
-            commit_hash=commit_hash,
-            message=data.commit_message,
-            branch=data.branch,
-        )
-    except RuntimeError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
-
-
-async def list_branches_with_validation(
-    session: AsyncSession,
-    project_id: uuid.UUID,
-    repo_id: uuid.UUID,
-) -> dict:
-    repo = await get_repo_and_validate(session, repo_id, project_id)
-    ensure_repo_on_disk(repo)
-    try:
-        branches, default_branch = list_branches(repo.path)
-        return {
-            "branches": [
-                {
-                    "name": b.name,
-                    "is_default": b.is_default,
-                    "last_commit": b.last_commit,
-                }
-                for b in branches
-            ],
-            "default_branch": default_branch,
-        }
-    except RuntimeError as e:
-        logger.error(
-            "Failed to list branches for repo %s: %s",
-            repo_id,
-            str(e),
-            exc_info=True,
-        )
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))

apps/api/src/services/git/repository.py

@@ -1,211 +0,0 @@
-"""Repository lifecycle and path helpers."""
-
-import logging
-import os
-import shutil
-import subprocess
-import uuid
-
-from fastapi import HTTPException, status
-from sqlalchemy import select
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from src.config import Settings
-from src.models.git_repository import GitRepository
-from src.models.project import Project
-from src.models.user import User
-from src.schemas.git_repository import GitRepositoryCreate
-from src.utils.git_url_parser import parse_git_url
-
-logger = logging.getLogger(__name__)
-
-
-def _get_repo_path(user_id: uuid.UUID, project_id: uuid.UUID, name: str) -> str:
-    """Generate the filesystem path for a repository."""
-    base = Settings().repo_base_path or "/data/repos"
-    return os.path.join(base, str(user_id), str(project_id), f"{name}.git")
-
-
-def _build_provider_clone_url(owner: str, repo: str) -> str:
-    """Build the SSH clone URL for the fixed git provider."""
-    return f"git@git.commumedia.org:{owner}/{repo}.git"
-
-
-def _preflight_remote_repository(remote_url: str) -> None:
-    """Verify a remote repository is reachable before cloning."""
-    try:
-        result = subprocess.run(
-            ["git", "ls-remote", remote_url],
-            capture_output=True,
-            text=True,
-            timeout=60,
-        )
-    except subprocess.TimeoutExpired:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="remote repository check timed out")
-    except FileNotFoundError:
-        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="git command not found")
-
-    if result.returncode != 0:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="repository not found or inaccessible",
-        )
-
-
-def _clone_working_repository(remote_url: str, repo_path: str) -> None:
-    try:
-        result = subprocess.run(
-            ["git", "clone", remote_url, repo_path],
-            capture_output=True,
-            text=True,
-            timeout=300,
-        )
-    except subprocess.TimeoutExpired:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="clone operation timed out")
-    except FileNotFoundError:
-        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="git command not found")
-
-    if result.returncode != 0:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"failed to clone repository: {result.stderr}",
-        )
-
-
-def _init_working_repository(repo_path: str) -> None:
-    try:
-        result = subprocess.run(
-            ["git", "init", "-b", "main", repo_path],
-            capture_output=True,
-            text=True,
-        )
-    except FileNotFoundError:
-        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="git command not found")
-
-    if result.returncode == 0:
-        return
-
-    fallback = subprocess.run(
-        ["git", "init", repo_path],
-        capture_output=True,
-        text=True,
-    )
-    if fallback.returncode != 0:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"failed to initialize repository: {fallback.stderr}",
-        )
-
-    ref_result = subprocess.run(
-        ["git", "-C", repo_path, "symbolic-ref", "HEAD", "refs/heads/main"],
-        capture_output=True,
-        text=True,
-    )
-    if ref_result.returncode != 0:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"failed to set initial branch: {ref_result.stderr}",
-        )
-
-
-async def get_repo_and_validate(
-    session: AsyncSession,
-    repo_id: uuid.UUID,
-    project_id: uuid.UUID,
-) -> GitRepository:
-    """Fetch a repository and validate ownership + disk presence."""
-    repo = await session.get(GitRepository, repo_id)
-    if repo is None or repo.project_id != project_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found")
-    return repo
-
-
-def ensure_repo_on_disk(repo: GitRepository) -> None:
-    """Raise 404 if the repository is not present on disk."""
-    if not os.path.exists(repo.path):
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk")
-
-
-async def create_repository(
-    session: AsyncSession,
-    project_id: uuid.UUID,
-    data: GitRepositoryCreate,
-    user: User,
-) -> GitRepository:
-    """Create a new git repository (clone or init)."""
-    # Check for duplicate name
-    existing = await session.execute(
-        select(GitRepository).where(
-            GitRepository.project_id == project_id,
-            GitRepository.name == data.name,
-        )
-    )
-    if existing.scalar_one_or_none():
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="repository name already exists")
-
-    # Validate and potentially correct the URL
-    remote_url = data.remote_url
-    if remote_url and not data.force_original_url:
-        parse_result = parse_git_url(remote_url)
-        if parse_result["needs_parsing"] and parse_result["base_url"]:
-            raise HTTPException(
-                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
-                detail={
-                    "message": "The provided URL appears to be a browser URL, not a git clone URL",
-                    "suggested_url": parse_result["base_url"],
-                    "original_url": remote_url,
-                    "error_code": "URL_NEEDS_PARSING",
-                },
-            )
-        if parse_result["base_url"]:
-            remote_url = parse_result["base_url"]
-
-    if remote_url:
-        _preflight_remote_repository(remote_url)
-
-    repo_path = _get_repo_path(user.id, project_id, data.name)
-    os.makedirs(os.path.dirname(repo_path), exist_ok=True)
-
-    if remote_url:
-        _clone_working_repository(remote_url, repo_path)
-    else:
-        _init_working_repository(repo_path)
-
-    repo = GitRepository(
-        name=data.name,
-        path=repo_path,
-        project_id=project_id,
-        owner_id=user.id,
-        is_mirror=False,
-        remote_url=remote_url,
-    )
-    session.add(repo)
-    await session.commit()
-    await session.refresh(repo)
-    return repo
-
-
-async def delete_repository(
-    session: AsyncSession,
-    repo_id: uuid.UUID,
-    project_id: uuid.UUID,
-) -> None:
-    """Delete a repository from DB and disk."""
-    repo = await get_repo_and_validate(session, repo_id, project_id)
-
-    if os.path.exists(repo.path):
-        shutil.rmtree(repo.path)
-
-    await session.delete(repo)
-    await session.commit()
-
-
-async def list_repositories(
-    session: AsyncSession,
-    project_id: uuid.UUID,
-) -> list[GitRepository]:
-    """List all repositories in a project."""
-    result = await session.execute(
-        select(GitRepository).where(GitRepository.project_id == project_id)
-    )
-    return list(result.scalars().all())

apps/api/src/services/instance_lifecycle.py

@@ -1,420 +0,0 @@
-"""High-level tool instance lifecycle orchestration.
-
-Coordinates Docker compose, container, tunnel, and config staging services
-to create, start, stop, restart, and delete tool instances.
-"""
-
-import logging
-import os
-import shutil
-from datetime import datetime
-from typing import Any
-
-from fastapi import HTTPException, status
-from sqlalchemy import select
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from src.models.config_folder import ConfigFolder
-from src.models.config_profile import ConfigProfile
-from src.models.git_repository import GitRepository
-from src.models.project import Project
-from src.models.tool_config import ToolConfig
-from src.models.tool_instance import ToolInstance
-from src.models.tool_type import ToolType
-from src.models.user import User
-from src.services.docker import compose as compose_svc
-from src.services.docker import config_staging
-from src.services.docker import container as container_svc
-from src.services.docker import tunnel as tunnel_svc
-from src.services.docker_build import build_image
-from src.services.readiness_probe import execute_probe
-
-logger = logging.getLogger(__name__)
-
-
-async def create_new_instance(
-    session: AsyncSession,
-    project: Project,
-    repo: GitRepository,
-    tool_type: ToolType,
-    user: User,
-    display_name: str | None,
-    selected_profile: ConfigProfile | None,
-) -> ToolInstance:
-    """Create a new tool instance record and its compose file."""
-    instance_name = await compose_svc._generate_instance_name(
-        session, project.name, tool_type.name
-    )
-    instance_dir = compose_svc.ensure_instance_directory(instance_name)
-    tool_port = container_svc.find_free_port()
-
-    compose_path = await _build_or_render_compose(
-        tool_type, instance_name, instance_dir, repo, user, project.id, tool_port
-    )
-
-    instance = ToolInstance(
-        name=instance_name,
-        display_name=display_name or f"{project.name} / {repo.name} / {tool_type.display_name}",
-        tool_type_id=tool_type.id,
-        repository_id=repo.id,
-        project_id=project.id,
-        owner_id=user.id,
-        status="pending",
-        compose_path=compose_path,
-        port=tool_port,
-        selected_profile_id=selected_profile.id if selected_profile else None,
-    )
-    session.add(instance)
-    await session.commit()
-    await session.refresh(instance)
-    return instance
-
-
-async def start_existing_instance(
-    session: AsyncSession,
-    instance: ToolInstance,
-    user: User,
-    project_id: Any,
-) -> dict:
-    """Start an existing instance: stage configs, compose up, probe, tunnel."""
-    if not instance.compose_path or not os.path.exists(instance.compose_path):
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST, detail="compose file not found"
-        )
-
-    instance.status = "building"
-    await session.commit()
-
-    env_vars, config_files, port_override, start_command, working_directory, _extra_env, extra_volumes = await _fetch_tool_configs(
-        session, user.id, instance.tool_type_id, project_id
-    )
-
-    selected_profile = None
-    if instance.selected_profile_id:
-        selected_profile = await session.get(ConfigProfile, instance.selected_profile_id)
-        if selected_profile and selected_profile.user_id == user.id:
-            instance_dir = os.path.dirname(instance.compose_path)
-            env_vars, port_override, start_command, working_directory, extra_volumes = await compose_svc._apply_resolved_profile(
-                selected_profile,
-                instance_dir,
-                env_vars,
-                port_override,
-                start_command,
-                working_directory,
-                extra_volumes,
-            )
-
-    env_file_path, extra_volumes = await _stage_configs_and_folders(
-        session, user.id, project_id, os.path.dirname(instance.compose_path),
-        env_vars, config_files, extra_volumes
-    )
-
-    if port_override or start_command or working_directory or extra_volumes:
-        compose_svc._modify_compose_file(
-            instance.compose_path, port_override, start_command, working_directory, extra_volumes
-        )
-
-    returncode, _stdout, stderr = compose_svc.execute_compose_command(
-        instance.compose_path, "up", env_file=env_file_path
-    )
-    if returncode != 0:
-        instance.status = "error"
-        await session.commit()
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"failed to start instance: {stderr}",
-        )
-
-    container_id = container_svc.get_container_id(instance.name)
-    if container_id:
-        instance.container_id = container_id
-    container_name = container_svc.get_container_name(instance.name)
-    if container_name:
-        instance.container_name = container_name
-        container_svc.connect_container_to_network(container_name, "backend")
-
-    instance.status = "starting"
-    instance.last_started_at = datetime.now()
-    await session.commit()
-
-    tool_type = await session.get(ToolType, instance.tool_type_id)
-    success, probe_logs = await _run_readiness_probe(instance, tool_type)
-    if not success:
-        instance.status = "failed"
-        instance.url = None
-        instance.public_url = None
-        await session.commit()
-        return {
-            "status": "failed",
-            "error": f"Readiness probe failed: {' '.join(probe_logs)}",
-        }
-
-    instance.status = "running"
-    await session.commit()
-    await _start_tunnel_if_web(instance, tool_type)
-    await session.commit()
-
-    return {"status": instance.status, "url": instance.url}
-
-
-async def restart_existing_instance(
-    session: AsyncSession,
-    instance: ToolInstance,
-    user: User,
-    project_id: Any,
-) -> dict:
-    """Restart an instance: re-stage configs, compose restart, tunnel."""
-    if instance.tunnel_id:
-        try:
-            tunnel_svc.stop_cloudflared_tunnel(instance.tunnel_id)
-        except Exception as exc:
-            logger.warning("Failed to stop old tunnel: %s", exc)
-
-    if not instance.compose_path or not os.path.exists(instance.compose_path):
-        instance.status = "error"
-        await session.commit()
-        return {"status": instance.status}
-
-    env_vars, config_files, port_override, start_command, working_directory, _extra_env, extra_volumes = await _fetch_tool_configs(
-        session, user.id, instance.tool_type_id, project_id
-    )
-
-    stored_profile = None
-    if instance.selected_profile_id:
-        stored_profile = await session.get(ConfigProfile, instance.selected_profile_id)
-        if stored_profile and stored_profile.user_id == user.id:
-            instance_dir = os.path.dirname(instance.compose_path)
-            env_vars, port_override, start_command, working_directory, extra_volumes = await compose_svc._apply_resolved_profile(
-                stored_profile, instance_dir, env_vars, port_override, start_command, working_directory, extra_volumes
-            )
-
-    env_file_path, extra_volumes = await _stage_configs_and_folders(
-        session, user.id, project_id, os.path.dirname(instance.compose_path),
-        env_vars, config_files, extra_volumes
-    )
-
-    if port_override or start_command or working_directory or extra_volumes:
-        compose_svc._modify_compose_file(
-            instance.compose_path, port_override, start_command, working_directory, extra_volumes
-        )
-
-    returncode, _stdout, _stderr = compose_svc.execute_compose_command(
-        instance.compose_path, "restart", env_file=env_file_path
-    )
-    if returncode != 0:
-        instance.status = "error"
-        await session.commit()
-        return {"status": instance.status}
-
-    instance.status = "running"
-    instance.last_started_at = datetime.now()
-
-    tool_type = await session.get(ToolType, instance.tool_type_id)
-    await _start_tunnel_if_web(instance, tool_type)
-    await session.commit()
-
-    return {"status": instance.status, "url": instance.url}
-
-
-async def stop_existing_instance(session: AsyncSession, instance: ToolInstance) -> None:
-    """Stop an instance and its tunnel."""
-    if instance.tunnel_id:
-        try:
-            tunnel_svc.stop_cloudflared_tunnel(instance.tunnel_id)
-        except Exception as exc:
-            logger.warning("Failed to stop tunnel: %s", exc)
-
-    if instance.compose_path and os.path.exists(instance.compose_path):
-        compose_svc.execute_compose_command(instance.compose_path, "stop")
-
-    instance.status = "stopped"
-    instance.last_stopped_at = datetime.now()
-    instance.url = None
-    instance.public_url = None
-    instance.tunnel_id = None
-    await session.commit()
-
-
-async def delete_existing_instance(session: AsyncSession, instance: ToolInstance) -> None:
-    """Delete an instance, its containers, and its directory."""
-    if instance.tunnel_id:
-        try:
-            tunnel_svc.stop_cloudflared_tunnel(instance.tunnel_id)
-        except Exception as exc:
-            logger.warning("Failed to stop tunnel: %s", exc)
-
-    if instance.compose_path and os.path.exists(instance.compose_path):
-        compose_svc.execute_compose_command(instance.compose_path, "down")
-        instance_dir = os.path.dirname(instance.compose_path)
-        if os.path.exists(instance_dir):
-            shutil.rmtree(instance_dir)
-
-    await session.delete(instance)
-    await session.commit()
-
-
-# ── Internal helpers ───────────────────────────────────────────────────────
-
-async def _build_or_render_compose(
-    tool_type: ToolType,
-    instance_name: str,
-    instance_dir: str,
-    repo: GitRepository,
-    user: User,
-    project_id: Any,
-    tool_port: int,
-) -> str:
-    """Build Dockerfile or render compose template."""
-    if tool_type.definition_type == "dockerfile":
-        image_tag = f"headquarter/{instance_name}:latest"
-        if tool_type.dockerfile_template:
-            returncode, _stdout, stderr = build_image(
-                instance_dir=instance_dir,
-                dockerfile=tool_type.dockerfile_template,
-                tag=image_tag,
-                build_context=tool_type.build_context,
-            )
-            if returncode != 0:
-                logger.error("Build failed for %s: %s", instance_name, stderr)
-                raise HTTPException(
-                    status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-                    detail=f"Failed to build Docker image: {stderr[:500]}",
-                )
-
-        compose_content = (
-            f'version: "3.8"\nservices:\n  app:\n'
-            f'    image: {image_tag}\n'
-            f'    container_name: {instance_name}\n'
-            f'    ports:\n      - "{tool_port}:{tool_type.default_port}"\n'
-            f'    volumes:\n      - {repo.path}:/workspace\n'
-            f'    restart: unless-stopped\n'
-        )
-    else:
-        variables = {
-            "REPO_PATH": repo.path,
-            "INSTANCE_NAME": instance_name,
-            "INSTANCE_ID": instance_name,
-            "TOOL_NAME": instance_name,
-            "TOOL_PORT": tool_port,
-            "USER_ID": str(user.id),
-            "PROJECT_ID": str(project_id),
-        }
-        compose_content = compose_svc.render_compose_template(
-            tool_type.compose_template, variables
-        )
-
-    compose_svc.write_compose_file(instance_dir, compose_content)
-    return os.path.join(instance_dir, "docker-compose.yml")
-
-
-async def _fetch_tool_configs(
-    session: AsyncSession,
-    user_id: Any,
-    tool_type_id: Any,
-    project_id: Any,
-) -> tuple[dict, dict, Any, Any, Any, dict, list]:
-    """Fetch tool configs and return parsed values."""
-    env_vars: dict[str, str] = {}
-    config_files: dict[str, str] = {}
-    port_override = None
-    start_command = None
-    working_directory = None
-    extra_env_vars: dict[str, str] = {}
-    extra_volumes: list[dict] = []
-
-    query = (
-        select(ToolConfig)
-        .where(ToolConfig.user_id == user_id, ToolConfig.tool_type_id == tool_type_id)
-        .where((ToolConfig.project_id == project_id) | (ToolConfig.project_id.is_(None)))
-    )
-    configs = (await session.execute(query)).scalars().all()
-
-    for cfg in configs:
-        if cfg.config_type == "env":
-            env_vars[cfg.key] = cfg.value
-        elif cfg.config_type == "file" and cfg.file_path:
-            config_files[cfg.file_path] = cfg.value
-        if cfg.port_override:
-            port_override = cfg.port_override
-        if cfg.start_command:
-            start_command = cfg.start_command
-        if cfg.working_directory:
-            working_directory = cfg.working_directory
-        if cfg.environment_variables:
-            extra_env_vars.update(cfg.environment_variables)
-        if cfg.volumes:
-            extra_volumes.extend(cfg.volumes)
-
-    env_vars.update(extra_env_vars)
-    return env_vars, config_files, port_override, start_command, working_directory, extra_env_vars, extra_volumes
-
-
-async def _stage_configs_and_folders(
-    session: AsyncSession,
-    user_id: Any,
-    project_id: Any,
-    instance_dir: str,
-    env_vars: dict[str, str],
-    config_files: dict[str, str],
-    extra_volumes: list[dict],
-) -> tuple[str | None, list[dict]]:
-    """Write env/config files and config folders."""
-    env_file_path: str | None = None
-    if env_vars:
-        env_file_path = compose_svc.write_env_file(instance_dir, env_vars)
-    if config_files:
-        config_staging.write_config_files(instance_dir, config_files)
-
-    folder_query = select(ConfigFolder).where(
-        ConfigFolder.user_id == user_id, ConfigFolder.is_active.is_(True)
-    )
-    folders = (await session.execute(folder_query)).scalars().all()
-    if folders:
-        folder_volumes = config_staging.write_config_folder_files(
-            instance_dir, folders, str(project_id)
-        )
-        extra_volumes.extend(folder_volumes)
-
-    return env_file_path, extra_volumes
-
-
-async def _start_tunnel_if_web(instance: ToolInstance, tool_type: ToolType) -> None:
-    """Create Cloudflare tunnel for web-enabled tools."""
-    if "web" not in tool_type.interfaces or not tool_type.default_port:
-        instance.url = None
-        instance.public_url = None
-        return
-
-    try:
-        tunnel_info = tunnel_svc.start_cloudflared_tunnel(
-            container_name=instance.container_name or instance.name,
-            port=tool_type.default_port,
-        )
-        instance.tunnel_id = tunnel_info["pid"]
-        instance.public_url = tunnel_info["url"]
-        instance.url = tunnel_info["url"]
-        logger.info("Created tunnel for instance %s: %s", instance.id, tunnel_info["url"])
-    except Exception as exc:
-        logger.error("Failed to create tunnel for instance %s: %s", instance.id, exc)
-        instance.status = "error"
-        instance.url = None
-
-
-async def _run_readiness_probe(
-    instance: ToolInstance, tool_type: ToolType
-) -> tuple[bool, list[str]]:
-    """Run readiness probe if configured."""
-    if not tool_type.readiness_probe or not instance.container_id:
-        return True, []
-
-    probe = tool_type.readiness_probe
-    command = probe.get("command", "")
-    if not command:
-        return True, []
-
-    return await execute_probe(
-        container_id=instance.container_id,
-        command=command,
-        timeout=probe.get("timeout", 30),
-        interval=probe.get("interval", 2),
-    )

apps/api/src/services/profile_resolver.py

@@ -1,251 +0,0 @@
-"""Profile resolver service for recursive ordered include resolution.
-
-Provides deterministic merge rules, save-independent cycle protection,
-and resolved output structures for env vars, runtime hints, mounts,
-file trees, and override metadata.
-"""
-
-from __future__ import annotations
-
-import uuid
-from dataclasses import dataclass, field
-
-from src.models.config_include import ConfigInclude
-from src.models.config_mount import ConfigMount
-from src.models.config_profile import ConfigProfile
-
-
-@dataclass
-class ResolvedMount:
-    """A resolved mount with merged file tree and final mode."""
-
-    target_path: str
-    mode: str  # "ro" or "rw"
-    files: dict[str, str] = field(default_factory=dict)
-    """Relative file paths to UTF-8 text content."""
-    overridden_files: dict[str, list[str]] = field(default_factory=dict)
-    """Map of relative file path to list of profile names that contributed
-    (latest is the winner)."""
-    mode_overridden_by: str | None = None
-    """Name of the profile that set the final mode, if different from first."""
-
-
-@dataclass
-class ResolvedRuntimeHints:
-    """Resolved runtime hints from profile layers."""
-
-    start_command: str | None = None
-    working_directory: str | None = None
-    port: int | None = None
-    overridden_hints: dict[str, str] = field(default_factory=dict)
-    """Map of hint key to profile name that provided the winning value."""
-
-
-@dataclass
-class ResolvedProfileOutput:
-    """Complete resolved output for a config profile."""
-
-    profile_id: uuid.UUID
-    profile_name: str
-    environment_variables: dict[str, str] = field(default_factory=dict)
-    """Final merged env vars (later layers win)."""
-    env_var_sources: dict[str, list[str]] = field(default_factory=dict)
-    """Map of env var key to ordered list of contributing profile names
-    (latest is the winner)."""
-    runtime_hints: ResolvedRuntimeHints = field(
-        default_factory=lambda: ResolvedRuntimeHints()
-    )
-    mounts: dict[str, ResolvedMount] = field(default_factory=dict)
-    """Map of target_path to ResolvedMount."""
-    resolution_order: list[str] = field(default_factory=list)
-    """Ordered list of profile names as they were resolved."""
-    cycle_detected: bool = False
-    cycle_path: list[str] | None = None
-
-
-class ProfileResolutionError(Exception):
-    """Raised when profile resolution fails."""
-
-    pass
-
-
-class ProfileCycleError(ProfileResolutionError):
-    """Raised when a cycle is detected during profile resolution."""
-
-    def __init__(self, cycle_path: list[str]) -> None:
-        self.cycle_path = cycle_path
-        path_str = " -> ".join(cycle_path)
-        super().__init__(f"Profile include cycle detected: {path_str}")
-
-
-def _merge_env_vars(
-    current: dict[str, str],
-    sources: dict[str, list[str]],
-    profile: ConfigProfile,
-) -> None:
-    """Merge a profile's env vars into the current dict, tracking sources."""
-    if not profile.environment_variables:
-        return
-    for key, value in profile.environment_variables.items():
-        current[key] = value
-        if key not in sources:
-            sources[key] = []
-        sources[key].append(profile.name)
-
-
-def _merge_runtime_hints(
-    hints: ResolvedRuntimeHints,
-    profile: ConfigProfile,
-) -> None:
-    """Merge a profile's runtime hints, tracking overrides."""
-    if profile.start_command is not None:
-        hints.start_command = profile.start_command
-        hints.overridden_hints["start_command"] = profile.name
-    if profile.working_directory is not None:
-        hints.working_directory = profile.working_directory
-        hints.overridden_hints["working_directory"] = profile.name
-    if profile.port is not None:
-        hints.port = profile.port
-        hints.overridden_hints["port"] = profile.name
-
-
-def _merge_mounts(
-    mounts: dict[str, ResolvedMount],
-    profile_mounts: list[ConfigMount],
-    profile: ConfigProfile,
-) -> None:
-    """Merge a profile's mounts into the current mounts dict."""
-    for mount in profile_mounts:
-        target = mount.target_path
-        if target not in mounts:
-            mounts[target] = ResolvedMount(
-                target_path=target,
-                mode=mount.mode,
-                files={},
-                overridden_files={},
-            )
-        resolved = mounts[target]
-        
-        # Mode override: later wins
-        if resolved.mode != mount.mode:
-            resolved.mode = mount.mode
-            resolved.mode_overridden_by = profile.name
-        
-        # File tree merge: later wins for same relative path
-        if mount.files:
-            for rel_path, content in mount.files.items():
-                if rel_path not in resolved.files:
-                    resolved.overridden_files[rel_path] = []
-                else:
-                    if rel_path not in resolved.overridden_files:
-                        resolved.overridden_files[rel_path] = []
-                    resolved.overridden_files[rel_path].append(profile.name)
-                resolved.files[rel_path] = content
-
-
-def _resolve_profile_recursive(
-    profile: ConfigProfile,
-    visited: set[uuid.UUID],
-    path: list[str],
-    resolution_order: list[str],
-    env_vars: dict[str, str],
-    env_var_sources: dict[str, list[str]],
-    runtime_hints: ResolvedRuntimeHints,
-    mounts: dict[str, ResolvedMount],
-) -> None:
-    """Recursively resolve a profile and its includes.
-
-    Args:
-        profile: The profile to resolve
-        visited: Set of already-resolved profile IDs to avoid duplicates
-        path: Current recursion path for cycle detection
-        resolution_order: Ordered list of profile names being resolved
-        env_vars: Accumulated environment variables
-        env_var_sources: Tracking of which profiles contributed each env var
-        runtime_hints: Accumulated runtime hints
-        mounts: Accumulated mounts
-
-    Raises:
-        ProfileCycleError: If a cycle is detected
-    """
-    if profile.name in path:
-        # Cycle detected
-        cycle_start = path.index(profile.name)
-        cycle_path = path[cycle_start:] + [profile.name]
-        raise ProfileCycleError(cycle_path)
-
-    if profile.id in visited:
-        # Already resolved in another branch (diamond graph)
-        return
-
-    visited.add(profile.id)
-    path.append(profile.name)
-    resolution_order.append(profile.name)
-
-    # Resolve includes first (in order)
-    includes: list[ConfigInclude] = list(profile.includes)
-    includes.sort(key=lambda inc: inc.order_index)
-    for include in includes:
-        included_profile = include.included_profile
-        if included_profile is not None:
-            _resolve_profile_recursive(
-                included_profile,
-                visited,
-                path,
-                resolution_order,
-                env_vars,
-                env_var_sources,
-                runtime_hints,
-                mounts,
-            )
-
-    # Apply this profile's values (later layers win)
-    _merge_env_vars(env_vars, env_var_sources, profile)
-    _merge_runtime_hints(runtime_hints, profile)
-    _merge_mounts(mounts, list(profile.mounts), profile)
-
-    path.pop()
-
-
-def resolve_profile(profile: ConfigProfile) -> ResolvedProfileOutput:
-    """Resolve a config profile with all its includes.
-
-    Processes included profiles in configured order, then applies the
-    selected profile itself. Later layers override earlier layers.
-
-    Args:
-        profile: The root profile to resolve
-
-    Returns:
-        ResolvedProfileOutput with merged env vars, runtime hints, mounts,
-        and override metadata
-
-    Raises:
-        ProfileCycleError: If a cycle is detected in the include graph
-    """
-    env_vars: dict[str, str] = {}
-    env_var_sources: dict[str, list[str]] = {}
-    runtime_hints = ResolvedRuntimeHints()
-    mounts: dict[str, ResolvedMount] = {}
-    resolution_order: list[str] = []
-
-    _resolve_profile_recursive(
-        profile,
-        set(),
-        [],
-        resolution_order,
-        env_vars,
-        env_var_sources,
-        runtime_hints,
-        mounts,
-    )
-
-    return ResolvedProfileOutput(
-        profile_id=profile.id,
-        profile_name=profile.name,
-        environment_variables=env_vars,
-        env_var_sources=env_var_sources,
-        runtime_hints=runtime_hints,
-        mounts=mounts,
-        resolution_order=resolution_order,
-    )

apps/api/src/services/ssh_keys.py

@@ -0,0 +1,73 @@
+"""SSH key service utilities for preparing keys for container use."""
+
+import os
+from pathlib import Path
+
+from cryptography.fernet import Fernet
+
+from src.config import Settings
+
+
+def _get_fernet() -> Fernet:
+    """Generate a valid Fernet key from the session secret."""
+    import base64
+    import hashlib
+
+    settings = Settings()
+    key_bytes = hashlib.sha256(settings.session_secret.encode()).digest()
+    key = base64.urlsafe_b64encode(key_bytes)
+    return Fernet(key)
+
+
+def prepare_ssh_key_files(instance_dir: str, ssh_key) -> str:
+    """Decrypt and write SSH key files to instance directory for container mounting.
+
+    Args:
+        instance_dir: Path to instance directory
+        ssh_key: SSHKey model instance with encrypted private key
+
+    Returns:
+        Path to the .ssh directory
+    """
+    ssh_dir = Path(instance_dir) / ".ssh"
+    ssh_dir.mkdir(parents=True, exist_ok=True)
+
+    # Decrypt private key
+    fernet = _get_fernet()
+    private_key = fernet.decrypt(ssh_key.private_key_encrypted.encode()).decode()
+
+    # Write private key with restricted permissions
+    private_key_path = ssh_dir / "id_ed25519"
+    private_key_path.write_text(private_key)
+    os.chmod(private_key_path, 0o600)
+
+    # Write public key
+    public_key_path = ssh_dir / "id_ed25519.pub"
+    public_key_path.write_text(ssh_key.public_key)
+    os.chmod(public_key_path, 0o644)
+
+    # Write SSH config
+    config_path = ssh_dir / "config"
+    config_content = """Host *
+    StrictHostKeyChecking no
+    UserKnownHostsFile /dev/null
+    IdentityFile ~/.ssh/id_ed25519
+    IdentitiesOnly yes
+"""
+    config_path.write_text(config_content)
+    os.chmod(config_path, 0o644)
+
+    return str(ssh_dir)
+
+
+def cleanup_ssh_key_files(instance_dir: str) -> None:
+    """Remove temporary SSH key files from instance directory.
+
+    Args:
+        instance_dir: Path to instance directory
+    """
+    ssh_dir = Path(instance_dir) / ".ssh"
+    if ssh_dir.exists():
+        for file_path in ssh_dir.iterdir():
+            file_path.unlink()
+        ssh_dir.rmdir()

apps/api/src/services/terminal_manager.py

@@ -1,12 +1,8 @@
 """Terminal session manager for WebSocket connections."""
 
 import asyncio
-import contextlib
-import json
 import logging
-import time
 import uuid
-from collections.abc import Coroutine
 from typing import Any
 
 from fastapi import WebSocket
@@ -15,178 +11,149 @@ from src.services.terminal_session import TerminalSession
 
 logger = logging.getLogger(__name__)
 
-_READ_BATCH_INTERVAL_S = 0.016  # 16ms max batching delay
-_READ_POLL_TIMEOUT_S = 0.005
-_READ_POLL_SLEEP_S = 0.001
-_HEARTBEAT_INTERVAL_S = 15.0
-_IDLE_TIMEOUT_S = 60.0
-
 
 class TerminalManager:
-    """Manages active terminal sessions."""
+    """Manages active terminal sessions with persistence support."""
 
     def __init__(self) -> None:
-        """Initialise the terminal manager."""
+        # Track sessions by instance_id for persistence
         self._sessions: dict[str, TerminalSession] = {}
-        self._last_client_message: dict[str, float] = {}
-        self._background_tasks: set[asyncio.Task[Any]] = set()
+        self._idle_check_task: asyncio.Task | None = None
+        self._start_idle_check()
 
-    async def create_session(
+    def _start_idle_check(self) -> None:
+        """Start the idle timeout background task."""
+        if self._idle_check_task is not None and not self._idle_check_task.done():
+            return
+        try:
+            loop = asyncio.get_running_loop()
+            self._idle_check_task = loop.create_task(self._idle_check_loop())
+        except RuntimeError:
+            # No event loop running yet, will be started lazily
+            pass
+
+    async def _idle_check_loop(self) -> None:
+        """Periodically check for idle sessions and clean them up."""
+        while True:
+            try:
+                await asyncio.sleep(60)  # Check every minute
+                await self._cleanup_idle_sessions()
+            except Exception as exc:
+                logger.error("Error in idle check loop: %s", exc)
+
+    async def _cleanup_idle_sessions(self) -> None:
+        """Clean up sessions that have been idle for too long."""
+        idle_sessions = []
+        for instance_id, session in list(self._sessions.items()):
+            if session.is_idle():
+                idle_sessions.append(instance_id)
+        
+        for instance_id in idle_sessions:
+            logger.info("Cleaning up idle terminal session for instance %s", instance_id)
+            session = self._sessions.pop(instance_id, None)
+            if session:
+                await session.close()
+
+    async def get_or_create_session(
         self,
         instance_id: uuid.UUID,
         container_id: str,
-        websocket: WebSocket,
     ) -> TerminalSession:
-        """Create a new terminal session."""
+        """Get existing session or create a new one."""
+        # Ensure idle check is running (lazy start)
+        self._start_idle_check()
+        
+        instance_id_str = str(instance_id)
+        
+        # Check for existing session
+        if instance_id_str in self._sessions:
+            session = self._sessions[instance_id_str]
+            
+            # Check if session is still alive
+            if session.is_alive():
+                logger.info("Reattaching to existing terminal session for instance %s", instance_id)
+                return session
+            else:
+                # Session died, clean it up
+                logger.info("Existing session for instance %s is dead, cleaning up", instance_id)
+                await session.close()
+                del self._sessions[instance_id_str]
+        
+        # Create new session
+        logger.info("Creating new terminal session for instance %s", instance_id)
         session_id = str(uuid.uuid4())
         session = TerminalSession(session_id, instance_id, container_id)
         await session.start()
-        self._sessions[session_id] = session
-        self._last_client_message[session_id] = time.monotonic()
-
-        # Start background tasks for I/O streaming
-        self._start_task(self._read_loop(session, websocket))
-        self._start_task(self._write_loop(session, websocket))
-        self._start_task(self._heartbeat_loop(session, websocket))
-
+        self._sessions[instance_id_str] = session
+        
         return session
 
-    def _start_task(self, coro: Coroutine[Any, Any, None]) -> None:
-        """Start a background task and store a reference to prevent GC."""
-        task = asyncio.create_task(coro)
-        self._background_tasks.add(task)
-        task.add_done_callback(self._background_tasks.discard)
-
-    async def _read_loop(
+    async def attach_websocket(
         self,
         session: TerminalSession,
         websocket: WebSocket,
     ) -> None:
-        """Read output from the container and send to WebSocket with batching."""
-        try:
-            buffer = bytearray()
-            last_flush = time.monotonic()
+        """Attach a WebSocket to an existing session."""
+        # Handle concurrent connections - close existing ones
+        if session.has_websockets():
+            logger.info("Closing existing WebSocket connections for instance %s", session.instance_id)
+            for ws in list(session._websockets):
+                try:
+                    await ws.close(code=4000, reason="New connection established")
+                except Exception:
+                    pass
+            session._websockets.clear()
+        
+        # Attach new WebSocket
+        session.attach_websocket(websocket)
+        
+        # Replay buffer
+        buffer = session.get_buffer()
+        if buffer:
+            try:
+                await websocket.send_bytes(buffer)
+            except Exception:
+                pass
 
-            while session.is_alive() and not session.closed:
-                data = await session.read_output(select_timeout=_READ_POLL_TIMEOUT_S)
-                if data:
-                    buffer.extend(data)
-
-                now = time.monotonic()
-                flush_due = buffer and (
-                    now - last_flush >= _READ_BATCH_INTERVAL_S or not data
-                )
-
-                if flush_due:
-                    await websocket.send_bytes(bytes(buffer))
-                    buffer.clear()
-                    last_flush = now
-                elif not data:
-                    await asyncio.sleep(_READ_POLL_SLEEP_S)
-
-            # Flush any remaining data
-            if buffer:
-                with contextlib.suppress(Exception):
-                    await websocket.send_bytes(bytes(buffer))
-
-        except Exception:
-            logger.exception("Read loop error for session %s", session.session_id)
-        finally:
-            await self._cleanup_session(session)
-
-    async def _write_loop(
+    async def detach_websocket(
         self,
         session: TerminalSession,
         websocket: WebSocket,
     ) -> None:
-        """Read input from WebSocket and send to container."""
-        try:
-            while session.is_alive() and not session.closed:
-                message = await websocket.receive()
-                self._last_client_message[session.session_id] = time.monotonic()
+        """Detach a WebSocket from a session."""
+        session.detach_websocket(websocket)
 
-                if message["type"] == "websocket.receive":
-                    if "bytes" in message:
-                        await session.write_input(message["bytes"])
-                    elif "text" in message:
-                        text = message["text"]
-                        if text.startswith("{"):
-                            try:
-                                ctrl = json.loads(text)
-                                await self._handle_control_message(
-                                    session,
-                                    websocket,
-                                    ctrl,
-                                )
-                            except json.JSONDecodeError:
-                                logger.debug("Invalid JSON control message: %s", text)
-                        else:
-                            await session.write_input(text.encode("utf-8"))
-                elif message["type"] == "websocket.disconnect":
-                    break
-        except Exception:
-            logger.exception("Write loop error for session %s", session.session_id)
-        finally:
-            await self._cleanup_session(session)
-
-    async def _handle_control_message(
+    async def reset_session(
         self,
-        session: TerminalSession,
-        websocket: WebSocket,
-        ctrl: dict[str, Any],
-    ) -> None:
-        """Handle a JSON control message from the client."""
-        msg_type = ctrl.get("type")
-        if msg_type == "resize":
-            await session.resize(
-                ctrl.get("cols", 80),
-                ctrl.get("rows", 24),
-            )
-        elif msg_type == "ping":
-            await websocket.send_json(
-                {"type": "pong", "id": ctrl.get("id")},
-            )
-
-    async def _heartbeat_loop(
-        self,
-        session: TerminalSession,
-        websocket: WebSocket,
-    ) -> None:
-        """Monitor client activity and close idle connections."""
-        try:
-            while session.is_alive() and not session.closed:
-                await asyncio.sleep(_HEARTBEAT_INTERVAL_S)
-                last_msg = self._last_client_message.get(session.session_id, 0)
-                if time.monotonic() - last_msg > _IDLE_TIMEOUT_S:
-                    # Client has been silent for 60s — close connection
-                    with contextlib.suppress(Exception):
-                        await websocket.close(
-                            code=1000,
-                            reason="Idle timeout",
-                        )
-                    break
-        except Exception:
-            logger.exception(
-                "Heartbeat loop error for session %s",
-                session.session_id,
-            )
-        finally:
-            await self._cleanup_session(session)
-
-    async def _cleanup_session(self, session: TerminalSession) -> None:
-        """Clean up a session."""
-        if session.session_id in self._sessions:
-            del self._sessions[session.session_id]
-        self._last_client_message.pop(session.session_id, None)
-        await session.close()
+        instance_id: uuid.UUID,
+        container_id: str,
+    ) -> TerminalSession:
+        """Reset a session by killing it and creating a new one."""
+        instance_id_str = str(instance_id)
+        
+        # Close existing session if any
+        if instance_id_str in self._sessions:
+            logger.info("Resetting terminal session for instance %s", instance_id)
+            old_session = self._sessions.pop(instance_id_str)
+            await old_session.close()
+        
+        # Create new session
+        session_id = str(uuid.uuid4())
+        session = TerminalSession(session_id, instance_id, container_id)
+        await session.start()
+        self._sessions[instance_id_str] = session
+        
+        return session
 
     async def close_all(self) -> None:
         """Close all active sessions."""
         sessions = list(self._sessions.values())
         self._sessions.clear()
-        self._last_client_message.clear()
         for session in sessions:
             await session.close()
+        
+        if self._idle_check_task and not self._idle_check_task.done():
+            self._idle_check_task.cancel()
 
 
 # Global terminal manager instance

apps/api/src/services/terminal_session.py

@@ -1,29 +1,34 @@
 """Terminal session management for tool instances."""
 
 import asyncio
-import contextlib
-import fcntl
 import logging
 import os
 import pty
 import select
 import struct
-import termios
+import fcntl
+import time
 import uuid
+from collections import deque
+from typing import Any
 
 logger = logging.getLogger(__name__)
 
 
 class TerminalSession:
-    """Manages a single terminal session connected to a docker container."""
+    """Manages a single terminal session connected to a docker container.
+    
+    Supports persistent sessions that survive WebSocket disconnections.
+    Multiple WebSocket connections can attach/detach from the same session.
+    """
 
-    def __init__(
-        self,
-        session_id: str,
-        instance_id: uuid.UUID,
-        container_id: str,
-    ) -> None:
-        """Initialize a terminal session."""
+    # Circular buffer size (10KB)
+    BUFFER_SIZE = 10 * 1024
+    
+    # Idle timeout in seconds (30 minutes)
+    IDLE_TIMEOUT = 30 * 60
+
+    def __init__(self, session_id: str, instance_id: uuid.UUID, container_id: str) -> None:
         self.session_id = session_id
         self.instance_id = instance_id
         self.container_id = container_id
@@ -31,20 +36,38 @@ class TerminalSession:
         self._closed = False
         self._master_fd: int | None = None
         self._slave_fd: int | None = None
-        self._echo_enabled = True
-        self._exit_reason: str | None = None
+        
+        # Circular buffer for output replay
+        self._output_buffer: deque[bytes] = deque(maxlen=self.BUFFER_SIZE)
+        self._buffer_size = 0
+        
+        # WebSocket connections
+        self._websockets: set[Any] = set()
+        
+        # Activity tracking
+        self.last_activity = time.time()
+        
+        # Terminal size
+        self._cols = 80
+        self._rows = 24
 
     async def start(self) -> None:
         """Start the docker exec process with a shell using a PTY."""
+        # Create a pseudo-terminal on the host
         self._master_fd, self._slave_fd = pty.openpty()
-        self._set_terminal_size(80, 24)
-
+        
+        # Set the terminal size initially
+        self._set_terminal_size(self._cols, self._rows)
+        logger.info(f"Starting terminal session {self.session_id} for container {self.container_id} with initial size {self._cols}x{self._rows}")
+        
+        # Start docker exec with the slave fd as stdin/stdout/stderr
+        # Using -it because the slave fd IS a TTY
         self.process = await asyncio.create_subprocess_exec(
             "docker",
             "exec",
             "-it",
             "-e",
-            "TERM=xterm-256color",
+            "TERM=xterm",
             self.container_id,
             "bash",
             "-il",
@@ -52,81 +75,104 @@ class TerminalSession:
             stdout=self._slave_fd,
             stderr=self._slave_fd,
         )
-
+        
+        # Close slave fd in parent process
         os.close(self._slave_fd)
         self._slave_fd = None
-        self._echo_enabled = self._detect_echo_state()
+        
+        self.last_activity = time.time()
 
     def _set_terminal_size(self, cols: int, rows: int) -> None:
         """Set the terminal size using TIOCSWINSZ."""
         if self._master_fd is None:
+            logger.warning("Cannot resize: master_fd is None (session not started)")
             return
-        tiocswinsz = 0x5414
-        size = struct.pack("HHHH", rows, cols, 0, 0)
-        with contextlib.suppress(OSError):
-            fcntl.ioctl(self._master_fd, tiocswinsz, size)
-
-    def _detect_echo_state(self) -> bool:
-        """Detect whether the PTY has echo enabled via termios."""
-        if self._master_fd is None:
-            return True
+        # TIOCSWINSZ = 0x5414 on Linux
+        TIOCSWINSZ = 0x5414
+        size = struct.pack('HHHH', rows, cols, 0, 0)
         try:
-            attrs = termios.tcgetattr(self._master_fd)
-            return bool(attrs[3] & termios.ECHO)
-        except OSError:
-            return True
+            fcntl.ioctl(self._master_fd, TIOCSWINSZ, size)
+            logger.info(f"Resized PTY to {cols}x{rows} (fd={self._master_fd})")
+        except (OSError, IOError) as e:
+            logger.error(f"Failed to resize PTY: {e}")
 
-    async def check_echo_state(self) -> bool | None:
-        """Check if echo state changed. Returns new state if changed, None otherwise."""
-        current = self._detect_echo_state()
-        if current != self._echo_enabled:
-            self._echo_enabled = current
-            return current
-        return None
-
-    @property
-    def echo_enabled(self) -> bool:
-        """Return whether the PTY currently has echo enabled."""
-        return self._echo_enabled
-
-    @property
-    def closed(self) -> bool:
-        """Return whether the session has been closed."""
-        return self._closed
-
-    async def read_output(self, select_timeout: float = 0.1) -> bytes:
-        """Read output from the PTY master."""
+    async def read_output(self) -> bytes:
+        """Read output from the PTY master and store in buffer."""
         if self._master_fd is None or self._closed:
             return b""
         try:
-            readable, _, _ = select.select(
-                [self._master_fd],
-                [],
-                [],
-                select_timeout,
-            )
+            # Use select to check if data is available
+            readable, _, _ = select.select([self._master_fd], [], [], 0.1)
             if readable:
-                return os.read(self._master_fd, 8192)
+                data = os.read(self._master_fd, 4096)
+                if data:
+                    self._add_to_buffer(data)
+                    self.last_activity = time.time()
+                return data
             return b""
-        except (OSError, ValueError):
+        except (OSError, IOError, ValueError):
             return b""
 
+    def _add_to_buffer(self, data: bytes) -> None:
+        """Add data to circular buffer, maintaining size limit."""
+        self._output_buffer.append(data)
+        self._buffer_size += len(data)
+        
+        # Trim if exceeds max size
+        while self._buffer_size > self.BUFFER_SIZE and self._output_buffer:
+            removed = self._output_buffer.popleft()
+            self._buffer_size -= len(removed)
+
+    def get_buffer(self) -> bytes:
+        """Get buffered output for replay."""
+        return b"".join(self._output_buffer)
+
     async def write_input(self, data: bytes) -> None:
         """Write input to the PTY master."""
         if self._master_fd is None or self._closed:
             return
-        with contextlib.suppress(OSError):
+        try:
             os.write(self._master_fd, data)
+            self.last_activity = time.time()
+        except (OSError, IOError):
+            pass
 
     async def resize(self, cols: int, rows: int) -> None:
         """Resize the terminal."""
         if self._closed:
+            logger.warning("Cannot resize: session is closed")
             return
+        
+        # Only resize if dimensions actually changed
+        if cols == self._cols and rows == self._rows:
+            return
+            
+        self._cols = cols
+        self._rows = rows
+        logger.info(f"resize() called for session {self.session_id}: {cols}x{rows}")
         self._set_terminal_size(cols, rows)
+        
+        # Docker exec doesn't forward PTY resize to the container process,
+        # so we need to explicitly set the size inside the container shell.
+        # Send on every resize so the container shell always matches the frontend.
+        # Use stty -echo to prevent the command from being visible, then clear the line.
+        stty_cmd = (
+            f"stty -echo; stty cols {cols} rows {rows}; stty echo\n"
+            f"\x1b[A\x1b[M"  # Move up 1 line and delete it (clears the stty command)
+        ).encode()
+        await self.write_input(stty_cmd)
+        logger.debug(f"Sent stty resize to container for session {self.session_id}: {cols}x{rows}")
 
-    def get_exit_reason(self) -> str | None:
-        """Return the reason the session ended, if known."""
-        return self._exit_reason
+    async def reset(self) -> None:
+        """Reset the session by killing the process and clearing state."""
+        await self.close()
+        self._closed = False
+        self._output_buffer.clear()
+        self._buffer_size = 0
+        self._websockets.clear()
+        self.process = None
+        self._master_fd = None
+        self._slave_fd = None
 
     async def close(self) -> None:
         """Close the session and cleanup."""
@@ -134,25 +180,18 @@ class TerminalSession:
             return
         self._closed = True
 
-        # Determine exit reason
-        if self.process is not None and self.process.returncode is not None:
-            if self.process.returncode == 0:
-                self._exit_reason = "process_exit"
-            else:
-                self._exit_reason = "process_exit"
-        else:
-            self._exit_reason = "timeout"
-
         if self._master_fd is not None:
-            with contextlib.suppress(OSError):
+            try:
                 os.close(self._master_fd)
+            except OSError:
+                pass
             self._master_fd = None
 
         if self.process is not None:
             try:
                 self.process.kill()
                 await asyncio.wait_for(self.process.wait(), timeout=2.0)
-            except (TimeoutError, ProcessLookupError):
+            except (asyncio.TimeoutError, ProcessLookupError):
                 pass
 
     def is_alive(self) -> bool:
@@ -160,3 +199,35 @@ class TerminalSession:
         if self.process is None:
             return False
         return self.process.returncode is None
+
+    def is_idle(self) -> bool:
+        """Check if the session has been idle for too long."""
+        if self._websockets:
+            return False
+        return time.time() - self.last_activity > self.IDLE_TIMEOUT
+
+    def attach_websocket(self, websocket: Any) -> None:
+        """Attach a WebSocket to this session."""
+        self._websockets.add(websocket)
+        self.last_activity = time.time()
+
+    def detach_websocket(self, websocket: Any) -> None:
+        """Detach a WebSocket from this session."""
+        self._websockets.discard(websocket)
+
+    def has_websockets(self) -> bool:
+        """Check if any WebSockets are attached."""
+        return len(self._websockets) > 0
+
+    async def send_to_all(self, data: bytes) -> None:
+        """Send data to all attached WebSockets."""
+        dead_sockets = set()
+        for ws in self._websockets:
+            try:
+                await ws.send_bytes(data)
+            except Exception:
+                dead_sockets.add(ws)
+        
+        # Clean up dead sockets
+        for ws in dead_sockets:
+            self._websockets.discard(ws)

apps/api/src/utils/git_control.py

@@ -124,7 +124,15 @@ def create_branch(repo_path: str, name: str, base_branch: str = "HEAD") -> None:
     try:
         _run_git_command(repo_path, "rev-parse", "--verify", "HEAD^{commit}")
     except RuntimeError:
-        _run_git_command(repo_path, "checkout", "--orphan", name)
+        # No commits yet - empty repository
+        try:
+            _run_git_command(repo_path, "checkout", "--orphan", name)
+        except RuntimeError as e:
+            if "work tree" in str(e).lower():
+                # Bare repository - use symbolic-ref instead
+                _run_git_command(repo_path, "symbolic-ref", "HEAD", f"refs/heads/{name}")
+                return
+            raise
         return
 
     _run_git_command(repo_path, "branch", name, base_branch)
@@ -155,7 +163,14 @@ def checkout_branch(repo_path: str, name: str) -> None:
     Raises:
         RuntimeError: If checkout fails
     """
-    _run_git_command(repo_path, "checkout", name)
+    try:
+        _run_git_command(repo_path, "checkout", name)
+    except RuntimeError as e:
+        if "work tree" in str(e).lower():
+            # Bare repository - use symbolic-ref instead
+            _run_git_command(repo_path, "symbolic-ref", "HEAD", f"refs/heads/{name}")
+            return
+        raise
 
 
 def commit_changes(
@@ -290,6 +305,10 @@ def get_current_branch(repo_path: str) -> str:
         Current branch name
     """
     try:
-        return _run_git_command(repo_path, "rev-parse", "--abbrev-ref", "HEAD").strip()
+        branch = _run_git_command(repo_path, "rev-parse", "--abbrev-ref", "HEAD").strip()
+        if branch != "HEAD":
+            return branch
     except RuntimeError:
-        return _run_git_command(repo_path, "symbolic-ref", "--short", "HEAD").strip()
+        pass
+
+    return _run_git_command(repo_path, "symbolic-ref", "--short", "HEAD").strip()

apps/api/src/utils/git_files.py

@@ -289,19 +289,37 @@ def list_branches(repo_path: str) -> tuple[list[BranchInfo], str]:
     branches: list[BranchInfo] = []
     default_branch = "main"
 
+    # Get list of remote names to properly filter remote tracking branches
+    try:
+        remote_output = _run_git_command(repo_path, "remote")
+        remote_names = {r.strip() for r in remote_output.strip().split("\n") if r.strip()}
+    except RuntimeError:
+        remote_names = set()
+
     for line in output.strip().split("\n"):
         if not line:
             continue
 
         branch_name = line.strip()
-        # Skip remote tracking branches (they start with remotes/)
-        if branch_name.startswith("remotes/"):
-            # Extract just the branch name part
-            parts = branch_name.split("/", 2)
-            if len(parts) >= 3:
-                branch_name = parts[2]
-            else:
-                continue
+        
+        # Skip detached HEAD pointer
+        if branch_name == "HEAD":
+            continue
+            
+        # Skip remote tracking branches - they appear as "origin/branch-name"
+        # Check if first part is a remote name
+        if "/" in branch_name:
+            first_part = branch_name.split("/", 1)[0]
+            if first_part in remote_names:
+                # Extract just the branch name part (after "origin/")
+                branch_name = branch_name.split("/", 1)[1]
+            elif branch_name.startswith("remotes/"):
+                # Handle "remotes/origin/branch-name" format
+                parts = branch_name.split("/", 2)
+                if len(parts) >= 3:
+                    branch_name = parts[2]
+                else:
+                    continue
 
         # Skip duplicates
         if any(b.name == branch_name for b in branches):

apps/api/src/utils/git_history.py

@@ -60,12 +60,9 @@ def get_commit_history(repo_path: str, branch: str | None = None, limit: int = 1
 
     Returns structured data including commits, branches, and graph information.
     """
-    # Get list of branches (may fail for empty repos)
-    try:
-        branches_output = _run_git_command(repo_path, ["branch", "-a", "--format=%(refname:short)"])
-        branches = [b.strip() for b in branches_output.strip().split("\n") if b.strip()]
-    except RuntimeError:
-        branches = []
+    # Get list of branches
+    branches_output = _run_git_command(repo_path, ["branch", "-a", "--format=%(refname:short)"])
+    branches = [b.strip() for b in branches_output.strip().split("\n") if b.strip()]
 
     # Build git log command - use NULL bytes as separators to avoid parsing issues
     log_args = [
@@ -79,16 +76,7 @@ def get_commit_history(repo_path: str, branch: str | None = None, limit: int = 1
     else:
         log_args.append("--all")
 
-    try:
-        log_output = _run_git_command(repo_path, log_args)
-    except RuntimeError:
-        # Empty repo or no commits
-        return {
-            "commits": [],
-            "branches": branches,
-            "total_commits": 0,
-            "graph_data": {"nodes": [], "edges": []},
-        }
+    log_output = _run_git_command(repo_path, log_args)
 
     # Get branch info for each commit
     branch_map = _get_branch_map(repo_path)
@@ -125,11 +113,8 @@ def get_commit_history(repo_path: str, branch: str | None = None, limit: int = 1
         )
 
     # Get total commit count
-    try:
-        count_output = _run_git_command(repo_path, ["rev-list", "--all", "--count"])
-        total_commits = int(count_output.strip()) if count_output.strip() else 0
-    except RuntimeError:
-        total_commits = 0
+    count_output = _run_git_command(repo_path, ["rev-list", "--all", "--count"])
+    total_commits = int(count_output.strip()) if count_output.strip() else 0
 
     # Build graph data and generate graph symbols
     graph_data = _build_graph_data(commits)

apps/api/tests/conftest.py

@@ -47,10 +47,8 @@ def test_client() -> Generator[TestClient, None, None]:
     app.dependency_overrides[get_db_session] = override_get_db_session
     
     # Patch startup events to prevent PostgreSQL connection attempts
-    with patch("src.main.init_database") as mock_init, \
-         patch("src.main.seed_builtin_tool_types") as mock_seed:
+    with patch("src.main.init_database") as mock_init:
         mock_init.return_value = True
-        mock_seed.return_value = None
         
         try:
             with TestClient(app) as client:
@@ -61,6 +59,31 @@ def test_client() -> Generator[TestClient, None, None]:
             asyncio.run(engine.dispose())
 
 
+@pytest_asyncio.fixture
+async def db_session(test_client) -> AsyncGenerator[AsyncSession, None]:
+    """Provide an async database session for unit tests."""
+    # Get the override function from the test_client fixture
+    override_fn = app.dependency_overrides.get(get_db_session)
+    if override_fn:
+        gen = override_fn()
+        session = await gen.asend(None)
+        try:
+            yield session
+        finally:
+            await gen.aclose()
+    else:
+        # Fallback: create a new engine and session
+        engine = create_async_engine(
+            "sqlite+aiosqlite:///:memory:",
+            connect_args={"check_same_thread": False},
+        )
+        async with engine.begin() as conn:
+            await conn.run_sync(Base.metadata.create_all)
+        async with async_sessionmaker(engine, expire_on_commit=False)() as session:
+            yield session
+        await engine.dispose()
+
+
 @pytest.fixture
 def authenticated_client(test_client) -> Generator[TestClient, None, None]:
     """Provide an authenticated test client with a test user."""

apps/api/tests/integration/test_config_profiles_api.py

@@ -1,7 +1,4 @@
-"""Integration tests for config profiles API."""
-
 import uuid
-
 import pytest
 from fastapi.testclient import TestClient
 
@@ -20,9 +17,7 @@ class TestConfigProfilesAPI:
         response = authenticated_client.get("/config-profiles")
         assert response.status_code == 200
         data = response.json()
-        assert isinstance(data, dict)
-        assert "profiles" in data
-        assert isinstance(data["profiles"], list)
+        assert isinstance(data, list)
 
     def test_create_config_profile_successfully(self, authenticated_client: TestClient) -> None:
         """Test creating a config profile."""
@@ -31,48 +26,99 @@ class TestConfigProfilesAPI:
             json={
                 "name": "test-profile",
                 "description": "Test profile",
+                "env_vars": {"VAR": "value"},
+                "runtime_hints": {"start_command": "npm start"},
+                "mounts": [{"target": "/app", "mode": "rw", "files": {}}],
+                "files": {"test.txt": "hello"},
             },
         )
         assert response.status_code == 201
         data = response.json()
         assert data["name"] == "test-profile"
-        assert data["description"] == "Test profile"
+        assert data["env_vars"] == {"VAR": "value"}
+        assert data["files"] == {"test.txt": "hello"}
+        assert data["mounts"][0]["target"] == "/app"
 
     def test_create_config_profile_duplicate_name(self, authenticated_client: TestClient) -> None:
         """Test that duplicate profile names are rejected."""
-        authenticated_client.post(
-            "/config-profiles",
-            json={"name": "duplicate-profile"},
-        )
-
+        # Create first profile
         response = authenticated_client.post(
             "/config-profiles",
-            json={"name": "duplicate-profile"},
+            json={
+                "name": "duplicate-profile",
+                "env_vars": {},
+                "files": {},
+            },
+        )
+        assert response.status_code == 201
+
+        # Try to create second with same name
+        response = authenticated_client.post(
+            "/config-profiles",
+            json={
+                "name": "duplicate-profile",
+                "env_vars": {},
+                "files": {},
+            },
         )
         assert response.status_code == 409
 
-    def test_create_config_profile_empty_name(self, authenticated_client: TestClient) -> None:
-        """Test that empty profile names are rejected."""
+    def test_create_config_profile_exceeds_size_limit(self, authenticated_client: TestClient) -> None:
+        """Test that profiles exceeding 10MB are rejected."""
+        large_content = "x" * (11 * 1024 * 1024)  # 11MB
         response = authenticated_client.post(
             "/config-profiles",
-            json={"name": "  "},
+            json={
+                "name": "large-profile",
+                "env_vars": {},
+                "files": {"large.txt": large_content},
+            },
+        )
+        assert response.status_code == 413
+
+    def test_create_config_profile_invalid_file_path(self, authenticated_client: TestClient) -> None:
+        """Test that invalid file paths are rejected."""
+        response = authenticated_client.post(
+            "/config-profiles",
+            json={
+                "name": "bad-profile",
+                "env_vars": {},
+                "files": {"../../../etc/passwd": "malicious"},
+            },
+        )
+        assert response.status_code == 422
+
+    def test_create_config_profile_invalid_mount_target(self, authenticated_client: TestClient) -> None:
+        """Test that invalid mount targets are rejected."""
+        response = authenticated_client.post(
+            "/config-profiles",
+            json={
+                "name": "bad-mount-profile",
+                "env_vars": {},
+                "files": {},
+                "mounts": [{"target": "relative/path", "mode": "rw", "files": {}}],
+            },
         )
         assert response.status_code == 422
 
     def test_get_config_profile_by_id(self, authenticated_client: TestClient) -> None:
         """Test getting a config profile by ID."""
+        # Create profile first
         create_response = authenticated_client.post(
             "/config-profiles",
-            json={"name": "get-test"},
+            json={
+                "name": "get-test",
+                "env_vars": {},
+                "files": {},
+            },
         )
         profile_id = create_response.json()["id"]
 
+        # Get it back
         response = authenticated_client.get(f"/config-profiles/{profile_id}")
         assert response.status_code == 200
         data = response.json()
         assert data["name"] == "get-test"
-        assert "includes" in data
-        assert "mounts" in data
 
     def test_get_config_profile_not_found(self, authenticated_client: TestClient) -> None:
         """Test getting a non-existent profile."""
@@ -81,381 +127,196 @@ class TestConfigProfilesAPI:
 
     def test_update_config_profile_successfully(self, authenticated_client: TestClient) -> None:
         """Test updating a config profile."""
+        # Create profile first
         create_response = authenticated_client.post(
             "/config-profiles",
-            json={"name": "update-test"},
+            json={
+                "name": "update-test",
+                "env_vars": {},
+                "files": {},
+            },
         )
         profile_id = create_response.json()["id"]
 
+        # Update it
         response = authenticated_client.put(
             f"/config-profiles/{profile_id}",
-            json={"name": "updated-name", "description": "updated desc"},
+            json={
+                "name": "updated-name",
+                "env_vars": {"NEW_VAR": "new_value"},
+            },
         )
         assert response.status_code == 200
         data = response.json()
         assert data["name"] == "updated-name"
-        assert data["description"] == "updated desc"
+        assert data["env_vars"] == {"NEW_VAR": "new_value"}
 
     def test_delete_config_profile_successfully(self, authenticated_client: TestClient) -> None:
         """Test deleting a config profile."""
+        # Create profile first
         create_response = authenticated_client.post(
             "/config-profiles",
-            json={"name": "delete-test"},
+            json={
+                "name": "delete-test",
+                "env_vars": {},
+                "files": {},
+            },
         )
         profile_id = create_response.json()["id"]
 
+        # Delete it
         response = authenticated_client.delete(f"/config-profiles/{profile_id}")
         assert response.status_code == 204
 
+        # Verify it's gone
         get_response = authenticated_client.get(f"/config-profiles/{profile_id}")
         assert get_response.status_code == 404
 
-    def test_profile_access_check(self, authenticated_client: TestClient) -> None:
-        """Test that users can only access their own profiles."""
-        # Create a profile
-        create_response = authenticated_client.post(
+    def test_update_profile_includes_successfully(self, authenticated_client: TestClient) -> None:
+        """Test updating profile includes."""
+        # Create base profile
+        base_response = authenticated_client.post(
             "/config-profiles",
-            json={"name": "access-test"},
+            json={
+                "name": "base-profile",
+                "env_vars": {"BASE_VAR": "base_value"},
+                "files": {},
+            },
         )
-        profile_id = create_response.json()["id"]
+        base_id = base_response.json()["id"]
 
-        # The profile should be accessible
-        response = authenticated_client.get(f"/config-profiles/{profile_id}")
-        assert response.status_code == 200
-
-
-@pytest.mark.integration
-class TestConfigProfileIncludes:
-    """Integration tests for config profile includes."""
-
-    def test_add_include_successfully(self, authenticated_client: TestClient) -> None:
-        """Test adding an include to a profile."""
-        # Create two profiles
-        profile1 = authenticated_client.post(
+        # Create child profile
+        child_response = authenticated_client.post(
             "/config-profiles",
-            json={"name": "profile-1"},
-        ).json()
-        profile2 = authenticated_client.post(
-            "/config-profiles",
-            json={"name": "profile-2"},
-        ).json()
-
-        # Add include
-        response = authenticated_client.post(
-            f"/config-profiles/{profile1['id']}/includes",
-            json={"included_profile_id": profile2["id"], "order_index": 0},
+            json={
+                "name": "child-profile",
+                "env_vars": {},
+                "files": {},
+            },
         )
-        assert response.status_code == 201
-        data = response.json()
-        assert data["included_profile_id"] == profile2["id"]
-        assert data["included_profile_name"] == "profile-2"
-
-    def test_add_self_include_rejected(self, authenticated_client: TestClient) -> None:
-        """Test that self-includes are rejected."""
-        profile = authenticated_client.post(
-            "/config-profiles",
-            json={"name": "self-include-test"},
-        ).json()
-
-        response = authenticated_client.post(
-            f"/config-profiles/{profile['id']}/includes",
-            json={"included_profile_id": profile["id"], "order_index": 0},
-        )
-        assert response.status_code == 400
-
-    def test_add_include_cycle_rejected(self, authenticated_client: TestClient) -> None:
-        """Test that circular includes are rejected."""
-        profile1 = authenticated_client.post(
-            "/config-profiles",
-            json={"name": "cycle-1"},
-        ).json()
-        profile2 = authenticated_client.post(
-            "/config-profiles",
-            json={"name": "cycle-2"},
-        ).json()
-
-        # Add profile1 includes profile2
-        authenticated_client.post(
-            f"/config-profiles/{profile1['id']}/includes",
-            json={"included_profile_id": profile2["id"], "order_index": 0},
-        )
-
-        # Try to add profile2 includes profile1 (creates cycle)
-        response = authenticated_client.post(
-            f"/config-profiles/{profile2['id']}/includes",
-            json={"included_profile_id": profile1["id"], "order_index": 0},
-        )
-        assert response.status_code == 400
-
-    def test_add_deep_cycle_rejected(self, authenticated_client: TestClient) -> None:
-        """Test that deep circular includes are rejected."""
-        p1 = authenticated_client.post(
-            "/config-profiles", json={"name": "deep-1"}
-        ).json()
-        p2 = authenticated_client.post(
-            "/config-profiles", json={"name": "deep-2"}
-        ).json()
-        p3 = authenticated_client.post(
-            "/config-profiles", json={"name": "deep-3"}
-        ).json()
-
-        # p1 -> p2 -> p3
-        authenticated_client.post(
-            f"/config-profiles/{p1['id']}/includes",
-            json={"included_profile_id": p2["id"], "order_index": 0},
-        )
-        authenticated_client.post(
-            f"/config-profiles/{p2['id']}/includes",
-            json={"included_profile_id": p3["id"], "order_index": 0},
-        )
-
-        # Try p3 -> p1 (creates cycle)
-        response = authenticated_client.post(
-            f"/config-profiles/{p3['id']}/includes",
-            json={"included_profile_id": p1["id"], "order_index": 0},
-        )
-        assert response.status_code == 400
-
-    def test_add_duplicate_include_rejected(self, authenticated_client: TestClient) -> None:
-        """Test that duplicate includes are rejected."""
-        p1 = authenticated_client.post(
-            "/config-profiles", json={"name": "dup-1"}
-        ).json()
-        p2 = authenticated_client.post(
-            "/config-profiles", json={"name": "dup-2"}
-        ).json()
-
-        authenticated_client.post(
-            f"/config-profiles/{p1['id']}/includes",
-            json={"included_profile_id": p2["id"], "order_index": 0},
-        )
-
-        response = authenticated_client.post(
-            f"/config-profiles/{p1['id']}/includes",
-            json={"included_profile_id": p2["id"], "order_index": 1},
-        )
-        assert response.status_code == 409
-
-    def test_list_includes(self, authenticated_client: TestClient) -> None:
-        """Test listing includes for a profile."""
-        p1 = authenticated_client.post(
-            "/config-profiles", json={"name": "list-inc-1"}
-        ).json()
-        p2 = authenticated_client.post(
-            "/config-profiles", json={"name": "list-inc-2"}
-        ).json()
-
-        authenticated_client.post(
-            f"/config-profiles/{p1['id']}/includes",
-            json={"included_profile_id": p2["id"], "order_index": 0},
-        )
-
-        response = authenticated_client.get(f"/config-profiles/{p1['id']}/includes")
-        assert response.status_code == 200
-        data = response.json()
-        assert len(data["includes"]) == 1
-
-    def test_update_include_order(self, authenticated_client: TestClient) -> None:
-        """Test updating include order index."""
-        p1 = authenticated_client.post(
-            "/config-profiles", json={"name": "order-1"}
-        ).json()
-        p2 = authenticated_client.post(
-            "/config-profiles", json={"name": "order-2"}
-        ).json()
-
-        inc = authenticated_client.post(
-            f"/config-profiles/{p1['id']}/includes",
-            json={"included_profile_id": p2["id"], "order_index": 0},
-        ).json()
+        child_id = child_response.json()["id"]
 
+        # Update includes
         response = authenticated_client.put(
-            f"/config-profiles/{p1['id']}/includes/{inc['id']}",
-            json={"order_index": 5},
-        )
-        assert response.status_code == 200
-        assert response.json()["order_index"] == 5
-
-    def test_remove_include(self, authenticated_client: TestClient) -> None:
-        """Test removing an include."""
-        p1 = authenticated_client.post(
-            "/config-profiles", json={"name": "rem-1"}
-        ).json()
-        p2 = authenticated_client.post(
-            "/config-profiles", json={"name": "rem-2"}
-        ).json()
-
-        inc = authenticated_client.post(
-            f"/config-profiles/{p1['id']}/includes",
-            json={"included_profile_id": p2["id"], "order_index": 0},
-        ).json()
-
-        response = authenticated_client.delete(
-            f"/config-profiles/{p1['id']}/includes/{inc['id']}"
-        )
-        assert response.status_code == 204
-
-
-@pytest.mark.integration
-class TestConfigProfileMounts:
-    """Integration tests for config profile mounts."""
-
-    def test_add_mount_successfully(self, authenticated_client: TestClient) -> None:
-        """Test adding a mount to a profile."""
-        profile = authenticated_client.post(
-            "/config-profiles",
-            json={"name": "mount-test"},
-        ).json()
-
-        response = authenticated_client.post(
-            f"/config-profiles/{profile['id']}/mounts",
-            json={"target_path": "/etc/config", "files": {"test.txt": "hello"}, "order_index": 0},
-        )
-        assert response.status_code == 201
-        data = response.json()
-        assert data["target_path"] == "/etc/config"
-        assert data["files"] == {"test.txt": "hello"}
-
-    def test_add_mount_relative_path_rejected(self, authenticated_client: TestClient) -> None:
-        """Test that relative mount paths are rejected."""
-        profile = authenticated_client.post(
-            "/config-profiles",
-            json={"name": "rel-path-test"},
-        ).json()
-
-        response = authenticated_client.post(
-            f"/config-profiles/{profile['id']}/mounts",
-            json={"target_path": "etc/config", "files": {"test.txt": "hello"}},
-        )
-        assert response.status_code == 422
-
-    def test_add_target_path_traversal_rejected(self, authenticated_client: TestClient) -> None:
-        """Test that path traversal in mount paths is rejected."""
-        profile = authenticated_client.post(
-            "/config-profiles",
-            json={"name": "traversal-test"},
-        ).json()
-
-        response = authenticated_client.post(
-            f"/config-profiles/{profile['id']}/mounts",
-            json={"target_path": "/etc/../passwd", "files": {"test.txt": "hello"}},
-        )
-        assert response.status_code == 422
-
-    def test_add_duplicate_mount_rejected(self, authenticated_client: TestClient) -> None:
-        """Test that duplicate mount paths are rejected."""
-        profile = authenticated_client.post(
-            "/config-profiles",
-            json={"name": "dup-mount-test"},
-        ).json()
-
-        authenticated_client.post(
-            f"/config-profiles/{profile['id']}/mounts",
-            json={"target_path": "/etc/config", "files": {"test.txt": "hello"}},
-        )
-
-        response = authenticated_client.post(
-            f"/config-profiles/{profile['id']}/mounts",
-            json={"target_path": "/etc/config", "files": {"test.txt": "world"}},
-        )
-        assert response.status_code == 409
-
-    def test_update_mount(self, authenticated_client: TestClient) -> None:
-        """Test updating a mount."""
-        profile = authenticated_client.post(
-            "/config-profiles",
-            json={"name": "update-mount-test"},
-        ).json()
-
-        mount = authenticated_client.post(
-            f"/config-profiles/{profile['id']}/mounts",
-            json={"target_path": "/old/path", "files": {"test.txt": "old"}},
-        ).json()
-
-        response = authenticated_client.put(
-            f"/config-profiles/{profile['id']}/mounts/{mount['id']}",
-            json={"target_path": "/new/path", "files": {"test.txt": "new"}, "order_index": 2},
+            f"/config-profiles/{child_id}/includes",
+            json={"includes": [base_id]},
         )
         assert response.status_code == 200
         data = response.json()
-        assert data["target_path"] == "/new/path"
-        assert data["files"] == {"test.txt": "new"}
-        assert data["order_index"] == 2
+        print(f"Response data: {data}")
+        print(f"Includes: {data.get('includes', 'NO INCLUDES KEY')}")
+        assert len(data["includes"]) == 1, f"Expected 1 include, got {len(data.get('includes', []))}: {data.get('includes', [])}"
+        assert data["includes"][0]["included_profile_id"] == base_id
 
-    def test_remove_mount(self, authenticated_client: TestClient) -> None:
-        """Test removing a mount."""
-        profile = authenticated_client.post(
+    def test_update_profile_includes_cycle_detection(self, authenticated_client: TestClient) -> None:
+        """Test that include cycles are detected."""
+        # Create profile A
+        a_response = authenticated_client.post(
             "/config-profiles",
-            json={"name": "rem-mount-test"},
-        ).json()
-
-        mount = authenticated_client.post(
-            f"/config-profiles/{profile['id']}/mounts",
-            json={"target_path": "/tmp/test", "files": {"test.txt": "x"}},
-        ).json()
-
-        response = authenticated_client.delete(
-            f"/config-profiles/{profile['id']}/mounts/{mount['id']}"
+            json={
+                "name": "profile-a",
+                "env_vars": {},
+                "files": {},
+            },
         )
-        assert response.status_code == 204
+        a_id = a_response.json()["id"]
 
-
-@pytest.mark.integration
-class TestConfigProfileDefaults:
-    """Integration tests for default profile APIs."""
-
-    def test_get_default_profiles_empty(self, authenticated_client: TestClient) -> None:
-        """Test getting default profiles when none are set."""
-        response = authenticated_client.get("/config-profiles/defaults")
-        assert response.status_code == 200
-        data = response.json()
-        assert data["default_profiles"] == {}
-
-    def test_set_default_profiles(self, authenticated_client: TestClient) -> None:
-        """Test setting default profiles."""
-        profile = authenticated_client.post(
+        # Create profile B
+        b_response = authenticated_client.post(
             "/config-profiles",
-            json={"name": "default-test"},
-        ).json()
-
-        response = authenticated_client.put(
-            "/config-profiles/defaults",
-            json={"default_profiles": {"code-server": profile["id"]}},
+            json={
+                "name": "profile-b",
+                "env_vars": {},
+                "files": {},
+            },
         )
-        assert response.status_code == 200
-        data = response.json()
-        assert data["default_profiles"]["code-server"] == profile["id"]
-
-    def test_set_default_profiles_invalid_profile(self, authenticated_client: TestClient) -> None:
-        """Test setting default profiles with invalid profile ID."""
-        response = authenticated_client.put(
-            "/config-profiles/defaults",
-            json={"default_profiles": {"code-server": str(uuid.uuid4())}},
-        )
-        assert response.status_code == 404
-
-    def test_get_default_profile_for_tool_type(self, authenticated_client: TestClient) -> None:
-        """Test getting default profile for a specific tool type."""
-        profile = authenticated_client.post(
-            "/config-profiles",
-            json={"name": "tool-default-test"},
-        ).json()
+        b_id = b_response.json()["id"]
 
+        # Make B include A
         authenticated_client.put(
-            "/config-profiles/defaults",
-            json={"default_profiles": {"jupyter-notebook": profile["id"]}},
+            f"/config-profiles/{b_id}/includes",
+            json={"includes": [a_id]},
         )
 
-        response = authenticated_client.get("/config-profiles/defaults/jupyter-notebook")
-        assert response.status_code == 200
-        data = response.json()
-        assert data["tool_type_id"] == "jupyter-notebook"
-        assert data["profile_id"] == profile["id"]
+        # Try to make A include B (would create cycle)
+        response = authenticated_client.put(
+            f"/config-profiles/{a_id}/includes",
+            json={"includes": [b_id]},
+        )
+        assert response.status_code == 400
 
-    def test_get_default_profile_for_tool_type_not_set(self, authenticated_client: TestClient) -> None:
-        """Test getting default profile when not set."""
-        response = authenticated_client.get("/config-profiles/defaults/opencode")
+    def test_preview_config_profile_successfully(self, authenticated_client: TestClient) -> None:
+        """Test previewing a resolved config profile."""
+        # Create base profile
+        base_response = authenticated_client.post(
+            "/config-profiles",
+            json={
+                "name": "preview-base",
+                "env_vars": {"BASE_VAR": "base"},
+                "files": {},
+            },
+        )
+        base_id = base_response.json()["id"]
+
+        # Create child profile
+        child_response = authenticated_client.post(
+            "/config-profiles",
+            json={
+                "name": "preview-child",
+                "env_vars": {"CHILD_VAR": "child"},
+                "files": {},
+            },
+        )
+        child_id = child_response.json()["id"]
+
+        # Make child include base
+        authenticated_client.put(
+            f"/config-profiles/{child_id}/includes",
+            json={"includes": [base_id]},
+        )
+
+        # Preview child
+        response = authenticated_client.get(f"/config-profiles/{child_id}/preview")
+        assert response.status_code == 200
+        data = response.json()
+        assert data["profile_name"] == "preview-child"
+        assert data["env_vars"]["BASE_VAR"] == "base"
+        assert data["env_vars"]["CHILD_VAR"] == "child"
+        assert len(data["included_profiles"]) == 1
+
+    def test_resolve_default_profile(self, authenticated_client: TestClient) -> None:
+        """Test resolving default profile for project/tool."""
+        # Create a global default profile (no project/tool scoping)
+        authenticated_client.post(
+            "/config-profiles",
+            json={
+                "name": "default-profile",
+                "env_vars": {},
+                "files": {},
+                "is_default": True,
+            },
+        )
+
+        # Resolve default with random project/tool (should fall back to global)
+        project_id = str(uuid.uuid4())
+        tool_type_id = str(uuid.uuid4())
+        response = authenticated_client.get(
+            "/config-profiles/defaults/resolve",
+            params={"project_id": project_id, "tool_type_id": tool_type_id},
+        )
+        assert response.status_code == 200
+        data = response.json()
+        assert data["profile_name"] == "default-profile"
+
+    def test_resolve_default_profile_no_match(self, authenticated_client: TestClient) -> None:
+        """Test resolving default profile when no profiles exist."""
+        project_id = str(uuid.uuid4())
+        tool_type_id = str(uuid.uuid4())
+
+        response = authenticated_client.get(
+            "/config-profiles/defaults/resolve",
+            params={"project_id": project_id, "tool_type_id": tool_type_id},
+        )
         assert response.status_code == 200
         data = response.json()
-        assert data["tool_type_id"] == "opencode"
         assert data["profile_id"] is None

apps/api/tests/integration/test_git_control.py

@@ -70,6 +70,20 @@ def test_get_current_branch_handles_unborn_main() -> None:
         assert get_current_branch(tmpdir) == "main"
 
 
+def test_create_branch_on_bare_repo_with_no_commits() -> None:
+    with tempfile.TemporaryDirectory() as tmpdir:
+        os.system(f"git init --bare {tmpdir}/bare.git >/dev/null 2>&1")
+        create_branch(f"{tmpdir}/bare.git", "main")
+        assert get_current_branch(f"{tmpdir}/bare.git") == "main"
+
+
+def test_checkout_branch_on_bare_repo_with_no_commits() -> None:
+    with tempfile.TemporaryDirectory() as tmpdir:
+        os.system(f"git init --bare {tmpdir}/bare.git >/dev/null 2>&1")
+        checkout_branch(f"{tmpdir}/bare.git", "main")
+        assert get_current_branch(f"{tmpdir}/bare.git") == "main"
+
+
 class TestBranchOperations:
     """Tests for branch management functions."""
 

apps/api/tests/integration/test_projects_api.py

@@ -1,5 +1,5 @@
 import uuid
-from datetime import datetime, timedelta, timezone
+from datetime import UTC, datetime, timedelta
 import asyncio
 
 import pytest
@@ -58,7 +58,7 @@ def _mint_token(user_id: str) -> str:
         subject=user_id,
         email="test@headquarter.local",
         name="Test User",
-        expires_at=datetime.now(timezone.utc) + timedelta(minutes=15),
+        expires_at=datetime.now(UTC) + timedelta(minutes=15),
     )
 
 

apps/api/tests/integration/test_tool_types_api.py

@@ -1,5 +1,5 @@
 import uuid
-from datetime import datetime, timedelta, timezone
+from datetime import UTC, datetime, timedelta
 import asyncio
 
 import pytest
@@ -59,7 +59,7 @@ def _mint_token(user_id: str) -> str:
         subject=user_id,
         email="test@headquarter.local",
         name="Test User",
-        expires_at=datetime.now(timezone.utc) + timedelta(minutes=15),
+        expires_at=datetime.now(UTC) + timedelta(minutes=15),
     )
 
 
@@ -98,7 +98,6 @@ def _insert_tool_type(
     name: str,
     display_name: str,
     compose_template: str,
-    is_builtin: bool = False,
     created_by_id: str | None = None,
 ) -> None:
     async def _run() -> None:
@@ -120,7 +119,6 @@ def _insert_tool_type(
                 description="A test tool type",
                 compose_template=compose_template,
                 required_variables=["REPO_PATH", "TOOL_NAME"],
-                is_builtin=is_builtin,
                 created_by_id=uuid.UUID(created_by_id) if created_by_id else None,
             )
             await session.merge(tool_type)
@@ -234,7 +232,6 @@ def test_create_tool_type_successfully() -> None:
     assert data["name"] == "my-custom-tool"
     assert data["display_name"] == "My Custom Tool"
     assert data["description"] == "A custom development tool"
-    assert data["is_builtin"] == False
     assert data["created_by_id"] == user_id
     assert "id" in data
 
@@ -376,28 +373,7 @@ def test_update_tool_type_not_found() -> None:
     assert response.status_code == 404
 
 
-@pytest.mark.integration
-def test_update_builtin_tool_type_fails() -> None:
-    _prepare_test_db()
-    user_id = "11111111-1111-1111-1111-111111111111"
-    tool_type_id = "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
-    _insert_user(user_id)
-    _insert_tool_type(
-        tool_type_id,
-        "builtin-tool",
-        "Built-in Tool",
-        "version: '3.8'\nservices:\n  app:\n    image: builtin",
-        is_builtin=True,
-    )
-    
-    app = _load_app()
-    client = TestClient(app)
-    client.cookies.set("access_token", _mint_token(user_id))
 
-    payload = {"display_name": "Updated"}
-    response = client.put(f"/tool-types/{tool_type_id}", json=payload)
-    
-    assert response.status_code == 403
 
 
 @pytest.mark.integration
@@ -442,53 +418,4 @@ def test_delete_tool_type_not_found() -> None:
     assert response.status_code == 404
 
 
-@pytest.mark.integration
-def test_delete_builtin_tool_type_fails() -> None:
-    _prepare_test_db()
-    user_id = "11111111-1111-1111-1111-111111111111"
-    tool_type_id = "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
-    _insert_user(user_id)
-    _insert_tool_type(
-        tool_type_id,
-        "builtin-tool",
-        "Built-in Tool",
-        "version: '3.8'\nservices:\n  app:\n    image: builtin",
-        is_builtin=True,
-    )
-    
-    app = _load_app()
-    client = TestClient(app)
-    client.cookies.set("access_token", _mint_token(user_id))
 
-    response = client.delete(f"/tool-types/{tool_type_id}")
-    
-    assert response.status_code == 403
-
-
-@pytest.mark.integration
-def test_builtin_tool_types_seeded_on_startup() -> None:
-    _prepare_test_db()
-    user_id = "11111111-1111-1111-1111-111111111111"
-    _insert_user(user_id)
-    
-    # Load app triggers startup event which seeds built-in types
-    app = _load_app()
-    client = TestClient(app)
-    client.cookies.set("access_token", _mint_token(user_id))
-
-    response = client.get("/tool-types")
-    
-    assert response.status_code == 200
-    data = response.json()
-    
-    # Check that built-in types exist
-    builtin_names = [t["name"] for t in data if t["is_builtin"]]
-    assert "code-server" in builtin_names
-    assert "jupyter-notebook" in builtin_names
-    
-    # Verify built-in types have correct attributes
-    code_server = next((t for t in data if t["name"] == "code-server"), None)
-    assert code_server is not None
-    assert code_server["display_name"] == "VS Code Server"
-    assert "services" in code_server["compose_template"]
-    assert code_server["required_variables"] == ["REPO_PATH", "TOOL_NAME"]

apps/api/tests/integration/test_tool_types_api_extended.py

@@ -39,7 +39,7 @@ class TestToolTypesAPIExtended:
                 "interfaces": ["web"],
                 "default_port": 8080,
                 "definition_type": "compose",
-                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: nginx",
+                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: nginx\n    ports:\n      - '8080:8080'",
                 "readiness_probe": {
                     "command": "curl -f http://localhost:8080",
                     "timeout": 30,
@@ -92,7 +92,7 @@ class TestToolTypesAPIExtended:
                 "display_name": "Update Test Tool",
                 "default_port": 8080,
                 "definition_type": "compose",
-                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: nginx",
+                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: nginx\n    ports:\n      - '8080:8080'",
                 "required_variables": [],
             },
         )
@@ -167,7 +167,7 @@ class TestToolTypesAPIExtended:
                 "interfaces": ["web", "terminal"],
                 "default_port": 8443,
                 "definition_type": "compose",
-                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: code-server\n    volumes:\n      - \"{{REPO_PATH}}:/workspace\"",
+                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: code-server\n    ports:\n      - '8443:8443'\n    volumes:\n      - \"{{REPO_PATH}}:/workspace\"",
                 "readiness_probe": {
                     "command": "curl -f http://localhost:8443",
                     "timeout": 30,
@@ -186,3 +186,40 @@ class TestToolTypesAPIExtended:
         assert data["category"] == "editor"
         assert data["interfaces"] == ["web", "terminal"]
         assert "readiness_probe" in data
+
+    def test_create_tool_type_without_port_fails(self, authenticated_client: TestClient) -> None:
+        """Test that creating a tool type without default_port fails validation."""
+        response = authenticated_client.post(
+            "/tool-types",
+            json={
+                "name": "no-port-tool",
+                "display_name": "No Port Tool",
+                "category": "utility",
+                "interfaces": ["web"],
+                "definition_type": "compose",
+                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: nginx\n    ports:\n      - '8080:8080'",
+                "required_variables": [],
+            },
+        )
+        assert response.status_code == 422
+        data = response.json()
+        assert "default_port" in str(data)
+
+    def test_create_tool_type_with_port_mismatch_fails(self, authenticated_client: TestClient) -> None:
+        """Test that port mismatch between default_port and compose template fails."""
+        response = authenticated_client.post(
+            "/tool-types",
+            json={
+                "name": "port-mismatch-tool",
+                "display_name": "Port Mismatch Tool",
+                "category": "utility",
+                "interfaces": ["web"],
+                "default_port": 9999,
+                "definition_type": "compose",
+                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: nginx\n    ports:\n      - '8080:8080'",
+                "required_variables": [],
+            },
+        )
+        assert response.status_code == 422
+        data = response.json()
+        assert "Port 9999 is not exposed" in str(data)

apps/api/tests/integration/test_users_api.py

@@ -1,5 +1,5 @@
 import uuid
-from datetime import datetime, timedelta, timezone
+from datetime import UTC, datetime, timedelta
 import asyncio
 import io
 
@@ -83,7 +83,7 @@ def _create_auth_cookie(user_id: str) -> str:
         subject=user_id,
         email="test@headquarter.local",
         name="Test User",
-        expires_at=datetime.now(timezone.utc) + timedelta(minutes=15),
+        expires_at=datetime.now(UTC) + timedelta(minutes=15),
     )
 
 

apps/api/tests/unit/test_config_profile_resolver.py

@@ -0,0 +1,383 @@
+import uuid
+import pytest
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.models.config_profile import ConfigProfile, ConfigProfileInclude
+from src.services.config_profile_resolver import (
+    ConfigProfileCycleError,
+    ConfigProfileNotFoundError,
+    ResolvedProfile,
+    check_include_cycle,
+    resolve_profile,
+    _merge_env_vars,
+    _merge_files,
+    _merge_mounts,
+    _merge_runtime_hints,
+)
+
+
+class TestMergeFunctions:
+    """Unit tests for merge helper functions."""
+
+    def test_merge_env_vars_basic(self) -> None:
+        """Test basic env var merging."""
+        result = _merge_env_vars(
+            {"A": "1", "B": "2"},
+            {"B": "3", "C": "4"},
+            {},
+            "source",
+        )
+        assert result == {"A": "1", "B": "3", "C": "4"}
+
+    def test_merge_env_vars_tracks_overrides(self) -> None:
+        """Test that env var overrides are tracked."""
+        overrides = {}
+        _merge_env_vars(
+            {"A": "1"},
+            {"A": "2"},
+            overrides,
+            "source",
+        )
+        assert overrides == {"A": "source"}
+
+    def test_merge_runtime_hints_basic(self) -> None:
+        """Test basic runtime hint merging."""
+        result = _merge_runtime_hints(
+            {"command": "old"},
+            {"command": "new", "port": 8080},
+            {},
+            "source",
+        )
+        assert result == {"command": "new", "port": 8080}
+
+    def test_merge_files_basic(self) -> None:
+        """Test basic file merging."""
+        result = _merge_files(
+            {"a.txt": "old"},
+            {"a.txt": "new", "b.txt": "content"},
+            {},
+            "source",
+        )
+        assert result == {"a.txt": "new", "b.txt": "content"}
+
+    def test_merge_mounts_basic(self) -> None:
+        """Test basic mount merging."""
+        from src.services.config_profile_resolver import ResolvedMount
+        result = _merge_mounts(
+            {},
+            [{"target": "/app", "mode": "rw", "files": {"a.txt": "content"}}],
+            {},
+            "source",
+        )
+        assert "/app" in result
+        assert result["/app"].mode == "rw"
+        assert result["/app"].files == {"a.txt": "content"}
+
+    def test_merge_mounts_file_override(self) -> None:
+        """Test mount file map merging with overrides."""
+        from src.services.config_profile_resolver import ResolvedMount
+        result = _merge_mounts(
+            {"/app": ResolvedMount(target="/app", mode="rw", files={"a.txt": "old"})},
+            [{"target": "/app", "mode": "rw", "files": {"a.txt": "new"}}],
+            {},
+            "source",
+        )
+        assert result["/app"].files == {"a.txt": "new"}
+
+    def test_merge_mounts_mode_conflict(self) -> None:
+        """Test that mount mode conflicts are resolved (later wins)."""
+        from src.services.config_profile_resolver import ResolvedMount
+        overrides = {}
+        result = _merge_mounts(
+            {"/app": ResolvedMount(target="/app", mode="rw", files={})},
+            [{"target": "/app", "mode": "ro", "files": {}}],
+            overrides,
+            "source",
+        )
+        assert result["/app"].mode == "ro"
+        assert overrides == {"/app": "source"}
+
+
+class TestResolveProfile:
+    """Unit tests for profile resolution."""
+
+    @pytest.mark.asyncio
+    async def test_resolve_simple_profile(self, db_session: AsyncSession) -> None:
+        """Test resolving a profile with no includes."""
+        user_id = uuid.uuid4()
+        profile = ConfigProfile(
+            id=uuid.uuid4(),
+            user_id=user_id,
+            name="simple",
+            env_vars={"VAR": "value"},
+            runtime_hints={"command": "run"},
+            files={"test.txt": "content"},
+            mounts=[{"target": "/app", "mode": "rw", "files": {}}],
+        )
+        db_session.add(profile)
+        await db_session.commit()
+
+        result = await resolve_profile(db_session, profile.id)
+        assert result.profile_name == "simple"
+        assert result.env_vars == {"VAR": "value"}
+        assert result.runtime_hints == {"command": "run"}
+        assert result.files == {"test.txt": "content"}
+
+    @pytest.mark.asyncio
+    async def test_resolve_profile_with_includes(self, db_session: AsyncSession) -> None:
+        """Test resolving a profile that includes another."""
+        user_id = uuid.uuid4()
+
+        # Create base profile
+        base = ConfigProfile(
+            id=uuid.uuid4(),
+            user_id=user_id,
+            name="base",
+            env_vars={"BASE_VAR": "base_value"},
+            files={},
+        )
+        db_session.add(base)
+
+        # Create child profile
+        child = ConfigProfile(
+            id=uuid.uuid4(),
+            user_id=user_id,
+            name="child",
+            env_vars={"CHILD_VAR": "child_value"},
+            files={},
+        )
+        db_session.add(child)
+        await db_session.commit()
+
+        # Create include relationship
+        include = ConfigProfileInclude(
+            id=uuid.uuid4(),
+            profile_id=child.id,
+            included_profile_id=base.id,
+            order_index=0,
+        )
+        db_session.add(include)
+        await db_session.commit()
+
+        result = await resolve_profile(db_session, child.id)
+        assert result.env_vars == {
+            "BASE_VAR": "base_value",
+            "CHILD_VAR": "child_value",
+        }
+        assert len(result.included_profiles) == 1
+        assert result.included_profiles[0]["name"] == "base"
+
+    @pytest.mark.asyncio
+    async def test_resolve_profile_child_overrides_parent(self, db_session: AsyncSession) -> None:
+        """Test that child profile values override parent values."""
+        user_id = uuid.uuid4()
+
+        base = ConfigProfile(
+            id=uuid.uuid4(),
+            user_id=user_id,
+            name="base",
+            env_vars={"VAR": "base"},
+            files={},
+        )
+        db_session.add(base)
+
+        child = ConfigProfile(
+            id=uuid.uuid4(),
+            user_id=user_id,
+            name="child",
+            env_vars={"VAR": "child"},
+            files={},
+        )
+        db_session.add(child)
+        await db_session.commit()
+
+        include = ConfigProfileInclude(
+            id=uuid.uuid4(),
+            profile_id=child.id,
+            included_profile_id=base.id,
+            order_index=0,
+        )
+        db_session.add(include)
+        await db_session.commit()
+
+        result = await resolve_profile(db_session, child.id)
+        assert result.env_vars == {"VAR": "child"}
+        assert result.env_overrides == {"VAR": "child"}
+
+    @pytest.mark.asyncio
+    async def test_resolve_profile_cycle_detection(self, db_session: AsyncSession) -> None:
+        """Test that cycles are detected during resolution."""
+        user_id = uuid.uuid4()
+
+        profile_a = ConfigProfile(
+            id=uuid.uuid4(),
+            user_id=user_id,
+            name="a",
+            env_vars={},
+            files={},
+        )
+        db_session.add(profile_a)
+
+        profile_b = ConfigProfile(
+            id=uuid.uuid4(),
+            user_id=user_id,
+            name="b",
+            env_vars={},
+            files={},
+        )
+        db_session.add(profile_b)
+        await db_session.commit()
+
+        # A includes B
+        include_ab = ConfigProfileInclude(
+            id=uuid.uuid4(),
+            profile_id=profile_a.id,
+            included_profile_id=profile_b.id,
+            order_index=0,
+        )
+        db_session.add(include_ab)
+
+        # B includes A (creates cycle)
+        include_ba = ConfigProfileInclude(
+            id=uuid.uuid4(),
+            profile_id=profile_b.id,
+            included_profile_id=profile_a.id,
+            order_index=0,
+        )
+        db_session.add(include_ba)
+        await db_session.commit()
+
+        with pytest.raises(ConfigProfileCycleError):
+            await resolve_profile(db_session, profile_a.id)
+
+    @pytest.mark.asyncio
+    async def test_resolve_profile_not_found(self, db_session: AsyncSession) -> None:
+        """Test resolving a non-existent profile."""
+        with pytest.raises(ConfigProfileNotFoundError):
+            await resolve_profile(db_session, uuid.uuid4())
+
+
+class TestCheckIncludeCycle:
+    """Unit tests for include cycle checking."""
+
+    @pytest.mark.asyncio
+    async def test_check_no_cycle(self, db_session: AsyncSession) -> None:
+        """Test checking when no cycle exists."""
+        user_id = uuid.uuid4()
+
+        profile_a = ConfigProfile(
+            id=uuid.uuid4(),
+            user_id=user_id,
+            name="a",
+            env_vars={},
+            files={},
+        )
+        db_session.add(profile_a)
+
+        profile_b = ConfigProfile(
+            id=uuid.uuid4(),
+            user_id=user_id,
+            name="b",
+            env_vars={},
+            files={},
+        )
+        db_session.add(profile_b)
+        await db_session.commit()
+
+        # A includes B
+        include = ConfigProfileInclude(
+            id=uuid.uuid4(),
+            profile_id=profile_a.id,
+            included_profile_id=profile_b.id,
+            order_index=0,
+        )
+        db_session.add(include)
+        await db_session.commit()
+
+        result = await check_include_cycle(db_session, profile_a.id)
+        assert result is None
+
+    @pytest.mark.asyncio
+    async def test_check_detects_cycle(self, db_session: AsyncSession) -> None:
+        """Test detecting an existing cycle."""
+        user_id = uuid.uuid4()
+
+        profile_a = ConfigProfile(
+            id=uuid.uuid4(),
+            user_id=user_id,
+            name="a",
+            env_vars={},
+            files={},
+        )
+        db_session.add(profile_a)
+
+        profile_b = ConfigProfile(
+            id=uuid.uuid4(),
+            user_id=user_id,
+            name="b",
+            env_vars={},
+            files={},
+        )
+        db_session.add(profile_b)
+        await db_session.commit()
+
+        # A includes B
+        include_ab = ConfigProfileInclude(
+            id=uuid.uuid4(),
+            profile_id=profile_a.id,
+            included_profile_id=profile_b.id,
+            order_index=0,
+        )
+        db_session.add(include_ab)
+
+        # B includes A
+        include_ba = ConfigProfileInclude(
+            id=uuid.uuid4(),
+            profile_id=profile_b.id,
+            included_profile_id=profile_a.id,
+            order_index=0,
+        )
+        db_session.add(include_ba)
+        await db_session.commit()
+
+        result = await check_include_cycle(db_session, profile_a.id)
+        assert result is not None
+        assert len(result) > 1
+
+    @pytest.mark.asyncio
+    async def test_check_would_create_cycle(self, db_session: AsyncSession) -> None:
+        """Test detecting a cycle that would be created."""
+        user_id = uuid.uuid4()
+
+        profile_a = ConfigProfile(
+            id=uuid.uuid4(),
+            user_id=user_id,
+            name="a",
+            env_vars={},
+            files={},
+        )
+        db_session.add(profile_a)
+
+        profile_b = ConfigProfile(
+            id=uuid.uuid4(),
+            user_id=user_id,
+            name="b",
+            env_vars={},
+            files={},
+        )
+        db_session.add(profile_b)
+        await db_session.commit()
+
+        # A includes B
+        include = ConfigProfileInclude(
+            id=uuid.uuid4(),
+            profile_id=profile_a.id,
+            included_profile_id=profile_b.id,
+            order_index=0,
+        )
+        db_session.add(include)
+        await db_session.commit()
+
+        # Check if adding B includes A would create cycle
+        result = await check_include_cycle(db_session, profile_b.id, profile_a.id)
+        assert result is not None

apps/api/tests/unit/test_migration_metadata.py

@@ -39,18 +39,3 @@ def test_refresh_tokens_migration_has_expected_revision_chain() -> None:
 
     assert module.revision == "0002_refresh_tokens"
     assert module.down_revision == "0001_initial_schema"
-
-
-@pytest.mark.unit
-def test_config_profiles_migration_has_expected_revision_chain() -> None:
-    migration_path = Path(__file__).resolve().parents[2] / "alembic" / "versions" / "0013_add_config_profiles.py"
-    spec = spec_from_file_location("add_config_profiles", migration_path)
-
-    assert spec is not None
-    assert spec.loader is not None
-
-    module = module_from_spec(spec)
-    spec.loader.exec_module(module)
-
-    assert module.revision == "0013_add_config_profiles"
-    assert module.down_revision == "0012_default_port_req"

apps/api/tests/unit/test_profile_resolver.py

@@ -1,463 +0,0 @@
-"""Unit tests for the profile resolver service."""
-
-import uuid
-from unittest.mock import MagicMock
-
-import pytest
-
-from src.services.profile_resolver import (
-    ProfileCycleError,
-    ResolvedProfileOutput,
-    resolve_profile,
-)
-
-
-def _make_profile(
-    name: str,
-    env_vars: dict[str, str] | None = None,
-    start_command: str | None = None,
-    working_directory: str | None = None,
-    port: int | None = None,
-    mounts: list[MagicMock] | None = None,
-    includes: list[MagicMock] | None = None,
-) -> MagicMock:
-    """Create a mock ConfigProfile for testing."""
-    profile = MagicMock()
-    profile.id = uuid.uuid4()
-    profile.name = name
-    profile.environment_variables = env_vars or {}
-    profile.start_command = start_command
-    profile.working_directory = working_directory
-    profile.port = port
-    profile.mounts = mounts or []
-    profile.includes = includes or []
-    return profile
-
-
-def _make_include(included_profile: MagicMock, order_index: int = 0) -> MagicMock:
-    """Create a mock ConfigInclude for testing."""
-    include = MagicMock()
-    include.included_profile = included_profile
-    include.order_index = order_index
-    return include
-
-
-def _make_mount(
-    target_path: str,
-    mode: str = "rw",
-    files: dict[str, str] | None = None,
-    order_index: int = 0,
-) -> MagicMock:
-    """Create a mock ConfigMount for testing."""
-    mount = MagicMock()
-    mount.target_path = target_path
-    mount.mode = mode
-    mount.files = files or {}
-    mount.order_index = order_index
-    return mount
-
-
-class TestResolveProfileBasic:
-    """Tests for basic profile resolution without includes."""
-
-    def test_empty_profile(self) -> None:
-        """Resolving an empty profile returns empty output."""
-        profile = _make_profile("empty")
-        result = resolve_profile(profile)
-
-        assert isinstance(result, ResolvedProfileOutput)
-        assert result.profile_name == "empty"
-        assert result.environment_variables == {}
-        assert result.runtime_hints.start_command is None
-        assert result.runtime_hints.working_directory is None
-        assert result.runtime_hints.port is None
-        assert result.mounts == {}
-        assert result.resolution_order == ["empty"]
-
-    def test_env_vars_only(self) -> None:
-        """Profile with env vars resolves correctly."""
-        profile = _make_profile(
-            "env-only",
-            env_vars={"FOO": "bar", "BAZ": "qux"},
-        )
-        result = resolve_profile(profile)
-
-        assert result.environment_variables == {"FOO": "bar", "BAZ": "qux"}
-        assert result.env_var_sources == {
-            "FOO": ["env-only"],
-            "BAZ": ["env-only"],
-        }
-
-    def test_runtime_hints_only(self) -> None:
-        """Profile with runtime hints resolves correctly."""
-        profile = _make_profile(
-            "hints-only",
-            start_command="python app.py",
-            working_directory="/app",
-            port=8080,
-        )
-        result = resolve_profile(profile)
-
-        assert result.runtime_hints.start_command == "python app.py"
-        assert result.runtime_hints.working_directory == "/app"
-        assert result.runtime_hints.port == 8080
-        assert result.runtime_hints.overridden_hints == {
-            "start_command": "hints-only",
-            "working_directory": "hints-only",
-            "port": "hints-only",
-        }
-
-    def test_mounts_only(self) -> None:
-        """Profile with mounts resolves correctly."""
-        profile = _make_profile(
-            "mounts-only",
-            mounts=[
-                _make_mount(
-                    "/config",
-                    mode="ro",
-                    files={"settings.json": '{"key": "value"}'},
-                ),
-            ],
-        )
-        result = resolve_profile(profile)
-
-        assert "/config" in result.mounts
-        mount = result.mounts["/config"]
-        assert mount.target_path == "/config"
-        assert mount.mode == "ro"
-        assert mount.files == {"settings.json": '{"key": "value"}'}
-
-
-class TestResolveProfileIncludes:
-    """Tests for profile resolution with includes."""
-
-    def test_single_include(self) -> None:
-        """Profile with one include resolves in correct order."""
-        base = _make_profile("base", env_vars={"FOO": "base"})
-        derived = _make_profile(
-            "derived",
-            env_vars={"BAR": "derived"},
-            includes=[_make_include(base, order_index=0)],
-        )
-        result = resolve_profile(derived)
-
-        assert result.resolution_order == ["derived", "base"]
-        assert result.environment_variables == {
-            "FOO": "base",
-            "BAR": "derived",
-        }
-
-    def test_multiple_includes_ordered(self) -> None:
-        """Multiple includes are resolved in order_index order."""
-        first = _make_profile("first", env_vars={"KEY": "first"})
-        second = _make_profile("second", env_vars={"KEY": "second"})
-        main = _make_profile(
-            "main",
-            includes=[
-                _make_include(first, order_index=0),
-                _make_include(second, order_index=1),
-            ],
-        )
-        result = resolve_profile(main)
-
-        assert result.resolution_order == ["main", "first", "second"]
-        # second overrides first
-        assert result.environment_variables == {"KEY": "second"}
-        assert result.env_var_sources["KEY"] == ["first", "second"]
-
-    def test_include_order_matters(self) -> None:
-        """Changing include order changes resolution."""
-        a = _make_profile("a", env_vars={"KEY": "a"})
-        b = _make_profile("b", env_vars={"KEY": "b"})
-        main1 = _make_profile(
-            "main",
-            includes=[
-                _make_include(a, order_index=0),
-                _make_include(b, order_index=1),
-            ],
-        )
-        main2 = _make_profile(
-            "main",
-            includes=[
-                _make_include(b, order_index=0),
-                _make_include(a, order_index=1),
-            ],
-        )
-
-        result1 = resolve_profile(main1)
-        result2 = resolve_profile(main2)
-
-        assert result1.environment_variables["KEY"] == "b"
-        assert result2.environment_variables["KEY"] == "a"
-
-    def test_nested_includes(self) -> None:
-        """Deeply nested includes resolve recursively."""
-        deep = _make_profile("deep", env_vars={"DEEP": "value"})
-        mid = _make_profile(
-            "mid",
-            env_vars={"MID": "value"},
-            includes=[_make_include(deep, order_index=0)],
-        )
-        top = _make_profile(
-            "top",
-            env_vars={"TOP": "value"},
-            includes=[_make_include(mid, order_index=0)],
-        )
-        result = resolve_profile(top)
-
-        assert result.resolution_order == ["top", "mid", "deep"]
-        assert result.environment_variables == {
-            "TOP": "value",
-            "MID": "value",
-            "DEEP": "value",
-        }
-
-
-class TestResolveProfileOverrides:
-    """Tests for deterministic override rules."""
-
-    def test_env_var_override(self) -> None:
-        """Later layers override earlier env vars."""
-        base = _make_profile("base", env_vars={"KEY": "base"})
-        override = _make_profile("override", env_vars={"KEY": "override"})
-        main = _make_profile(
-            "main",
-            includes=[
-                _make_include(base, order_index=0),
-                _make_include(override, order_index=1),
-            ],
-        )
-        result = resolve_profile(main)
-
-        assert result.environment_variables["KEY"] == "override"
-        assert result.env_var_sources["KEY"] == ["base", "override"]
-
-    def test_main_profile_wins_over_includes(self) -> None:
-        """The main profile itself wins over all includes."""
-        base = _make_profile("base", env_vars={"KEY": "base"})
-        main = _make_profile(
-            "main",
-            env_vars={"KEY": "main"},
-            includes=[_make_include(base, order_index=0)],
-        )
-        result = resolve_profile(main)
-
-        assert result.environment_variables["KEY"] == "main"
-        assert result.env_var_sources["KEY"] == ["base", "main"]
-
-    def test_runtime_hint_override(self) -> None:
-        """Later layers override earlier runtime hints."""
-        base = _make_profile("base", start_command="python old.py")
-        override = _make_profile("override", start_command="python new.py")
-        main = _make_profile(
-            "main",
-            includes=[
-                _make_include(base, order_index=0),
-                _make_include(override, order_index=1),
-            ],
-        )
-        result = resolve_profile(main)
-
-        assert result.runtime_hints.start_command == "python new.py"
-        assert result.runtime_hints.overridden_hints["start_command"] == "override"
-
-    def test_mount_file_override(self) -> None:
-        """Later layers override earlier files in the same mount."""
-        base = _make_profile(
-            "base",
-            mounts=[
-                _make_mount(
-                    "/config",
-                    files={"app.json": '{"v": 1}'},
-                ),
-            ],
-        )
-        override = _make_profile(
-            "override",
-            mounts=[
-                _make_mount(
-                    "/config",
-                    files={"app.json": '{"v": 2}'},
-                ),
-            ],
-        )
-        main = _make_profile(
-            "main",
-            includes=[
-                _make_include(base, order_index=0),
-                _make_include(override, order_index=1),
-            ],
-        )
-        result = resolve_profile(main)
-
-        mount = result.mounts["/config"]
-        assert mount.files["app.json"] == '{"v": 2}'
-        assert mount.overridden_files["app.json"] == ["override"]
-
-    def test_mount_mode_override(self) -> None:
-        """Later layers override mount mode."""
-        base = _make_profile(
-            "base",
-            mounts=[_make_mount("/data", mode="ro")],
-        )
-        override = _make_profile(
-            "override",
-            mounts=[_make_mount("/data", mode="rw")],
-        )
-        main = _make_profile(
-            "main",
-            includes=[
-                _make_include(base, order_index=0),
-                _make_include(override, order_index=1),
-            ],
-        )
-        result = resolve_profile(main)
-
-        assert result.mounts["/data"].mode == "rw"
-        assert result.mounts["/data"].mode_overridden_by == "override"
-
-    def test_mount_file_merge(self) -> None:
-        """Different files in the same mount are merged."""
-        base = _make_profile(
-            "base",
-            mounts=[
-                _make_mount(
-                    "/config",
-                    files={"a.json": "1"},
-                ),
-            ],
-        )
-        override = _make_profile(
-            "override",
-            mounts=[
-                _make_mount(
-                    "/config",
-                    files={"b.json": "2"},
-                ),
-            ],
-        )
-        main = _make_profile(
-            "main",
-            includes=[
-                _make_include(base, order_index=0),
-                _make_include(override, order_index=1),
-            ],
-        )
-        result = resolve_profile(main)
-
-        mount = result.mounts["/config"]
-        assert mount.files == {"a.json": "1", "b.json": "2"}
-
-
-class TestResolveProfileCycles:
-    """Tests for cycle detection during resolution."""
-
-    def test_direct_cycle(self) -> None:
-        """A -> B -> A is detected."""
-        a = _make_profile("a")
-        b = _make_profile("b", includes=[_make_include(a, order_index=0)])
-        a.includes = [_make_include(b, order_index=0)]
-
-        with pytest.raises(ProfileCycleError) as exc_info:
-            resolve_profile(a)
-
-        assert "a" in exc_info.value.cycle_path
-        assert "b" in exc_info.value.cycle_path
-
-    def test_indirect_cycle(self) -> None:
-        """A -> B -> C -> A is detected."""
-        a = _make_profile("a")
-        c = _make_profile("c")
-        b = _make_profile("b", includes=[_make_include(c, order_index=0)])
-        a.includes = [_make_include(b, order_index=0)]
-        c.includes = [_make_include(a, order_index=0)]
-
-        with pytest.raises(ProfileCycleError) as exc_info:
-            resolve_profile(a)
-
-        assert "a" in exc_info.value.cycle_path
-        assert "b" in exc_info.value.cycle_path
-        assert "c" in exc_info.value.cycle_path
-
-    def test_self_cycle(self) -> None:
-        """A -> A is detected."""
-        a = _make_profile("a")
-        a.includes = [_make_include(a, order_index=0)]
-
-        with pytest.raises(ProfileCycleError) as exc_info:
-            resolve_profile(a)
-
-        assert exc_info.value.cycle_path == ["a", "a"]
-
-    def test_cycle_does_not_partially_resolve(self) -> None:
-        """Cycle detection prevents any partial resolution."""
-        a = _make_profile("a", env_vars={"A": "a"})
-        b = _make_profile("b", env_vars={"B": "b"})
-        a.includes = [_make_include(b, order_index=0)]
-        b.includes = [_make_include(a, order_index=0)]
-
-        with pytest.raises(ProfileCycleError):
-            resolve_profile(a)
-
-
-class TestResolveProfileDiamond:
-    """Tests for diamond-shaped include graphs."""
-
-    def test_diamond_resolution(self) -> None:
-        """Diamond graph resolves correctly without duplication issues."""
-        base = _make_profile("base", env_vars={"BASE": "base"})
-        left = _make_profile(
-            "left",
-            env_vars={"LEFT": "left"},
-            includes=[_make_include(base, order_index=0)],
-        )
-        right = _make_profile(
-            "right",
-            env_vars={"RIGHT": "right"},
-            includes=[_make_include(base, order_index=0)],
-        )
-        top = _make_profile(
-            "top",
-            env_vars={"TOP": "top"},
-            includes=[
-                _make_include(left, order_index=0),
-                _make_include(right, order_index=1),
-            ],
-        )
-        result = resolve_profile(top)
-
-        # base should appear once (via left, then right skips because visited)
-        assert result.resolution_order == ["top", "left", "base", "right"]
-        assert result.environment_variables == {
-            "TOP": "top",
-            "LEFT": "left",
-            "RIGHT": "right",
-            "BASE": "base",
-        }
-
-    def test_diamond_override(self) -> None:
-        """Diamond graph with conflicting overrides resolves correctly."""
-        base = _make_profile("base", env_vars={"KEY": "base"})
-        left = _make_profile(
-            "left",
-            env_vars={"KEY": "left"},
-            includes=[_make_include(base, order_index=0)],
-        )
-        right = _make_profile(
-            "right",
-            env_vars={"KEY": "right"},
-            includes=[_make_include(base, order_index=0)],
-        )
-        top = _make_profile(
-            "top",
-            includes=[
-                _make_include(left, order_index=0),
-                _make_include(right, order_index=1),
-            ],
-        )
-        result = resolve_profile(top)
-
-        # right wins because it's later
-        assert result.environment_variables["KEY"] == "right"
-        assert result.env_var_sources["KEY"] == ["base", "left", "right"]
-        # Note: base appears once because visited set skips duplicate resolution in diamond graphs

apps/api/tests/unit/test_session_branch_selection.py

@@ -0,0 +1,182 @@
+"""Tests for session creation with branch selection and new branch creation."""
+
+import os
+import subprocess
+import tempfile
+from unittest.mock import MagicMock, patch
+
+import pytest
+from fastapi.testclient import TestClient
+
+from src.api.tool_instances import CreateInstanceRequest
+
+
+class TestCreateInstanceRequest:
+    """Tests for CreateInstanceRequest model."""
+
+    def test_default_values(self):
+        """Test default values for CreateInstanceRequest."""
+        request = CreateInstanceRequest(tool_type_id="123")
+        assert request.clone_mode == "mount"
+        assert request.branch == "main"
+        assert request.new_branch is None
+        assert request.display_name is None
+
+    def test_clone_mode_with_branch(self):
+        """Test CreateInstanceRequest with clone mode and branch."""
+        request = CreateInstanceRequest(
+            tool_type_id="123",
+            clone_mode="clone",
+            branch="dev",
+        )
+        assert request.clone_mode == "clone"
+        assert request.branch == "dev"
+
+    def test_new_branch_field(self):
+        """Test CreateInstanceRequest with new_branch field."""
+        request = CreateInstanceRequest(
+            tool_type_id="123",
+            clone_mode="clone",
+            branch="main",
+            new_branch="feature/test",
+        )
+        assert request.new_branch == "feature/test"
+
+
+class TestBranchCreationInClone:
+    """Tests for branch creation logic in clone process."""
+
+    def test_create_local_branch_success(self):
+        """Test successful local branch creation."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            # Initialize repo
+            subprocess.run(
+                ["git", "init", tmpdir],
+                capture_output=True,
+                check=True,
+            )
+            subprocess.run(
+                ["git", "-C", tmpdir, "config", "user.email", "test@test.com"],
+                capture_output=True,
+                check=True,
+            )
+            subprocess.run(
+                ["git", "-C", tmpdir, "config", "user.name", "Test User"],
+                capture_output=True,
+                check=True,
+            )
+            
+            # Create initial commit
+            readme = os.path.join(tmpdir, "README.md")
+            with open(readme, "w") as f:
+                f.write("# Test\n")
+            subprocess.run(
+                ["git", "-C", tmpdir, "add", "README.md"],
+                capture_output=True,
+                check=True,
+            )
+            subprocess.run(
+                ["git", "-C", tmpdir, "commit", "-m", "Initial commit"],
+                capture_output=True,
+                check=True,
+            )
+            
+            # Create new branch
+            result = subprocess.run(
+                ["git", "-C", tmpdir, "checkout", "-b", "feature/new-branch"],
+                capture_output=True,
+                text=True,
+            )
+            
+            assert result.returncode == 0
+            
+            # Verify branch exists
+            branches_result = subprocess.run(
+                ["git", "-C", tmpdir, "branch", "--show-current"],
+                capture_output=True,
+                text=True,
+            )
+            assert branches_result.stdout.strip() == "feature/new-branch"
+
+    def test_create_local_branch_invalid_name(self):
+        """Test local branch creation with invalid name fails."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            # Initialize repo
+            subprocess.run(
+                ["git", "init", tmpdir],
+                capture_output=True,
+                check=True,
+            )
+            subprocess.run(
+                ["git", "-C", tmpdir, "config", "user.email", "test@test.com"],
+                capture_output=True,
+                check=True,
+            )
+            subprocess.run(
+                ["git", "-C", tmpdir, "config", "user.name", "Test User"],
+                capture_output=True,
+                check=True,
+            )
+            
+            # Create initial commit
+            readme = os.path.join(tmpdir, "README.md")
+            with open(readme, "w") as f:
+                f.write("# Test\n")
+            subprocess.run(
+                ["git", "-C", tmpdir, "add", "README.md"],
+                capture_output=True,
+                check=True,
+            )
+            subprocess.run(
+                ["git", "-C", tmpdir, "commit", "-m", "Initial commit"],
+                capture_output=True,
+                check=True,
+            )
+            
+            # Try to create branch with invalid name (contains spaces)
+            result = subprocess.run(
+                ["git", "-C", tmpdir, "checkout", "-b", "invalid branch name"],
+                capture_output=True,
+                text=True,
+            )
+            
+            # Git accepts branch names with spaces but it's not recommended
+            # This test verifies the command structure
+            assert result.returncode == 0 or "fatal" in result.stderr
+
+
+class TestCreateInstanceAPI:
+    """Tests for create instance API endpoint with branch options."""
+
+    def test_create_instance_request_validation(self):
+        """Test that CreateInstanceRequest validates correctly."""
+        # Valid request with new_branch
+        request = CreateInstanceRequest(
+            tool_type_id="550e8400-e29b-41d4-a716-446655440000",
+            clone_mode="clone",
+            branch="main",
+            new_branch="feature/test",
+        )
+        assert request.new_branch == "feature/test"
+        
+        # Valid request without new_branch
+        request2 = CreateInstanceRequest(
+            tool_type_id="550e8400-e29b-41d4-a716-446655440000",
+            clone_mode="clone",
+            branch="dev",
+        )
+        assert request2.new_branch is None
+
+    def test_create_instance_with_new_branch_sets_instance_branch(self):
+        """Test that instance branch is set to new_branch when provided."""
+        # This tests the logic: data.new_branch if data.new_branch else data.branch
+        new_branch = "feature/test"
+        base_branch = "main"
+        
+        # Simulate the logic from create_instance
+        stored_branch = new_branch if new_branch else base_branch
+        assert stored_branch == "feature/test"
+        
+        # Without new_branch
+        stored_branch2 = None if None else base_branch
+        assert stored_branch2 == "main"

apps/api/tests/unit/test_terminal_manager.py

@@ -1,112 +0,0 @@
-"""Unit tests for TerminalManager."""
-
-from unittest.mock import AsyncMock, MagicMock, patch
-
-import pytest
-
-from src.services.terminal_manager import TerminalManager
-from src.services.terminal_session import TerminalSession
-
-
-@pytest.fixture
-def manager():
-    return TerminalManager()
-
-
-@pytest.fixture
-def mock_websocket():
-    ws = AsyncMock()
-    ws.send_bytes = AsyncMock()
-    ws.send_json = AsyncMock()
-    ws.close = AsyncMock()
-    ws.receive = AsyncMock()
-    return ws
-
-
-@pytest.fixture
-def mock_session():
-    session = MagicMock(spec=TerminalSession)
-    session.session_id = "sess-123"
-    session.is_alive.return_value = True
-    session._closed = False
-    session.read_output = AsyncMock(return_value=b"")
-    session.write_input = AsyncMock()
-    session.resize = AsyncMock()
-    session.close = AsyncMock()
-    session.get_exit_reason.return_value = None
-    return session
-
-
-class TestCreateSession:
-    @patch("src.services.terminal_manager.asyncio.create_task")
-    @patch("src.services.terminal_manager.uuid.uuid4", return_value="sess-123")
-    async def test_create_session_registers_and_starts_loops(
-        self, mock_uuid, mock_create_task, manager, mock_websocket
-    ):
-        instance_id = __import__("uuid").uuid4()
-        mock_sess = MagicMock()
-        mock_sess.session_id = "sess-123"
-        mock_sess.is_alive.return_value = True
-        mock_sess._closed = False
-        mock_sess.start = AsyncMock()
-        mock_sess.read_output = AsyncMock(return_value=b"")
-        mock_sess.write_input = AsyncMock()
-        mock_sess.resize = AsyncMock()
-        mock_sess.close = AsyncMock()
-        mock_sess.get_exit_reason.return_value = None
-
-        with (
-            patch.object(manager, "_read_loop", new=AsyncMock()),
-            patch.object(manager, "_write_loop", new=AsyncMock()),
-            patch.object(manager, "_heartbeat_loop", new=AsyncMock()),
-            patch(
-                "src.services.terminal_manager.TerminalSession",
-                return_value=mock_sess,
-            ),
-        ):
-            session = await manager.create_session(
-                instance_id, "container-abc", mock_websocket
-            )
-            assert session.session_id == "sess-123"
-            assert "sess-123" in manager._sessions
-            assert "sess-123" in manager._last_client_message
-
-
-class TestHandleControlMessage:
-    async def test_handle_resize(self, manager, mock_session, mock_websocket):
-        ctrl = {"type": "resize", "cols": 120, "rows": 40}
-        await manager._handle_control_message(mock_session, mock_websocket, ctrl)
-        mock_session.resize.assert_awaited_once_with(120, 40)
-
-    async def test_handle_ping(self, manager, mock_session, mock_websocket):
-        ctrl = {"type": "ping", "id": 42}
-        await manager._handle_control_message(mock_session, mock_websocket, ctrl)
-        mock_websocket.send_json.assert_awaited_once_with({"type": "pong", "id": 42})
-
-    async def test_handle_unknown_type(self, manager, mock_session, mock_websocket):
-        ctrl = {"type": "unknown", "data": "test"}
-        await manager._handle_control_message(mock_session, mock_websocket, ctrl)
-        mock_websocket.send_json.assert_not_awaited()
-        mock_session.resize.assert_not_awaited()
-
-
-class TestCleanupSession:
-    async def test_cleanup_removes_session(self, manager, mock_session):
-        manager._sessions["sess-123"] = mock_session
-        manager._last_client_message["sess-123"] = 123.0
-
-        await manager._cleanup_session(mock_session)
-        assert "sess-123" not in manager._sessions
-        assert "sess-123" not in manager._last_client_message
-        mock_session.close.assert_awaited_once()
-
-
-class TestCloseAll:
-    async def test_close_all_clears_sessions(self, manager, mock_session):
-        manager._sessions["sess-123"] = mock_session
-        manager._last_client_message["sess-123"] = 123.0
-
-        await manager.close_all()
-        assert len(manager._sessions) == 0
-        assert len(manager._last_client_message) == 0
-        mock_session.close.assert_awaited_once()

apps/api/tests/unit/test_terminal_session.py

@@ -1,168 +0,0 @@
-"""Unit tests for TerminalSession."""
-
-import asyncio
-from unittest.mock import MagicMock, patch
-
-import pytest
-
-from src.services.terminal_session import TerminalSession
-
-
-@pytest.fixture
-def mock_pty():
-    """Mock pty.openpty to return predictable fds."""
-    master_fd = 10
-    slave_fd = 11
-    with (
-        patch(
-            "src.services.terminal_session.pty.openpty",
-            return_value=(master_fd, slave_fd),
-        ),
-        patch("src.services.terminal_session.os.close") as mock_close,
-    ):
-        yield master_fd, slave_fd, mock_close
-
-
-class TestTerminalSessionStart:
-    def test_init_state(self, mock_pty):
-        session = TerminalSession("sess-1", __import__("uuid").uuid4(), "container-abc")
-
-        assert session.session_id == "sess-1"
-        assert session.container_id == "container-abc"
-        assert session._echo_enabled is True
-        assert session._exit_reason is None
-
-
-class TestTerminalSessionEchoDetection:
-    @patch("src.services.terminal_session.termios.tcgetattr")
-    def test_detect_echo_state_enabled(self, mock_tcgetattr):
-        session = TerminalSession("sess-1", __import__("uuid").uuid4(), "container-abc")
-        session._master_fd = 10
-
-        # termios.ECHO flag set
-        attrs = [[], [], [], __import__("termios").ECHO, [], [], []]
-        mock_tcgetattr.return_value = attrs
-
-        result = session._detect_echo_state()
-        assert result is True
-
-    @patch("src.services.terminal_session.termios.tcgetattr")
-    def test_detect_echo_state_disabled(self, mock_tcgetattr):
-        session = TerminalSession("sess-1", __import__("uuid").uuid4(), "container-abc")
-        session._master_fd = 10
-
-        # termios.ECHO flag NOT set
-        attrs = [[], [], [], 0, [], [], []]
-        mock_tcgetattr.return_value = attrs
-
-        result = session._detect_echo_state()
-        assert result is False
-
-    def test_detect_echo_state_no_master_fd(self):
-        session = TerminalSession("sess-1", __import__("uuid").uuid4(), "container-abc")
-        session._master_fd = None
-
-        result = session._detect_echo_state()
-        assert result is True  # default
-
-
-class TestTerminalSessionResize:
-    @patch("src.services.terminal_session.fcntl.ioctl")
-    def test_resize_sets_size(self, mock_ioctl):
-        session = TerminalSession("sess-1", __import__("uuid").uuid4(), "container-abc")
-        session._master_fd = 10
-
-        # Should not raise
-        asyncio.run(session.resize(120, 40))
-        mock_ioctl.assert_called_once()
-
-    def test_resize_when_closed(self):
-        session = TerminalSession("sess-1", __import__("uuid").uuid4(), "container-abc")
-        session._closed = True
-
-        # Should not raise
-        asyncio.run(session.resize(120, 40))
-
-
-class TestTerminalSessionWriteInput:
-    @patch("src.services.terminal_session.os.write")
-    def test_write_input(self, mock_write):
-        session = TerminalSession("sess-1", __import__("uuid").uuid4(), "container-abc")
-        session._master_fd = 10
-
-        asyncio.run(session.write_input(b"hello"))
-        mock_write.assert_called_once_with(10, b"hello")
-
-    def test_write_input_when_closed(self):
-        session = TerminalSession("sess-1", __import__("uuid").uuid4(), "container-abc")
-        session._closed = True
-
-        # Should not raise
-        asyncio.run(session.write_input(b"hello"))
-
-
-class TestTerminalSessionReadOutput:
-    @patch("src.services.terminal_session.select.select")
-    @patch("src.services.terminal_session.os.read")
-    def test_read_output_with_data(self, mock_read, mock_select):
-        session = TerminalSession("sess-1", __import__("uuid").uuid4(), "container-abc")
-        session._master_fd = 10
-
-        mock_select.return_value = ([10], [], [])
-        mock_read.return_value = b"output"
-
-        result = asyncio.run(session.read_output())
-        assert result == b"output"
-
-    @patch("src.services.terminal_session.select.select")
-    def test_read_output_no_data(self, mock_select):
-        session = TerminalSession("sess-1", __import__("uuid").uuid4(), "container-abc")
-        session._master_fd = 10
-
-        mock_select.return_value = ([], [], [])
-
-        result = asyncio.run(session.read_output())
-        assert result == b""
-
-
-class TestTerminalSessionClose:
-    @patch("src.services.terminal_session.os.close")
-    @patch("src.services.terminal_session.asyncio.wait_for")
-    async def test_close_sets_exit_reason(self, mock_wait_for, mock_close):
-        session = TerminalSession("sess-1", __import__("uuid").uuid4(), "container-abc")
-        session._master_fd = 10
-        session.process = MagicMock()
-        session.process.returncode = 0
-
-        await session.close()
-        assert session._exit_reason == "process_exit"
-        assert session._closed is True
-
-    async def test_close_idempotent(self):
-        session = TerminalSession("sess-1", __import__("uuid").uuid4(), "container-abc")
-        session._closed = True
-
-        # Should not raise
-        await session.close()
-
-
-class TestTerminalSessionIsAlive:
-    def test_is_alive_with_running_process(self):
-        session = TerminalSession("sess-1", __import__("uuid").uuid4(), "container-abc")
-        session.process = MagicMock()
-        session.process.returncode = None
-
-        assert session.is_alive() is True
-
-    def test_is_alive_with_exited_process(self):
-        session = TerminalSession("sess-1", __import__("uuid").uuid4(), "container-abc")
-        session.process = MagicMock()
-        session.process.returncode = 0
-
-        assert session.is_alive() is False
-
-    def test_is_alive_no_process(self):
-        session = TerminalSession("sess-1", __import__("uuid").uuid4(), "container-abc")
-        session.process = None
-
-        assert session.is_alive() is False

apps/web/package-lock.json

@@ -19,7 +19,6 @@
         "tailwindcss": "^3.3.0",
         "xterm": "^5.3.0",
         "xterm-addon-fit": "^0.8.0",
-        "xterm-addon-serialize": "^0.11.0",
         "xterm-addon-web-links": "^0.9.0"
       },
       "devDependencies": {
@@ -6373,16 +6372,6 @@
         "xterm": "^5.0.0"
       }
     },
-    "node_modules/xterm-addon-serialize": {
-      "version": "0.11.0",
-      "resolved": "https://registry.npmjs.org/xterm-addon-serialize/-/xterm-addon-serialize-0.11.0.tgz",
-      "integrity": "sha512-2CNDnmLdLkNWfsxNFkGsI5FE9W/BbsMzeOrbu59yNqH9L6k1gmL+Ab6VXxEp2NQUJSzaiqi6t0nFR5k5EDkVIg==",
-      "deprecated": "This package is now deprecated. Move to @xterm/addon-serialize instead.",
-      "license": "MIT",
-      "peerDependencies": {
-        "xterm": "^5.0.0"
-      }
-    },
     "node_modules/xterm-addon-web-links": {
       "version": "0.9.0",
       "resolved": "https://registry.npmjs.org/xterm-addon-web-links/-/xterm-addon-web-links-0.9.0.tgz",

apps/web/package.json

@@ -22,7 +22,6 @@
     "tailwindcss": "^3.3.0",
     "xterm": "^5.3.0",
     "xterm-addon-fit": "^0.8.0",
-    "xterm-addon-serialize": "^0.11.0",
     "xterm-addon-web-links": "^0.9.0"
   },
   "devDependencies": {

apps/web/scripts/check-structure.js

@@ -1,83 +0,0 @@
-#!/usr/bin/env node
-/* eslint-disable */
-/**
- * Verifies repository structure conventions.
- * Run with: node scripts/check-structure.js
- */
-
-import fs from "fs";
-import path from "path";
-import { fileURLToPath } from "url";
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const SRC_DIR = path.join(__dirname, "..", "src");
-
-let errors = 0;
-let warnings = 0;
-
-// Known acceptable deviations — documented in naming.md
-const OVERSIZE_ALLOWLIST = [
-	// Form-heavy admin tabs: 15+ fields each, splitting would create micro-components
-	"components/features/tool-workshop/ToolTypesTab.tsx",
-	"components/features/tool-workshop/ToolConfigsTab.tsx",
-	// Complex terminal hook: WS lifecycle + ping-pong + echo + resize debouncing
-	"hooks/use-terminal-connection.ts",
-	// Terminal component: xterm lifecycle + resize observer + overlay UI
-	"components/features/terminal/TerminalComponent.tsx",
-	// Instance list with health polling + inline confirmations
-	"components/features/session/InstanceList.tsx",
-	// Dialog with form validation + SSH key handling
-	"components/features/project/RepositoryCreateDialog.tsx",
-	// Test files: complex test coverage
-	"hooks/use-terminal-connection.test.ts",
-	"pages/ToolWorkshopPage.test.tsx",
-	// Global utility CSS: will be further split in future iteration
-	"styles/utilities.css",
-];
-
-function checkFileSize(filePath, maxLines = 300) {
-	const content = fs.readFileSync(filePath, "utf-8");
-	const lines = content.split("\n").length;
-	const relative = path.relative(SRC_DIR, filePath);
-	if (lines > maxLines) {
-		if (OVERSIZE_ALLOWLIST.includes(relative)) {
-			console.warn(`⚠️  OVERSIZED (${lines} lines, allowlisted): ${relative}`);
-			warnings++;
-		} else {
-			console.error(`❌ OVERSIZED (${lines} lines): ${relative}`);
-			errors++;
-		}
-	}
-}
-
-function walk(dir, callback) {
-	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-		const fullPath = path.join(dir, entry.name);
-		if (entry.isDirectory()) {
-			if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
-			walk(fullPath, callback);
-		} else {
-			callback(fullPath);
-		}
-	}
-}
-
-console.log("Checking file sizes...\n");
-walk(SRC_DIR, (filePath) => {
-	const ext = path.extname(filePath);
-	if ([".ts", ".tsx", ".py", ".css"].includes(ext)) {
-		checkFileSize(filePath);
-	}
-});
-
-console.log("\n---");
-if (errors === 0 && warnings === 0) {
-	console.log("✅ All checks passed!");
-	process.exit(0);
-} else if (errors === 0) {
-	console.log(`✅ All checks passed with ${warnings} warning(s)`);
-	process.exit(0);
-} else {
-	console.log(`❌ ${errors} error(s), ${warnings} warning(s)`);
-	process.exit(1);
-}

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

@@ -1,77 +0,0 @@
-import { apiClient } from "./client";
-import type {
-	ConfigFolder,
-	CreateConfigFolderRequest,
-	UpdateConfigFolderRequest,
-	ProjectOverrideRequest,
-} from "../types/config-folder";
-
-export type {
-	ConfigFolder,
-	CreateConfigFolderRequest,
-	UpdateConfigFolderRequest,
-	ProjectOverrideRequest,
-} from "../types/config-folder";
-
-export const listConfigFolders = async (): Promise<ConfigFolder[]> => {
-	const response = await apiClient.get<ConfigFolder[]>("/config-folders");
-	return response.data;
-};
-
-export const getConfigFolder = async (id: string): Promise<ConfigFolder> => {
-	const response = await apiClient.get<ConfigFolder>(`/config-folders/${id}`);
-	return response.data;
-};
-
-export const createConfigFolder = async (
-	data: CreateConfigFolderRequest,
-): Promise<ConfigFolder> => {
-	const response = await apiClient.post<ConfigFolder>("/config-folders", data);
-	return response.data;
-};
-
-export const updateConfigFolder = async (
-	id: string,
-	data: UpdateConfigFolderRequest,
-): Promise<ConfigFolder> => {
-	const response = await apiClient.put<ConfigFolder>(
-		`/config-folders/${id}`,
-		data,
-	);
-	return response.data;
-};
-
-export const deleteConfigFolder = async (id: string): Promise<void> => {
-	await apiClient.delete(`/config-folders/${id}`);
-};
-
-export const addProjectOverride = async (
-	id: string,
-	projectId: string,
-	data: ProjectOverrideRequest,
-): Promise<ConfigFolder> => {
-	const response = await apiClient.post<ConfigFolder>(
-		`/config-folders/${id}/overrides/${projectId}`,
-		data,
-	);
-	return response.data;
-};
-
-export const updateProjectOverride = async (
-	id: string,
-	projectId: string,
-	data: ProjectOverrideRequest,
-): Promise<ConfigFolder> => {
-	const response = await apiClient.put<ConfigFolder>(
-		`/config-folders/${id}/overrides/${projectId}`,
-		data,
-	);
-	return response.data;
-};
-
-export const deleteProjectOverride = async (
-	id: string,
-	projectId: string,
-): Promise<void> => {
-	await apiClient.delete(`/config-folders/${id}/overrides/${projectId}`);
-};

apps/web/src/api/config_folders.test.ts

@@ -5,7 +5,7 @@ import {
   deleteConfigFolder,
   listConfigFolders,
   updateConfigFolder,
-} from "../api/config-folders";
+} from "../api/config_folders";
 
 const mockGet = vi.fn();
 const mockPost = vi.fn();

apps/web/src/api/config_folders.ts

@@ -0,0 +1,95 @@
+import { apiClient } from "./client";
+
+export interface ConfigFolder {
+  id: string;
+  user_id: string;
+  name: string;
+  description: string | null;
+  mount_path: string;
+  files: Record<string, string>;
+  project_overrides: Record<string, { mount_path?: string; files?: Record<string, string> }> | null;
+  is_active: boolean;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface CreateConfigFolderRequest {
+  name: string;
+  description?: string;
+  mount_path: string;
+  files?: Record<string, string>;
+  is_active?: boolean;
+}
+
+export interface UpdateConfigFolderRequest {
+  name?: string;
+  description?: string;
+  mount_path?: string;
+  files?: Record<string, string>;
+  is_active?: boolean;
+}
+
+export interface ProjectOverrideRequest {
+  mount_path?: string;
+  files?: Record<string, string>;
+}
+
+export const listConfigFolders = async (): Promise<ConfigFolder[]> => {
+  const response = await apiClient.get<ConfigFolder[]>("/config-folders");
+  return response.data;
+};
+
+export const getConfigFolder = async (id: string): Promise<ConfigFolder> => {
+  const response = await apiClient.get<ConfigFolder>(`/config-folders/${id}`);
+  return response.data;
+};
+
+export const createConfigFolder = async (
+  data: CreateConfigFolderRequest
+): Promise<ConfigFolder> => {
+  const response = await apiClient.post<ConfigFolder>("/config-folders", data);
+  return response.data;
+};
+
+export const updateConfigFolder = async (
+  id: string,
+  data: UpdateConfigFolderRequest
+): Promise<ConfigFolder> => {
+  const response = await apiClient.put<ConfigFolder>(`/config-folders/${id}`, data);
+  return response.data;
+};
+
+export const deleteConfigFolder = async (id: string): Promise<void> => {
+  await apiClient.delete(`/config-folders/${id}`);
+};
+
+export const addProjectOverride = async (
+  id: string,
+  projectId: string,
+  data: ProjectOverrideRequest
+): Promise<ConfigFolder> => {
+  const response = await apiClient.post<ConfigFolder>(
+    `/config-folders/${id}/overrides/${projectId}`,
+    data
+  );
+  return response.data;
+};
+
+export const updateProjectOverride = async (
+  id: string,
+  projectId: string,
+  data: ProjectOverrideRequest
+): Promise<ConfigFolder> => {
+  const response = await apiClient.put<ConfigFolder>(
+    `/config-folders/${id}/overrides/${projectId}`,
+    data
+  );
+  return response.data;
+};
+
+export const deleteProjectOverride = async (
+  id: string,
+  projectId: string
+): Promise<void> => {
+  await apiClient.delete(`/config-folders/${id}/overrides/${projectId}`);
+};

apps/web/src/api/config_profiles.ts

@@ -0,0 +1,145 @@
+import { apiClient } from "./client";
+
+export interface ConfigProfile {
+  id: string;
+  user_id: string;
+  name: string;
+  description: string | null;
+  project_id: string | null;
+  tool_type_id: string | null;
+  env_vars: Record<string, string>;
+  runtime_hints: Record<string, unknown>;
+  mounts: ConfigProfileMount[];
+  files: Record<string, string>;
+  is_default: boolean;
+  includes: ConfigProfileInclude[];
+  created_at: string;
+  updated_at: string;
+}
+
+export interface ConfigProfileMount {
+  target: string;
+  mode: "ro" | "rw";
+  files: Record<string, string>;
+}
+
+export interface ConfigProfileInclude {
+  id: string;
+  included_profile_id: string;
+  order_index: number;
+}
+
+export interface ResolvedProfile {
+  profile_id: string;
+  profile_name: string;
+  env_vars: Record<string, string>;
+  runtime_hints: Record<string, unknown>;
+  mounts: ResolvedMount[];
+  files: Record<string, string>;
+  overrides: {
+    env_vars: Record<string, string>;
+    runtime_hints: Record<string, string>;
+    files: Record<string, string>;
+    mounts: Record<string, string>;
+  };
+  included_profiles: Array<{ id: string; name: string }>;
+}
+
+export interface ResolvedMount {
+  target: string;
+  mode: "ro" | "rw";
+  files: Record<string, string>;
+  overridden_files: Record<string, string>;
+}
+
+export interface CreateConfigProfileRequest {
+  name: string;
+  description?: string;
+  project_id?: string;
+  tool_type_id?: string;
+  env_vars?: Record<string, string>;
+  runtime_hints?: Record<string, unknown>;
+  mounts?: ConfigProfileMount[];
+  files?: Record<string, string>;
+  is_default?: boolean;
+}
+
+export interface UpdateConfigProfileRequest {
+  name?: string;
+  description?: string;
+  project_id?: string;
+  tool_type_id?: string;
+  env_vars?: Record<string, string>;
+  runtime_hints?: Record<string, unknown>;
+  mounts?: ConfigProfileMount[];
+  files?: Record<string, string>;
+  is_default?: boolean;
+}
+
+export interface UpdateIncludesRequest {
+  includes: string[];
+}
+
+export const listConfigProfiles = async (
+  projectId?: string,
+  toolTypeId?: string
+): Promise<ConfigProfile[]> => {
+  const response = await apiClient.get<ConfigProfile[]>("/config-profiles", {
+    params: { project_id: projectId, tool_type_id: toolTypeId },
+  });
+  return response.data;
+};
+
+export const getConfigProfile = async (id: string): Promise<ConfigProfile> => {
+  const response = await apiClient.get<ConfigProfile>(`/config-profiles/${id}`);
+  return response.data;
+};
+
+export const createConfigProfile = async (
+  data: CreateConfigProfileRequest
+): Promise<ConfigProfile> => {
+  const response = await apiClient.post<ConfigProfile>("/config-profiles", data);
+  return response.data;
+};
+
+export const updateConfigProfile = async (
+  id: string,
+  data: UpdateConfigProfileRequest
+): Promise<ConfigProfile> => {
+  const response = await apiClient.put<ConfigProfile>(`/config-profiles/${id}`, data);
+  return response.data;
+};
+
+export const deleteConfigProfile = async (id: string): Promise<void> => {
+  await apiClient.delete(`/config-profiles/${id}`);
+};
+
+export const updateProfileIncludes = async (
+  id: string,
+  data: UpdateIncludesRequest
+): Promise<ConfigProfile> => {
+  const response = await apiClient.put<ConfigProfile>(
+    `/config-profiles/${id}/includes`,
+    data
+  );
+  return response.data;
+};
+
+export const previewConfigProfile = async (
+  id: string
+): Promise<ResolvedProfile> => {
+  const response = await apiClient.get<ResolvedProfile>(
+    `/config-profiles/${id}/preview`
+  );
+  return response.data;
+};
+
+export const resolveDefaultProfile = async (
+  projectId: string,
+  toolTypeId: string
+): Promise<{ profile_id: string | null; profile_name: string | null }> => {
+  const response = await apiClient.get("/config-profiles/defaults/resolve", {
+    params: { project_id: projectId, tool_type_id: toolTypeId },
+  });
+  return response.data;
+};

apps/web/src/api/git-repositories.ts

@@ -1,191 +0,0 @@
-import { apiClient } from "./client";
-import type {
-	CommitDetail,
-	CommitHistoryResponse,
-	CommitResponse,
-	GitRepository,
-	GitRepositoryCreate,
-	GitStatus,
-	MergeResponse,
-	URLParseResult,
-} from "../types/git-repository";
-
-export type {
-	CommitDetail,
-	CommitHistoryEntry,
-	CommitHistoryResponse,
-	CommitResponse,
-	GitRepository,
-	GitRepositoryCreate,
-	GitStatus,
-	MergeResponse,
-	URLParseResult,
-} from "../types/git-repository";
-
-export async function parseGitUrl(url: string): Promise<URLParseResult> {
-	const response = await apiClient.post("/projects/repositories/parse-url", {
-		url,
-	});
-	return response.data;
-}
-
-export async function listRepositories(
-	projectId: string,
-): Promise<GitRepository[]> {
-	const response = await apiClient.get(`/projects/${projectId}/repositories`);
-	return response.data;
-}
-
-export async function createRepository(
-	projectId: string,
-	data: GitRepositoryCreate,
-): Promise<GitRepository> {
-	const response = await apiClient.post(
-		`/projects/${projectId}/repositories`,
-		data,
-	);
-	return response.data;
-}
-
-export async function deleteRepository(
-	projectId: string,
-	repoId: string,
-): Promise<void> {
-	await apiClient.delete(`/projects/${projectId}/repositories/${repoId}`);
-}
-
-export async function getRepositoryHistory(
-	projectId: string,
-	repoId: string,
-	branch?: string,
-	limit?: number,
-): Promise<CommitHistoryResponse> {
-	const searchParams = new URLSearchParams();
-	if (branch) searchParams.set("branch", branch);
-	if (limit) searchParams.set("limit", String(limit));
-	const queryString = searchParams.toString();
-	const params = queryString ? `?${queryString}` : "";
-	const response = await apiClient.get(
-		`/projects/${projectId}/repositories/${repoId}/history${params}`,
-	);
-	return response.data;
-}
-
-export async function getCommitDetail(
-	projectId: string,
-	repoId: string,
-	commitHash: string,
-): Promise<CommitDetail> {
-	const response = await apiClient.get(
-		`/projects/${projectId}/repositories/${repoId}/commits/${commitHash}`,
-	);
-	return response.data;
-}
-
-export async function getRepositoryStatus(
-	projectId: string,
-	repoId: string,
-): Promise<GitStatus> {
-	const response = await apiClient.get(
-		`/projects/${projectId}/repositories/${repoId}/status`,
-	);
-	return response.data;
-}
-
-export async function createBranch(
-	projectId: string,
-	repoId: string,
-	name: string,
-	baseBranch: string = "HEAD",
-): Promise<{ message: string; branch: string }> {
-	const response = await apiClient.post(
-		`/projects/${projectId}/repositories/${repoId}/branches`,
-		{ name, base_branch: baseBranch },
-	);
-	return response.data;
-}
-
-export async function deleteBranch(
-	projectId: string,
-	repoId: string,
-	branchName: string,
-	force: boolean = false,
-): Promise<{ message: string }> {
-	const response = await apiClient.delete(
-		`/projects/${projectId}/repositories/${repoId}/branches/${branchName}?force=${force}`,
-	);
-	return response.data;
-}
-
-export async function checkoutBranch(
-	projectId: string,
-	repoId: string,
-	branch: string,
-): Promise<{ message: string; branch: string }> {
-	const response = await apiClient.post(
-		`/projects/${projectId}/repositories/${repoId}/checkout`,
-		{ branch },
-	);
-	return response.data;
-}
-
-export async function commitChanges(
-	projectId: string,
-	repoId: string,
-	message: string,
-	files?: string[],
-): Promise<CommitResponse> {
-	const response = await apiClient.post(
-		`/projects/${projectId}/repositories/${repoId}/commit`,
-		{ message, files },
-	);
-	return response.data;
-}
-
-export async function fetchRepository(
-	projectId: string,
-	repoId: string,
-): Promise<{ message: string }> {
-	const response = await apiClient.post(
-		`/projects/${projectId}/repositories/${repoId}/fetch`,
-	);
-	return response.data;
-}
-
-export async function pullRepository(
-	projectId: string,
-	repoId: string,
-	branch?: string,
-): Promise<{ message: string }> {
-	const params = branch ? `?branch=${branch}` : "";
-	const response = await apiClient.post(
-		`/projects/${projectId}/repositories/${repoId}/pull${params}`,
-	);
-	return response.data;
-}
-
-export async function pushRepository(
-	projectId: string,
-	repoId: string,
-	branch?: string,
-): Promise<{ message: string }> {
-	const params = branch ? `?branch=${branch}` : "";
-	const response = await apiClient.post(
-		`/projects/${projectId}/repositories/${repoId}/push${params}`,
-	);
-	return response.data;
-}
-
-export async function mergeBranches(
-	projectId: string,
-	repoId: string,
-	sourceBranch: string,
-	targetBranch?: string,
-	message?: string,
-): Promise<MergeResponse> {
-	const response = await apiClient.post(
-		`/projects/${projectId}/repositories/${repoId}/merge`,
-		{ source_branch: sourceBranch, target_branch: targetBranch, message },
-	);
-	return response.data;
-}

apps/web/src/api/git_repositories.ts

@@ -0,0 +1,280 @@
+import { apiClient } from "./client";
+
+export interface GitRepository {
+  id: string;
+  name: string;
+  path: string;
+  project_id: string;
+  owner_id: string;
+  is_mirror: boolean;
+  remote_url: string | null;
+  ssh_key_id: string | null;
+  last_push: string | null;
+  created_at: string | null;
+}
+
+export interface GitRepositoryCreate {
+  name: string;
+  remote_url?: string;
+  force_original_url?: boolean;
+  ssh_key_id?: string;
+}
+
+export interface URLParseResult {
+  original_url: string;
+  base_url: string | null;
+  is_valid_clone_url: boolean;
+  needs_parsing: boolean;
+  host: string | null;
+  message: string;
+  error_code: string | null;
+}
+
+export async function parseGitUrl(url: string): Promise<URLParseResult> {
+  const response = await apiClient.post("/projects/repositories/parse-url", { url });
+  return response.data;
+}
+
+export async function listRepositories(projectId: string): Promise<GitRepository[]> {
+  const response = await apiClient.get(`/projects/${projectId}/repositories`);
+  return response.data;
+}
+
+export async function createRepository(
+  projectId: string,
+  data: GitRepositoryCreate
+): Promise<GitRepository> {
+  const response = await apiClient.post(`/projects/${projectId}/repositories`, data);
+  return response.data;
+}
+
+export async function deleteRepository(projectId: string, repoId: string): Promise<void> {
+  await apiClient.delete(`/projects/${projectId}/repositories/${repoId}`);
+}
+
+export async function updateRepositorySshKey(
+  projectId: string,
+  repoId: string,
+  sshKeyId: string | null
+): Promise<GitRepository> {
+  const response = await apiClient.patch(
+    `/projects/${projectId}/repositories/${repoId}/ssh-key`,
+    { ssh_key_id: sshKeyId }
+  );
+  return response.data;
+}
+
+export interface Branch {
+  name: string;
+  is_default: boolean;
+  last_commit: string | null;
+}
+
+export interface BranchesResponse {
+  branches: Branch[];
+  default_branch: string;
+}
+
+export async function listRepositoryBranches(
+  projectId: string,
+  repoId: string
+): Promise<BranchesResponse> {
+  const response = await apiClient.get(
+    `/projects/${projectId}/repositories/${repoId}/branches`
+  );
+  return response.data;
+}
+
+export interface CommitHistoryEntry {
+  hash: string;
+  short_hash: string;
+  message: string;
+  author_name: string;
+  author_email: string;
+  author_date: string;
+  refs: string[];
+  graph_symbol: string;
+  graph_depth: number;
+}
+
+export interface CommitHistoryResponse {
+  commits: CommitHistoryEntry[];
+  branches: string[];
+  tags: string[];
+}
+
+export async function getRepositoryHistory(
+  projectId: string,
+  repoId: string,
+  branch?: string,
+  limit?: number
+): Promise<CommitHistoryResponse> {
+  const searchParams = new URLSearchParams();
+  if (branch) searchParams.set("branch", branch);
+  if (limit) searchParams.set("limit", String(limit));
+  const queryString = searchParams.toString();
+  const params = queryString ? `?${queryString}` : "";
+  const response = await apiClient.get(`/projects/${projectId}/repositories/${repoId}/history${params}`);
+  return response.data;
+}
+
+export interface CommitDetail {
+  hash: string;
+  short_hash: string;
+  message: string;
+  author_name: string;
+  author_email: string;
+  author_date: string;
+  committer_name: string;
+  committer_email: string;
+  committer_date: string;
+  stats: {
+    additions: number;
+    deletions: number;
+    files_changed: number;
+  };
+  diff: string;
+  parents: string[];
+}
+
+export async function getCommitDetail(
+  projectId: string,
+  repoId: string,
+  commitHash: string
+): Promise<CommitDetail> {
+  const response = await apiClient.get(
+    `/projects/${projectId}/repositories/${repoId}/commits/${commitHash}`
+  );
+  return response.data;
+}
+
+// Git Control API
+
+export interface GitStatus {
+  branch: string;
+  modified: string[];
+  added: string[];
+  deleted: string[];
+  untracked: string[];
+  renamed: string[];
+  ahead: number;
+  behind: number;
+}
+
+export async function getRepositoryStatus(
+  projectId: string,
+  repoId: string
+): Promise<GitStatus> {
+  const response = await apiClient.get(
+    `/projects/${projectId}/repositories/${repoId}/status`
+  );
+  return response.data;
+}
+
+export async function createBranch(
+  projectId: string,
+  repoId: string,
+  name: string,
+  baseBranch: string = "HEAD"
+): Promise<{ message: string; branch: string }> {
+  const response = await apiClient.post(
+    `/projects/${projectId}/repositories/${repoId}/branches`,
+    { name, base_branch: baseBranch }
+  );
+  return response.data;
+}
+
+export async function deleteBranch(
+  projectId: string,
+  repoId: string,
+  branchName: string,
+  force: boolean = false
+): Promise<{ message: string }> {
+  const response = await apiClient.delete(
+    `/projects/${projectId}/repositories/${repoId}/branches/${branchName}?force=${force}`
+  );
+  return response.data;
+}
+
+export async function checkoutBranch(
+  projectId: string,
+  repoId: string,
+  branch: string
+): Promise<{ message: string; branch: string }> {
+  const response = await apiClient.post(
+    `/projects/${projectId}/repositories/${repoId}/checkout`,
+    { branch }
+  );
+  return response.data;
+}
+
+export interface CommitResponse {
+  commit_hash: string;
+  message: string;
+}
+
+export async function commitChanges(
+  projectId: string,
+  repoId: string,
+  message: string,
+  files?: string[]
+): Promise<CommitResponse> {
+  const response = await apiClient.post(
+    `/projects/${projectId}/repositories/${repoId}/commit`,
+    { message, files }
+  );
+  return response.data;
+}
+
+export async function fetchRepository(
+  projectId: string,
+  repoId: string
+): Promise<{ message: string }> {
+  const response = await apiClient.post(
+    `/projects/${projectId}/repositories/${repoId}/fetch`
+  );
+  return response.data;
+}
+
+export async function pullRepository(
+  projectId: string,
+  repoId: string,
+  branch?: string
+): Promise<{ message: string }> {
+  const params = branch ? `?branch=${branch}` : "";
+  const response = await apiClient.post(
+    `/projects/${projectId}/repositories/${repoId}/pull${params}`
+  );
+  return response.data;
+}
+
+export async function pushRepository(
+  projectId: string,
+  repoId: string,
+  branch?: string
+): Promise<{ message: string }> {
+  const params = branch ? `?branch=${branch}` : "";
+  const response = await apiClient.post(
+    `/projects/${projectId}/repositories/${repoId}/push${params}`
+  );
+  return response.data;
+}
+
+export interface MergeResponse {
+  commit_hash: string;
+  message: string;
+}
+
+export async function mergeBranches(
+  projectId: string,
+  repoId: string,
+  sourceBranch: string,
+  targetBranch?: string,
+  message?: string
+): Promise<MergeResponse> {
+  const response = await apiClient.post(
+    `/projects/${projectId}/repositories/${repoId}/merge`,
+    { source_branch: sourceBranch, target_branch: targetBranch, message }
+  );
+  return response.data;
+}