fix(terminal): suppress competing context menus

Stop contextmenu propagation after recognizing selected xterm output so the native browser overlay cannot block Copy.

.atl/.skill-registry.cache.json

@@ -1,3 +1,3 @@
 {
-  "fingerprint": "639c16d45210921c3c8ece071ef18bbe0c426ea2"
+  "fingerprint": "e7b3130f52a328d4051e75364e5394ac63df60c6"
 }

.atl/skill-registry.md

@@ -1,8 +1,8 @@
-# Skill Registry — workspace
+# Skill Registry — headquarter
 
 <!-- Auto-generated by gentle-pi extensions/skill-registry.ts. Run /skill-registry:refresh to regenerate. -->
 
-Last updated: 2026-06-05
+Last updated: 2026-06-17
 
 ## Sources scanned
 
@@ -19,11 +19,11 @@ Last updated: 2026-06-05
 
 | Skill | Trigger / description | Scope | Path |
 | --- | --- | --- | --- |
-| `openspec-apply-change` | Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks. | project | `/workspace/.opencode/skills/openspec-apply-change/SKILL.md` |
-| `openspec-archive-change` | Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete. | project | `/workspace/.opencode/skills/openspec-archive-change/SKILL.md` |
-| `openspec-explore` | Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change. | project | `/workspace/.opencode/skills/openspec-explore/SKILL.md` |
-| `openspec-propose` | Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation. | project | `/workspace/.opencode/skills/openspec-propose/SKILL.md` |
-| `sift-backlog` | Triage and organize backlog tasks into actionable plans. Use when asked to review the backlog, prioritize tasks, create plans from backlog items, or move tasks from backlog to open status. Handles the full workflow of listing backlog tasks, grouping related tasks into plans, setting priorities and dependencies, activating plans, and changing task status from backlog to open. | project | `/workspace/.claude/skills/sift-backlog/SKILL.md` |
+| `openspec-apply-change` | Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks. | project | `/home/user/headquarter/.opencode/skills/openspec-apply-change/SKILL.md` |
+| `openspec-archive-change` | Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete. | project | `/home/user/headquarter/.opencode/skills/openspec-archive-change/SKILL.md` |
+| `openspec-explore` | Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change. | project | `/home/user/headquarter/.opencode/skills/openspec-explore/SKILL.md` |
+| `openspec-propose` | Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation. | project | `/home/user/headquarter/.opencode/skills/openspec-propose/SKILL.md` |
+| `sift-backlog` | Triage and organize backlog tasks into actionable plans. Use when asked to review the backlog, prioritize tasks, create plans from backlog items, or move tasks from backlog to open status. Handles the full workflow of listing backlog tasks, grouping related tasks into plans, setting priorities and dependencies, activating plans, and changing task status from backlog to open. | project | `/home/user/headquarter/.claude/skills/sift-backlog/SKILL.md` |
 
 ## Loading protocol
 

.pi-map.index.md

@@ -16,7 +16,7 @@ dir: .
 Trust boundary: index routes, map orients, source decides.
 
 ## role
-A self-hosted web platform for managing projects, git repositories, and development tools with OAuth2 authentication, built as a Dockerized multi-service application.
+Package .
 ## parent
 -
 ## children
@@ -56,6 +56,9 @@ A self-hosted web platform for managing projects, git repositories, and developm
 - tool-images
   index: tool-images/.pi-map.index.md
   map: tool-images/.pi-map.md
+- uploads
+  index: uploads/.pi-map.index.md
+  map: uploads/.pi-map.md
 ## files
 - .env.example
 - .gitignore

.pi-map.md

@@ -18,25 +18,25 @@ index: ./.pi-map.index.md
 Trust boundary: index routes, map orients, source decides.
 
 ## role
-A self-hosted web platform for managing projects, git repositories, and development tools with OAuth2 authentication, built as a Dockerized multi-service application.
+Package .
 ## files
-- .env.example | Template environment configuration file defining all required and optional environment variables for a multi-service application stack
-- .gitignore | Specifies patterns for files and directories that Git should ignore in this project. | dep: git
-- AGENTS.md | Defines agent behavior rules, workflow procedures, and project conventions for AI agents working on an OpenSpec-driven codebase. | dep: OpenSpec, git, superpowers workflow system, conventional commits
-- CHANGELOG.md | Documents version history and notable changes to a project management and Git repository application
-- Makefile | Provides standard development commands for managing a Docker Compose-based multi-service application (API, web, Postgres, Redis) with testing, migration, linting, and build automation. | dep: docker compose, alembic, pytest, ruff, mypy, playwright, npm/node
-- README.md | A self-hosted platform for managing projects, git repositories, and development tools with OAuth2 authentication. | dep: FastAPI, SQLAlchemy, Pydantic, Alembic, python-jose, React, TypeScript, Vite, React Router, Docker, PostgreSQL, Traefik, Authentik
-- docker-compose.traefik.yml | Deploys a multi-service web application stack (frontend, API, PostgreSQL, Redis) behind an existing Traefik reverse proxy with automatic HTTPS | dep: Docker, Docker Compose, Traefik, PostgreSQL, Redis, Authentik
-- docker-compose.yml | Defines a multi-container Docker application with PostgreSQL, Redis, API backend, and web frontend services for a "headquarter" application. | dep: Docker Compose, PostgreSQL 15, Redis 7, Python/FastAPI (implied by asyncpg), Vite/Node.js (implied by web build), Alpine Linux
-- progress.md | Documents the completed phases and remaining work of a backend-frontend code refactoring project involving modularization, subpackage extraction, and file reorganization.
-- swap-pane | Swaps two tmux panes between windows, preserving active pane state and layout | dep: tmux
-- ui-audit-spacing-typography.md | Documents a comprehensive UI audit of spacing, typography, and visual rhythm issues in a React web application, identifying missing CSS classes, unstyled mobile components, inconsistent design tokens, and layout bugs across component and stylesheet files. | dep: React/TSX components, CSS modules/stylesheets, CSS custom properties (tokens), mobile-specific components, design system tokens
-- ui-rework-foundations-apply.md | Documents the implementation of Pass 1 (Foundations) of a web UI spacing/typography/visual-rhythm rework, including token expansion, primitive CSS classes, component updates, and validation results. | dep: CSS design tokens, React/TSX components, OpenSpec documentation system, git/SSH, npm build toolchain
-- ui-rework-pass2-apply.md | Documents a completed web UI refactoring pass that converted inline styles to token-based utility classes, unified form patterns, and added component utilities across multiple React components. | dep: React, CSS custom properties, OpenSpec, Git, npm, TypeScript, ESLint
+- .env.example | Provides example environment variable configuration for a full-stack application with database, caching, authentication, and deployment settings
+- .gitignore | Specifies files and directories for Git to ignore across a project using Beads/Dolt, Python, Node, and various IDE/OS tooling. | dep: git, dolt, beads, python, node, npm, yarn, pnpm, pytest, mypy, ruff, coverage
+- AGENTS.md | Defines operational guidelines and workflows for AI agents collaborating on a software project governed by OpenSpec | dep: OpenSpec, superpowers (brainstorming, writing-plans, test-driven-development, systematic-debugging, verification-before-completion, using-git-worktrees, dispatching-parallel-agents), git
+- CHANGELOG.md | Documents version history and notable changes for a project management and Git repository application
+- Makefile | Provides standardized development commands for managing a Docker-based full-stack application with API, web frontend, database, and testing infrastructure | dep: docker compose, alembic, pytest, ruff, mypy, playwright, npm, postgres, redis
+- README.md | Documentation for a self-hosted development platform that manages projects, git repositories, and development tools with OAuth2 authentication | dep: FastAPI, SQLAlchemy, Pydantic, Alembic, python-jose, React, TypeScript, Vite, React Router, Docker, PostgreSQL, Traefik, Authentik
+- docker-compose.traefik.yml | Deploys a multi-service application (PostgreSQL, Redis, web frontend, API) behind an existing Traefik reverse proxy with TLS termination | dep: docker, docker-compose, traefik, postgres, redis, node/vite, python/fastapi
+- docker-compose.yml | Defines a multi-service Docker Compose stack for a web application with PostgreSQL, Redis, API backend, and web frontend services | dep: Docker, Docker Compose, PostgreSQL, Redis, Vite, asyncpg, Python/FastAPI (implied), Node.js (implied)
+- progress.md | Documents the progress and remaining tasks for a backend-frontend refactoring project involving modularization, code reorganization, and verification.
+- swap-pane | Provides a command to swap the position of two tmux panes within a window or between windows | dep: tmux, client, window, layout, cmd-find, cmd-parse, options
+- ui-audit-spacing-typography.md | A detailed audit report identifying critical CSS styling gaps, mobile layout failures, and design system inconsistencies in a web application's UI components and stylesheets. | dep: React/TSX components, CSS stylesheets (global.css, utilities.css, tokens.css, page-specific CSS), JSX/TSX files in apps/web/src/components and apps/web/src/pages
+- ui-rework-foundations-apply.md | Documents the implementation of Pass 1 (Foundations) of a web UI spacing/typography/visual-rhythm rework, including design token expansion, primitive CSS class additions, component refactors, and OpenSpec documentation. | dep: CSS design tokens, React/TSX components, OpenSpec documentation system, Git/SSH, npm build toolchain
+- ui-rework-pass2-apply.md | Documents the implementation and verification of Pass 2 of a web UI spacing/typography rework, refactoring inline styles into utility classes and design tokens across six components. | dep: CSS custom properties, BEM methodology, utility-first CSS, React/TSX components, OpenSpec documentation system
 ## arch
-Full-stack monolithic architecture with React frontend, API backend, PostgreSQL and Redis services, containerized via Docker Compose, using Traefik for reverse proxy/HTTPS, and following a token-based design system for UI consistency.
+Contains 13 files.
 ## tags
-docker, application, git, web, react, ui, documents, rework
+docker, web, git, application, ui, rework, python, redis
 ## symbols
 -
 ## workflows

apps/.pi-map.index.md

@@ -2,7 +2,7 @@
 dir: apps
 
 ## role
-Contains the main application entry points and executable modules for the project.
+Package apps
 ## parent
 index: ./.pi-map.index.md
 map: ./.pi-map.md

apps/.pi-map.md

@@ -4,10 +4,10 @@ dir: apps
 index: apps/.pi-map.index.md
 
 ## role
-Contains the main application entry points and executable modules for the project.
+Package apps
 ## files
 ## arch
-Modular application structure with separate deployable units, likely following microservices or multi-app monorepo pattern with shared infrastructure.
+Contains 0 files.
 ## tags
 -
 ## symbols

apps/api/.pi-map.index.md

@@ -2,17 +2,32 @@
 dir: apps/api
 
 ## role
-FastAPI-based backend API service for managing projects, git repositories, and development tools in a self-hosted development platform.
+Backend API server for the Headquarter platform, providing self-hosted project management, git repository management, and development tool orchestration services.
 ## parent
 index: apps/.pi-map.index.md
 map: apps/.pi-map.md
 ## children
+- apps/api/.mypy_cache
+  index: apps/api/.mypy_cache/.pi-map.index.md
+  map: apps/api/.mypy_cache/.pi-map.md
 - apps/api/.pi-lens
   index: apps/api/.pi-lens/.pi-map.index.md
   map: apps/api/.pi-lens/.pi-map.md
+- apps/api/.pytest_cache
+  index: apps/api/.pytest_cache/.pi-map.index.md
+  map: apps/api/.pytest_cache/.pi-map.md
+- apps/api/.ruff_cache
+  index: apps/api/.ruff_cache/.pi-map.index.md
+  map: apps/api/.ruff_cache/.pi-map.md
 - apps/api/alembic
   index: apps/api/alembic/.pi-map.index.md
   map: apps/api/alembic/.pi-map.md
+- apps/api/app
+  index: apps/api/app/.pi-map.index.md
+  map: apps/api/app/.pi-map.md
+- apps/api/headquarter_api.egg-info
+  index: apps/api/headquarter_api.egg-info/.pi-map.index.md
+  map: apps/api/headquarter_api.egg-info/.pi-map.md
 - apps/api/src
   index: apps/api/src/.pi-map.index.md
   map: apps/api/src/.pi-map.md

apps/api/.pi-map.md

@@ -4,19 +4,19 @@ dir: apps/api
 index: apps/api/.pi-map.index.md
 
 ## role
-FastAPI-based backend API service for managing projects, git repositories, and development tools in a self-hosted development platform.
+Backend API server for the Headquarter platform, providing self-hosted project management, git repository management, and development tool orchestration services.
 ## files
-- .dockerignore | Specifies files and directories to exclude from Docker build context to reduce image size and improve build performance. | dep: Docker
-- Dockerfile | Multi-stage Docker image for a Python web application with Docker-in-Docker capabilities, database waiting, and Cloudflare tunnel support | dep: python:3.11-slim, gcc, libpq-dev, docker-ce-cli, docker-compose-plugin, cloudflared, uvicorn, pyproject.toml dependencies
-- README.md | README documentation for Headquarter API, a self-hosted FastAPI backend for managing projects, git repositories, and development tools. | dep: FastAPI, SQLAlchemy, PostgreSQL, asyncpg, Alembic, Docker, Docker Compose, Authentik, uvicorn, pytest, ruff, mypy
-- alembic.ini | Configuration file for Alembic database migration tool specifying script location, database connection URL, and logging settings | dep: alembic, sqlalchemy, asyncpg, postgresql
-- pyproject.toml | Defines Python project configuration, dependencies, and tool settings for a FastAPI-based backend API service | dep: fastapi, uvicorn, sqlalchemy, asyncpg, alembic, pydantic, pydantic-settings, python-multipart, httpx, structlog, cryptography, pytest, pytest-asyncio, mypy, ruff, aiosqlite
-- uv.lock | Lock file generated by uv package manager that records exact dependency versions, hashes, and download URLs for reproducible Python environment installation | dep: uv, PyPI, python
-- wait-for-db.sh | Waits for a PostgreSQL database to become available before executing the provided command | dep: nc (netcat), sh, sleep
+- .dockerignore | Specifies files and directories to exclude from the Docker build context to optimize image build times and prevent sensitive or unnecessary files from being included.
+- Dockerfile | Multi-stage Dockerfile that builds and runs a Python application with Docker CLI access, cloudflared, and database readiness checks. | dep: python:3.11-slim, libpq5, git, openssh-client, docker-ce-cli, docker-compose-plugin, cloudflared, uvicorn, netcat-openbsd
+- README.md | Provides comprehensive documentation for the Headquarter API, a self-hosted platform for managing projects, git repositories, and development tools. | dep: FastAPI, SQLAlchemy, PostgreSQL, asyncpg, Alembic, Docker, Authentik, Pydantic, Ruff, mypy, pytest
+- alembic.ini | Configuration file for Alembic database migration tool, defining database connection and logging settings. | dep: alembic, sqlalchemy, asyncpg, postgresql
+- pyproject.toml | Defines project metadata, dependencies, and tool configuration for the Headquarter platform API. | dep: fastapi, uvicorn, sqlalchemy, asyncpg, alembic, pydantic, pydantic-settings, httpx, structlog, cryptography, pytest, mypy, ruff
+- uv.lock | This file is a UV lockfile that pins exact versions, hashes, and metadata for all Python project dependencies to ensure reproducible environments. | dep: uv, aiosqlite, alembic, annotated-types, anyio, asyncpg, sqlalchemy, mako
+- wait-for-db.sh | Polls a PostgreSQL host/port until it is available or a retry limit is reached, then executes the passed command. | dep: nc, sleep
 ## arch
-Modern Python backend with FastAPI, SQLAlchemy/ORM with Alembic migrations, uv for dependency management, multi-stage Docker containerization with Docker-in-Docker support, and PostgreSQL database connectivity.
+Modern Python async API using FastAPI/Starlette with SQLAlchemy ORM, Alembic migrations, multi-stage Docker containerization with cloudflared tunneling, UV package management, and PostgreSQL database with health-checked startup orchestration.
 ## tags
-docker, alembic, python, database, fastapi, uvicorn, pyproject, readme
+alembic, docker, sqlalchemy, asyncpg, dockerfile, database, postgresql, pydantic
 ## symbols
 -
 ## workflows

apps/api/alembic/.pi-map.index.md

@@ -2,7 +2,7 @@
 dir: apps/api/alembic
 
 ## role
-Database migration infrastructure for the API application, enabling version-controlled schema changes with async database support.
+Database migration tooling for the API service, enabling version-controlled schema changes with async SQLAlchemy support.
 ## parent
 index: apps/api/.pi-map.index.md
 map: apps/api/.pi-map.md

apps/api/alembic/.pi-map.md

@@ -4,14 +4,14 @@ dir: apps/api/alembic
 index: apps/api/alembic/.pi-map.index.md
 
 ## role
-Database migration infrastructure for the API application, enabling version-controlled schema changes with async database support.
+Database migration tooling for the API service, enabling version-controlled schema changes with async SQLAlchemy support.
 ## files
-- env.py | Configures Alembic database migration environment with async SQLAlchemy support | exp: func:run_migrations_offline() → None, call:context.configure, call:context.begin_transaction, call:context.run_migrations, func:do_run_migrations(connection: Connection) → None, call:context.configure, call:context.begin_transaction, call:context.run_migrations, func:run_async_migrations() → None, call:async_engine_from_config, call:config.get_section, call:connectable.connect, call:connection.run_sync, call:connectable.dispose, func:run_migrations_online() → None, call:asyncio.run, call:run_async_migrations | dep: logging.config, alembic, sqlalchemy, sqlalchemy.engine, sqlalchemy.ext.asyncio, src.config, src.models, asyncio
-- script.py.mako | Alembic database migration script template that generates upgrade/downgrade functions for SQL schema revisions | dep: alembic, sqlalchemy
+- env.py | Configures Alembic database migration environment with async SQLAlchemy support. | exp: func:run_migrations_offline() → None, call:context.configure, call:context.begin_transaction, call:context.run_migrations, func:do_run_migrations(connection: Connection) → None, call:context.configure, call:context.begin_transaction, call:context.run_migrations, func:run_async_migrations() → None, call:async_engine_from_config, call:config.get_section, call:connectable.connect, call:connection.run_sync, call:connectable.dispose, func:run_migrations_online() → None, call:asyncio.run, call:run_async_migrations | dep: logging.config, alembic, sqlalchemy, sqlalchemy.engine, sqlalchemy.ext.asyncio, src.config, src.models, asyncio
+- script.py.mako | Alembic database migration script template that generates Python migration files for SQLAlchemy database schema changes | dep: alembic, sqlalchemy, mako
 ## arch
-Template-based migration generation using Alembic with async SQLAlchemy engine configuration and environment setup.
+Template-based migration generation using Alembic's standard env.py configuration pattern with async SQLAlchemy engine integration and Mako templating for migration script scaffolding.
 ## tags
-migrations, run, async, sqlalchemy, alembic, call:context.configure, call:context.begin, transaction
+migrations, run, sqlalchemy, async, alembic, call:context.configure, call:context.begin, transaction
 ## symbols
 - run_migrations_offline
 - do_run_migrations

apps/api/alembic/versions/.pi-map.index.md

@@ -2,12 +2,14 @@
 dir: apps/api/alembic/versions
 
 ## role
-Manages database schema evolution and version control for the API application using Alembic migration scripts.
+Database schema versioning and incremental migration management for the API's relational data model using Alembic.
 ## parent
 index: apps/api/alembic/.pi-map.index.md
 map: apps/api/alembic/.pi-map.md
 ## children
--
+- apps/api/alembic/versions/.ruff_cache
+  index: apps/api/alembic/versions/.ruff_cache/.pi-map.index.md
+  map: apps/api/alembic/versions/.ruff_cache/.pi-map.md
 ## files
 - 0001_initial_schema.py
 - 0002_refresh_tokens.py
@@ -51,6 +53,7 @@ map: apps/api/alembic/.pi-map.md
 - 2026_06_14_104415_add_tool_type_home_directory.py
 - 2026_06_14_182955_fix_pi_agent_home_directory_mount.py
 - 2026_06_15_090500_remove_pi_agent_explicit_repo_mount.py
+- 2026_06_19_113000_remove_pi_agent_workspace_symlink.py
 - 398082499c30_add_tool_config_fields.py
 - 6fc7bfcf199f_merge_remove_is_builtin_and_add_config_.py
 - 86cec91fdb00_merge_profile_resolver_and_workspaces_.py
@@ -69,5 +72,7 @@ map: apps/api/alembic/versions/.pi-map.md
   read: 2026_05_24_220141_add_startup_command.py, 2026_05_29_remove_lsio_command_override.py
 - change versions config
   read: 0003_user_configs.py, 0009_tool_configs.py, 0013_add_config_profiles.py
+- explore versions subdirectories
+  index: apps/api/alembic/versions/.ruff_cache/.pi-map.index.md
 ## dirty
 -

apps/api/alembic/versions/.pi-map.md

@@ -4,60 +4,61 @@ dir: apps/api/alembic/versions
 index: apps/api/alembic/versions/.pi-map.index.md
 
 ## role
-Manages database schema evolution and version control for the API application using Alembic migration scripts.
+Database schema versioning and incremental migration management for the API's relational data model using Alembic.
 ## files
-- 0001_initial_schema.py | Creates the initial database schema with five tables (users, ssh_keys, projects, git_repositories, user_configs) using Alembic migrations | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:sa.String, call:postgresql.UUID, call:sa.DateTime, call:sa.func.now, call:sa.PrimaryKeyConstraint, call:sa.UniqueConstraint, call:op.create_index, call:op.f, call:sa.Text, call:sa.ForeignKeyConstraint, call:sa.Boolean, call:postgresql.JSONB, func:downgrade() → None, call:op.drop_table, call:op.drop_index, call:op.f | dep: alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
-- 0002_refresh_tokens.py | Alembic database migration that creates a refresh_tokens table with indexes for user authentication/session management | exp: func:upgrade() → None, call:op.get_bind, call:sa.inspect, call:inspector.has_table, call:op.create_table, call:sa.Column, call:postgresql.UUID, call:sa.String, call:sa.DateTime, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:sa.UniqueConstraint, call:inspector.get_indexes, call:op.f, call:op.create_index, func:downgrade() → None, call:op.get_bind, call:sa.inspect, call:inspector.has_table, call:inspector.get_indexes, call:op.f, call:op.drop_index, call:op.drop_table | dep: alembic, sqlalchemy.dialects, sqlalchemy, postgresql dialect
-- 0003_user_configs.py | Alembic database migration that creates a user_configs table with JSON configuration storage linked to users via foreign key | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:sa.UUID, call:sa.JSON, call:sa.DateTime, call:sa.text, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:sa.UniqueConstraint, func:downgrade() → None, call:op.drop_table | dep: typing, alembic, sqlalchemy
-- 0004_tool_types.py | Alembic database migration that creates a tool_types table with metadata, templates, and user relationship columns | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:sa.Uuid, call:sa.String, call:sa.Text, call:sa.JSON, call:sa.Boolean, call:sa.ForeignKey, call:sa.DateTime, call:sa.text, func:downgrade() → None, call:op.drop_table | dep: typing, alembic, sqlalchemy
+- 0001_initial_schema.py | Alembic database migration that creates the initial schema with five tables (users, ssh_keys, projects, git_repositories, user_configs) for a Git/SSH management application. | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:sa.String, call:postgresql.UUID, call:sa.DateTime, call:sa.func.now, call:sa.PrimaryKeyConstraint, call:sa.UniqueConstraint, call:op.create_index, call:op.f, call:sa.Text, call:sa.ForeignKeyConstraint, call:sa.Boolean, call:postgresql.JSONB, func:downgrade() → None, call:op.drop_table, call:op.drop_index, call:op.f | dep: alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
+- 0002_refresh_tokens.py | Alembic database migration that creates a refresh_tokens table with indexes for secure session management | exp: func:upgrade() → None, call:op.get_bind, call:sa.inspect, call:inspector.has_table, call:op.create_table, call:sa.Column, call:postgresql.UUID, call:sa.String, call:sa.DateTime, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:sa.UniqueConstraint, call:inspector.get_indexes, call:op.f, call:op.create_index, func:downgrade() → None, call:op.get_bind, call:sa.inspect, call:inspector.has_table, call:inspector.get_indexes, call:op.f, call:op.drop_index, call:op.drop_table | dep: alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
+- 0003_user_configs.py | Alembic database migration that creates a user_configs table with JSON configuration storage per user | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:sa.UUID, call:sa.JSON, call:sa.DateTime, call:sa.text, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:sa.UniqueConstraint, func:downgrade() → None, call:op.drop_table | dep: typing, alembic, sqlalchemy
+- 0004_tool_types.py | Alembic database migration that creates a tool_types table with metadata, templates, and user tracking fields | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:sa.Uuid, call:sa.String, call:sa.Text, call:sa.JSON, call:sa.Boolean, call:sa.ForeignKey, call:sa.DateTime, call:sa.text, func:downgrade() → None, call:op.drop_table | dep: typing, alembic, sqlalchemy
 - 0005_ssh_keys_timestamps.py | Alembic database migration that adds created_at and updated_at timestamp columns to the ssh_keys table | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.DateTime, call:sa.text, func:downgrade() → None, call:op.drop_column | dep: typing, alembic, sqlalchemy
-- 0006_tool_instances.py | Alembic database migration that creates a tool_instances table with UUID primary key, foreign key relationships, timestamps, and indexes for tracking deployed tool instances | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:postgresql.UUID, call:sa.text, call:sa.String, call:sa.Integer, call:sa.DateTime, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:op.create_index, func:downgrade() → None, call:op.drop_index, call:op.drop_table | dep: typing, alembic, sqlalchemy.dialects, sqlalchemy, postgresql dialect
+- 0006_tool_instances.py | Alembic database migration that creates a tool_instances table with foreign key relationships to tool_types, git_repositories, projects, and users tables, plus indexes for common query patterns. | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:postgresql.UUID, call:sa.text, call:sa.String, call:sa.Integer, call:sa.DateTime, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:op.create_index, func:downgrade() → None, call:op.drop_index, call:op.drop_table | dep: typing, alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
 - 0007_instance_container_name.py | Alembic database migration that adds a nullable container_name column to the tool_instances table | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.String, func:downgrade() → None, call:op.drop_column | dep: typing, alembic, sqlalchemy
-- 0008_tool_type_category.py | Alembic database migration that adds 'category' and 'interfaces' columns to the 'tool_types' table | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.String, call:sa.JSON, func:downgrade() → None, call:op.drop_column | dep: typing, alembic, sqlalchemy
-- 0009_tool_configs.py | Alembic database migration that creates a tool_configs table for storing user tool configuration key-value pairs with optional project scoping | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:postgresql.UUID, call:sa.text, call:sa.String, call:sa.Text, call:sa.DateTime, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:op.create_index, func:downgrade() → None, call:op.drop_index, call:op.drop_table | dep: typing, alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
+- 0008_tool_type_category.py | Alembic database migration that adds `category` and `interfaces` columns to the `tool_types` table | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.String, call:sa.JSON, func:downgrade() → None, call:op.drop_column | dep: typing, alembic, sqlalchemy
+- 0009_tool_configs.py | Alembic database migration that creates a tool_configs table with UUID primary keys, foreign keys to users/tool_types/projects, key-value configuration storage, and supporting indexes. | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:postgresql.UUID, call:sa.text, call:sa.String, call:sa.Text, call:sa.DateTime, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:op.create_index, func:downgrade() → None, call:op.drop_index, call:op.drop_table | dep: typing, alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
 - 0010_tool_type_default_port.py | Alembic database migration that adds a nullable default_port column to the tool_types table | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.Integer, func:downgrade() → None, call:op.drop_column | dep: typing, alembic, sqlalchemy
-- 0011_tool_instance_tunnel_fields.py | Alembic database migration that adds public_url and tunnel_id columns to the tool_instances table for tunnel functionality. | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.String, func:downgrade() → None, call:op.drop_column | dep: typing, alembic, sqlalchemy
-- 0012_default_port_req.py | Alembic database migration that backfills default_port values for existing tool types and makes the column non-nullable | exp: func:upgrade() → None, call:op.execute, call:op.alter_column, call:sa.Integer, func:downgrade() → None, call:op.alter_column, call:sa.Integer | dep: typing, alembic, sqlalchemy
-- 0013_add_config_profiles.py | Database migration that adds config profiles, profile includes, profile mounts, and tool instance profile selection tables with defensive idempotent checks | exp: func:_table_exists(table_name: str) → bool, call:sa.inspect(op.get_bind()).has_table, call:op.get_bind, func:_column_exists(table_name: str, column_name: str) → bool, call:_table_exists, call:sa.inspect(op.get_bind()).get_columns, call:op.get_bind, func:_index_exists(table_name: str, index_name: str) → bool, call:_table_exists, call:sa.inspect(op.get_bind()).get_indexes, call:op.get_bind, func:_foreign_key_exists(table_name: str, constrained_columns: list[str], referred_table: str) → bool, call:_table_exists, call:sa.inspect(op.get_bind()).get_foreign_keys, call:op.get_bind, call:foreign_key.get, func:upgrade() → None, call:_table_exists, call:op.create_table, call:sa.Column, call:postgresql.UUID, call:sa.String, call:sa.Text, call:sa.DateTime, call:sa.text, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:sa.UniqueConstraint, call:_index_exists, call:op.create_index, call:sa.Integer, call:_column_exists, call:op.add_column, call:_foreign_key_exists, call:op.create_foreign_key, func:downgrade() → None, call:op.drop_index, call:op.drop_constraint, call:op.drop_column, call:op.drop_table | dep: collections.abc, alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
-- 0013_add_probe_result.py | Alembic database migration that adds a JSON probe_result column to the tool_instances table | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, func:downgrade() → None, call:op.drop_column | dep: typing, alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
-- 0014_add_profile_resolver_fields.py | Alembic database migration that adds profile resolver fields (project_id, tool_type_id, environment_variables, start_command, working_directory, port, is_default) to config_profiles table, renames mount_path to target_path and adds mode/files columns to config_mounts table while removing source_profile_id and content columns | exp: func:_table_exists(table_name: str) → bool, call:sa.inspect(op.get_bind()).has_table, call:op.get_bind, func:_column_exists(table_name: str, column_name: str) → bool, call:_table_exists, call:sa.inspect(op.get_bind()).get_columns, call:op.get_bind, func:_index_exists(table_name: str, index_name: str) → bool, call:_table_exists, call:sa.inspect(op.get_bind()).get_indexes, call:op.get_bind, func:_foreign_key_exists(table_name: str, constrained_columns: list[str], referred_table: str) → bool, call:_table_exists, call:sa.inspect(op.get_bind()).get_foreign_keys, call:op.get_bind, call:foreign_key.get, func:_foreign_key_names_for_column(table_name: str, column_name: str) → list[str], call:_table_exists, call:sa.inspect(op.get_bind()).get_foreign_keys, call:op.get_bind, call:foreign_key.get, call:names.append, func:upgrade() → None, call:_column_exists, call:op.add_column, call:sa.Column, call:postgresql.UUID, call:sa.JSON, call:sa.Text, call:sa.Integer, call:sa.Boolean, call:_foreign_key_exists, call:op.create_foreign_key, call:_index_exists, call:op.create_index, call:op.alter_column, call:sa.String, call:_foreign_key_names_for_column, call:op.drop_constraint, call:op.drop_column, func:downgrade() → None, call:op.add_column, call:sa.Column, call:postgresql.UUID, call:sa.Text, call:op.drop_column, call:op.alter_column, call:op.drop_index, call:op.drop_constraint | dep: collections.abc, alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
-- 0014_merge_heads.py | Alembic merge migration that combines two divergent migration branches into a single history line | exp: func:upgrade() → None, func:downgrade() → None | dep: typing, alembic
-- 0015_single_interface.py | Alembic database migration that replaces a plural JSON interfaces column with singular interface_type and requires_port columns on tool_types table | exp: func:_get_dialect() → str, call:op.get_bind, func:upgrade() → None, call:_get_dialect, call:op.add_column, call:sa.Column, call:sa.String, call:sa.Boolean, call:op.execute, call:op.alter_column, call:op.drop_column, call:op.create_check_constraint, call:sa.text, func:downgrade() → None, call:_get_dialect, call:op.drop_constraint, call:op.add_column, call:sa.Column, call:postgresql.JSONB, call:sa.Text, call:op.execute, call:sa.JSON, call:op.drop_column | dep: typing, alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
+- 0011_tool_instance_tunnel_fields.py | Alembic database migration that adds tunnel-related fields (public_url and tunnel_id) to the tool_instances table. | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.String, func:downgrade() → None, call:op.drop_column | dep: typing, alembic, sqlalchemy
+- 0012_default_port_req.py | Alembic database migration that populates default_port values for existing tool types and makes the column non-nullable | exp: func:upgrade() → None, call:op.execute, call:op.alter_column, call:sa.Integer, func:downgrade() → None, call:op.alter_column, call:sa.Integer | dep: typing, alembic, sqlalchemy
+- 0013_add_config_profiles.py | Alembic database migration that adds config_profiles, config_includes, config_mounts tables and a selected_profile_id column to tool_instances with defensive checks for idempotent execution | exp: func:_table_exists(table_name: str) → bool, call:sa.inspect(op.get_bind()).has_table, call:op.get_bind, func:_column_exists(table_name: str, column_name: str) → bool, call:_table_exists, call:sa.inspect(op.get_bind()).get_columns, call:op.get_bind, func:_index_exists(table_name: str, index_name: str) → bool, call:_table_exists, call:sa.inspect(op.get_bind()).get_indexes, call:op.get_bind, func:_foreign_key_exists(table_name: str, constrained_columns: list[str], referred_table: str) → bool, call:_table_exists, call:sa.inspect(op.get_bind()).get_foreign_keys, call:op.get_bind, call:foreign_key.get, func:upgrade() → None, call:_table_exists, call:op.create_table, call:sa.Column, call:postgresql.UUID, call:sa.String, call:sa.Text, call:sa.DateTime, call:sa.text, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:sa.UniqueConstraint, call:_index_exists, call:op.create_index, call:sa.Integer, call:_column_exists, call:op.add_column, call:_foreign_key_exists, call:op.create_foreign_key, func:downgrade() → None, call:op.drop_index, call:op.drop_constraint, call:op.drop_column, call:op.drop_table | dep: collections.abc, alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
+- 0013_add_probe_result.py | Database migration to add a JSON probe_result column to the tool_instances table | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, func:downgrade() → None, call:op.drop_column | dep: typing, alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
+- 0014_add_profile_resolver_fields.py | Alembic database migration that adds profile resolver fields to config_profiles and config_mounts tables with idempotent schema checks | exp: func:_table_exists(table_name: str) → bool, call:sa.inspect(op.get_bind()).has_table, call:op.get_bind, func:_column_exists(table_name: str, column_name: str) → bool, call:_table_exists, call:sa.inspect(op.get_bind()).get_columns, call:op.get_bind, func:_index_exists(table_name: str, index_name: str) → bool, call:_table_exists, call:sa.inspect(op.get_bind()).get_indexes, call:op.get_bind, func:_foreign_key_exists(table_name: str, constrained_columns: list[str], referred_table: str) → bool, call:_table_exists, call:sa.inspect(op.get_bind()).get_foreign_keys, call:op.get_bind, call:foreign_key.get, func:_foreign_key_names_for_column(table_name: str, column_name: str) → list[str], call:_table_exists, call:sa.inspect(op.get_bind()).get_foreign_keys, call:op.get_bind, call:foreign_key.get, call:names.append, func:upgrade() → None, call:_column_exists, call:op.add_column, call:sa.Column, call:postgresql.UUID, call:sa.JSON, call:sa.Text, call:sa.Integer, call:sa.Boolean, call:_foreign_key_exists, call:op.create_foreign_key, call:_index_exists, call:op.create_index, call:op.alter_column, call:sa.String, call:_foreign_key_names_for_column, call:op.drop_constraint, call:op.drop_column, func:downgrade() → None, call:op.add_column, call:sa.Column, call:postgresql.UUID, call:sa.Text, call:op.drop_column, call:op.alter_column, call:op.drop_index, call:op.drop_constraint | dep: collections.abc, alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
+- 0014_merge_heads.py | Alembic merge migration that reconciles two divergent migration branches without applying schema changes | exp: func:upgrade() → None, func:downgrade() → None | dep: typing, alembic
+- 0015_single_interface.py | Alembic database migration that replaces a JSON array `interfaces` column with a single `interface_type` string column and adds a `requires_port` boolean column, with dialect-specific SQL for PostgreSQL and SQLite data migration. | exp: func:_get_dialect() → str, call:op.get_bind, func:upgrade() → None, call:_get_dialect, call:op.add_column, call:sa.Column, call:sa.String, call:sa.Boolean, call:op.execute, call:op.alter_column, call:op.drop_column, call:op.create_check_constraint, call:sa.text, func:downgrade() → None, call:_get_dialect, call:op.drop_constraint, call:op.add_column, call:sa.Column, call:postgresql.JSONB, call:sa.Text, call:op.execute, call:sa.JSON, call:op.drop_column | dep: typing, alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
 - 069d3da4dc9b_add_ssh_key_id_to_config_profiles.py | Alembic database migration that adds an ssh_key_id foreign key column to the config_profiles table | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.Uuid, call:sa.ForeignKey, func:downgrade() → None, call:op.drop_column | dep: alembic, sqlalchemy
-- 20260527160017_add_pi_agent_tool_type.py | Alembic database migration that adds a new "pi-agent" tool type with terminal-based Docker development environment configuration | exp: func:upgrade() → None, call:op.get_bind, call:conn.execute( sa.text("SELECT id FROM tool_types WHERE name = 'pi-agent'") ).fetchone, call:sa.text, call:json.dumps, func:downgrade() → None, call:op.get_bind, call:conn.execute, call:sa.text | dep: json, typing, alembic, uuid, sqlalchemy
-- 2026_05_22_add_clone_mode.py | Alembic database migration that adds ssh_key_id foreign key to git_repositories and clone_mode/branch columns to tool_instances | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:postgresql.UUID, call:op.create_foreign_key, call:sa.String, func:downgrade() → None, call:op.drop_column, call:op.drop_constraint | dep: alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
-- 2026_05_23_remove_is_builtin.py | Alembic database migration that removes the `is_builtin` column from the `tool_types` table with downgrade support to restore it. | exp: func:upgrade() → None, call:op.execute, func:downgrade() → None, call:op.add_column, call:sa.Column, call:sa.Boolean | dep: alembic, sqlalchemy
-- 2026_05_24_220141_add_startup_command.py | Alembic database migration that adds a nullable `startup_command` text column to the `tool_types` table. | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.Text, func:downgrade() → None, call:op.drop_column | dep: typing, alembic, sqlalchemy
-- 2026_05_24_add_config_profiles.py | Alembic database migration that creates config_profiles and config_profile_includes tables with indexes, and adds a selected_config_profile_id foreign key to tool_instances | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:postgresql.UUID, call:sa.text, call:sa.ForeignKey, call:sa.String, call:sa.Text, call:postgresql.JSONB, call:sa.Boolean, call:sa.DateTime, call:sa.PrimaryKeyConstraint, call:sa.UniqueConstraint, call:op.create_index, call:sa.Integer, call:op.add_column, func:downgrade() → None, call:op.drop_index, call:op.drop_column, call:op.drop_table | dep: typing, alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
-- 2026_05_26_add_git_mounts.py | Alembic database migration that adds a git_mounts JSON column to the config_profiles table | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.JSON, func:downgrade() → None, call:op.drop_column | dep: typing, alembic, sqlalchemy
-- 2026_05_27_external_repos.py | Alembic database migration that makes project_id nullable in git_repositories to support external repositories and expands alembic_version version_num column to prevent truncation. | exp: func:upgrade() → None, call:op.execute, call:op.alter_column, call:sa.UUID, func:downgrade() → None, call:op.alter_column, call:sa.UUID, call:op.execute | dep: typing, alembic, sqlalchemy
-- 2026_05_28_add_monitoring_tables.py | Alembic database migration that creates monitoring tables (instance_events and health_checks) with indexes for tracking tool instance events and health check status. | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:sa.Uuid, call:sa.String, call:sa.Text, call:sa.JSON, call:sa.DateTime, call:sa.func.now, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:op.create_index, call:sa.Boolean, call:sa.Integer, func:downgrade() → None, call:op.drop_index, call:op.drop_table | dep: collections.abc, alembic, sqlalchemy
-- 2026_05_28_add_terminal_sessions_table.py | Alembic database migration that creates a terminal_sessions table with foreign key to tool_instances for tracking terminal session lifecycle | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:sa.UUID, call:sa.String, call:sa.DateTime, call:sa.text, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:op.create_index, call:op.f, func:downgrade() → None, call:op.drop_index, call:op.f, call:op.drop_table | dep: collections.abc, alembic, sqlalchemy
-- 2026_05_28_add_tool_definition_manifests.py | Alembic database migration that creates a tool_definition_manifests table, adds manifest support to tool_types and tool_instances, and migrates the pi-agent tool from Dockerfile/compose templates to a JSON-based manifest system with a base Ubuntu image definition. | exp: func:upgrade() → None, call:op.get_bind, call:op.create_table, call:sa.Column, call:sa.UUID, call:sa.String, call:sa.Text, call:sa.JSON, call:sa.Boolean, call:sa.TIMESTAMP, call:sa.func.now, call:sa.PrimaryKeyConstraint, call:sa.UniqueConstraint, call:sa.ForeignKeyConstraint, call:sa.CheckConstraint, call:conn.execute, call:sa.text, call:result.fetchone, call:op.add_column, call:op.create_foreign_key, call:op.drop_constraint, call:op.execute, call:json.dumps, call:str, func:downgrade() → None, call:op.get_bind, call:conn.execute, call:sa.text, call:result.fetchone, call:op.drop_column, call:op.drop_constraint, call:op.drop_table | dep: json, uuid, typing, alembic, sqlalchemy
-- 2026_05_28_drop_tool_configs_and_config_folders.py | Database migration that drops the `tool_configs` and `config_folders` tables with conditional existence checks, and provides downgrade to recreate them. | exp: func:upgrade() → None, call:op.get_bind, call:conn.execute, call:sa.text, call:result.fetchone, call:op.drop_table, func:downgrade() → None, call:op.create_table, call:sa.Column, call:sa.UUID, call:sa.String, call:sa.Text, call:sa.JSON, call:sa.Boolean, call:sa.TIMESTAMP, call:sa.func.now, call:sa.PrimaryKeyConstraint, call:sa.Integer | dep: typing, alembic, sqlalchemy
-- 2026_05_29_add_notifications_table.py | Alembic database migration that creates a notifications table with user-linked, categorized, and severity-based notification records including read/dismissed tracking and optimized indexes. | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:sa.Uuid, call:sa.String, call:sa.Text, call:sa.JSON, call:sa.DateTime, call:sa.func.now, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:op.create_index, call:sa.text, func:downgrade() → None, call:op.drop_index, call:op.drop_table | dep: collections.abc, alembic, sqlalchemy
+- 20260527160017_add_pi_agent_tool_type.py | Adds a database migration that inserts a new "pi-agent" tool type into a tool_types table, defining a terminal-based Docker development environment with nvim, ranger, and tmux. | exp: func:upgrade() → None, call:op.get_bind, call:conn.execute( sa.text("SELECT id FROM tool_types WHERE name = 'pi-agent'") ).fetchone, call:sa.text, call:json.dumps, func:downgrade() → None, call:op.get_bind, call:conn.execute, call:sa.text | dep: json, typing, alembic, uuid, sqlalchemy
+- 2026_05_22_add_clone_mode.py | Alembic database migration that adds ssh_key_id foreign key to git_repositories table and clone_mode/branch columns to tool_instances table | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:postgresql.UUID, call:op.create_foreign_key, call:sa.String, func:downgrade() → None, call:op.drop_column, call:op.drop_constraint | dep: alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
+- 2026_05_23_remove_is_builtin.py | Alembic database migration that removes the `is_builtin` column from the `tool_types` table with a downgrade path to restore it. | exp: func:upgrade() → None, call:op.execute, func:downgrade() → None, call:op.add_column, call:sa.Column, call:sa.Boolean | dep: alembic, sqlalchemy
+- 2026_05_24_220141_add_startup_command.py | Alembic database migration that adds a nullable startup_command column to the tool_types table. | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.Text, func:downgrade() → None, call:op.drop_column | dep: typing, alembic, sqlalchemy
+- 2026_05_24_add_config_profiles.py | Alembic database migration that creates config_profiles and config_profile_includes tables with indexes, and adds a selected_config_profile_id foreign key to tool_instances. | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:postgresql.UUID, call:sa.text, call:sa.ForeignKey, call:sa.String, call:sa.Text, call:postgresql.JSONB, call:sa.Boolean, call:sa.DateTime, call:sa.PrimaryKeyConstraint, call:sa.UniqueConstraint, call:op.create_index, call:sa.Integer, call:op.add_column, func:downgrade() → None, call:op.drop_index, call:op.drop_column, call:op.drop_table | dep: typing, alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
+- 2026_05_26_add_git_mounts.py | Database migration to add a `git_mounts` JSON column to the `config_profiles` table | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.JSON, func:downgrade() → None, call:op.drop_column | dep: typing, alembic, sqlalchemy
+- 2026_05_27_external_repos.py | Alembic database migration that makes project_id nullable in git_repositories table to support external repositories and expands alembic_version version_num column to VARCHAR(64). | exp: func:upgrade() → None, call:op.execute, call:op.alter_column, call:sa.UUID, func:downgrade() → None, call:op.alter_column, call:sa.UUID, call:op.execute | dep: typing, alembic, sqlalchemy
+- 2026_05_28_add_monitoring_tables.py | Creates two database tables (instance_events and health_checks) for monitoring tool instances via an Alembic migration. | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:sa.Uuid, call:sa.String, call:sa.Text, call:sa.JSON, call:sa.DateTime, call:sa.func.now, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:op.create_index, call:sa.Boolean, call:sa.Integer, func:downgrade() → None, call:op.drop_index, call:op.drop_table | dep: collections.abc, alembic, sqlalchemy
+- 2026_05_28_add_terminal_sessions_table.py | Alembic database migration that creates a terminal_sessions table with foreign key to tool_instances, including indexes and audit timestamps | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:sa.UUID, call:sa.String, call:sa.DateTime, call:sa.text, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:op.create_index, call:op.f, func:downgrade() → None, call:op.drop_index, call:op.f, call:op.drop_table | dep: collections.abc, alembic, sqlalchemy
+- 2026_05_28_add_tool_definition_manifests.py | Alembic database migration that creates a tool_definition_manifests table, adds manifest support to tool_types and tool_instances, and migrates the pi-agent tool to a manifest-based definition with a base Ubuntu image. | exp: func:upgrade() → None, call:op.get_bind, call:op.create_table, call:sa.Column, call:sa.UUID, call:sa.String, call:sa.Text, call:sa.JSON, call:sa.Boolean, call:sa.TIMESTAMP, call:sa.func.now, call:sa.PrimaryKeyConstraint, call:sa.UniqueConstraint, call:sa.ForeignKeyConstraint, call:sa.CheckConstraint, call:conn.execute, call:sa.text, call:result.fetchone, call:op.add_column, call:op.create_foreign_key, call:op.drop_constraint, call:op.execute, call:json.dumps, call:str, func:downgrade() → None, call:op.get_bind, call:conn.execute, call:sa.text, call:result.fetchone, call:op.drop_column, call:op.drop_constraint, call:op.drop_table | dep: json, uuid, typing, alembic, sqlalchemy
+- 2026_05_28_drop_tool_configs_and_config_folders.py | Alembic database migration that drops the tool_configs and config_folders tables with conditional existence checks, and provides downgrade to recreate them | exp: func:upgrade() → None, call:op.get_bind, call:conn.execute, call:sa.text, call:result.fetchone, call:op.drop_table, func:downgrade() → None, call:op.create_table, call:sa.Column, call:sa.UUID, call:sa.String, call:sa.Text, call:sa.JSON, call:sa.Boolean, call:sa.TIMESTAMP, call:sa.func.now, call:sa.PrimaryKeyConstraint, call:sa.Integer | dep: typing, alembic, sqlalchemy
+- 2026_05_29_add_notifications_table.py | Creates a notifications table with user-linked, categorized, severity-graded messages supporting read/dismissed states and optimized querying via partial indexes. | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:sa.Uuid, call:sa.String, call:sa.Text, call:sa.JSON, call:sa.DateTime, call:sa.func.now, call:sa.ForeignKeyConstraint, call:sa.PrimaryKeyConstraint, call:op.create_index, call:sa.text, func:downgrade() → None, call:op.drop_index, call:op.drop_table | dep: collections.abc, alembic, sqlalchemy
 - 2026_05_29_add_ssh_key_ids_to_tool_instances.py | Alembic database migration that adds a JSON ssh_key_ids column to the tool_instances table | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.JSON, func:downgrade() → None, call:op.drop_column | dep: alembic, sqlalchemy
 - 2026_05_29_drop_ssh_key_id_from_config_profiles.py | Alembic database migration that removes the ssh_key_id column from the config_profiles table | exp: func:upgrade() → None, call:op.drop_column, func:downgrade() → None, call:op.add_column, call:sa.Column, call:sa.Uuid, call:sa.ForeignKey | dep: alembic, sqlalchemy
 - 2026_05_29_fix_code_server_bind_addr.py | Alembic database migration that fixes code-server tool type compose templates by replacing deprecated --bind-addr flag with --host flag | exp: func:upgrade() → None, call:op.get_bind, call:conn.execute( sa.text(""" SELECT id, compose_template FROM tool_types WHERE name = 'code-server' AND compose_template LIKE '%--bind-addr%' """) ).fetchall, call:sa.text, call:compose_template.replace( "--bind-addr 0.0.0.0:8443", "--host 0.0.0.0" ).replace, call:print, func:downgrade() → None | dep: typing, alembic, sqlalchemy
-- 2026_05_29_fix_code_server_bind_addr_port.py | Alembic database migration that fixes code-server Docker compose templates by replacing broken `--host` flags with correct `--bind-addr 0.0.0.0:{port}` configurations in both database tool_type templates and on-disk instance compose files. | exp: func:_fix_tool_type_templates(conn) → None, call:conn.execute( sa.text(""" SELECT id, compose_template, default_port FROM tool_types WHERE name = 'code-server' AND compose_template LIKE '%--host%' """) ).fetchall, call:sa.text, call:compose_template.split, call:len, call:line.lstrip, call:new_lines.append, call:"\n".join, call:print, func:_fix_instance_compose_files(conn) → None, call:conn.execute( sa.text(""" SELECT column_name FROM information_schema.columns WHERE table_name = 'tool_instances' AND column_name = 'compose_path' """) ).fetchone, call:sa.text, call:print, call:conn.execute( sa.text(""" SELECT id, compose_path, tool_type_id FROM tool_instances WHERE compose_path IS NOT NULL """) ).fetchall, call:Path, call:path.exists, call:path.read_text, call:conn.execute( sa.text(""" SELECT default_port FROM tool_types WHERE id = :id """), {"id": tool_type_id}, ).fetchone, call:yaml.safe_load, call:data["services"].values, call:path.write_text, call:yaml.dump, func:upgrade() → None, call:op.get_bind, call:_fix_tool_type_templates, call:_fix_instance_compose_files, func:downgrade() → None | dep: typing, alembic, yaml, pathlib, sqlalchemy
-- 2026_05_29_fix_web_tool_bind_address.py | Alembic database migration that fixes code-server and jupyter-notebook tool compose templates to bind to 0.0.0.0 | exp: func:_fix_code_server_compose(conn) → None, call:conn.execute( sa.text(""" SELECT id, compose_template, definition_type FROM tool_types WHERE name = 'code-server' """) ).fetchone, call:sa.text, call:compose_template.split, call:enumerate, call:len, call:line.lstrip, call:new_lines.append, call:image_line.lstrip, call:new_lines.index, call:new_lines.insert, call:"\n".join, call:print, func:_fix_jupyter_compose(conn) → None, call:conn.execute( sa.text(""" SELECT id, compose_template, definition_type FROM tool_types WHERE name = 'jupyter-notebook' """) ).fetchone, call:sa.text, call:compose_template.split, call:enumerate, call:new_lines.append, call:len, call:line.lstrip, call:"\n".join, call:print, func:upgrade() → None, call:op.get_bind, call:_fix_code_server_compose, call:_fix_jupyter_compose, func:downgrade() → None | dep: typing, alembic, sqlalchemy
-- 2026_05_29_remove_lsio_command_override.py | Alembic database migration that removes broken command overrides containing --bind-addr or --host flags from LinuxServer.io code-server Docker Compose templates in both database records and on-disk compose files. | exp: func:upgrade() → None, call:op.get_bind, call:conn.execute( sa.text(""" SELECT id, compose_template FROM tool_types WHERE name = 'code-server' """) ).fetchall, call:sa.text, call:yaml.safe_load, call:data["services"].values, call:svc.get, call:yaml.dump, call:print, call:conn.execute( sa.text(""" SELECT column_name FROM information_schema.columns WHERE table_name = 'tool_instances' AND column_name = 'compose_path' """) ).fetchone, call:conn.execute( sa.text(""" SELECT id, compose_path FROM tool_instances WHERE compose_path IS NOT NULL """) ).fetchall, call:Path, call:path.exists, call:path.read_text, call:path.write_text, func:downgrade() → None | dep: collections.abc, alembic, yaml, pathlib, sqlalchemy
-- 2026_05_29_remove_ssh_keys_mount_from_manifest.py | Alembic database migration that removes (and can restore) the ssh_keys mount from the pi-agent tool definition manifest stored as JSON | exp: func:upgrade() → None, call:op.get_bind, call:conn.execute, call:sa.text, call:result.fetchone, call:isinstance, call:json.loads, call:manifest.get, call:len, call:m.get, call:json.dumps, func:downgrade() → None, call:op.get_bind, call:conn.execute, call:sa.text, call:result.fetchone, call:isinstance, call:json.loads, call:manifest.get, call:any, call:m.get, call:mounts.append, call:json.dumps | dep: json, typing, alembic, sqlalchemy
-- 2026_06_01_add_workspaces.py | Alembic database migration that creates a workspaces table with indexes and adds a workspace_id foreign key to tool_instances | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:sa.Uuid, call:sa.String, call:sa.ForeignKey, call:sa.DateTime, call:sa.text, call:sa.UniqueConstraint, call:op.create_index, call:op.add_column, func:downgrade() → None, call:op.drop_index, call:op.drop_column, call:op.drop_table | dep: collections.abc, alembic, sqlalchemy
-- 2026_06_13_make_clone_mode_nullable.py | Alembic database migration to make the `clone_mode` column nullable in the `tool_instances` table | exp: func:upgrade() → None, call:op.alter_column, call:sa.String, func:downgrade() → None, call:op.alter_column, call:sa.String | dep: alembic, sqlalchemy
-- 2026_06_14_104415_add_tool_type_home_directory.py | Alembic database migration that adds a home_directory column to tool_types table and updates template strings from /workspace to a configurable path | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.String, call:op.execute, call:sa.update(tool_types) .where(tool_types.c.compose_template.is_not(None)) .values, call:tool_types.c.compose_template.is_not, call:sa.func.replace, call:sa.update(tool_types) .where(tool_types.c.dockerfile_template.is_not(None)) .values, call:tool_types.c.dockerfile_template.is_not, func:downgrade() → None, call:op.execute, call:sa.update(tool_types) .where(tool_types.c.compose_template.is_not(None)) .values, call:tool_types.c.compose_template.is_not, call:sa.func.replace, call:sa.update(tool_types) .where(tool_types.c.dockerfile_template.is_not(None)) .values, call:tool_types.c.dockerfile_template.is_not, call:op.drop_column | dep: typing, alembic, sqlalchemy.sql, sqlalchemy
-- 2026_06_14_182955_fix_pi_agent_home_directory_mount.py | Alembic database migration that updates the pi-agent tool definition manifest to mount repos under the home directory instead of /workspace | exp: func:_find_pi_agent_manifest(conn: sa.Connection) → tuple[Union[str, None], Union[dict, None]], call:conn.execute( sa.select(tool_definition_manifests.c.id, tool_definition_manifests.c.manifest) .where(tool_definition_manifests.c.name == "pi-agent") ).fetchone, call:sa.select(tool_definition_manifests.c.id, tool_definition_manifests.c.manifest) .where, call:dict, func:_update_manifest(conn: sa.Connection, manifest_id: str, manifest: dict) → None, call:conn.execute, call:sa.update(tool_definition_manifests) .where(tool_definition_manifests.c.id == manifest_id) .values, func:upgrade() → None, call:op.get_bind, call:_find_pi_agent_manifest, call:manifest.get, call:mount.get, call:manifest.setdefault, call:_update_manifest, func:downgrade() → None, call:op.get_bind, call:_find_pi_agent_manifest, call:manifest.get, call:mount.get, call:manifest.setdefault, call:_update_manifest | dep: typing, alembic, sqlalchemy.sql, sqlalchemy
-- 2026_06_15_090500_remove_pi_agent_explicit_repo_mount.py | Alembic database migration that removes explicit repo mounts from pi-agent tool definition manifests since they are now synthesized by compile_compose | exp: func:_find_pi_agent_manifest(conn: sa.Connection) → tuple[Union[str, None], Union[dict, None]], call:conn.execute( sa.select( tool_definition_manifests.c.id, tool_definition_manifests.c.manifest ).where(tool_definition_manifests.c.name == "pi-agent") ).fetchone, call:sa.select( tool_definition_manifests.c.id, tool_definition_manifests.c.manifest ).where, call:dict, func:_update_manifest(conn: sa.Connection, manifest_id: str, manifest: dict) → None, call:conn.execute, call:sa.update(tool_definition_manifests) .where(tool_definition_manifests.c.id == manifest_id) .values, func:upgrade() → None, call:op.get_bind, call:_find_pi_agent_manifest, call:manifest.get, call:mount.get, call:_update_manifest, func:downgrade() → None, call:op.get_bind, call:_find_pi_agent_manifest, call:manifest.setdefault, call:any, call:mount.get, call:mounts.append, call:_update_manifest | dep: typing, alembic, sqlalchemy.sql, sqlalchemy
-- 398082499c30_add_tool_config_fields.py | Alembic database migration that adds configuration fields (port_override, start_command, working_directory, environment_variables, volumes) to the tool_configs table with a port range check constraint. | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.Integer, call:sa.Text, call:postgresql.JSONB, call:op.create_check_constraint, call:sa.text, func:downgrade() → None, call:op.drop_constraint, call:op.drop_column | dep: alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
-- 6fc7bfcf199f_merge_remove_is_builtin_and_add_config_.py | Alembic database migration that merges two branches (removing is_builtin and adding config_profiles) with no actual schema changes | exp: func:upgrade() → None, func:downgrade() → None | dep: alembic
-- 86cec91fdb00_merge_profile_resolver_and_workspaces_.py | Alembic database migration that merges two divergent migration branches (profile resolver and workspaces) into a single head | exp: func:upgrade() → None, func:downgrade() → None | dep: alembic
-- 8c6d1dbd4798_remove_pi_config_and_state_mounts_from_.py | Alembic database migration that removes pi_state and pi_config mounts from the pi-agent manifest in upgrade, and restores them in downgrade | exp: func:_load_manifest(manifest_json), call:isinstance, call:json.loads, func:upgrade() → None, call:op.get_bind, call:conn.execute, call:sa.text, call:result.fetchone, call:_load_manifest, call:manifest.get, call:len, call:m.get, call:json.dumps, func:downgrade() → None, call:op.get_bind, call:conn.execute, call:sa.text, call:result.fetchone, call:_load_manifest, call:manifest.get, call:m.get, call:mounts.append, call:json.dumps | dep: json, alembic, sqlalchemy
-- 8ed7dd80973d_create_config_folders_table.py | Creates a database migration that adds a config_folders table for storing user configuration folders with JSONB metadata, foreign key relationships, and indexing. | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:postgresql.UUID, call:sa.text, call:sa.ForeignKey, call:sa.String, call:sa.Text, call:postgresql.JSONB, call:sa.Boolean, call:sa.DateTime, call:sa.UniqueConstraint, call:op.create_index, func:downgrade() → None, call:op.drop_index, call:op.drop_table | dep: alembic, sqlalchemy.dialects, sqlalchemy, postgresql dialect
-- af8512103d67_add_tool_type_fields.py | Alembic database migration that adds new columns (definition_type, dockerfile_template, build_context, readiness_probe) to the tool_types table with a CHECK constraint on definition_type. | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.String, call:sa.Text, call:postgresql.JSONB, call:op.create_check_constraint, call:sa.text, func:downgrade() → None, call:op.drop_constraint, call:op.drop_column | dep: alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
-- f3d2dc90ba3a_merge_single_interface_and_clone_mode.py | Alembic database migration that merges two parent revisions (single_interface and clone_mode) into a single branch point with no actual schema changes | exp: func:upgrade() → None, func:downgrade() → None | dep: typing, alembic
+- 2026_05_29_fix_code_server_bind_addr_port.py | Alembic database migration that fixes code-server Docker compose templates by replacing incorrect `--host` flags with proper `--bind-addr 0.0.0.0:PORT` configurations in both database-stored tool type templates and on-disk instance compose files. | exp: func:_fix_tool_type_templates(conn) → None, call:conn.execute( sa.text(""" SELECT id, compose_template, default_port FROM tool_types WHERE name = 'code-server' AND compose_template LIKE '%--host%' """) ).fetchall, call:sa.text, call:compose_template.split, call:len, call:line.lstrip, call:new_lines.append, call:"\n".join, call:print, func:_fix_instance_compose_files(conn) → None, call:conn.execute( sa.text(""" SELECT column_name FROM information_schema.columns WHERE table_name = 'tool_instances' AND column_name = 'compose_path' """) ).fetchone, call:sa.text, call:print, call:conn.execute( sa.text(""" SELECT id, compose_path, tool_type_id FROM tool_instances WHERE compose_path IS NOT NULL """) ).fetchall, call:Path, call:path.exists, call:path.read_text, call:conn.execute( sa.text(""" SELECT default_port FROM tool_types WHERE id = :id """), {"id": tool_type_id}, ).fetchone, call:yaml.safe_load, call:data["services"].values, call:path.write_text, call:yaml.dump, func:upgrade() → None, call:op.get_bind, call:_fix_tool_type_templates, call:_fix_instance_compose_files, func:downgrade() → None | dep: typing, alembic, yaml, pathlib, sqlalchemy
+- 2026_05_29_fix_web_tool_bind_address.py | Alembic database migration that fixes web tool (code-server and jupyter-notebook) compose templates to bind to 0.0.0.0 for network accessibility. | exp: func:_fix_code_server_compose(conn) → None, call:conn.execute( sa.text(""" SELECT id, compose_template, definition_type FROM tool_types WHERE name = 'code-server' """) ).fetchone, call:sa.text, call:compose_template.split, call:enumerate, call:len, call:line.lstrip, call:new_lines.append, call:image_line.lstrip, call:new_lines.index, call:new_lines.insert, call:"\n".join, call:print, func:_fix_jupyter_compose(conn) → None, call:conn.execute( sa.text(""" SELECT id, compose_template, definition_type FROM tool_types WHERE name = 'jupyter-notebook' """) ).fetchone, call:sa.text, call:compose_template.split, call:enumerate, call:new_lines.append, call:len, call:line.lstrip, call:"\n".join, call:print, func:upgrade() → None, call:op.get_bind, call:_fix_code_server_compose, call:_fix_jupyter_compose, func:downgrade() → None | dep: typing, alembic, sqlalchemy
+- 2026_05_29_remove_lsio_command_override.py | Alembic database migration that removes broken command overrides containing --bind-addr or --host from LinuxServer.io (LSIO) code-server Docker Compose templates in both database tool_types records and on-disk instance compose files. | exp: func:upgrade() → None, call:op.get_bind, call:conn.execute( sa.text(""" SELECT id, compose_template FROM tool_types WHERE name = 'code-server' """) ).fetchall, call:sa.text, call:yaml.safe_load, call:data["services"].values, call:svc.get, call:yaml.dump, call:print, call:conn.execute( sa.text(""" SELECT column_name FROM information_schema.columns WHERE table_name = 'tool_instances' AND column_name = 'compose_path' """) ).fetchone, call:conn.execute( sa.text(""" SELECT id, compose_path FROM tool_instances WHERE compose_path IS NOT NULL """) ).fetchall, call:Path, call:path.exists, call:path.read_text, call:path.write_text, func:downgrade() → None | dep: collections.abc, alembic, yaml, pathlib, sqlalchemy
+- 2026_05_29_remove_ssh_keys_mount_from_manifest.py | Alembic database migration that removes the ssh_keys mount from the pi-agent manifest in the tool_definition_manifests table, with downgrade support to restore it. | exp: func:upgrade() → None, call:op.get_bind, call:conn.execute, call:sa.text, call:result.fetchone, call:isinstance, call:json.loads, call:manifest.get, call:len, call:m.get, call:json.dumps, func:downgrade() → None, call:op.get_bind, call:conn.execute, call:sa.text, call:result.fetchone, call:isinstance, call:json.loads, call:manifest.get, call:any, call:m.get, call:mounts.append, call:json.dumps | dep: json, typing, alembic, sqlalchemy
+- 2026_06_01_add_workspaces.py | Alembic database migration that creates a workspaces table with foreign keys to git_repositories and users, adds indexes, and adds a workspace_id column to tool_instances. | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:sa.Uuid, call:sa.String, call:sa.ForeignKey, call:sa.DateTime, call:sa.text, call:sa.UniqueConstraint, call:op.create_index, call:op.add_column, func:downgrade() → None, call:op.drop_index, call:op.drop_column, call:op.drop_table | dep: collections.abc, alembic, sqlalchemy
+- 2026_06_13_make_clone_mode_nullable.py | Alembic database migration that makes the `clone_mode` column in the `tool_instances` table nullable to allow NULL values for new rows. | exp: func:upgrade() → None, call:op.alter_column, call:sa.String, func:downgrade() → None, call:op.alter_column, call:sa.String | dep: alembic, sqlalchemy
+- 2026_06_14_104415_add_tool_type_home_directory.py | An Alembic database migration that adds a `home_directory` column to `tool_types` table and updates template strings from `/workspace` to a configurable `/home/user/{{WORKSPACE_NAME}}` path. | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.String, call:op.execute, call:sa.update(tool_types) .where(tool_types.c.compose_template.is_not(None)) .values, call:tool_types.c.compose_template.is_not, call:sa.func.replace, call:sa.update(tool_types) .where(tool_types.c.dockerfile_template.is_not(None)) .values, call:tool_types.c.dockerfile_template.is_not, func:downgrade() → None, call:op.execute, call:sa.update(tool_types) .where(tool_types.c.compose_template.is_not(None)) .values, call:tool_types.c.compose_template.is_not, call:sa.func.replace, call:sa.update(tool_types) .where(tool_types.c.dockerfile_template.is_not(None)) .values, call:tool_types.c.dockerfile_template.is_not, call:op.drop_column | dep: typing, alembic, sqlalchemy.sql, sqlalchemy
+- 2026_06_14_182955_fix_pi_agent_home_directory_mount.py | Alembic database migration that fixes the pi-agent tool definition manifest's home directory mount path from /workspace to ~/{{WORKSPACE_NAME}} with a compatibility symlink and updated startup script. | exp: func:_find_pi_agent_manifest(conn: sa.Connection) → tuple[Union[str, None], Union[dict, None]], call:conn.execute( sa.select(tool_definition_manifests.c.id, tool_definition_manifests.c.manifest) .where(tool_definition_manifests.c.name == "pi-agent") ).fetchone, call:sa.select(tool_definition_manifests.c.id, tool_definition_manifests.c.manifest) .where, call:dict, func:_update_manifest(conn: sa.Connection, manifest_id: str, manifest: dict) → None, call:conn.execute, call:sa.update(tool_definition_manifests) .where(tool_definition_manifests.c.id == manifest_id) .values, func:upgrade() → None, call:op.get_bind, call:_find_pi_agent_manifest, call:manifest.get, call:mount.get, call:manifest.setdefault, call:_update_manifest, func:downgrade() → None, call:op.get_bind, call:_find_pi_agent_manifest, call:manifest.get, call:mount.get, call:manifest.setdefault, call:_update_manifest | dep: typing, alembic, sqlalchemy.sql, sqlalchemy
+- 2026_06_15_090500_remove_pi_agent_explicit_repo_mount.py | Alembic database migration that removes explicit repo mounts from the pi-agent tool definition manifest and restores them on downgrade | exp: func:_find_pi_agent_manifest(conn: sa.Connection) → tuple[Union[str, None], Union[dict, None]], call:conn.execute( sa.select( tool_definition_manifests.c.id, tool_definition_manifests.c.manifest ).where(tool_definition_manifests.c.name == "pi-agent") ).fetchone, call:sa.select( tool_definition_manifests.c.id, tool_definition_manifests.c.manifest ).where, call:dict, func:_update_manifest(conn: sa.Connection, manifest_id: str, manifest: dict) → None, call:conn.execute, call:sa.update(tool_definition_manifests) .where(tool_definition_manifests.c.id == manifest_id) .values, func:upgrade() → None, call:op.get_bind, call:_find_pi_agent_manifest, call:manifest.get, call:mount.get, call:_update_manifest, func:downgrade() → None, call:op.get_bind, call:_find_pi_agent_manifest, call:manifest.setdefault, call:any, call:mount.get, call:mounts.append, call:_update_manifest | dep: typing, alembic, sqlalchemy.sql, sqlalchemy
+- 2026_06_19_113000_remove_pi_agent_workspace_symlink.py | Alembic database migration that updates the pi-agent tool definition manifest to remove the /workspace symlink dependency and adjust working directory and startup script accordingly. | exp: func:_find_pi_agent_manifest(conn: sa.Connection) → tuple[str | None, dict | None], call:conn.execute( sa.select( tool_definition_manifests.c.id, tool_definition_manifests.c.manifest ).where(tool_definition_manifests.c.name == "pi-agent") ).fetchone, call:sa.select( tool_definition_manifests.c.id, tool_definition_manifests.c.manifest ).where, call:dict, func:_update_manifest(conn: sa.Connection, manifest_id: str, manifest: dict) → None, call:conn.execute, call:sa.update(tool_definition_manifests) .where(tool_definition_manifests.c.id == manifest_id) .values, func:upgrade() → None, call:op.get_bind, call:_find_pi_agent_manifest, call:manifest.setdefault, call:runtime.get, call:_update_manifest, func:downgrade() → None, call:op.get_bind, call:_find_pi_agent_manifest, call:manifest.setdefault, call:_update_manifest | dep: collections.abc, alembic, sqlalchemy.sql, sqlalchemy
+- 398082499c30_add_tool_config_fields.py | Alembic database migration that adds configuration fields (port_override, start_command, working_directory, environment_variables, volumes) to the tool_configs table with a port range validation constraint. | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.Integer, call:sa.Text, call:postgresql.JSONB, call:op.create_check_constraint, call:sa.text, func:downgrade() → None, call:op.drop_constraint, call:op.drop_column | dep: alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
+- 6fc7bfcf199f_merge_remove_is_builtin_and_add_config_.py | Alembic merge migration that combines two parallel migration branches (remove_is_builtin and add_config_profiles) into a single revision history | exp: func:upgrade() → None, func:downgrade() → None | dep: alembic
+- 86cec91fdb00_merge_profile_resolver_and_workspaces_.py | Merges two Alembic migration branches (profile resolver and workspaces) into a single migration head | exp: func:upgrade() → None, func:downgrade() → None | dep: alembic
+- 8c6d1dbd4798_remove_pi_config_and_state_mounts_from_.py | Alembic database migration that removes or restores pi_state and pi_config mounts from a JSON manifest stored in the tool_definition_manifests table for the 'pi-agent' tool. | exp: func:_load_manifest(manifest_json), call:isinstance, call:json.loads, func:upgrade() → None, call:op.get_bind, call:conn.execute, call:sa.text, call:result.fetchone, call:_load_manifest, call:manifest.get, call:len, call:m.get, call:json.dumps, func:downgrade() → None, call:op.get_bind, call:conn.execute, call:sa.text, call:result.fetchone, call:_load_manifest, call:manifest.get, call:m.get, call:mounts.append, call:json.dumps | dep: json, alembic, sqlalchemy
+- 8ed7dd80973d_create_config_folders_table.py | Alembic database migration that creates a config_folders table with UUID primary key, user foreign key, JSONB fields for files and project overrides, and supporting indexes/constraints | exp: func:upgrade() → None, call:op.create_table, call:sa.Column, call:postgresql.UUID, call:sa.text, call:sa.ForeignKey, call:sa.String, call:sa.Text, call:postgresql.JSONB, call:sa.Boolean, call:sa.DateTime, call:sa.UniqueConstraint, call:op.create_index, func:downgrade() → None, call:op.drop_index, call:op.drop_table | dep: alembic, sqlalchemy.dialects, sqlalchemy, postgresql dialect
+- af8512103d67_add_tool_type_fields.py | Alembic database migration that adds columns (definition_type, dockerfile_template, build_context, readiness_probe) and a check constraint to the tool_types table. | exp: func:upgrade() → None, call:op.add_column, call:sa.Column, call:sa.String, call:sa.Text, call:postgresql.JSONB, call:op.create_check_constraint, call:sa.text, func:downgrade() → None, call:op.drop_constraint, call:op.drop_column | dep: alembic, sqlalchemy.dialects, sqlalchemy, sqlalchemy.dialects.postgresql
+- f3d2dc90ba3a_merge_single_interface_and_clone_mode.py | Alembic database migration that merges two previous migrations (single_interface and clone_mode) into a single revision point | exp: func:upgrade() → None, func:downgrade() → None | dep: typing, alembic
 - fc8f1a20cbf6_merge_home_directory_and_pi_agent_mount_.py | Alembic database migration that merges two branch heads (home directory and pi agent mount cleanup) into a single revision point | exp: func:upgrade() → None, func:downgrade() → None | dep: alembic
 ## arch
-Linear migration history with branching/merge resolution pattern; each migration is an immutable, timestamped or sequenced script containing declarative SQLAlchemy operations (create_table, add_column, drop_column) with bidirectional upgrade/downgrade functions; includes data migrations, idempotent guards, and cross-references to on-disk file mutations.
+Linear migration history with occasional branch/merge patterns (using merge heads), sequential numbered and timestamped revision files, each containing declarative schema changes (CREATE TABLE/ALTER TABLE/DROP TABLE) with idempotent guards, downgrade paths, and occasional data migrations; supports PostgreSQL and SQLite dialects.
 ## tags
 column, table, call:op.drop, downgrade, upgrade, alembic, key, call:sa.text
 ## symbols
@@ -76,5 +77,7 @@ column, table, call:op.drop, downgrade, upgrade, alembic, key, call:sa.text
   read: 2026_05_24_220141_add_startup_command.py, 2026_05_29_remove_lsio_command_override.py
 - change versions config
   read: 0003_user_configs.py, 0009_tool_configs.py, 0013_add_config_profiles.py
+- explore versions subdirectories
+  index: apps/api/alembic/versions/.ruff_cache/.pi-map.index.md
 ## dirty
 -

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

@@ -0,0 +1,87 @@
+"""remove pi agent workspace symlink
+
+Revision ID: 2026_06_19_113000
+Revises: 2026_06_15_090500
+Create Date: 2026-06-19 11:30:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.sql import column, table
+
+# revision identifiers, used by Alembic.
+revision: str = "2026_06_19_113000"
+down_revision: str | Sequence[str] | None = "2026_06_15_090500"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+tool_definition_manifests = table(
+    "tool_definition_manifests",
+    column("id", sa.UUID),
+    column("name", sa.String),
+    column("manifest", sa.JSON),
+)
+
+
+def _find_pi_agent_manifest(
+    conn: sa.Connection,
+) -> tuple[str | None, dict | None]:
+    result = conn.execute(
+        sa.select(
+            tool_definition_manifests.c.id, tool_definition_manifests.c.manifest
+        ).where(tool_definition_manifests.c.name == "pi-agent")
+    ).fetchone()
+    if result is None:
+        return None, None
+    return result.id, dict(result.manifest)
+
+
+def _update_manifest(conn: sa.Connection, manifest_id: str, manifest: dict) -> None:
+    conn.execute(
+        sa.update(tool_definition_manifests)
+        .where(tool_definition_manifests.c.id == manifest_id)
+        .values(manifest=manifest)
+    )
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    manifest_id, manifest = _find_pi_agent_manifest(conn)
+    if not manifest_id or not manifest:
+        return
+
+    runtime = manifest.setdefault("runtime", {})
+    # The /workspace compatibility symlink is no longer created by the
+    # compiler/entrypoint. Leaving working_dir set to /workspace causes the
+    # container to start in an empty directory. Let compile_compose default
+    # to /home/user/{workspace_name} instead.
+    if runtime.get("working_dir") == "/workspace":
+        del runtime["working_dir"]
+
+    scripts = manifest.setdefault("scripts", {})
+    # Update the startup script to operate on the real repo-named directory.
+    scripts["startup"] = [
+        'if [ -n "$WORKSPACE_NAME" ]; then sudo chown -R user:user "$HOME/$WORKSPACE_NAME" 2>/dev/null || true; fi',
+    ]
+
+    _update_manifest(conn, manifest_id, manifest)
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    manifest_id, manifest = _find_pi_agent_manifest(conn)
+    if not manifest_id or not manifest:
+        return
+
+    runtime = manifest.setdefault("runtime", {})
+    runtime["working_dir"] = "/workspace"
+
+    scripts = manifest.setdefault("scripts", {})
+    scripts["startup"] = [
+        "if [ -d /workspace ]; then sudo chown -R user:user /workspace 2>/dev/null || true; fi",
+    ]
+
+    _update_manifest(conn, manifest_id, manifest)

apps/api/src/.pi-map.index.md

@@ -2,17 +2,23 @@
 dir: apps/api/src
 
 ## role
-Core backend API package for the "Headquarter API" FastAPI application, handling configuration, database setup, logging, and application bootstrap.
+Core FastAPI application package that initializes and configures the Headquarter API with database, authentication, logging, and middleware infrastructure.
 ## parent
 index: apps/api/.pi-map.index.md
 map: apps/api/.pi-map.md
 ## children
+- apps/api/src/.ruff_cache
+  index: apps/api/src/.ruff_cache/.pi-map.index.md
+  map: apps/api/src/.ruff_cache/.pi-map.md
 - apps/api/src/api
   index: apps/api/src/api/.pi-map.index.md
   map: apps/api/src/api/.pi-map.md
 - apps/api/src/auth
   index: apps/api/src/auth/.pi-map.index.md
   map: apps/api/src/auth/.pi-map.md
+- apps/api/src/headquarter_api.egg-info
+  index: apps/api/src/headquarter_api.egg-info/.pi-map.index.md
+  map: apps/api/src/headquarter_api.egg-info/.pi-map.md
 - apps/api/src/models
   index: apps/api/src/models/.pi-map.index.md
   map: apps/api/src/models/.pi-map.md
@@ -46,6 +52,6 @@ map: apps/api/src/.pi-map.md
 - change src config
   read: config.py, logging_config.py
 - explore src subdirectories
-  index: apps/api/src/api/.pi-map.index.md, apps/api/src/auth/.pi-map.index.md, apps/api/src/models/.pi-map.index.md
+  index: apps/api/src/.ruff_cache/.pi-map.index.md, apps/api/src/api/.pi-map.index.md, apps/api/src/auth/.pi-map.index.md
 ## dirty
 -

apps/api/src/.pi-map.md

@@ -4,17 +4,17 @@ dir: apps/api/src
 index: apps/api/src/.pi-map.index.md
 
 ## role
-Core backend API package for the "Headquarter API" FastAPI application, handling configuration, database setup, logging, and application bootstrap.
+Core FastAPI application package that initializes and configures the Headquarter API with database, authentication, logging, and middleware infrastructure.
 ## files
 - __init__.py | Marks the directory as a Python package for the Headquarter API.
-- config.py | Defines application configuration settings with environment variable loading, database URL construction, and computed properties for service URLs and security settings. | exp: class:Settings, func:build_database_url(user: str, password: str, host: str, port: int, database: str) → str | dep: pydantic, pydantic_settings
-- database.py | Sets up an async SQLAlchemy database engine with retry logic and runs Alembic migrations via subprocess to initialize the database. | exp: func:init_database(max_retries, retry_delay) → bool, call:range, call:engine.connect, call:test_conn.execute, call:text, call:test_conn.close, call:logger.info, call:asyncio.get_event_loop().run_in_executor, call:subprocess.run, call:os.path.dirname, call:os.path.abspath, call:logger.debug, call:logger.error, call:asyncio.sleep, call:str(exc).lower, call:logger.warning | dep: asyncio, logging, os, subprocess, sqlalchemy.ext.asyncio, sqlalchemy.pool, src.config, sqlalchemy
-- logging_config.py | Configures structured JSON logging with correlation ID injection, request/response logging middleware, and exception handling for a FastAPI application. | exp: class:CorrelationIdFilter, method:filter(self, record: logging.LogRecord) → bool, call:get_correlation_id, class:JSONFormatter, method:format(self, record: logging.LogRecord) → str, call:self.formatTime, call:record.getMessage, call:getattr, call:self.formatException, call:json.dumps, method:formatTime(self, record: logging.LogRecord, datefmt) → str, call:time.strftime, call:time.gmtime, class:RequestLoggingMiddleware, method:dispatch(self, request: Request, call_next: Callable) → Response, call:time.time, call:logger.info, call:call_next, call:int, call:logger.error, call:type, call:traceback.format_exc, class:ExceptionLoggingMiddleware, method:dispatch(self, request: Request, call_next: Callable) → Response, call:call_next, call:logger.critical, call:traceback.format_exc, func:configure_logging(level) → None, call:JSONFormatter, call:logging.StreamHandler, call:console_handler.setFormatter, call:console_handler.addFilter, call:CorrelationIdFilter, call:root_logger.setLevel, call:logging.getLogger("uvicorn").setLevel, call:logging.getLogger("uvicorn.access").setLevel, call:logging.getLogger("sqlalchemy.engine").setLevel, call:logger.info, call:logging.getLevelName | dep: json, logging, sys, time, traceback, collections.abc, fastapi, starlette.middleware.base, src.services.shared.correlation, starlette
-- main.py | Bootstraps a FastAPI application called "Headquarter API" with database initialization, health monitoring, CORS, logging middleware, and modular API routers. | exp: func:_sanitize_validation_errors(errors), call:error.get, call:str, call:ctx.items, call:isinstance, call:type, call:sanitized.append, func:validation_exception_handler(request: Request, exc: RequestValidationError), call:exc.errors, call:logger.warning, call:_sanitize_validation_errors, call:JSONResponse, func:on_startup(), call:logger.info, call:init_database, call:logger.error, call:sys.exit, call:_health_monitor.start, call:seed_builtin_tool_types, func:on_shutdown(), call:logger.info, call:_health_monitor.stop | dep: logging, os, fastapi, fastapi.exceptions, fastapi.middleware.cors, fastapi.responses, fastapi.staticfiles, src.api.config, src.api.project, src.api.system, src.api.tool, src.api.user, src.api.workspace, src.config, src.models, src.database, src.logging_config, src.seeds.builtin_tool_types, src.services.instance, src.services.shared, sys, src.api
+- config.py | Defines application configuration settings using pydantic-settings, including database connectivity, Authentik SSO, JWT, session, and domain-based URL resolution. | exp: class:Settings, func:build_database_url(user: str, password: str, host: str, port: int, database: str) → str | dep: pydantic, pydantic_settings
+- database.py | Configures an async SQLAlchemy database engine/session and provides a retry-based initialization function that runs Alembic migrations via subprocess. | exp: func:init_database(max_retries, retry_delay) → bool, call:range, call:engine.connect, call:test_conn.execute, call:text, call:test_conn.close, call:logger.info, call:asyncio.get_event_loop().run_in_executor, call:subprocess.run, call:os.path.dirname, call:os.path.abspath, call:logger.debug, call:logger.error, call:asyncio.sleep, call:str(exc).lower, call:logger.warning | dep: asyncio, logging, os, subprocess, sqlalchemy.ext.asyncio, sqlalchemy.pool, src.config, sqlalchemy
+- logging_config.py | Configures structured JSON logging with correlation ID injection and provides ASGI middleware for logging HTTP requests, responses, and unhandled exceptions. | exp: class:CorrelationIdFilter, method:filter(self, record: logging.LogRecord) → bool, call:get_correlation_id, class:JSONFormatter, method:format(self, record: logging.LogRecord) → str, call:self.formatTime, call:record.getMessage, call:getattr, call:self.formatException, call:json.dumps, method:formatTime(self, record: logging.LogRecord, datefmt) → str, call:time.strftime, call:time.gmtime, class:RequestLoggingMiddleware, method:dispatch(self, request: Request, call_next: Callable) → Response, call:time.time, call:logger.info, call:call_next, call:int, call:logger.error, call:type, call:traceback.format_exc, class:ExceptionLoggingMiddleware, method:dispatch(self, request: Request, call_next: Callable) → Response, call:call_next, call:logger.critical, call:traceback.format_exc, func:configure_logging(level) → None, call:JSONFormatter, call:logging.StreamHandler, call:console_handler.setFormatter, call:console_handler.addFilter, call:CorrelationIdFilter, call:root_logger.setLevel, call:logging.getLogger("uvicorn").setLevel, call:logging.getLogger("uvicorn.access").setLevel, call:logging.getLogger("sqlalchemy.engine").setLevel, call:logger.info, call:logging.getLevelName | dep: json, logging, sys, time, traceback, collections.abc, fastapi, starlette.middleware.base, src.services.shared.correlation, starlette
+- main.py | Initializes and configures the FastAPI application, setting up middleware, routers, database connections, and lifecycle event handlers for the Headquarter API. | exp: func:_sanitize_validation_errors(errors), call:error.get, call:str, call:ctx.items, call:isinstance, call:type, call:sanitized.append, func:validation_exception_handler(request: Request, exc: RequestValidationError), call:exc.errors, call:logger.warning, call:_sanitize_validation_errors, call:JSONResponse, func:on_startup(), call:logger.info, call:init_database, call:logger.error, call:sys.exit, call:_health_monitor.start, call:seed_builtin_tool_types, func:on_shutdown(), call:logger.info, call:_health_monitor.stop | dep: logging, os, fastapi, fastapi.exceptions, fastapi.middleware.cors, fastapi.responses, fastapi.staticfiles, src.api.config, src.api.project, src.api.system, src.api.tool, src.api.user, src.api.workspace, src.config, src.models, src.database, src.logging_config, src.seeds.builtin_tool_types, src.services.instance, src.services.shared, sys, src.api, src.seeds, src.services
 ## arch
-Layered architecture with separation of concerns across config (settings/env), database (async SQLAlchemy with Alembic migrations), logging (structured JSON with middleware), and main (app composition with modular routers and health monitoring).
+Layered architecture using Pydantic-settings for configuration, async SQLAlchemy with Alembic migrations, structured JSON logging with correlation ID tracking, and FastAPI lifecycle management with dependency injection for cross-cutting concerns.
 ## tags
-src, logging, database, api, call:logger.info, middleware, fastapi, filter
+src, logging, database, call:logger.info, api, middleware, filter, call:logging.get
 ## symbols
 - Settings
 - CorrelationIdFilter
@@ -30,6 +30,6 @@ src, logging, database, api, call:logger.info, middleware, fastapi, filter
 - change src config
   read: config.py, logging_config.py
 - explore src subdirectories
-  index: apps/api/src/api/.pi-map.index.md, apps/api/src/auth/.pi-map.index.md, apps/api/src/models/.pi-map.index.md
+  index: apps/api/src/.ruff_cache/.pi-map.index.md, apps/api/src/api/.pi-map.index.md, apps/api/src/auth/.pi-map.index.md
 ## dirty
 -

apps/api/src/api/.pi-map.index.md

@@ -2,11 +2,14 @@
 dir: apps/api/src/api
 
 ## role
-Provides shared Pydantic validators and package initialization for API schema validation across the API layer.
+Defines the core API router package with reusable Pydantic validation utilities for container and filesystem-related API schemas.
 ## parent
 index: apps/api/src/.pi-map.index.md
 map: apps/api/src/.pi-map.md
 ## children
+- apps/api/src/api/.ruff_cache
+  index: apps/api/src/api/.ruff_cache/.pi-map.index.md
+  map: apps/api/src/api/.ruff_cache/.pi-map.md
 - apps/api/src/api/config
   index: apps/api/src/api/config/.pi-map.index.md
   map: apps/api/src/api/config/.pi-map.md
@@ -35,6 +38,6 @@ map: apps/api/src/api/.pi-map.md
 - change api behavior
   read: __init__.py, shared_validators.py
 - explore api subdirectories
-  index: apps/api/src/api/config/.pi-map.index.md, apps/api/src/api/project/.pi-map.index.md, apps/api/src/api/system/.pi-map.index.md
+  index: apps/api/src/api/.ruff_cache/.pi-map.index.md, apps/api/src/api/config/.pi-map.index.md, apps/api/src/api/project/.pi-map.index.md
 ## dirty
 -

apps/api/src/api/.pi-map.md

@@ -4,14 +4,14 @@ dir: apps/api/src/api
 index: apps/api/src/api/.pi-map.index.md
 
 ## role
-Provides shared Pydantic validators and package initialization for API schema validation across the API layer.
+Defines the core API router package with reusable Pydantic validation utilities for container and filesystem-related API schemas.
 ## files
 - __init__.py | Marks the directory as a Python package for API routers.
-- shared_validators.py | Provides reusable Pydantic validators for API schema fields including mount paths, file dictionaries, environment variables, and volume mounts. | exp: func:validate_mount_path(v: str | None) → str | None, call:v.startswith, raise:ValueError, func:validate_files(v: dict | None, max_size_bytes) → dict | None, call:v.items, call:path.startswith, call:len, call:content.encode, raise:ValueError, func:validate_env_vars(v: dict | None) → dict | None, call:isinstance, raise:ValueError, func:validate_volumes(v: list | None) → list | None, call:isinstance, call:enumerate, raise:ValueError
+- shared_validators.py | Provides reusable Pydantic validator functions for validating mount paths, file contents, environment variables, and volume mounts in API schemas. | exp: func:validate_mount_path(v: str | None) → str | None, call:v.startswith, raise:ValueError, func:validate_files(v: dict | None, max_size_bytes) → dict | None, call:v.items, call:path.startswith, call:len, call:content.encode, raise:ValueError, func:validate_env_vars(v: dict | None) → dict | None, call:isinstance, raise:ValueError, func:validate_volumes(v: list | None) → list | None, call:isinstance, call:enumerate, raise:ValueError
 ## arch
-Utility module pattern with reusable cross-cutting Pydantic validators for common API field types (mount paths, files, env vars, volumes).
+Modular package structure separating router organization from shared cross-cutting validation concerns using Pydantic validators.
 ## tags
-validate, raise:value, error, call:isinstance, validators, mount, api, init
+validate, raise:value, error, call:isinstance, mount, api, init, path
 ## symbols
 - validate_mount_path
 - validate_files
@@ -25,6 +25,6 @@ validate, raise:value, error, call:isinstance, validators, mount, api, init
 - change api behavior
   read: __init__.py, shared_validators.py
 - explore api subdirectories
-  index: apps/api/src/api/config/.pi-map.index.md, apps/api/src/api/project/.pi-map.index.md, apps/api/src/api/system/.pi-map.index.md
+  index: apps/api/src/api/.ruff_cache/.pi-map.index.md, apps/api/src/api/config/.pi-map.index.md, apps/api/src/api/project/.pi-map.index.md
 ## dirty
 -

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

@@ -1,7 +1,9 @@
 """Config profile API endpoints."""
 
 import logging
+import os
 import uuid
+from pathlib import Path
 
 from fastapi import APIRouter, Depends, HTTPException, Query, status
 from sqlalchemy import select
@@ -9,7 +11,8 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import selectinload
 
 from src.auth.dependencies import get_current_user_id, get_db_session
-from src.models import ConfigProfile, ConfigProfileInclude, UserConfig
+from src.config import Settings
+from src.models import ConfigProfile, ConfigProfileInclude, ToolInstance, UserConfig
 from src.schemas.config import (
     ConfigProfileCreate,
     ConfigProfileIncludeUpdate,
@@ -21,6 +24,7 @@ from src.schemas.config import (
 )
 from src.services.config.config_profile_resolver import (
     ConfigProfileCycleError,
+    apply_resolved_profile,
     resolve_profile,
     resolved_profile_to_dict,
 )
@@ -43,6 +47,59 @@ logger = logging.getLogger(__name__)
 router = APIRouter(prefix="/config-profiles", tags=["config-profiles"])
 
 
+def _canonical_profile_response(profile: ConfigProfile) -> dict:
+    """Return profile data with edits from its shared working copy."""
+    response = profile_to_response(profile)
+    root = Path(Settings().instance_base_path) / "config-profiles" / str(profile.id)
+
+    def read_file(path: Path, fallback: str) -> str:
+        try:
+            return path.read_text() if path.is_file() else fallback
+        except OSError:
+            return fallback
+
+    response["files"] = {
+        relative_path: read_file(root / "files" / relative_path, content)
+        for relative_path, content in response["files"].items()
+    }
+    response["mounts"] = [dict(mount) for mount in response["mounts"]]
+    for mount in response["mounts"]:
+        mount_root = root / "mounts" / mount["target"].lstrip("/").replace("/", "_")
+        mount["files"] = {
+            relative_path: read_file(mount_root / relative_path, content)
+            for relative_path, content in mount.get("files", {}).items()
+        }
+    return response
+
+
+async def _running_profile_outcomes(
+    session: AsyncSession, profile_id: uuid.UUID
+) -> list[dict[str, str]]:
+    """Report running instances that must restart to adopt a profile revision."""
+    result = await session.execute(
+        select(ToolInstance).where(ToolInstance.status == "running")
+    )
+    outcomes: list[dict[str, str]] = []
+    for instance in result.scalars().all():
+        if instance.selected_config_profile_id is None:
+            continue
+        resolved = await resolve_profile(session, instance.selected_config_profile_id)
+        dependencies = {resolved.profile_id} | {
+            uuid.UUID(item["id"])
+            for item in resolved.included_profiles
+            if item.get("id")
+        }
+        if profile_id in dependencies:
+            outcomes.append(
+                {
+                    "instance_id": str(instance.id),
+                    "status": "restart_required",
+                    "reason": "Existing instance must restart to adopt shared profile mounts",
+                }
+            )
+    return outcomes
+
+
 @router.get("", response_model=list[ConfigProfileResponse])
 async def list_config_profiles(
     project_id: str | None = Query(None, description="Filter by project compatibility"),
@@ -85,7 +142,7 @@ async def list_config_profiles(
 
     result = await session.execute(query)
     profiles = result.scalars().all()
-    return [profile_to_response(p) for p in profiles]
+    return [_canonical_profile_response(profile) for profile in profiles]
 
 
 @router.post(
@@ -118,7 +175,7 @@ async def get_config_profile(
         raise HTTPException(
             status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized"
         )
-    return profile_to_response(profile)
+    return _canonical_profile_response(profile)
 
 
 @router.put("/{profile_id}", response_model=ConfigProfileResponse)
@@ -140,8 +197,63 @@ async def update_config_profile(
         )
 
     profile = await update_profile(session, profile, data)
+    resolved = await resolve_profile(session, profile.id)
+    apply_resolved_profile(
+        os.path.join(Settings().instance_base_path, "profile-refresh"),
+        resolved,
+    )
+    response = _canonical_profile_response(profile)
+    response["refresh_outcomes"] = await _running_profile_outcomes(session, profile.id)
     logger.debug("Updated config profile %s", profile.id)
-    return profile_to_response(profile)
+    return response
+
+
+@router.post("/{profile_id}/refresh-git-mounts")
+async def refresh_profile_git_mounts(
+    profile_id: str,
+    confirm_destructive_refresh: bool = False,
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+):
+    """Destructively refresh profile Git working copies used by instances."""
+    if not confirm_destructive_refresh:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="Confirm destructive Git refresh before replacing local edits",
+        )
+
+    profile = await get_profile_with_includes(session, uuid.UUID(profile_id))
+    if profile is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="Profile not found"
+        )
+    if profile.user_id != current_user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized"
+        )
+
+    # Import lazily: instance_service imports tool schemas that transitively
+    # load API routers, so importing it during router initialization cycles.
+    from src.services.tool.instance_service import resolve_git_mounts
+
+    outcomes = await _running_profile_outcomes(session, profile.id)
+    for outcome in outcomes:
+        instance = await session.get(ToolInstance, uuid.UUID(outcome["instance_id"]))
+        if (
+            instance is None
+            or not instance.compose_path
+            or instance.selected_config_profile_id is None
+        ):
+            continue
+        resolved = await resolve_profile(session, instance.selected_config_profile_id)
+        await resolve_git_mounts(
+            session,
+            resolved,
+            os.path.dirname(instance.compose_path),
+        )
+        outcome["status"] = "refreshed"
+        outcome["reason"] = "Canonical Git mount source refreshed in place"
+    return {"refresh_outcomes": outcomes}
 
 
 @router.delete("/{profile_id}", status_code=status.HTTP_204_NO_CONTENT)
@@ -161,6 +273,16 @@ async def delete_config_profile(
             status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized"
         )
 
+    outcomes = await _running_profile_outcomes(session, profile.id)
+    if outcomes:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail={
+                "message": "Profile is still used by running instances",
+                "outcomes": outcomes,
+            },
+        )
+
     await session.delete(profile)
     await session.commit()
 

apps/api/src/api/system/.pi-map.index.md

@@ -2,12 +2,14 @@
 dir: apps/api/src/api/system
 
 ## role
-Provides system-level API endpoints for monitoring, administration, and operational infrastructure including health checks, dashboards, real-time events, notifications, and container terminal access.
+Provides system-level API endpoints for monitoring, administration, and infrastructure operations including dashboards, health checks, event streaming, instance proxying, notifications, and terminal access.
 ## parent
 index: apps/api/src/api/.pi-map.index.md
 map: apps/api/src/api/.pi-map.md
 ## children
--
+- apps/api/src/api/system/.ruff_cache
+  index: apps/api/src/api/system/.ruff_cache/.pi-map.index.md
+  map: apps/api/src/api/system/.ruff_cache/.pi-map.md
 ## files
 - __init__.py
 - dashboard.py
@@ -22,5 +24,7 @@ map: apps/api/src/api/system/.pi-map.md
 ## workflows
 - change system behavior
   read: __init__.py, dashboard.py, events.py
+- explore system subdirectories
+  index: apps/api/src/api/system/.ruff_cache/.pi-map.index.md
 ## dirty
 -

apps/api/src/api/system/.pi-map.md

@@ -4,19 +4,19 @@ dir: apps/api/src/api/system
 index: apps/api/src/api/system/.pi-map.index.md
 
 ## role
-Provides system-level API endpoints for monitoring, administration, and operational infrastructure including health checks, dashboards, real-time events, notifications, and container terminal access.
+Provides system-level API endpoints for monitoring, administration, and infrastructure operations including dashboards, health checks, event streaming, instance proxying, notifications, and terminal access.
 ## files
-- __init__.py | Aggregates and re-exports system API routers from submodules for centralized access. | dep: src.api.system.dashboard, src.api.system.events, src.api.system.health, src.api.system.instance_proxy, src.api.system.notifications, src.api.system.terminal
+- __init__.py | Aggregates and exports system API routers for a modular web application framework. | dep: src.api.system.dashboard, src.api.system.events, src.api.system.health, src.api.system.instance_proxy, src.api.system.notifications, src.api.system.terminal
 - dashboard.py | Provides a FastAPI endpoint that returns a dashboard summary with counts of projects, repositories, SSH keys, and recent activity for the authenticated user. | exp: func:get_dashboard_summary(user_id, session) → dict, call:session.execute, call:select(func.count()).select_from(Project).where, call:func.count, call:projects_result.scalar, call:select(func.count()).select_from(GitRepository).where, call:repos_result.scalar, call:select(func.count()).select_from(SSHKey).where, call:ssh_keys_result.scalar, call:select(Project) .where(Project.owner_id == user_id) .order_by(Project.created_at.desc()) .limit, call:Project.created_at.desc, call:recent_projects.scalars().all | dep: uuid, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models, src.models.project
-- events.py | Implements an SSE streaming endpoint that broadcasts instance events to authenticated users with per-user connection limits and backpressure handling. | exp: func:events_stream(request: Request, user_id) → StreamingResponse, call:_connection_counts.get, call:InstanceEventBus, call:asyncio.Queue, call:queue.put_nowait, call:contextlib.suppress, call:queue.get_nowait, call:event_bus.subscribe, call:asyncio.wait_for, call:queue.get, call:json.dumps, call:unsubscribe, call:max, call:_connection_counts.pop, call:StreamingResponse, call:event_generator, raise:HTTPException, func:event_generator() → AsyncGenerator[str, None], call:InstanceEventBus, call:asyncio.Queue, call:queue.put_nowait, call:contextlib.suppress, call:queue.get_nowait, call:event_bus.subscribe, call:asyncio.wait_for, call:queue.get, call:json.dumps, call:unsubscribe, call:max, call:_connection_counts.get, call:_connection_counts.pop, func:on_event(payload: InstanceEventPayload) → None, call:queue.put_nowait, call:contextlib.suppress, call:queue.get_nowait | dep: asyncio, contextlib, json, uuid, collections.abc, fastapi, fastapi.responses, src.auth.dependencies, src.services.instance.event_bus
-- health.py | Provides FastAPI health check endpoints that monitor database connectivity, disk space, and system uptime with performance timing. | exp: func:health_check() → dict[str, Any], call:HealthChecks, call:time_module.perf_counter, call:SessionLocal, call:session.execute, call:text, call:DatabaseHealth, call:round, call:shutil.disk_usage, call:DiskHealth, call:HealthResponse( status=overall_status, timestamp=datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"), version="0.1.0", checks=checks, uptime_seconds=round(time.time() - _start_time, 2), ).model_dump, call:datetime.now(timezone.utc).isoformat().replace, call:time.time, func:health_check_db() → dict[str, Any], call:time_module.perf_counter, call:SessionLocal, call:session.execute, call:text, call:DatabaseHealthResponse( status="healthy", response_time_ms=round(db_time, 2), ).model_dump, call:round, call:DatabaseHealthResponse( status="unhealthy", response_time_ms=0.0, ).model_dump | dep: time, datetime, typing, fastapi, sqlalchemy, src.database, src.schemas.system, shutil
-- instance_proxy.py | HTTP proxy router that forwards incoming requests to running containerized tool instances after verifying ownership and instance status. | exp: func:_proxy_request(request: Request, instance_id: uuid.UUID, path: str, user_id: uuid.UUID, session: AsyncSession) → Response, call:session.get, call:str, call:request.headers.items, call:key.lower, call:httpx.AsyncClient, call:request.body, call:client.request, call:logger.error, call:dict, call:response_headers.pop, call:Response, raise:HTTPException, func:proxy_to_instance(request: Request, instance_id: uuid.UUID, path, user_id, session) → Response, call:_proxy_request | dep: logging, uuid, httpx, fastapi, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models
-- notifications.py | Provides FastAPI REST endpoints for managing user notifications including listing, marking read/unread, dismissing, and clearing all notifications with support for muted categories. | exp: class:NotificationItem, class:NotificationListResponse, class:UnreadCountResponse, class:MarkAllReadResponse, class:ClearAllResponse, func:_get_mute_categories(session: AsyncSession, user_id: uuid.UUID) → list[str], call:session.execute, call:select(UserConfig).where, call:result.scalar_one_or_none, call:config.config.get, call:isinstance, func:list_notifications(limit, offset, unread_only, user, session) → NotificationListResponse, call:_get_mute_categories, call:notification_service.list_notifications, call:NotificationListResponse, call:NotificationItem.model_validate, func:get_unread_count(user, session) → UnreadCountResponse, call:notification_service.get_unread_count, call:UnreadCountResponse, func:mark_notification_read(notification_id: uuid.UUID, user, session) → NotificationItem, call:notification_service.mark_read, call:NotificationItem.model_validate, raise:HTTPException, func:mark_all_read(user, session) → MarkAllReadResponse, call:notification_service.mark_all_read, call:MarkAllReadResponse, func:clear_all_notifications(user, session) → ClearAllResponse, call:notification_service.dismiss_all, call:ClearAllResponse, func:dismiss_notification(notification_id: uuid.UUID, user, session) → None, call:notification_service.dismiss, raise:HTTPException | dep: uuid, datetime, fastapi, pydantic, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models.user, src.models, src.services.shared.notification_service, sqlalchemy
-- terminal.py | Provides WebSocket and REST endpoints for browser-based terminal access to running Docker container tool instances, supporting multiple named sessions, authentication, and terminal reset/reconnect functionality. | exp: class:SessionRef, method:__init__(self, session, slot_session_id), func:terminal_websocket_default(websocket: WebSocket, instance_id: str, db_session) → None, call:_handle_terminal_websocket, func:terminal_websocket_specific(websocket: WebSocket, instance_id: str, session_id: str, db_session) → None, call:_handle_terminal_websocket, func:_handle_terminal_websocket(websocket: WebSocket, instance_id: str, target_session_id: str | None, db_session: AsyncSession) → None, call:logger.debug, call:websocket.accept, call:uuid.UUID, call:logger.error, call:websocket.close, call:_get_user_from_websocket, call:logger.warning, call:db_session.get, call:get_container_status, call:terminal_manager.get_or_create_session, call:terminal_manager.get_session, call:logger.info, call:terminal_manager.create_session, call:terminal_manager._find_key_by_internal_id, call:terminal_manager.attach_websocket, call:websocket.send_json, call:SessionRef, call:asyncio.create_task, call:_write_loop, call:_heartbeat_loop, call:asyncio.wait, call:len, call:task.cancel, call:str, call:suppress, call:terminal_manager.detach_websocket, func:_write_loop(session_ref: SessionRef, websocket, instance_id: str) → None, call:session.is_alive, call:asyncio.sleep, call:websocket.receive, call:session.write_input, call:text.startswith, call:json.loads, call:ctrl.get, call:logger.debug, call:session.resize, call:session.acknowledge_data, call:websocket.send_json, call:terminal_manager.reset_session, call:terminal_manager.attach_websocket, call:text.encode, func:_heartbeat_loop(websocket: WebSocket) → None, call:asyncio.sleep, call:websocket.send_json, func:_get_terminal_instance(instance_id: uuid.UUID, user_id: uuid.UUID, db_session: AsyncSession) → ToolInstance, call:db_session.get, raise:HTTPException, func:list_terminal_sessions(instance_id: uuid.UUID, user_id, db_session) → dict, call:_get_terminal_instance, call:db_session.execute, call:select(TerminalSessionModel) .where(TerminalSessionModel.instance_id == instance_id) .where(TerminalSessionModel.status != "closed") .order_by, call:TerminalSessionModel.created_at.asc, call:result.scalars().all, call:terminal_manager.get_session, call:str, call:sessions.append, call:live_session.has_websockets, call:row.created_at.isoformat, call:row.last_activity_at.isoformat, func:create_terminal_session(instance_id: uuid.UUID, data: dict, user_id, db_session) → dict, call:_get_terminal_instance, call:db_session.get, call:data.get, call:terminal_manager.create_session, raise:HTTPException, func:close_terminal_session(instance_id: uuid.UUID, session_id: str, user_id, db_session) → dict, call:_get_terminal_instance, call:terminal_manager._find_key_by_internal_id, call:str, call:terminal_manager.get_session, call:terminal_manager.close_session, raise:HTTPException, func:reset_specific_terminal_session(instance_id: uuid.UUID, session_id: str, user_id, db_session) → dict, call:_get_terminal_instance, call:terminal_manager._find_key_by_internal_id, call:str, call:terminal_manager.get_session, call:db_session.get, call:terminal_manager.reset_session, raise:HTTPException, func:rename_terminal_session(instance_id: uuid.UUID, session_id: str, data: dict, user_id, db_session) → dict, call:_get_terminal_instance, call:data.get, call:isinstance, call:terminal_manager.get_session, call:str, call:db_session.get, call:uuid.UUID, call:db_session.commit, raise:HTTPException, func:reset_terminal_session(instance_id: uuid.UUID, user_id, db_session) → dict, call:_get_terminal_instance, call:db_session.get, call:terminal_manager.reset_session, call:logger.info, call:str, call:logger.error, raise:HTTPException, func:_get_user_from_websocket(websocket: WebSocket, db_session: AsyncSession) → uuid.UUID | None, call:websocket.cookies.get, call:Settings, call:decode_session_cookie, call:uuid.UUID, call:str | dep: asyncio, json, logging, uuid, contextlib, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, starlette.websockets, src.auth.dependencies, src.models, src.services.terminal.terminal_manager, src.services.docker, src.auth.session, src.config, starlette
+- events.py | Implements an SSE streaming endpoint that delivers instance events to authenticated users with per-user connection limits and heartbeat pings. | dep: asyncio, contextlib, json, uuid, collections.abc, fastapi, src.auth.dependencies, src.services.instance.event_bus
+- health.py | Provides FastAPI health check endpoints that monitor system health including database connectivity/response time and disk usage, returning structured health status responses. | exp: func:health_check() → dict[str, Any], call:HealthChecks, call:time_module.perf_counter, call:SessionLocal, call:session.execute, call:text, call:DatabaseHealth, call:round, call:shutil.disk_usage, call:DiskHealth, call:HealthResponse( status=overall_status, timestamp=datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"), version="0.1.0", checks=checks, uptime_seconds=round(time.time() - _start_time, 2), ).model_dump, call:datetime.now(timezone.utc).isoformat().replace, call:time.time, func:health_check_db() → dict[str, Any], call:time_module.perf_counter, call:SessionLocal, call:session.execute, call:text, call:DatabaseHealthResponse( status="healthy", response_time_ms=round(db_time, 2), ).model_dump, call:round, call:DatabaseHealthResponse( status="unhealthy", response_time_ms=0.0, ).model_dump | dep: time, datetime, typing, fastapi, sqlalchemy, src.database, src.schemas.system, shutil
+- instance_proxy.py | Proxies HTTP requests from authenticated users to running containerized tool instances after verifying ownership and instance status. | exp: func:_proxy_request(request: Request, instance_id: uuid.UUID, path: str, user_id: uuid.UUID, session: AsyncSession) → Response, call:session.get, call:str, call:request.headers.items, call:key.lower, call:httpx.AsyncClient, call:request.body, call:client.request, call:logger.error, call:dict, call:response_headers.pop, call:Response, raise:HTTPException, func:proxy_to_instance(request: Request, instance_id: uuid.UUID, path, user_id, session) → Response, call:_proxy_request | dep: logging, uuid, httpx, fastapi, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models
+- notifications.py | Defines FastAPI REST endpoints for user notification management including listing, marking as read, dismissing, and retrieving unread counts with support for muted categories. | exp: class:NotificationItem, class:NotificationListResponse, class:UnreadCountResponse, class:MarkAllReadResponse, class:ClearAllResponse, func:_get_mute_categories(session: AsyncSession, user_id: uuid.UUID) → list[str], call:session.execute, call:select(UserConfig).where, call:result.scalar_one_or_none, call:config.config.get, call:isinstance, func:list_notifications(limit, offset, unread_only, user, session) → NotificationListResponse, call:_get_mute_categories, call:notification_service.list_notifications, call:NotificationListResponse, call:NotificationItem.model_validate, func:get_unread_count(user, session) → UnreadCountResponse, call:notification_service.get_unread_count, call:UnreadCountResponse, func:mark_notification_read(notification_id: uuid.UUID, user, session) → NotificationItem, call:notification_service.mark_read, call:NotificationItem.model_validate, raise:HTTPException, func:mark_all_read(user, session) → MarkAllReadResponse, call:notification_service.mark_all_read, call:MarkAllReadResponse, func:clear_all_notifications(user, session) → ClearAllResponse, call:notification_service.dismiss_all, call:ClearAllResponse, func:dismiss_notification(notification_id: uuid.UUID, user, session) → None, call:notification_service.dismiss, raise:HTTPException | dep: uuid, datetime, fastapi, pydantic, sqlalchemy.ext.asyncio, src.auth.dependencies, src.models.user, src.models, src.services.shared.notification_service, sqlalchemy
+- terminal.py | Provides WebSocket endpoints for browser-based terminal access to running Docker container tool instances, handling authentication, session management, input/output streaming, and terminal resize/reset operations. | exp: class:SessionRef, method:__init__(self, session, slot_session_id), func:terminal_websocket_default(websocket: WebSocket, instance_id: str, db_session) → None, call:_handle_terminal_websocket, func:terminal_websocket_specific(websocket: WebSocket, instance_id: str, session_id: str, db_session) → None, call:_handle_terminal_websocket, func:_resolve_container_user(db_session: AsyncSession, instance: ToolInstance) → str | None, call:db_session.get, call:dict, call:resolve_base, call:deep_merge, call:get_manifest_container_user, func:_handle_terminal_websocket(websocket: WebSocket, instance_id: str, target_session_id: str | None, db_session: AsyncSession) → None, call:logger.debug, call:websocket.accept, call:uuid.UUID, call:logger.error, call:websocket.close, call:_get_user_from_websocket, call:logger.warning, call:db_session.get, call:get_container_status, call:_resolve_container_user, call:terminal_manager.get_or_create_session, call:terminal_manager.get_session, call:logger.info, call:terminal_manager.create_session, call:terminal_manager._find_key_by_internal_id, call:terminal_manager.attach_websocket, call:websocket.send_json, call:SessionRef, call:asyncio.create_task, call:_write_loop, call:_heartbeat_loop, call:asyncio.wait, call:len, call:task.cancel, call:str, call:suppress, call:terminal_manager.detach_websocket, func:_write_loop(session_ref: SessionRef, websocket, instance_id: str) → None, call:session.is_alive, call:asyncio.sleep, call:websocket.receive, call:session.write_input, call:text.startswith, call:json.loads, call:ctrl.get, call:logger.debug, call:session.resize, call:session.acknowledge_data, call:websocket.send_json, call:terminal_manager.reset_session, call:terminal_manager.attach_websocket, call:text.encode, func:_heartbeat_loop(websocket: WebSocket) → None, call:asyncio.sleep, call:websocket.send_json, func:_get_terminal_instance(instance_id: uuid.UUID, user_id: uuid.UUID, db_session: AsyncSession) → ToolInstance, call:db_session.get, raise:HTTPException, func:list_terminal_sessions(instance_id: uuid.UUID, user_id, db_session) → dict, call:_get_terminal_instance, call:db_session.execute, call:select(TerminalSessionModel) .where(TerminalSessionModel.instance_id == instance_id) .where(TerminalSessionModel.status != "closed") .order_by, call:TerminalSessionModel.created_at.asc, call:result.scalars().all, call:terminal_manager.get_session, call:str, call:sessions.append, call:live_session.has_websockets, call:row.created_at.isoformat, call:row.last_activity_at.isoformat, func:create_terminal_session(instance_id: uuid.UUID, data: dict, user_id, db_session) → dict, call:_get_terminal_instance, call:db_session.get, call:data.get, call:_resolve_container_user, call:terminal_manager.create_session, raise:HTTPException, func:close_terminal_session(instance_id: uuid.UUID, session_id: str, user_id, db_session) → dict, call:_get_terminal_instance, call:terminal_manager._find_key_by_internal_id, call:str, call:terminal_manager.get_session, call:terminal_manager.close_session, raise:HTTPException, func:reset_specific_terminal_session(instance_id: uuid.UUID, session_id: str, user_id, db_session) → dict, call:_get_terminal_instance, call:terminal_manager._find_key_by_internal_id, call:str, call:terminal_manager.get_session, call:db_session.get, call:_resolve_container_user, call:terminal_manager.reset_session, raise:HTTPException, func:rename_terminal_session(instance_id: uuid.UUID, session_id: str, data: dict, user_id, db_session) → dict, call:_get_terminal_instance, call:data.get, call:isinstance, call:terminal_manager.get_session, call:str, call:db_session.get, call:uuid.UUID, call:db_session.commit, raise:HTTPException, func:reset_terminal_session(instance_id: uuid.UUID, user_id, db_session) → dict, call:_get_terminal_instance, call:db_session.get, call:_resolve_container_user, call:terminal_manager.reset_session, call:logger.info, call:str, call:logger.error, raise:HTTPException, func:_get_user_from_websocket(websocket: WebSocket, db_session: AsyncSession) → uuid.UUID | None, call:websocket.cookies.get, call:Settings, call:decode_session_cookie, call:uuid.UUID, call:str | dep: asyncio, json, logging, uuid, contextlib, fastapi, sqlalchemy, sqlalchemy.ext.asyncio, starlette.websockets, src.auth.dependencies, src.models, src.services.build.manifest_compiler, src.services.terminal.terminal_manager, src.services.docker, src.auth.session, src.config, starlette
 ## arch
-FastAPI router composition pattern with modular sub-routers aggregated via __init__.py, combining synchronous REST endpoints, SSE streaming, and WebSocket connections for real-time features, with authentication enforcement and resource ownership validation across operational and infrastructure concerns.
+Modular FastAPI router pattern with per-feature separation, combining standard REST endpoints, SSE streaming, and WebSocket connections, all with unified authentication and user-scoped access control.
 ## tags
-terminal, session, call:terminal, call:, get, src, response, instance
+terminal, session, call:terminal, call:, src, get, response, instance
 ## symbols
 - NotificationItem
 - NotificationListResponse
@@ -25,9 +25,11 @@ terminal, session, call:terminal, call:, get, src, response, instance
 - ClearAllResponse
 - SessionRef
 - get_dashboard_summary
-- events_stream
+- health_check
 ## workflows
 - change system behavior
   read: __init__.py, dashboard.py, events.py
+- explore system subdirectories
+  index: apps/api/src/api/system/.ruff_cache/.pi-map.index.md
 ## dirty
 -

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

@@ -3,6 +3,8 @@
 import asyncio
 import json
 import logging
+from asyncio import QueueFull
+from json import JSONDecodeError
 import uuid
 from contextlib import suppress
 
@@ -12,14 +14,28 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from starlette.websockets import WebSocketDisconnect
 
 from src.auth.dependencies import get_current_user_id, get_db_session
-from src.models import TerminalSessionModel
-from src.models import ToolInstance
-from src.models import ToolType
-from src.services.terminal.terminal_manager import MaxSessionsExceededError, terminal_manager
+from src.models import (
+    TerminalSessionModel,
+    ToolDefinitionManifest,
+    ToolInstance,
+    ToolType,
+)
+from src.services.build.manifest_compiler import (
+    deep_merge,
+    get_manifest_container_user,
+    resolve_base,
+)
+from src.services.terminal.terminal_manager import (
+    MaxSessionsExceededError,
+    terminal_manager,
+)
 
 router = APIRouter()
 logger = logging.getLogger(__name__)
 
+MAX_PENDING_INPUT_MESSAGES = 64
+MAX_TERMINAL_INPUT_BYTES = 1024 * 1024
+
 
 class SessionRef:
     """Mutable reference to a terminal session, allowing updates during reset."""
@@ -57,6 +73,39 @@ async def terminal_websocket_specific(
     await _handle_terminal_websocket(websocket, instance_id, session_id, db_session)
 
 
+async def _resolve_container_user(
+    db_session: AsyncSession,
+    instance: ToolInstance,
+) -> str | None:
+    """Resolve the container user for docker exec from the tool manifest.
+
+    For manifest-based tools, the user declared in the manifest (or its base
+    definition) is returned so terminal sessions run with the same privileges
+    as the main container process. Legacy tools return None, preserving the
+    previous behavior.
+    """
+    tool_type = await db_session.get(ToolType, instance.tool_type_id)
+    if not tool_type or tool_type.definition_type != "manifest":
+        return None
+
+    if not tool_type.manifest_id:
+        return None
+
+    manifest_def = await db_session.get(ToolDefinitionManifest, tool_type.manifest_id)
+    if not manifest_def:
+        return None
+
+    manifest = dict(manifest_def.manifest)
+    if manifest_def.base_definition_id:
+        base_def = await db_session.get(
+            ToolDefinitionManifest, manifest_def.base_definition_id
+        )
+        if base_def:
+            manifest = resolve_base(deep_merge(dict(base_def.manifest), manifest))
+
+    return get_manifest_container_user(manifest)
+
+
 async def _handle_terminal_websocket(
     websocket: WebSocket,
     instance_id: str,
@@ -139,7 +188,7 @@ async def _handle_terminal_websocket(
         )
         return
 
-    # Fetch tool type to get startup_command
+    # Fetch tool type to get startup_command and container_user
     tool_type = await db_session.get(ToolType, instance.tool_type_id)
     startup_command = tool_type.startup_command if tool_type else None
     if startup_command:
@@ -149,6 +198,14 @@ async def _handle_terminal_websocket(
             startup_command,
         )
 
+    container_user = await _resolve_container_user(db_session, instance)
+    if container_user:
+        logger.debug(
+            "Terminal sessions for instance %s will run as user %s",
+            instance_id,
+            container_user,
+        )
+
     session = None
 
     # Get or create terminal session
@@ -159,6 +216,7 @@ async def _handle_terminal_websocket(
                 instance_uuid,
                 instance.container_id,
                 startup_command=startup_command,
+                container_user=container_user,
             )
             slot_session_id = "default"
         else:
@@ -189,6 +247,7 @@ async def _handle_terminal_websocket(
                         startup_command=startup_command,
                         name=db_row.name,
                         session_id=target_session_id,
+                        container_user=container_user,
                     )
                 else:
                     logger.warning(
@@ -266,8 +325,38 @@ async def _handle_terminal_websocket(
                 )
 
 
+async def _input_write_loop(input_queue: asyncio.Queue[tuple[object, bytes]]) -> None:
+    """Serialize PTY writes without blocking terminal control messages."""
+    while True:
+        session, data = await input_queue.get()
+        try:
+            await session.write_input(data)  # type: ignore[attr-defined]
+        except Exception:
+            logger.debug("Terminal input write failed", exc_info=True)
+        finally:
+            input_queue.task_done()
+
+
+def _queue_terminal_input(
+    input_queue: asyncio.Queue[tuple[object, bytes]], session: object, data: bytes
+) -> bool:
+    """Queue bounded terminal input without blocking control-message processing."""
+    if len(data) > MAX_TERMINAL_INPUT_BYTES:
+        return False
+    try:
+        input_queue.put_nowait((session, data))
+    except QueueFull:
+        return False
+    return True
+
+
 async def _write_loop(session_ref: SessionRef, websocket, instance_id: str) -> None:
-    """Read input from WebSocket and send to container."""
+    """Receive terminal messages while a dedicated worker serializes PTY input."""
+    input_queue: asyncio.Queue[tuple[object, bytes]] = asyncio.Queue(
+        maxsize=MAX_PENDING_INPUT_MESSAGES
+    )
+    input_writer = asyncio.create_task(_input_write_loop(input_queue))
+
     try:
         while True:
             session = session_ref.session
@@ -277,72 +366,100 @@ async def _write_loop(session_ref: SessionRef, websocket, instance_id: str) -> N
             message = await websocket.receive()
             if message["type"] == "websocket.receive":
                 if "bytes" in message:
-                    await session.write_input(message["bytes"])
+                    if not _queue_terminal_input(
+                        input_queue, session, message["bytes"]
+                    ):
+                        logger.warning("Terminal input buffer exceeded for %s", instance_id)
+                        await websocket.close(code=1009, reason="Terminal input buffer full")
+                        break
                 elif "text" in message:
                     text = message["text"]
+                    # A text frame that parses to a JSON object with a
+                    # "type" field is a control message and must NEVER be
+                    # written to the PTY (e.g. the heartbeat {"type":"pong"}
+                    # must be consumed, not typed into the shell/pi). Handle
+                    # known types and ignore unknown ones. Everything else
+                    # (keystrokes, bracketed-paste content, plain text) is
+                    # forwarded as raw terminal input.
+                    ctrl = None
                     if text.startswith("{"):
-                        # Control message (JSON)
                         try:
-                            ctrl = json.loads(text)
-                            msg_type = ctrl.get("type")
+                            parsed = json.loads(text)
+                        except JSONDecodeError:
+                            parsed = None
+                        if isinstance(parsed, dict) and "type" in parsed:
+                            ctrl = parsed
 
-                            if msg_type == "resize":
-                                cols = ctrl.get("cols", 80)
-                                rows = ctrl.get("rows", 24)
-                                logger.debug(
-                                    "Received resize message for instance %s: %sx%s",
-                                    instance_id,
-                                    cols,
-                                    rows,
-                                )
-                                await session.resize(cols, rows)
-                            elif msg_type == "ack":
-                                char_count = ctrl.get("chars", 0)
-                                if char_count > 0:
-                                    session.acknowledge_data(char_count)
-                            elif msg_type == "reset":
-                                # Reset terminal session (scoped to current slot)
-                                logger.debug(
-                                    "Resetting terminal session for instance %s (slot=%s)",
-                                    session.instance_id,
-                                    session_ref.slot_session_id,
-                                )
-                                await websocket.send_json(
-                                    {"type": "status", "status": "resetting"}
-                                )
+                    if ctrl is None:
+                        if not _queue_terminal_input(
+                            input_queue, session, text.encode("utf-8")
+                        ):
+                            logger.warning(
+                                "Terminal input buffer exceeded for %s", instance_id
+                            )
+                            await websocket.close(
+                                code=1009, reason="Terminal input buffer full"
+                            )
+                            break
+                        continue
 
-                                # Reset the session scoped to its slot
-                                new_session = await terminal_manager.reset_session(
-                                    session.instance_id,
-                                    session.container_id,
-                                    startup_command=session.startup_command,
-                                    session_id=session_ref.slot_session_id,
-                                    name=session.name,
-                                )
+                    msg_type = ctrl["type"]
+                    if msg_type == "resize":
+                        cols = ctrl.get("cols", 80)
+                        rows = ctrl.get("rows", 24)
+                        logger.debug(
+                            "Received resize message for instance %s: %sx%s",
+                            instance_id,
+                            cols,
+                            rows,
+                        )
+                        await session.resize(cols, rows)
+                    elif msg_type == "ack":
+                        char_count = ctrl.get("chars", 0)
+                        if char_count > 0:
+                            session.acknowledge_data(char_count)
+                    elif msg_type == "reset":
+                        # Reset terminal session (scoped to current slot)
+                        logger.debug(
+                            "Resetting terminal session for instance %s (slot=%s)",
+                            session.instance_id,
+                            session_ref.slot_session_id,
+                        )
+                        await websocket.send_json(
+                            {"type": "status", "status": "resetting"}
+                        )
 
-                                # Update the mutable session reference
-                                session_ref.session = new_session
+                        # Reset the session scoped to its slot
+                        new_session = await terminal_manager.reset_session(
+                            session.instance_id,
+                            session.container_id,
+                            startup_command=session.startup_command,
+                            session_id=session_ref.slot_session_id,
+                            name=session.name,
+                            container_user=session.container_user,
+                        )
 
-                                # Attach to new session
-                                await terminal_manager.attach_websocket(
-                                    new_session, websocket
-                                )
-                                await websocket.send_json(
-                                    {"type": "status", "status": "connected"}
-                                )
+                        # Update the mutable session reference
+                        session_ref.session = new_session
 
-                                # Continue the loop with the new session
-                                continue
+                        # Attach to new session
+                        await terminal_manager.attach_websocket(new_session, websocket)
+                        await websocket.send_json(
+                            {"type": "status", "status": "connected"}
+                        )
 
-                        except json.JSONDecodeError:
-                            # Not a valid JSON control message, treat as regular input
-                            await session.write_input(text.encode("utf-8"))
-                    else:
-                        await session.write_input(text.encode("utf-8"))
+                        # Continue the loop with the new session
+                        continue
             elif message["type"] == "websocket.disconnect":
                 break
-    except Exception:
+    except WebSocketDisconnect:
         pass
+    except (RuntimeError, TypeError, ValueError) as exc:
+        logger.debug("Terminal WebSocket receive loop ended: %s", exc)
+    finally:
+        input_writer.cancel()
+        with suppress(asyncio.CancelledError):
+            await input_writer
 
 
 async def _heartbeat_loop(websocket: WebSocket) -> None:
@@ -486,6 +603,7 @@ async def create_terminal_session(
     startup_command = tool_type.startup_command if tool_type else None
 
     name = data.get("name")
+    container_user = await _resolve_container_user(db_session, instance)
 
     try:
         session = await terminal_manager.create_session(
@@ -493,6 +611,7 @@ async def create_terminal_session(
             instance.container_id,
             startup_command=startup_command,
             name=name,
+            container_user=container_user,
         )
     except MaxSessionsExceededError:
         raise HTTPException(
@@ -595,6 +714,7 @@ async def reset_specific_terminal_session(
     # Preserve name if possible
     live_session = terminal_manager.get_session(str(instance_id), session_id)
     name = live_session.name if live_session else None
+    container_user = await _resolve_container_user(db_session, instance)
 
     new_session = await terminal_manager.reset_session(
         instance_id,
@@ -602,6 +722,7 @@ async def reset_specific_terminal_session(
         startup_command=startup_command,
         session_id=key[1],
         name=name,
+        container_user=container_user,
     )
 
     return {
@@ -687,6 +808,7 @@ async def reset_terminal_session(
     # Fetch tool type to get startup_command
     tool_type = await db_session.get(ToolType, instance.tool_type_id)
     startup_command = tool_type.startup_command if tool_type else None
+    container_user = await _resolve_container_user(db_session, instance)
 
     try:
         # Reset the default session
@@ -694,6 +816,7 @@ async def reset_terminal_session(
             instance_id,
             instance.container_id,
             startup_command=startup_command,
+            container_user=container_user,
         )
 
         logger.info(

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

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

apps/api/src/seeds/builtin_tool_types.py

@@ -5,10 +5,125 @@ import logging
 from sqlalchemy import select, text
 
 from src.database import SessionLocal
-from src.models import ToolType
+from src.models import ToolDefinitionManifest, ToolType
 
 logger = logging.getLogger(__name__)
 
+# All supported built-in tools run their long-lived process with these IDs.
+# Canonical writable Config Profile mounts can therefore be shared without
+# per-instance ownership changes.
+BUILTIN_USER_UID = 1000
+BUILTIN_USER_GID = 1000
+
+BUILTIN_TOOL_TYPES = [
+    {
+        "name": "code-server",
+        "display_name": "VS Code Server",
+        "description": "VS Code running in the browser via code-server",
+        "category": "editor",
+        "interface_type": "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: 'no'""",
+        "default_port": 8443,
+        "required_variables": ["REPO_PATH", "TOOL_NAME"],
+    },
+    {
+        "name": "jupyter-notebook",
+        "display_name": "Jupyter Notebook",
+        "description": "Jupyter Lab for interactive development",
+        "category": "notebook",
+        "interface_type": "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
+      - NB_UID=1000
+      - NB_GID=1000
+    volumes:
+      - {{REPO_PATH}}:/home/jovyan/work
+    ports:
+      - "8888:8888"
+    restart: 'no'""",
+        "required_variables": ["REPO_PATH", "TOOL_NAME"],
+    },
+    {
+        "name": "opencode",
+        "display_name": "OpenCode",
+        "description": "AI coding assistant - run opencode in terminal",
+        "category": "ai-assistant",
+        "interface_type": "terminal",
+        "default_port": 3000,
+        "compose_template": """version: "3.8"
+services:
+  opencode:
+    image: node:20-slim
+    container_name: {{TOOL_NAME}}
+    working_dir: /home/node/{{WORKSPACE_NAME}}
+    volumes:
+      - {{REPO_PATH}}:/home/node/{{WORKSPACE_NAME}}
+    ports:
+      - "3000:3000"
+    command: >
+      sh -ec "apt-get update && apt-get install -y git ca-certificates &&
+              npm install -g opencode-ai &&
+              exec setpriv --reuid=node --regid=node --init-groups opencode server"
+    stdin_open: true
+    tty: true
+    restart: 'no'""",
+        "required_variables": ["REPO_PATH", "TOOL_NAME"],
+    },
+]
+
+
+def _standardize_builtin_manifest_user(manifest: dict) -> bool:
+    """Set the built-in manifest user to the shared UID/GID in place.
+
+    The helper deliberately recognizes only Headquarter's conventional
+    ``user`` account so it cannot rewrite a future custom tool definition.
+    """
+    user = manifest.get("user")
+    if not isinstance(user, dict) or user.get("name") != "user":
+        return False
+
+    changed = user.get("uid") != BUILTIN_USER_UID or user.get("gid") != BUILTIN_USER_GID
+    if changed:
+        user["uid"] = BUILTIN_USER_UID
+        user["gid"] = BUILTIN_USER_GID
+    return changed
+
+
+async def _standardize_pi_agent_manifest(session) -> None:
+    """Bring the built-in Pi Agent manifest in line with shared mount IDs."""
+    manifest_definition = await session.scalar(
+        select(ToolDefinitionManifest).where(
+            ToolDefinitionManifest.name == "pi-agent",
+            ToolDefinitionManifest.created_by_id.is_(None),
+        )
+    )
+    if manifest_definition is None:
+        return
+
+    manifest = dict(manifest_definition.manifest)
+    if _standardize_builtin_manifest_user(manifest):
+        manifest_definition.manifest = manifest
+        logger.info("Standardized built-in Pi Agent user to 1000:1000")
+
 
 async def _table_exists(session, table_name: str) -> bool:
     """Check if a table exists in the database."""
@@ -45,88 +160,9 @@ async def seed_builtin_tool_types():
             )
             return
 
-        builtin_types = [
-            {
-                "name": "code-server",
-                "display_name": "VS Code Server",
-                "description": "VS Code running in the browser via code-server",
-                "category": "editor",
-                "interface_type": "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: 'no'""",
-                "default_port": 8443,
-                "required_variables": ["REPO_PATH", "TOOL_NAME"],
-            },
-            {
-                "name": "jupyter-notebook",
-                "display_name": "Jupyter Notebook",
-                "description": "Jupyter Lab for interactive development",
-                "category": "notebook",
-                "interface_type": "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: 'no'""",
-                "required_variables": ["REPO_PATH", "TOOL_NAME"],
-            },
-            {
-                "name": "opencode",
-                "display_name": "OpenCode",
-                "description": "AI coding assistant - run opencode in terminal",
-                "category": "ai-assistant",
-                "interface_type": "terminal",
-                "default_port": 3000,
-                "compose_template": """version: "3.8"
-services:
-  opencode:
-    image: node:20-slim
-    container_name: {{TOOL_NAME}}
-    working_dir: /home/user/{{WORKSPACE_NAME}}
-    volumes:
-      - {{REPO_PATH}}:/home/user/{{WORKSPACE_NAME}}
-    ports:
-      - "3000:3000"
-    command: >
-      sh -c "set -x &&
-             apt-get update && apt-get install -y git ca-certificates &&
-             echo 'Installing opencode...' &&
-             npm install -g opencode-ai 2>&1 || echo 'ERROR: npm install failed' &&
-             which opencode || echo 'ERROR: opencode not in PATH' &&
-             npm bin -g &&
-             ls -la $(npm bin -g) || echo 'ERROR: global bin dir not found' &&
-             echo 'export PATH=\"$(npm bin -g):\\$PATH\"' >> /root/.bashrc &&
-             echo 'cd /home/user/{{WORKSPACE_NAME}}' >> /root/.bashrc &&
-             echo 'OpenCode installation complete' &&
-             exec tail -f /dev/null"
-    stdin_open: true
-    tty: true
-    restart: 'no'""",
-                "required_variables": ["REPO_PATH", "TOOL_NAME"],
-            },
-        ]
+        await _standardize_pi_agent_manifest(session)
 
-        for tool_data in builtin_types:
+        for tool_data in BUILTIN_TOOL_TYPES:
             existing = await session.scalar(
                 select(ToolType).where(ToolType.name == tool_data["name"])
             )

apps/api/src/services/.pi-map.index.md

@@ -2,7 +2,7 @@
 dir: apps/api/src/services
 
 ## role
-Provides utility services for the API application, including tmux window management functionality.
+Provides a command to swap the position of two tmux panes within a window or between windows
 ## parent
 index: apps/api/src/.pi-map.index.md
 map: apps/api/src/.pi-map.md

apps/api/src/services/build/manifest_compiler.py

@@ -408,7 +408,6 @@ def compile_compose(manifest: dict, variables: dict[str, Any]) -> str:
         Docker Compose YAML content.
     """
     runtime = manifest.get("runtime", {})
-    user = manifest.get("user")
     interface_type = manifest["interface_type"]
     home_dir = get_manifest_home_dir(manifest)
 
@@ -436,12 +435,11 @@ def compile_compose(manifest: dict, variables: dict[str, Any]) -> str:
     else:
         service["working_dir"] = f"{home_dir}/{workspace_name}"
 
-    # The entrypoint starts as root (Dockerfile does not set USER) so it can
-    # fix mount ownership. It drops privileges to the container user internally
-    # before exec-ing the real command, so do not set compose-level user
-    # override here.
-    if user:
-        service["user"] = "0:0"
+    # The Dockerfile does not set USER so the entrypoint starts as root,
+    # fixes mount ownership, and drops privileges to the container user
+    # internally. Do not set a compose-level user override: that would pin
+    # the container metadata to root and make docker exec sessions run as
+    # root even after the entrypoint drops privileges.
 
     # Ports for web tools
     default_port = manifest.get("default_port")
@@ -568,6 +566,35 @@ def get_manifest_home_dir(manifest: dict) -> str:
     return "/root"
 
 
+def get_manifest_container_user(manifest: dict) -> str | None:
+    """Resolve the container user identifier from a manifest.
+
+    Returns the user name when available so that docker exec sessions can
+    attach as the container user instead of defaulting to root. Falls back
+    to ``uid:gid`` when a name is absent but numeric ids are present.
+
+    Args:
+        manifest: Fully resolved manifest JSON.
+
+    Returns:
+        User name (e.g. ``user``), ``uid:gid`` string, or None when the
+        manifest does not declare a user.
+    """
+    user = manifest.get("user")
+    if not user:
+        return None
+
+    name = user.get("name")
+    if name:
+        return name
+
+    uid = user.get("uid")
+    gid = user.get("gid")
+    if uid is not None and gid is not None:
+        return f"{uid}:{gid}"
+    return None
+
+
 def compute_image_tag(tool_name: str, manifest: dict) -> str:
     """Compute a deterministic image tag from manifest content.
 

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

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

apps/api/src/services/terminal/.pi-map.index.md

@@ -2,7 +2,7 @@
 dir: apps/api/src/services/terminal
 
 ## role
-Provides backend infrastructure for managing interactive WebSocket-based terminal sessions within Docker containers, including session lifecycle, PTY I/O handling, and resource cleanup.
+Provides WebSocket-based terminal session management for containerized environments with PTY support, session persistence, and resource limits.
 ## parent
 index: apps/api/src/services/.pi-map.index.md
 map: apps/api/src/services/.pi-map.md

apps/api/src/services/terminal/.pi-map.md

@@ -4,13 +4,13 @@ dir: apps/api/src/services/terminal
 index: apps/api/src/services/terminal/.pi-map.index.md
 
 ## role
-Provides backend infrastructure for managing interactive WebSocket-based terminal sessions within Docker containers, including session lifecycle, PTY I/O handling, and resource cleanup.
+Provides WebSocket-based terminal session management for containerized environments with PTY support, session persistence, and resource limits.
 ## files
-- __init__.py | Package initialization file that exports the public API for the terminal services module | dep: src.services.terminal.terminal_manager, src.services.terminal.terminal_session
-- terminal_manager.py | Manages active terminal sessions with WebSocket support, idle cleanup, database persistence, and per-instance session limits. | exp: class:MaxSessionsExceededError, method:__init__(self, instance_id: str, max_sessions) → None, call:super().__init__, class:TerminalManager, method:__init__(self) → None, call:self._start_idle_check, method:_start_idle_check(self) → None, call:self._idle_check_task.done, call:asyncio.get_running_loop, call:loop.create_task, call:self._idle_check_loop, method:_idle_check_loop(self) → None, call:asyncio.sleep, call:self._cleanup_idle_sessions, call:logger.error, method:_cleanup_idle_sessions(self) → None, call:list, call:self._sessions.items, call:session.is_idle, call:idle_keys.append, call:logger.info, call:self._sessions.pop, call:session.close, call:asyncio.create_task, call:self._mark_closed_in_db, method:_insert_db_session_row(self, session_id: str, instance_id: uuid.UUID, name: str) → None, call:SessionLocal, call:pg_insert(TerminalSessionModel) .values( id=uuid.UUID(session_id), instance_id=instance_id, name=name, status="active", created_at=datetime.now(timezone.utc), last_activity_at=datetime.now(timezone.utc), ) .on_conflict_do_nothing, call:uuid.UUID, call:datetime.now, call:db_session.execute, call:db_session.commit, call:logger.debug, call:logger.error, method:_mark_closed_in_db(self, session_id: str) → None, call:SessionLocal, call:db_session.get, call:uuid.UUID, call:datetime.now, call:db_session.commit, call:logger.debug, call:logger.error, method:_count_sessions_for_instance(self, instance_id_str: str) → int, call:sum, method:create_session(self, instance_id: uuid.UUID, container_id: str, startup_command, name, session_id) → TerminalSession, call:str, call:self._count_sessions_for_instance, call:uuid.uuid4, call:TerminalSession, call:session.start, call:asyncio.create_task, call:self._insert_db_session_row, call:logger.info, raise:MaxSessionsExceededError, method:get_or_create_session(self, instance_id: uuid.UUID, container_id: str, startup_command) → TerminalSession, call:self._start_idle_check, call:str, call:session.is_alive, call:logger.debug, call:session.close, call:logger.info, call:uuid.uuid4, call:TerminalSession, call:session.start, call:asyncio.create_task, call:self._insert_db_session_row, method:get_session(self, instance_id: str, session_id: str) → TerminalSession | None, call:self._sessions.get, call:self._sessions.items, method:_find_key_by_internal_id(self, instance_id: str, internal_session_id: str) → tuple[str, str] | None, call:self._sessions.items, method:get_sessions_for_instance(self, instance_id: str) → list[TerminalSession], call:self._sessions.items, method:close_session(self, instance_id: str, session_id: str) → None, call:self._sessions.pop, call:session.close, call:asyncio.create_task, call:self._mark_closed_in_db, call:logger.info, method:attach_websocket(self, session: TerminalSession, websocket: WebSocket) → None, call:session.has_websockets, call:logger.debug, call:list, call:ws.close, call:session._websockets.clear, call:session.attach_websocket, call:session.get_buffer, call:websocket.send_bytes, method:detach_websocket(self, session: TerminalSession, websocket: WebSocket) → None, call:session.detach_websocket, method:reset_session(self, instance_id: uuid.UUID, container_id: str, startup_command, session_id, name) → TerminalSession, call:str, call:logger.debug, call:self._sessions.pop, call:old_session.close, call:asyncio.create_task, call:self._mark_closed_in_db, call:uuid.uuid4, call:TerminalSession, call:new_session.start, call:self._insert_db_session_row, method:close_all(self) → None, call:list, call:self._sessions.values, call:self._sessions.clear, call:session.close, call:self._idle_check_task.done, call:self._idle_check_task.cancel | dep: asyncio, logging, uuid, datetime, fastapi, sqlalchemy.dialects.postgresql, src.database, src.models, src.services.terminal.terminal_session, fastapi.WebSocket
-- terminal_session.py | Manages a high-performance terminal session using asyncio-native event-driven I/O with PTY for docker exec processes, featuring output batching, flow control, and WebSocket broadcasting. | exp: class:TerminalSession, method:__init__(self, session_id: str, instance_id: uuid.UUID, container_id: str, startup_command, name) → None, call:deque, call:set, call:time.time, call:self._generate_name, call:str, call:bytearray, call:asyncio.Lock, method:start(self, startup_command) → None, call:pty.openpty, call:self._set_terminal_size, call:logger.debug, call:asyncio.create_subprocess_exec, call:os.close, call:time.time, call:self._start_reading, method:_start_reading(self) → None, call:asyncio.get_event_loop, call:loop.add_reader, call:logger.debug, call:logger.error, method:_stop_reading(self) → None, call:asyncio.get_event_loop, call:loop.remove_reader, method:_on_fd_readable(self) → None, call:os.read, call:logger.debug, call:self._handle_eof, call:self._add_to_buffer, call:time.time, call:self._queue_output, method:_add_to_buffer(self, data: bytes) → None, call:self._output_buffer.append, call:len, call:self._output_buffer.popleft, method:_queue_output(self, data: bytes) → None, call:self._batch_buffer.extend, call:len, call:self._pause_output, call:asyncio.get_event_loop, call:loop.call_later, method:_flush_batch_sync(self) → None, call:self._batch_buffer.clear, call:bytes, call:set, call:list, call:asyncio.create_task, call:self._send_bytes, call:dead_sockets.add, method:_send_bytes(self, ws: Any, payload: bytes) → None, call:ws.send_bytes, call:self._websockets.discard, method:acknowledge_data(self, char_count: int) → None, call:max, call:self._resume_output, call:self._ack_timeout_handle.cancel, call:asyncio.get_event_loop, call:loop.call_later, method:_ack_timeout_fallback(self) → None, call:logger.warning, call:self._resume_output, method:_pause_output(self) → None, call:self._stop_reading, call:logger.debug, method:_resume_output(self) → None, call:self._start_reading, call:logger.debug, method:get_buffer(self) → bytes, call:b"".join, method:_handle_eof(self) → None, call:self._stop_reading, call:self.process._transport.close, call:set, call:self._websockets.clear, call:asyncio.create_task, call:ws.close, call:logger.info, method:write_input(self, data: bytes) → None, call:os.write, call:time.time, call:logger.debug, call:self._handle_eof, method:_set_terminal_size(self, cols: int, rows: int) → None, call:logger.warning, call:struct.pack, call:fcntl.ioctl, call:logger.debug, call:logger.error, method:resize(self, cols: int, rows: int) → None, call:logger.warning, call:logger.debug, call:self._set_terminal_size, call:os.kill, method:reset(self) → None, call:self.close, call:self._output_buffer.clear, call:self._websockets.clear, call:self._batch_buffer.clear, method:close(self) → None, call:self._stop_reading, call:self._batch_timer.cancel, call:self._ack_timeout_handle.cancel, call:os.close, call:self.process.kill, call:asyncio.wait_for, call:self.process.wait, method:is_alive(self) → bool, method:is_idle(self) → bool, call:time.time, method:attach_websocket(self, websocket: Any) → None, call:self._websockets.add, call:time.time, method:detach_websocket(self, websocket: Any) → None, call:self._websockets.discard, method:has_websockets(self) → bool, call:len, method:send_to_all(self, data: bytes) → None, call:set, call:ws.send_bytes, call:dead_sockets.add, call:self._websockets.discard, method:read_output(self) → bytes | dep: asyncio, logging, os, pty, signal, struct, fcntl, time, uuid, collections, typing, collections.deque, typing.Any
+- __init__.py | Exports the public API for the terminal services module by re-exporting TerminalManager, TerminalSession, and MaxSessionsExceededError. | dep: src.services.terminal.terminal_manager, src.services.terminal.terminal_session
+- terminal_manager.py | Manages WebSocket-based terminal sessions with persistence, idle cleanup, and per-instance session limits for containerized environments. | exp: class:MaxSessionsExceededError, method:__init__(self, instance_id: str, max_sessions) → None, call:super().__init__, class:TerminalManager, method:__init__(self) → None, call:self._start_idle_check, method:_start_idle_check(self) → None, call:self._idle_check_task.done, call:asyncio.get_running_loop, call:loop.create_task, call:self._idle_check_loop, method:_idle_check_loop(self) → None, call:asyncio.sleep, call:self._cleanup_idle_sessions, call:logger.error, method:_cleanup_idle_sessions(self) → None, call:list, call:self._sessions.items, call:session.is_idle, call:idle_keys.append, call:logger.info, call:self._sessions.get, call:idle_session.close, call:asyncio.create_task, call:self._mark_closed_in_db, method:_insert_db_session_row(self, session_id: str, instance_id: uuid.UUID, name: str) → None, call:SessionLocal, call:pg_insert(TerminalSessionModel) .values( id=uuid.UUID(session_id), instance_id=instance_id, name=name, status="active", created_at=datetime.now(timezone.utc), last_activity_at=datetime.now(timezone.utc), ) .on_conflict_do_nothing, call:uuid.UUID, call:datetime.now, call:db_session.execute, call:db_session.commit, call:logger.debug, call:logger.error, method:_mark_closed_in_db(self, session_id: str) → None, call:SessionLocal, call:db_session.get, call:uuid.UUID, call:datetime.now, call:db_session.commit, call:logger.debug, call:logger.error, method:_count_sessions_for_instance(self, instance_id_str: str) → int, call:sum, method:create_session(self, instance_id: uuid.UUID, container_id: str, startup_command, name, session_id, container_user) → TerminalSession, call:str, call:self._count_sessions_for_instance, call:uuid.uuid4, call:TerminalSession, call:session.start, call:asyncio.create_task, call:self._insert_db_session_row, call:logger.info, raise:MaxSessionsExceededError, method:get_or_create_session(self, instance_id: uuid.UUID, container_id: str, startup_command, container_user) → TerminalSession, call:self._start_idle_check, call:str, call:session.is_alive, call:logger.debug, call:session.close, call:logger.info, call:uuid.uuid4, call:TerminalSession, call:session.start, call:asyncio.create_task, call:self._insert_db_session_row, method:get_session(self, instance_id: str, session_id: str) → TerminalSession | None, call:self._sessions.get, call:self._sessions.items, method:_find_key_by_internal_id(self, instance_id: str, internal_session_id: str) → tuple[str, str] | None, call:self._sessions.items, method:get_sessions_for_instance(self, instance_id: str) → list[TerminalSession], call:self._sessions.items, method:close_session(self, instance_id: str, session_id: str) → None, call:self._sessions.pop, call:session.close, call:asyncio.create_task, call:self._mark_closed_in_db, call:logger.info, method:attach_websocket(self, session: TerminalSession, websocket: WebSocket) → None, call:session.has_websockets, call:logger.debug, call:list, call:ws.close, call:session._websockets.clear, call:session.attach_websocket, call:session.get_buffer, call:websocket.send_bytes, method:detach_websocket(self, session: TerminalSession, websocket: WebSocket) → None, call:session.detach_websocket, method:reset_session(self, instance_id: uuid.UUID, container_id: str, startup_command, session_id, name, container_user) → TerminalSession, call:str, call:logger.debug, call:self._sessions.pop, call:old_session.close, call:asyncio.create_task, call:self._mark_closed_in_db, call:uuid.uuid4, call:TerminalSession, call:new_session.start, call:self._insert_db_session_row, method:close_all(self) → None, call:list, call:self._sessions.values, call:self._sessions.clear, call:session.close, call:self._idle_check_task.done, call:self._idle_check_task.cancel | dep: asyncio, logging, uuid, datetime, fastapi, sqlalchemy.dialects.postgresql, src.database, src.models, src.services.terminal.terminal_session, fastapi.WebSocket
+- terminal_session.py | Manages an asyncio-native terminal session using PTY with docker exec, featuring event-driven I/O, output batching, and flow control for WebSocket clients. | exp: class:TerminalSession, method:__init__(self, session_id: str, instance_id: uuid.UUID, container_id: str, startup_command, name, container_user) → None, call:deque, call:set, call:time.time, call:self._generate_name, call:str, call:bytearray, call:asyncio.Lock, method:start(self, startup_command) → None, call:exec_cmd.extend, call:pty.openpty, call:self._set_terminal_size, call:logger.debug, call:asyncio.create_subprocess_exec, call:os.close, call:time.time, call:self._start_reading, method:_start_reading(self) → None, call:asyncio.get_event_loop, call:loop.add_reader, call:logger.debug, call:logger.error, method:_stop_reading(self) → None, call:asyncio.get_event_loop, call:loop.remove_reader, method:_on_fd_readable(self) → None, call:os.read, call:logger.debug, call:self._handle_eof, call:self._add_to_buffer, call:time.time, call:self._queue_output, method:_add_to_buffer(self, data: bytes) → None, call:self._output_buffer.append, call:len, call:self._output_buffer.popleft, method:_queue_output(self, data: bytes) → None, call:self._batch_buffer.extend, call:len, call:self._pause_output, call:asyncio.get_event_loop, call:loop.call_later, method:_flush_batch_sync(self) → None, call:self._batch_buffer.clear, call:bytes, call:set, call:list, call:asyncio.create_task, call:self._send_bytes, call:dead_sockets.add, method:_send_bytes(self, ws: Any, payload: bytes) → None, call:ws.send_bytes, call:self._websockets.discard, method:acknowledge_data(self, char_count: int) → None, call:max, call:self._resume_output, call:self._ack_timeout_handle.cancel, call:asyncio.get_event_loop, call:loop.call_later, method:_ack_timeout_fallback(self) → None, call:logger.warning, call:self._resume_output, method:_pause_output(self) → None, call:self._stop_reading, call:logger.debug, method:_resume_output(self) → None, call:self._start_reading, call:logger.debug, method:get_buffer(self) → bytes, call:b"".join, method:_handle_eof(self) → None, call:self._stop_reading, call:self.process._transport.close, call:set, call:self._websockets.clear, call:asyncio.create_task, call:ws.close, call:logger.info, method:write_input(self, data: bytes) → None, call:os.write, call:time.time, call:logger.debug, call:self._handle_eof, method:_set_terminal_size(self, cols: int, rows: int) → None, call:logger.warning, call:struct.pack, call:fcntl.ioctl, call:logger.debug, call:logger.error, method:resize(self, cols: int, rows: int) → None, call:logger.warning, call:logger.debug, call:self._set_terminal_size, call:os.kill, method:reset(self) → None, call:self.close, call:self._output_buffer.clear, call:self._websockets.clear, call:self._batch_buffer.clear, method:close(self) → None, call:self._stop_reading, call:self._batch_timer.cancel, call:self._ack_timeout_handle.cancel, call:os.close, call:self.process.kill, call:asyncio.wait_for, call:self.process.wait, method:is_alive(self) → bool, method:is_idle(self) → bool, call:time.time, method:attach_websocket(self, websocket: Any) → None, call:self._websockets.add, call:time.time, method:detach_websocket(self, websocket: Any) → None, call:self._websockets.discard, method:has_websockets(self) → bool, call:len, method:send_to_all(self, data: bytes) → None, call:set, call:ws.send_bytes, call:dead_sockets.add, call:self._websockets.discard, method:read_output(self) → bytes | dep: asyncio, logging, os, pty, signal, struct, fcntl, time, uuid, collections, typing, collections.deque, typing.Any
 ## arch
-Asyncio-native event-driven architecture with producer-consumer pattern for terminal output batching, WebSocket pub/sub broadcasting, session state machine with idle timeout and database persistence, and per-instance resource limits enforced by a centralized manager.
+Asyncio-native event-driven architecture using PTY/docker exec with manager pattern (TerminalManager orchestrates TerminalSession instances), featuring output batching, flow control, idle cleanup, and per-instance session limiting.
 ## tags
 call:self., session, call:logger.debug, idle, output, terminal, check, task
 ## symbols

apps/api/src/services/terminal/terminal_manager.py

@@ -72,9 +72,10 @@ class TerminalManager:
                 session_id,
                 instance_id,
             )
-            session = self._sessions.pop(key, None)
-            if session:
-                await session.close()
+            idle_session = self._sessions.get(key)
+            if idle_session is not None:
+                del self._sessions[key]
+                await idle_session.close()
                 # Update DB status fire-and-forget
                 asyncio.create_task(self._mark_closed_in_db(session_id))
 
@@ -141,6 +142,7 @@ class TerminalManager:
         startup_command: str | None = None,
         name: str | None = None,
         session_id: str | None = None,
+        container_user: str | None = None,
     ) -> TerminalSession:
         """Create a new terminal session for an instance.
 
@@ -152,6 +154,8 @@ class TerminalManager:
             container_id: Docker container ID.
             startup_command: Optional startup command to run.
             name: Optional session name (auto-generated if omitted).
+            session_id: Optional explicit session UUID.
+            container_user: Optional container user for docker exec.
 
         Returns:
             The newly created TerminalSession.
@@ -177,6 +181,7 @@ class TerminalManager:
             container_id=container_id,
             startup_command=startup_command,
             name=name,
+            container_user=container_user,
         )
         await session.start(startup_command=startup_command)
 
@@ -201,6 +206,7 @@ class TerminalManager:
         instance_id: uuid.UUID,
         container_id: str,
         startup_command: str | None = None,
+        container_user: str | None = None,
     ) -> TerminalSession:
         """Get existing session or create a new one.
 
@@ -243,6 +249,7 @@ class TerminalManager:
             container_id=container_id,
             startup_command=startup_command,
             name="Session 1",
+            container_user=container_user,
         )
         await session.start(startup_command=startup_command)
         self._sessions[key] = session
@@ -358,6 +365,7 @@ class TerminalManager:
         startup_command: str | None = None,
         session_id: str | None = None,
         name: str | None = None,
+        container_user: str | None = None,
     ) -> TerminalSession:
         """Reset a session by killing it and creating a new one.
 
@@ -367,6 +375,7 @@ class TerminalManager:
             startup_command: Optional startup command.
             session_id: Specific session to reset. If None, resets the default session.
             name: Optional name to preserve for the new session.
+            container_user: Optional container user for docker exec.
 
         Returns:
             The newly created TerminalSession.
@@ -400,6 +409,7 @@ class TerminalManager:
             container_id=container_id,
             startup_command=startup_command,
             name=old_name or ("Session 1" if target_session_id == "default" else None),
+            container_user=container_user,
         )
         await new_session.start(startup_command=startup_command)
         self._sessions[key] = new_session

apps/api/src/services/terminal/terminal_session.py

@@ -12,12 +12,15 @@ import signal
 import struct
 import fcntl
 import time
+import tty
 import uuid
 from collections import deque
 from typing import Any
 
 logger = logging.getLogger(__name__)
 
+_session_counters_by_instance: dict[str, int] = {}
+
 
 class TerminalSession:
     """Manages a single terminal session with event-driven PTY I/O.
@@ -45,9 +48,6 @@ class TerminalSession:
     # Max WebSocket frame size
     MAX_FRAME_SIZE = 64 * 1024
 
-    # Session number counter per instance_id for auto-naming
-    _instance_counters: dict[str, int] = {}
-
     def __init__(
         self,
         session_id: str,
@@ -55,10 +55,12 @@ class TerminalSession:
         container_id: str,
         startup_command: str | None = None,
         name: str | None = None,
+        container_user: str | None = None,
     ) -> None:
         self.session_id = session_id
         self.instance_id = instance_id
         self.container_id = container_id
+        self.container_user = container_user
         self.startup_command = startup_command
         self.process: asyncio.subprocess.Process | None = None
         self._closed = False
@@ -96,17 +98,43 @@ class TerminalSession:
         # Ack timeout fallback
         self._ack_timeout_handle: asyncio.TimerHandle | None = None
 
-    @classmethod
-    def _generate_name(cls, instance_id: str) -> str:
+    @staticmethod
+    def _generate_name(instance_id: str) -> str:
         """Generate an auto-incremented session name for the instance."""
-        count = cls._instance_counters.get(instance_id, 0) + 1
-        cls._instance_counters[instance_id] = count
+        count = _session_counters_by_instance.get(instance_id, 0) + 1
+        _session_counters_by_instance[instance_id] = count
         return f"Session {count}"
 
     async def start(self, startup_command: str | None = None) -> None:
         """Start the docker exec process with a shell using a PTY."""
-        # Create a pseudo-terminal on the host
+        # Build the docker exec command. When the tool manifest declares a
+        # non-root container user, run the shell as that user so terminal
+        # sessions match the privileges of the main container process.
+        exec_cmd = [
+            "docker",
+            "exec",
+            "-it",
+            "-e",
+            "TERM=xterm-256color",
+        ]
+        if self.container_user:
+            exec_cmd.extend(["--user", self.container_user])
+
+        # Create a pseudo-terminal on the host. The master must be
+        # non-blocking: a browser paste can be larger than the PTY input
+        # buffer, and write_input() drains it asynchronously without dropping
+        # the closing bracketed-paste marker.
         self._master_fd, slave_fd = pty.openpty()
+        os.set_blocking(self._master_fd, False)
+
+        # Put the host PTY into raw mode so it behaves as a pass-through
+        # pipe. openpty() leaves the slave in canonical mode by default,
+        # which line-buffers input, splits multiline pastes at newlines,
+        # and mangles bracketed-paste markers before docker exec / the
+        # foreground app (e.g. pi) ever see them. Real terminal discipline
+        # (echo, canonical editing for readline) is provided by the
+        # in-container PTY that `docker exec -t` allocates.
+        tty.setraw(slave_fd)
 
         # Set the terminal size initially
         self._set_terminal_size(self._cols, self._rows)
@@ -131,16 +159,9 @@ class TerminalSession:
             shell_cmd = "bash -il"
 
         # Start docker exec with the slave fd as stdin/stdout/stderr
+        exec_cmd.extend([self.container_id, "bash", "-c", shell_cmd])
         self.process = await asyncio.create_subprocess_exec(
-            "docker",
-            "exec",
-            "-it",
-            "-e",
-            "TERM=xterm-256color",
-            self.container_id,
-            "bash",
-            "-c",
-            shell_cmd,
+            *exec_cmd,
             stdin=slave_fd,
             stdout=slave_fd,
             stderr=slave_fd,
@@ -186,6 +207,9 @@ class TerminalSession:
 
         try:
             data = os.read(self._master_fd, 4096)
+        except BlockingIOError:
+            # The readiness notification raced with another callback.
+            return
         except (OSError, IOError) as exc:
             logger.debug("PTY read error for session %s: %s", self.session_id, exc)
             self._handle_eof()
@@ -325,12 +349,42 @@ class TerminalSession:
                 pass
         logger.info("Session %s EOF handled, websockets closed", self.session_id)
 
+    async def _wait_for_write_ready(self, fd: int) -> None:
+        """Wait until a non-blocking PTY master can accept more input."""
+        loop = asyncio.get_running_loop()
+        writable = loop.create_future()
+
+        def mark_writable() -> None:
+            if not writable.done():
+                writable.set_result(None)
+
+        loop.add_writer(fd, mark_writable)
+        try:
+            await writable
+        finally:
+            loop.remove_writer(fd)
+
     async def write_input(self, data: bytes) -> None:
-        """Write input to the PTY master."""
+        """Write all terminal input bytes to the PTY master in order."""
         if self._master_fd is None or self._closed:
             return
+
+        fd = self._master_fd
+        remaining = memoryview(data)
         try:
-            os.write(self._master_fd, data)
+            while remaining and not self._closed and self._master_fd == fd:
+                try:
+                    written = os.write(fd, remaining)
+                except BlockingIOError:
+                    await self._wait_for_write_ready(fd)
+                    continue
+
+                if written == 0:
+                    await self._wait_for_write_ready(fd)
+                    continue
+
+                remaining = remaining[written:]
+
             self.last_activity = time.time()
         except (OSError, IOError) as exc:
             logger.debug("PTY write error for session %s: %s", self.session_id, exc)

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

@@ -2,7 +2,9 @@
 
 import asyncio
 import contextlib
+import fcntl
 import glob as glob_module
+import hashlib
 import logging
 import os
 import re
@@ -125,15 +127,20 @@ def _chown_staged_mounts(
     uid: int,
     gid: int,
 ) -> None:
-    """Recursively chown staged mount sources to the container user.
+    """Recursively chown writable profile and instance mount sources.
 
-    Config-profile mounts, git mounts, and SSH key mounts are staged under
-    instance_dir by the API process (root). Without this, the container
-    user cannot write into bind-mounted directories such as ~/.config.
+    Canonical non-Git profile sources are shared by compatible instances, so
+    they must be writable by the container user rather than copied per
+    instance. Instance-local composites and SSH mounts remain supported.
     """
+    canonical_profile_root = os.path.join(
+        os.path.dirname(instance_dir), "config-profiles"
+    )
     for vol in extra_volumes:
         source = vol.get("source", "")
-        if not source or not source.startswith(instance_dir):
+        if not source or not (
+            source.startswith(instance_dir) or source.startswith(canonical_profile_root)
+        ):
             continue
         _chown_path(source, uid, gid)
 
@@ -154,61 +161,118 @@ def _relative_under(parent: str, child: str) -> str | None:
     return None
 
 
+def _stage_profile_mounts(profile_mounts: list[dict], instance_dir: str) -> list[dict]:
+    """Copy profile bind sources into an instance-local, writable staging area."""
+    staged_mounts: list[dict] = []
+    staging_root = os.path.join(instance_dir, "mounts", "profiles")
+
+    for mount in profile_mounts:
+        source = mount.get("source", "")
+        target = mount.get("target", "")
+        if not source or not target:
+            continue
+        if not os.path.exists(source):
+            logger.warning("Skipping missing config profile mount source: %s", source)
+            continue
+
+        digest = hashlib.sha256(f"{source}\0{target}".encode()).hexdigest()[:16]
+        staged_source = os.path.join(staging_root, digest)
+        try:
+            if os.path.lexists(staged_source):
+                if os.path.isdir(staged_source):
+                    shutil.rmtree(staged_source)
+                else:
+                    os.unlink(staged_source)
+            os.makedirs(os.path.dirname(staged_source), exist_ok=True)
+
+            if os.path.isdir(source):
+                shutil.copytree(source, staged_source, symlinks=True)
+            else:
+                shutil.copy2(source, staged_source, follow_symlinks=False)
+        except OSError as exc:
+            logger.error("Failed to stage config profile mount %s: %s", source, exc)
+            continue
+
+        staged_mount = dict(mount)
+        staged_mount["source"] = staged_source
+        staged_mounts.append(staged_mount)
+
+    return staged_mounts
+
+
+def _mounts_overlap(first_target: str, second_target: str) -> bool:
+    """Return whether two normalized container mount targets intersect."""
+    return (
+        _relative_under(first_target, second_target) is not None
+        or _relative_under(second_target, first_target) is not None
+    )
+
+
+def _copy_mount_source(source: str, destination: str) -> None:
+    """Copy a bind-mount source into its destination in a composite tree."""
+    try:
+        if os.path.isdir(source):
+            os.makedirs(destination, exist_ok=True)
+            for entry in os.listdir(source):
+                source_entry = os.path.join(source, entry)
+                destination_entry = os.path.join(destination, entry)
+                if os.path.isdir(source_entry):
+                    shutil.copytree(
+                        source_entry,
+                        destination_entry,
+                        dirs_exist_ok=True,
+                        symlinks=True,
+                    )
+                else:
+                    os.makedirs(os.path.dirname(destination_entry), exist_ok=True)
+                    shutil.copy2(source_entry, destination_entry, follow_symlinks=False)
+            return
+
+        os.makedirs(os.path.dirname(destination), exist_ok=True)
+        shutil.copy2(source, destination, follow_symlinks=False)
+    except OSError as exc:
+        raise RuntimeError(f"Unable to compose mount source {source}: {exc}") from exc
+
+
 def _stack_profile_mounts_with_git_mounts(
     profile_mounts: list[dict],
     git_mount_volumes: list[dict],
+    instance_dir: str,
 ) -> list[dict]:
-    """Merge profile file mounts into overlapping git-mount sources.
+    """Overlay canonical profile files on Git directories without snapshots.
 
-    When a config profile mounts static files to the same directory as a
-    git-mount (e.g. ``~/.pi``), a directory-level bind mount for the profile
-    would mask the cloned repository. Instead, copy the profile files into
-    the git-mount source directory so the container sees both sets of files
-    through a single bind mount.
-
-    Profile mounts whose target is a child of a git-mount target are copied
-    into the corresponding subdirectory. Mounts that do not overlap are
-    returned unchanged.
+    An overlapping profile directory is expanded into individual child-file
+    mounts. Docker then mounts the Git working directory first and the more
+    specific canonical profile files last, preserving shared writable sources
+    instead of constructing an instance-local composite copy.
     """
-    remaining: list[dict] = []
-    for pvol in profile_mounts:
-        p_source = pvol.get("source", "")
-        p_target = pvol.get("target", "")
-        if not p_source or not os.path.exists(p_source):
-            remaining.append(pvol)
+    del instance_dir
+    result: list[dict] = list(git_mount_volumes)
+
+    for profile_mount in profile_mounts:
+        source = profile_mount.get("source", "")
+        target = profile_mount.get("target", "")
+        overlaps_git = any(
+            _mounts_overlap(target, git_mount.get("target", ""))
+            for git_mount in git_mount_volumes
+        )
+        if not overlaps_git or not os.path.isdir(source):
+            result.append(profile_mount)
             continue
 
-        merged = False
-        for gvol in git_mount_volumes:
-            g_source = gvol.get("source", "")
-            g_target = gvol.get("target", "")
-            if not g_source or not os.path.isdir(g_source):
-                continue
+        for root, _dirs, files in os.walk(source):
+            for filename in files:
+                file_source = os.path.join(root, filename)
+                relative_path = os.path.relpath(file_source, source)
+                result.append(
+                    {
+                        **profile_mount,
+                        "source": file_source,
+                        "target": os.path.join(target, relative_path),
+                    }
+                )
 
-            rel = _relative_under(g_target, p_target)
-            if rel is None:
-                continue
-
-            dst = os.path.join(g_source, rel) if rel else g_source
-            if os.path.isdir(p_source):
-                shutil.copytree(p_source, dst, dirs_exist_ok=True)
-            else:
-                os.makedirs(os.path.dirname(dst), exist_ok=True)
-                shutil.copy2(p_source, dst)
-
-            logger.debug(
-                "Stacked profile mount %s into git mount %s at %s",
-                p_target,
-                g_target,
-                dst,
-            )
-            merged = True
-            break
-
-        if not merged:
-            remaining.append(pvol)
-
-    return remaining
+    return result
 
 
 async def resolve_git_mounts(
@@ -227,12 +291,18 @@ async def resolve_git_mounts(
     if not resolved.git_mounts:
         return []
 
+    # Git mount sources are profile-scoped, not instance-scoped, so compatible
+    # instances bind the same canonical checkout.
+    clone_parent = os.path.join(
+        os.path.dirname(instance_dir or ""), "config-profiles", str(resolved.profile_id)
+    )
+
     # Process all git mounts concurrently
     tasks = []
     for git_mount in resolved.git_mounts:
         tasks.append(
             resolve_single_git_mount(
-                session, git_mount, instance_dir, working_directory, home_dir
+                session, git_mount, clone_parent, working_directory, home_dir
             )
         )
 
@@ -265,6 +335,37 @@ def normalize_git_mount(entry: dict) -> dict:
     return entry
 
 
+@contextlib.contextmanager
+def _git_mount_lock(clone_parent: str, remote_url: str, branch: str | None):
+    """Serialize clone and refresh operations for one canonical Git source."""
+    lock_dir = os.path.join(clone_parent, "git-mounts")
+    identity = f"{remote_url}:{branch or 'default'}"
+    lock_path = os.path.join(
+        lock_dir, f".{hashlib.sha256(identity.encode()).hexdigest()}.lock"
+    )
+    try:
+        os.makedirs(lock_dir, exist_ok=True)
+        with open(lock_path, "a+", encoding="utf-8") as lock_file:
+            fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX)
+            try:
+                yield
+            finally:
+                fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)
+    except OSError as exc:
+        raise RuntimeError(f"Cannot lock Git mount source: {lock_path}") from exc
+
+
+def clone_git_repo_locked(
+    remote_url: str,
+    branch: str | None,
+    clone_parent: str,
+    project_name: str | None = None,
+) -> str:
+    """Clone or refresh a canonical source while holding its process lock."""
+    with _git_mount_lock(clone_parent, remote_url, branch):
+        return clone_git_repo(remote_url, branch, clone_parent, project_name)
+
+
 def clone_git_repo(
     remote_url: str,
     branch: str | None,
@@ -283,16 +384,27 @@ def clone_git_repo(
     url_hash = hashlib.md5(f"{remote_url}:{branch_segment}".encode()).hexdigest()[:12]
     repo_name = remote_url.split("/")[-1].replace(".git", "") or "repo"
     clone_dir = os.path.join(clone_parent, "git-mounts", f"{repo_name}-{url_hash}")
-    repo_path = clone_repository(
-        remote_url,
-        None,  # No SSH key for now - can be added later
-        clone_dir,
-        branch or "main",
-        project_name=project_name,
-    )
+    clone_name = _slugify_directory_name(project_name) if project_name else "repo-clone"
+    repo_path = os.path.join(clone_dir, clone_name)
 
-    if not os.path.exists(repo_path):
+    if os.path.isdir(os.path.join(repo_path, ".git")):
+        # Reuse the deterministic per-repository cache on repeated starts.
         try:
+            pull_repository_updates(repo_path, remote_url)
+            logger.debug("Pulled updates for git mount %s", remote_url)
+        except Exception as exc:
+            logger.warning("Failed to pull updates for %s: %s", remote_url, exc)
+    else:
+        try:
+            # A failed clone can leave its destination behind. Remove only the
+            # computed clone path so the next start can retry cleanly.
+            if os.path.lexists(repo_path):
+                logger.warning("Removing incomplete git mount clone at %s", repo_path)
+                if os.path.isdir(repo_path) and not os.path.islink(repo_path):
+                    shutil.rmtree(repo_path)
+                else:
+                    os.unlink(repo_path)
+
             os.makedirs(clone_dir, exist_ok=True)
             repo_path = clone_repository(
                 remote_url,
@@ -305,13 +417,6 @@ def clone_git_repo(
         except Exception as exc:
             logger.warning("Clone failed for git mount %s: %s", remote_url, exc)
             raise
-    else:
-        # Repo exists - pull latest updates
-        try:
-            pull_repository_updates(repo_path, remote_url)
-            logger.debug("Pulled updates for git mount %s", remote_url)
-        except Exception as exc:
-            logger.warning("Failed to pull updates for %s: %s", remote_url, exc)
 
     # Handle branch checkout if specified
     if branch and repo_path:
@@ -421,7 +526,7 @@ def resolve_git_mount_mappings(
 async def resolve_single_git_mount(
     session: AsyncSession,
     git_mount: dict,
-    instance_dir: str | None = None,
+    clone_parent: str | None = None,
     working_directory: str | None = None,
     home_dir: str = "/root",
 ) -> list[dict]:
@@ -443,15 +548,15 @@ async def resolve_single_git_mount(
         logger.warning("Invalid git mount skipped: no mappings")
         return []
 
-    if not instance_dir:
-        logger.warning("Git mount skipped: no instance_dir provided for cloning")
+    if not clone_parent:
+        logger.warning("Git mount skipped: no canonical profile directory provided")
         return []
 
     # Clone or pull the repository. Git mounts are auxiliary, so they keep
     # using the repository URL basename rather than the project name.
     try:
         repo_path = await asyncio.to_thread(
-            clone_git_repo, remote_url, branch, instance_dir
+            clone_git_repo_locked, remote_url, branch, clone_parent
         )
     except Exception as exc:
         logger.warning(
@@ -464,7 +569,14 @@ async def resolve_single_git_mount(
         return []
 
     # Resolve all mappings from the cloned repo
-    return resolve_git_mount_mappings(repo_path, mappings, working_directory, home_dir)
+    volumes = resolve_git_mount_mappings(
+        repo_path, mappings, working_directory, home_dir
+    )
+    # Profile-scoped Git working copies are writable and shared by compatible
+    # containers. Explicit refresh replaces local edits with the remote ref.
+    for volume in volumes:
+        volume["readonly"] = False
+    return volumes
 
 
 def checkout_branch(repo_path: str, branch: str) -> bool:
@@ -508,10 +620,10 @@ def checkout_branch(repo_path: str, branch: str) -> bool:
 
 
 def pull_repository_updates(repo_path: str, remote_url: str) -> None:
-    """Pull latest updates from remote repository.
+    """Replace a profile working copy with its current remote branch.
 
-    Used when starting a new container with an existing cloned repository
-    to ensure the latest code is mounted.
+    Git profile mounts are writable shared working copies. Refresh discards
+    local container/editor edits after fetching the remote baseline.
     """
     import subprocess
 
@@ -525,15 +637,22 @@ def pull_repository_updates(repo_path: str, remote_url: str) -> None:
     if result.returncode != 0:
         raise RuntimeError(f"Failed to fetch updates: {result.stderr}")
 
-    # Pull changes for current branch
-    result = subprocess.run(
-        ["git", "-C", repo_path, "pull", "origin"],
+    branch_result = subprocess.run(
+        ["git", "-C", repo_path, "branch", "--show-current"],
         capture_output=True,
         text=True,
     )
+    branch = branch_result.stdout.strip() if branch_result.returncode == 0 else ""
+    if not branch:
+        raise RuntimeError("Unable to determine Git working-copy branch")
 
+    result = subprocess.run(
+        ["git", "-C", repo_path, "reset", "--hard", f"origin/{branch}"],
+        capture_output=True,
+        text=True,
+    )
     if result.returncode != 0:
-        raise RuntimeError(f"Failed to pull updates: {result.stderr}")
+        raise RuntimeError(f"Failed to reset working copy: {result.stderr}")
 
 
 def expand_glob_source(source_path: str, repo_path: str) -> list[str]:
@@ -1398,17 +1517,22 @@ async def start_tool_instance(
             resolved = await resolve_profile(
                 session, instance.selected_config_profile_id
             )
+            # Profile working-directory hints determine where individual
+            # canonical profile files are bind-mounted at container creation.
+            profile_hints = resolved.runtime_hints
+            if profile_hints.get("working_directory"):
+                working_directory = expand_container_path(
+                    profile_hints["working_directory"], home_dir
+                )
             profile_env, profile_files, profile_mounts, profile_hints = (
-                apply_resolved_profile(instance_dir, resolved, home_dir)
+                apply_resolved_profile(
+                    instance_dir, resolved, home_dir, working_directory
+                )
             )
             # Profile hints override the manifest/tool defaults, and git mounts
             # need the final working directory to resolve relative target paths.
             if profile_hints.get("start_command"):
                 start_command = profile_hints["start_command"]
-            if profile_hints.get("working_directory"):
-                working_directory = expand_container_path(
-                    profile_hints["working_directory"], home_dir
-                )
             if profile_hints.get("port_override"):
                 port_override = profile_hints["port_override"]
             env_vars.update(profile_env)
@@ -1416,22 +1540,24 @@ async def start_tool_instance(
             git_mount_volumes = await resolve_git_mounts(
                 session, resolved, instance_dir, working_directory, home_dir
             )
-            # Stack static file mounts on top of git repo mounts so they do
-            # not mask each other when they target the same directory.
-            stacked_profile_mounts = _stack_profile_mounts_with_git_mounts(
-                profile_mounts, git_mount_volumes
+            # Non-Git profile mounts bind directly to canonical profile
+            # storage so edits made by one compatible container are visible to
+            # every other container and the profile editor readback path.
+            composed_mounts = _stack_profile_mounts_with_git_mounts(
+                profile_mounts,
+                git_mount_volumes,
+                instance_dir,
             )
-            extra_volumes.extend(stacked_profile_mounts)
-            extra_volumes.extend(git_mount_volumes)
+            extra_volumes.extend(composed_mounts)
             logger.debug(
-                "Applied config profile %s to instance %s (env=%d, files=%d, mounts=%d, git_mounts=%d, stacked=%d)",
+                "Applied config profile %s to instance %s (env=%d, files=%d, profile_mounts=%d, git_mounts=%d, composed_mounts=%d)",
                 resolved.profile_name,
                 instance.id,
                 len(profile_env),
                 len(profile_files),
                 len(profile_mounts),
                 len(git_mount_volumes),
-                len(profile_mounts) - len(stacked_profile_mounts),
+                len(composed_mounts),
             )
         except ConfigProfileCycleError as exc:
             logger.error(
@@ -1472,7 +1598,15 @@ async def start_tool_instance(
 
         if ssh_keys_to_mount:
             ssh_dir = os.path.join(instance_dir, "mounts", "ssh", ".ssh")
-            os.makedirs(ssh_dir, exist_ok=True)
+            try:
+                os.makedirs(ssh_dir, exist_ok=True)
+            except OSError as exc:
+                logger.error(
+                    "Failed to create SSH mount directory for instance %s: %s",
+                    instance.id,
+                    exc,
+                )
+                ssh_keys_to_mount = []
 
             key_filenames = []
             for ssh_key in ssh_keys_to_mount:
@@ -2185,7 +2319,13 @@ async def delete_tool_instance(
         if os.path.exists(instance_dir):
             import shutil
 
-            shutil.rmtree(instance_dir)
+            try:
+                shutil.rmtree(instance_dir)
+            except OSError as exc:
+                logger.error(
+                    "Failed to remove instance directory %s: %s", instance_dir, exc
+                )
+                raise RuntimeError("Failed to remove instance files") from exc
 
     await publish_lifecycle_event(
         event_bus=_event_bus,

apps/api/tests/.pi-map.index.md

@@ -2,7 +2,7 @@
 dir: apps/api/tests
 
 ## role
-Provides shared test infrastructure and fixtures for API endpoint testing
+Provides shared pytest fixtures and test utilities for FastAPI application testing
 ## parent
 index: apps/api/.pi-map.index.md
 map: apps/api/.pi-map.md
@@ -19,6 +19,12 @@ map: apps/api/.pi-map.md
 - apps/api/tests/system
   index: apps/api/tests/system/.pi-map.index.md
   map: apps/api/tests/system/.pi-map.md
+- apps/api/tests/test_routers
+  index: apps/api/tests/test_routers/.pi-map.index.md
+  map: apps/api/tests/test_routers/.pi-map.md
+- apps/api/tests/tools
+  index: apps/api/tests/tools/.pi-map.index.md
+  map: apps/api/tests/tools/.pi-map.md
 - apps/api/tests/unit
   index: apps/api/tests/unit/.pi-map.index.md
   map: apps/api/tests/unit/.pi-map.md

apps/api/tests/.pi-map.md

@@ -4,11 +4,11 @@ dir: apps/api/tests
 index: apps/api/tests/.pi-map.index.md
 
 ## role
-Provides shared test infrastructure and fixtures for API endpoint testing
+Provides shared pytest fixtures and test utilities for FastAPI application testing
 ## files
-- conftest.py | Configures shared pytest fixtures for FastAPI testing with async SQLite database, dependency overrides, and authenticated/admin test clients. | exp: func:test_client() → Generator[TestClient, None, None], call:create_async_engine, call:engine.begin, call:conn.run_sync, call:asyncio.run, call:init_db, call:async_sessionmaker, call:patch, call:TestClient, call:app.dependency_overrides.pop, call:engine.dispose, func:init_db(), call:engine.begin, call:conn.run_sync, func:override_get_db_session() → AsyncGenerator[AsyncSession, None], call:async_sessionmaker, func:db_session(test_client) → AsyncGenerator[AsyncSession, None], call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:gen.aclose, call:create_async_engine, call:engine.begin, call:conn.run_sync, call:async_sessionmaker, call:engine.dispose, func:authenticated_client(test_client) → Generator[TestClient, None, None], call:str, call:uuid.uuid4, call:Settings, call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:User, call:uuid.UUID, call:session.add, call:session.commit, call:gen.aclose, call:asyncio.run, call:create_test_user, call:create_session_cookie, call:test_client.cookies.set, func:create_test_user(), call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:User, call:uuid.UUID, call:session.add, call:session.commit, call:gen.aclose, func:test_project_and_repo(authenticated_client) → tuple[str, str], call:uuid.uuid4, call:Settings, call:authenticated_client.cookies.get, call:decode_session_cookie, call:uuid.UUID, call:asyncio.run, call:get_user_id, call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:Project, call:session.add, call:GitRepository, call:session.commit, call:gen.aclose, call:create_project_and_repo, call:str, raise:RuntimeError, func:get_user_id(), call:Settings, call:authenticated_client.cookies.get, call:decode_session_cookie, call:uuid.UUID, func:create_project_and_repo(), call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:Project, call:session.add, call:GitRepository, call:session.commit, call:gen.aclose, func:admin_client(test_client) → Generator[TestClient, None, None], call:str, call:uuid.uuid4, call:Settings, call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:User, call:uuid.UUID, call:session.add, call:session.commit, call:gen.aclose, call:asyncio.run, call:create_admin_user, call:create_session_cookie, call:test_client.cookies.set, func:create_admin_user(), call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:User, call:uuid.UUID, call:session.add, call:session.commit, call:gen.aclose | dep: asyncio, os, typing, unittest.mock, pytest, pytest_asyncio, fastapi.testclient, sqlalchemy.ext.asyncio, src.config, src.models.base, src.main, src.auth.dependencies, uuid, src.auth.session, src.models.user.user, src.models.project.project, src.models.project.git_repository, fastapi, sqlalchemy, aiosqlite, src.models, src.auth
+- conftest.py | Provides shared pytest fixtures including test clients, database sessions, authenticated clients, and test data for FastAPI application testing. | exp: func:test_client() → Generator[TestClient, None, None], call:create_async_engine, call:engine.begin, call:conn.run_sync, call:asyncio.run, call:init_db, call:async_sessionmaker, call:patch, call:TestClient, call:app.dependency_overrides.pop, call:engine.dispose, func:init_db(), call:engine.begin, call:conn.run_sync, func:override_get_db_session() → AsyncGenerator[AsyncSession, None], call:async_sessionmaker, func:db_session(test_client) → AsyncGenerator[AsyncSession, None], call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:gen.aclose, call:create_async_engine, call:engine.begin, call:conn.run_sync, call:async_sessionmaker, call:engine.dispose, func:authenticated_client(test_client) → Generator[TestClient, None, None], call:str, call:uuid.uuid4, call:Settings, call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:User, call:uuid.UUID, call:session.add, call:session.commit, call:gen.aclose, call:asyncio.run, call:create_test_user, call:create_session_cookie, call:test_client.cookies.set, func:create_test_user(), call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:User, call:uuid.UUID, call:session.add, call:session.commit, call:gen.aclose, func:test_project_and_repo(authenticated_client) → tuple[str, str], call:uuid.uuid4, call:Settings, call:authenticated_client.cookies.get, call:decode_session_cookie, call:uuid.UUID, call:asyncio.run, call:get_user_id, call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:Project, call:session.add, call:GitRepository, call:session.commit, call:gen.aclose, call:create_project_and_repo, call:str, raise:RuntimeError, func:get_user_id(), call:Settings, call:authenticated_client.cookies.get, call:decode_session_cookie, call:uuid.UUID, func:create_project_and_repo(), call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:Project, call:session.add, call:GitRepository, call:session.commit, call:gen.aclose, func:admin_client(test_client) → Generator[TestClient, None, None], call:str, call:uuid.uuid4, call:Settings, call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:User, call:uuid.UUID, call:session.add, call:session.commit, call:gen.aclose, call:asyncio.run, call:create_admin_user, call:create_session_cookie, call:test_client.cookies.set, func:create_admin_user(), call:app.dependency_overrides.get, call:override_fn, call:gen.asend, call:User, call:uuid.UUID, call:session.add, call:session.commit, call:gen.aclose | dep: asyncio, os, typing, unittest.mock, pytest, pytest_asyncio, fastapi.testclient, sqlalchemy.ext.asyncio, src.config, src.models.base, src.main, src.auth.dependencies, uuid, src.auth.session, src.models.user.user, src.models.project.project, src.models.project.git_repository, fastapi.testclient.TestClient
 ## arch
-Pytest plugin architecture with async SQLite test database, dependency injection overrides, and role-based client fixtures (authenticated/admin) for isolated FastAPI integration tests
+Pytest plugin pattern with dependency injection fixtures for database sessions, HTTP clients, and authentication state management
 ## tags
 call:app.dependency, call:create, overrides.get, call:override, fn, call:gen.asend, call:gen.aclose, user
 ## symbols

apps/api/tests/api/test_terminal_ws_multi.py

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

apps/api/tests/unit/.pi-map.index.md

@@ -2,12 +2,14 @@
 dir: apps/api/tests/unit
 
 ## role
-Contains unit tests for the API application's core services, utilities, and infrastructure components.
+Contains isolated unit tests for individual components of the API application, covering configuration, services, utilities, and core business logic without external dependencies.
 ## parent
 index: apps/api/tests/.pi-map.index.md
 map: apps/api/tests/.pi-map.md
 ## children
--
+- apps/api/tests/unit/.ruff_cache
+  index: apps/api/tests/unit/.ruff_cache/.pi-map.index.md
+  map: apps/api/tests/unit/.ruff_cache/.pi-map.md
 ## files
 - __init__.py
 - test_alembic_migrations.py
@@ -32,6 +34,8 @@ map: apps/api/tests/.pi-map.md
 - test_permission_fixer.py
 - test_readiness_probe.py
 - test_ssh_keys.py
+- test_terminal_container_user.py
+- test_terminal_session.py
 ## links
 index: apps/api/tests/unit/.pi-map.index.md
 map: apps/api/tests/unit/.pi-map.md
@@ -40,5 +44,7 @@ map: apps/api/tests/unit/.pi-map.md
   read: __init__.py, test_alembic_migrations.py, test_config.py
 - change unit config
   read: test_config.py, test_config_profile_resolver.py
+- explore unit subdirectories
+  index: apps/api/tests/unit/.ruff_cache/.pi-map.index.md
 ## dirty
 -

apps/api/tests/unit/.pi-map.md

@@ -4,35 +4,37 @@ dir: apps/api/tests/unit
 index: apps/api/tests/unit/.pi-map.index.md
 
 ## role
-Contains unit tests for the API application's core services, utilities, and infrastructure components.
+Contains isolated unit tests for individual components of the API application, covering configuration, services, utilities, and core business logic without external dependencies.
 ## files
-- __init__.py | Swaps two tmux panes between windows, preserving active pane state and layout | dep: tmux
-- test_alembic_migrations.py | Unit tests that verify Alembic database migration files are importable, have correct revision identifiers, and declare expected dependencies. | exp: func:test_home_directory_migration_imports_and_rewrites() → None, call:Path, call:migration_path.exists, call:importlib.util.spec_from_file_location, call:importlib.util.module_from_spec, call:spec.loader.exec_module, call:callable, func:test_merge_migration_resolves_heads() → None, call:Path, call:migration_path.exists, call:importlib.util.spec_from_file_location, call:importlib.util.module_from_spec, call:spec.loader.exec_module, call:callable, func:test_remove_pi_agent_repo_mount_migration_imports() → None, call:Path, call:migration_path.exists, call:importlib.util.spec_from_file_location, call:importlib.util.module_from_spec, call:spec.loader.exec_module, call:callable | dep: importlib.util, pathlib, pytest
-- test_config.py | Unit tests for application configuration settings including database URLs, authentication defaults, and cookie security policies | exp: func:test_settings_default_database_url_uses_asyncpg(monkeypatch) → None, call:monkeypatch.delenv, call:Settings, func:test_build_database_url_uses_explicit_values() → None, call:build_database_url, func:test_settings_prefers_explicit_database_url_env(monkeypatch) → None, call:monkeypatch.setenv, call:Settings, func:test_auth_settings_have_secure_defaults() → None, call:Settings, call:settings.resolved_authentik_authorize_url.endswith, call:settings.resolved_authentik_token_url.endswith, call:settings.resolved_authentik_jwks_url.endswith, func:test_cookie_policy_is_strict_in_production(monkeypatch) → None, call:monkeypatch.setenv, call:Settings, func:test_cookie_policy_is_relaxed_for_local_dev(monkeypatch) → None, call:monkeypatch.setenv, call:Settings | dep: pytest, src.config, src.database, src.config.Settings, src.database.build_database_url
-- test_config_profile_resolver.py | Unit tests for config profile resolution including merge helpers, profile inheritance with cycle detection, and git mount normalization | exp: class:TestMergeFunctions, method:test_merge_env_vars_basic(self) → None, call:_merge_env_vars, method:test_merge_env_vars_tracks_overrides(self) → None, call:_merge_env_vars, method:test_merge_runtime_hints_basic(self) → None, call:_merge_runtime_hints, method:test_merge_files_basic(self) → None, call:_merge_files, method:test_merge_mounts_basic(self) → None, call:_merge_mounts, method:test_merge_mounts_file_override(self) → None, call:_merge_mounts, call:ResolvedMount, method:test_merge_mounts_mode_conflict(self) → None, call:_merge_mounts, call:ResolvedMount, method:test_merge_git_mounts_basic(self) → None, call:_merge_git_mounts, call:len, method:test_merge_git_mounts_concatenate_same_repo_branch(self) → None, call:_merge_git_mounts, call:len, method:test_merge_git_mounts_dedup_same_mapping(self) → None, call:_merge_git_mounts, call:len, method:test_merge_git_mounts_different_repos(self) → None, call:_merge_git_mounts, call:len, method:test_merge_git_mounts_different_branches(self) → None, call:_merge_git_mounts, call:len, call:m.get, class:TestResolveProfile, class:TestApplyResolvedProfile, method:test_mounts_directory_not_individual_files(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, call:len, call:Path(volumes[0]["source"]).is_dir, call:(Path(volumes[0]["source"]) / "config.json").exists, call:(Path(volumes[0]["source"]) / "nested" / "file.txt").exists, method:test_directory_mount_target(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, call:len, call:Path, call:(Path(volumes[0]["source"]) / "z.json").exists, method:test_empty_mount_produces_no_volumes(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, method:test_home_expansion_in_directory_mount_target(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, call:len, call:(Path(volumes[0]["source"]) / "app.toml").exists, call:Path, method:test_readonly_mount_sets_readonly_flag(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, call:len, call:volumes[0].get, method:test_writable_mount_does_not_set_readonly_flag(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, call:len, call:volumes[0].get, class:TestCheckIncludeCycle | dep: uuid, pathlib, pytest, sqlalchemy.ext.asyncio, src.models.config.config_profile, src.services.config.config_profile_resolver
-- test_docker_build.py | Unit tests for a Docker image build service that verifies command construction, file writing, error handling, and security constraints. | exp: class:TestBuildImage | dep: subprocess, tempfile, pathlib, unittest.mock, pytest, src.services.build.docker_build
-- test_docker_service.py | Unit tests for Docker service utilities including container ID/name retrieval and volume sorting by specificity. | exp: class:TestGetContainerId, class:TestGetContainerName, class:TestSortVolumesBySpecificity, method:test_parent_before_child(self) → None, call:sort_volumes_by_specificity, method:test_stable_sort_for_equal_depth(self) → None, call:sort_volumes_by_specificity, method:test_with_type_suffix(self) → None, call:sort_volumes_by_specificity, method:test_empty_list(self) → None, call:sort_volumes_by_specificity, method:test_single_volume(self) → None, call:sort_volumes_by_specificity, method:test_duplicate_target_warning(self, caplog) → None, call:caplog.at_level, call:sort_volumes_by_specificity | dep: unittest.mock, logging, src.services.docker.container, src.services.docker.compose, subprocess
-- test_event_bus.py | Unit tests for InstanceEventBus verifying publish/subscribe, exception isolation, unsubscribe, async callback, and bulk unsubscribe functionality. | exp: func:event_bus() → InstanceEventBus, call:InstanceEventBus, call:bus._reset_for_testing, func:sample_payload() → InstanceEventPayload, call:str, call:uuid.uuid4, func:test_publish_delivers_to_all_subscribers(event_bus: InstanceEventBus, sample_payload: InstanceEventPayload) → None, call:received.append, call:event_bus.subscribe, call:event_bus.publish, call:len, func:callback_1(payload: InstanceEventPayload) → None, call:received.append, func:callback_2(payload: InstanceEventPayload) → None, call:received.append, func:callback_3(payload: InstanceEventPayload) → None, call:received.append, func:test_subscriber_exception_isolation(event_bus: InstanceEventBus, sample_payload: InstanceEventPayload) → None, call:received.append, call:event_bus.subscribe, call:event_bus.publish, raise:RuntimeError, func:bad_callback(_payload: InstanceEventPayload) → None, raise:RuntimeError, func:good_callback(_payload: InstanceEventPayload) → None, call:received.append, func:test_unsubscribe_removes_callback(event_bus: InstanceEventBus, sample_payload: InstanceEventPayload) → None, call:received.append, call:event_bus.subscribe, call:unsubscribe, call:event_bus.publish, func:callback(_payload: InstanceEventPayload) → None, call:received.append, func:test_publish_to_empty_subscriber_list(event_bus: InstanceEventBus, sample_payload: InstanceEventPayload) → None, call:event_bus.publish, func:test_async_subscriber_supported(event_bus: InstanceEventBus, sample_payload: InstanceEventPayload) → None, call:asyncio.sleep, call:received.append, call:event_bus.subscribe, call:event_bus.publish, func:async_callback(_payload: InstanceEventPayload) → None, call:asyncio.sleep, call:received.append, func:test_unsubscribe_all_clears_subscribers(event_bus: InstanceEventBus, sample_payload: InstanceEventPayload) → None, call:received.append, call:event_bus.subscribe, call:event_bus.unsubscribe_all, call:event_bus.publish, func:callback(_payload: InstanceEventPayload) → None, call:received.append | dep: asyncio, uuid, typing, pytest, src.services.instance.event_bus
-- test_file_service.py | Unit tests for FileService validating directory listing, file read/write operations, binary file rejection, and path traversal security. | exp: class:TestFileService, method:test_list_directory_empty(self, temp_workspace: Workspace), call:FileService, call:service.list_directory, method:test_list_directory_with_files(self, temp_workspace: Workspace), call:os.makedirs, call:os.path.join, call:open, call:f.write, call:FileService, call:service.list_directory, call:len, method:test_read_file(self, temp_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:FileService, call:service.read_file, method:test_read_binary_file_rejected(self, temp_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:FileService, call:pytest.raises, call:service.read_file, method:test_write_file(self, temp_workspace: Workspace), call:FileService, call:service.write_file, call:os.path.exists, call:os.path.join, call:open, call:f.read, method:test_path_escapes_workspace(self, temp_workspace: Workspace), call:FileService, call:pytest.raises, call:service.list_directory, func:temp_workspace(), call:tempfile.TemporaryDirectory, call:Workspace | dep: os, tempfile, pytest, src.models, src.services.shared.file_service, src.models.Workspace, src.services.shared.file_service.FileService
-- test_git_operations.py | Unit tests for GitOperations class covering status, commit, history, and branch operations | exp: class:TestGitOperationsStatus, method:test_status_clean(self, temp_workspace: Workspace), call:GitOperations, call:asyncio.run, call:git.status, method:test_status_modified(self, temp_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:GitOperations, call:asyncio.run, call:git.status, method:test_status_untracked(self, temp_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:GitOperations, call:asyncio.run, call:git.status, class:TestGitOperationsCommit, method:test_commit_stages_and_commits(self, temp_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:GitOperations, call:asyncio.run, call:git.commit, call:git.status, call:git.history, method:test_commit_fails_without_changes(self, temp_workspace: Workspace), call:GitOperations, call:pytest.raises, call:asyncio.run, call:git.commit, class:TestGitOperationsHistory, method:test_history_returns_commits(self, temp_workspace: Workspace), call:GitOperations, call:asyncio.run, call:git.history, call:len, method:test_history_filters_by_path(self, temp_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:GitOperations, call:asyncio.run, call:git.commit, call:git.history, call:len, class:TestGitOperationsBranches, method:test_branches_lists_main(self, temp_workspace: Workspace), call:GitOperations, call:asyncio.run, call:git.branches, method:test_checkout_switches_branch(self, temp_workspace: Workspace), call:_run_git, call:GitOperations, call:asyncio.run, call:git.checkout, call:git.status, func:_run_git(*args: str, cwd: str) → None, call:subprocess.run, func:temp_workspace(), call:tempfile.TemporaryDirectory, call:_run_git, call:os.path.join, call:open, call:f.write, call:Workspace | dep: asyncio, os, subprocess, tempfile, pytest, src.models, src.services.git.git_operations, src.models.Workspace, src.services.git.git_operations.GitOperations
-- test_git_service.py | Unit tests for GitService class covering clone, fetch, pull, and branch_exists_remotely operations with mocked subprocess calls. | exp: class:TestGitServiceClone, class:TestGitServiceFetch, class:TestGitServicePull, class:TestGitServiceBranchExistsRemotely, method:test_branch_exists(self), call:MagicMock, call:patch, call:GitService.branch_exists_remotely, call:mock_run.assert_called_once_with, method:test_branch_not_exists(self), call:MagicMock, call:patch, call:GitService.branch_exists_remotely, method:test_ls_remote_fails(self), call:MagicMock, call:patch, call:GitService.branch_exists_remotely | dep: asyncio, unittest.mock, pytest, src.services.git.git_service
-- test_git_url_parser.py | Unit tests for git URL parsing utilities that validate extraction of base repository URLs, clone URL validation, and comprehensive URL parsing across GitHub, GitLab, and Bitbucket formats. | exp: class:TestExtractBaseRepoUrl, method:test_github_tree_url(self), call:extract_base_repo_url, method:test_github_blob_url(self), call:extract_base_repo_url, method:test_github_pull_url(self), call:extract_base_repo_url, method:test_github_issues_url(self), call:extract_base_repo_url, method:test_github_valid_url(self), call:extract_base_repo_url, method:test_github_url_with_query_params(self), call:extract_base_repo_url, method:test_gitlab_tree_url(self), call:extract_base_repo_url, method:test_gitlab_blob_url(self), call:extract_base_repo_url, method:test_gitlab_merge_request_url(self), call:extract_base_repo_url, method:test_gitlab_valid_url(self), call:extract_base_repo_url, method:test_bitbucket_src_url(self), call:extract_base_repo_url, method:test_bitbucket_valid_url(self), call:extract_base_repo_url, method:test_ssh_url(self), call:extract_base_repo_url, method:test_ssh_url_without_git_suffix(self), call:extract_base_repo_url, method:test_invalid_url(self), call:extract_base_repo_url, method:test_empty_url(self), call:extract_base_repo_url, class:TestIsValidCloneUrl, method:test_valid_ssh_url(self), call:is_valid_clone_url, method:test_valid_https_url(self), call:is_valid_clone_url, method:test_browser_url(self), call:is_valid_clone_url, method:test_url_without_git_suffix(self), call:is_valid_clone_url, method:test_invalid_url(self), call:is_valid_clone_url, class:TestParseGitUrl, method:test_valid_git_url(self), call:parse_git_url, method:test_browser_url(self), call:parse_git_url, method:test_invalid_url(self), call:parse_git_url, method:test_empty_url(self), call:parse_git_url, method:test_ssh_url(self), call:parse_git_url | dep: src.utils.git_url_parser, pytest
-- test_health_monitor.py | Unit tests for HealthMonitor state-transition logic covering container crash detection, tunnel failure detection, recovery detection, write optimization, and exception resilience. | exp: func:event_bus() → InstanceEventBus, call:InstanceEventBus, call:bus._reset_for_testing, func:health_monitor(event_bus: InstanceEventBus) → HealthMonitor, call:HealthMonitor, func:_create_running_instance(db_session) → ToolInstance, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, call:ToolInstance, func:test_detects_container_crash(db_session, event_bus: InstanceEventBus, health_monitor: HealthMonitor) → None, call:_create_running_instance, call:events_captured.append, call:event_bus.subscribe, call:patch, call:health_monitor._check_instance, call:db_session.refresh, call:len, call:db_session.execute, call:select(HealthCheck).where, call:result.scalar_one, func:capture_event(payload: InstanceEventPayload) → None, call:events_captured.append, func:test_detects_tunnel_failure(db_session, event_bus: InstanceEventBus, health_monitor: HealthMonitor) → None, call:_create_running_instance, call:events_captured.append, call:event_bus.subscribe, call:patch, call:health_monitor._check_instance, call:db_session.refresh, call:len, call:db_session.execute, call:select(HealthCheck).where, call:result.scalar_one, func:capture_event(payload: InstanceEventPayload) → None, call:events_captured.append, func:test_detects_recovery(db_session, event_bus: InstanceEventBus, health_monitor: HealthMonitor) → None, call:_create_running_instance, call:db_session.commit, call:HealthSnapshot, call:events_captured.append, call:event_bus.subscribe, call:patch, call:health_monitor._check_instance, call:db_session.refresh, call:len, call:db_session.execute, call:select(HealthCheck).where, call:result.scalar_one, func:capture_event(payload: InstanceEventPayload) → None, call:events_captured.append, func:test_skips_writes_when_no_state_change(db_session, event_bus: InstanceEventBus, health_monitor: HealthMonitor) → None, call:_create_running_instance, call:HealthSnapshot, call:patch, call:health_monitor._check_instance, call:db_session.execute, call:select(HealthCheck).where, call:len, call:result.scalars().all, func:test_docker_exception_resilience(db_session, event_bus: InstanceEventBus, health_monitor: HealthMonitor) → None, call:_create_running_instance, call:events_captured.append, call:event_bus.subscribe, call:patch, call:RuntimeError, call:health_monitor._check_instance, call:db_session.execute, call:select(HealthCheck).where, call:result.scalar_one_or_none, func:capture_event(payload: InstanceEventPayload) → None, call:events_captured.append, func:test_monitor_start_stop(health_monitor: HealthMonitor) → None, call:health_monitor.start, call:task.done, call:health_monitor.stop, call:suppress, call:task.cancelled | dep: asyncio, uuid, contextlib, unittest.mock, pytest, sqlalchemy, src.models.system.health_check, src.models.tool.tool_instance, src.models.user.user, src.services.instance.event_bus, src.services.instance.health_monitor
-- test_home_path_expansion.py | Unit tests for tilde and $HOME expansion in container paths, plus manifest-based home directory resolution | exp: class:TestExpandContainerPath, method:test_tilde_slash_expands(self) → None, call:expand_container_path, method:test_tilde_alone_expands(self) → None, call:expand_container_path, method:test_dollar_home_slash_expands(self) → None, call:expand_container_path, method:test_dollar_home_alone_expands(self) → None, call:expand_container_path, method:test_absolute_path_unchanged(self) → None, call:expand_container_path, method:test_relative_path_unchanged(self) → None, call:expand_container_path, method:test_tilde_in_middle_unchanged(self) → None, call:expand_container_path, method:test_dollar_home_in_middle_unchanged(self) → None, call:expand_container_path, method:test_root_home(self) → None, call:expand_container_path, class:TestGetManifestHomeDir, method:test_with_user_block(self) → None, call:get_manifest_home_dir, method:test_without_user_block(self) → None, call:get_manifest_home_dir, method:test_with_empty_user_name(self) → None, call:get_manifest_home_dir, method:test_with_none_user_name(self) → None, call:get_manifest_home_dir | dep: pytest, src.services.config.config_profile_resolver, src.services.build.manifest_compiler
-- test_instance_service.py | Unit tests for tool instance service functions including compose file modification, repository mount name resolution, profile/git mount stacking, and manifest instance preparation. | exp: class:TestModifyComposeFile, method:test_extra_volumes_expand_home_dir(self, tmp_path), call:compose_path.write_text, call:modify_compose_file, call:str, call:compose_path.read_text, method:test_working_directory_expands_home_dir(self, tmp_path), call:compose_path.write_text, call:modify_compose_file, call:str, call:compose_path.read_text, class:TestGetRepositoryMountName, method:test_prefers_remote_url_name_over_user_provided_name(self), call:MagicMock, call:_get_repository_mount_name, method:test_parses_browser_url_to_repo_name(self), call:MagicMock, call:_get_repository_mount_name, method:test_uses_workspace_path_basename_when_workspace_provided(self), call:MagicMock, call:_get_repository_mount_name, method:test_falls_back_to_repo_name_when_remote_url_missing(self), call:MagicMock, call:_get_repository_mount_name, method:test_falls_back_to_repo_name_for_unparseable_url(self), call:MagicMock, call:_get_repository_mount_name, class:TestStackProfileMountsWithGitMounts, method:test_exact_overlap_merges_profile_files_into_git_source(self, tmp_path) → None, call:git_source.mkdir, call:(git_source / "existing.txt").write_text, call:profile_source.mkdir, call:(profile_source / "settings.json").write_text, call:str, call:_stack_profile_mounts_with_git_mounts, call:(git_source / "existing.txt").read_text, call:(git_source / "settings.json").read_text, method:test_descendant_overlap_copies_into_subdirectory(self, tmp_path) → None, call:git_source.mkdir, call:(git_source / "README").write_text, call:profile_source.mkdir, call:(profile_source / "settings.json").write_text, call:str, call:_stack_profile_mounts_with_git_mounts, call:(git_source / "agent" / "settings.json").read_text, call:(git_source / "README").read_text, method:test_non_overlapping_mounts_left_untouched(self, tmp_path) → None, call:git_source.mkdir, call:profile_source.mkdir, call:(profile_source / "config").write_text, call:str, call:_stack_profile_mounts_with_git_mounts, method:test_git_source_file_does_not_consume_profile_mount(self, tmp_path) → None, call:git_source.write_text, call:profile_source.mkdir, call:(profile_source / "settings.json").write_text, call:str, call:_stack_profile_mounts_with_git_mounts, method:test_profile_source_file_copied_into_git_source(self, tmp_path) → None, call:git_source.mkdir, call:profile_source.write_text, call:str, call:_stack_profile_mounts_with_git_mounts, call:(git_source / "settings.json").read_text, class:Result, func:test_prepare_manifest_instance_uses_workspace_path_basename(), call:MagicMock, call:AsyncMock, call:Result, call:prepare_manifest_instance, func:session_get(model, obj_id), func:fake_run(cmd), call:Result | dep: unittest.mock, pytest, src.services.tool.instance_service, subprocess, src.services.tool, pathlib
+- __init__.py | Empty package initialization file that marks a directory as a Python package.
+- test_alembic_migrations.py | Unit tests that verify Alembic database migration files are importable, have correct revision identifiers, and declare expected dependencies without requiring a live database. | exp: func:test_home_directory_migration_imports_and_rewrites() → None, call:Path, call:migration_path.exists, call:importlib.util.spec_from_file_location, call:importlib.util.module_from_spec, call:spec.loader.exec_module, call:callable, func:test_merge_migration_resolves_heads() → None, call:Path, call:migration_path.exists, call:importlib.util.spec_from_file_location, call:importlib.util.module_from_spec, call:spec.loader.exec_module, call:callable, func:test_remove_pi_agent_repo_mount_migration_imports() → None, call:Path, call:migration_path.exists, call:importlib.util.spec_from_file_location, call:importlib.util.module_from_spec, call:spec.loader.exec_module, call:callable, func:test_remove_pi_agent_workspace_symlink_migration_imports() → None, call:Path, call:migration_path.exists, call:importlib.util.spec_from_file_location, call:importlib.util.module_from_spec, call:spec.loader.exec_module, call:callable | dep: importlib.util, pathlib, pytest, pathlib.Path
+- test_config.py | Unit tests verifying configuration settings including database URLs, auth defaults, and environment-specific cookie policies. | exp: func:test_settings_default_database_url_uses_asyncpg(monkeypatch) → None, call:monkeypatch.delenv, call:Settings, func:test_build_database_url_uses_explicit_values() → None, call:build_database_url, func:test_settings_prefers_explicit_database_url_env(monkeypatch) → None, call:monkeypatch.setenv, call:Settings, func:test_auth_settings_have_secure_defaults() → None, call:Settings, call:settings.resolved_authentik_authorize_url.endswith, call:settings.resolved_authentik_token_url.endswith, call:settings.resolved_authentik_jwks_url.endswith, func:test_cookie_policy_is_strict_in_production(monkeypatch) → None, call:monkeypatch.setenv, call:Settings, func:test_cookie_policy_is_relaxed_for_local_dev(monkeypatch) → None, call:monkeypatch.setenv, call:Settings | dep: pytest, src.config, src.database, src.config.Settings, src.database.build_database_url
+- test_config_profile_resolver.py | Tests config profile resolution logic including merge functions, profile inheritance with includes, cycle detection, and git mount normalization. | exp: class:TestMergeFunctions, method:test_merge_env_vars_basic(self) → None, call:_merge_env_vars, method:test_merge_env_vars_tracks_overrides(self) → None, call:_merge_env_vars, method:test_merge_runtime_hints_basic(self) → None, call:_merge_runtime_hints, method:test_merge_files_basic(self) → None, call:_merge_files, method:test_merge_mounts_basic(self) → None, call:_merge_mounts, method:test_merge_mounts_file_override(self) → None, call:_merge_mounts, call:ResolvedMount, method:test_merge_mounts_mode_conflict(self) → None, call:_merge_mounts, call:ResolvedMount, method:test_merge_git_mounts_basic(self) → None, call:_merge_git_mounts, call:len, method:test_merge_git_mounts_concatenate_same_repo_branch(self) → None, call:_merge_git_mounts, call:len, method:test_merge_git_mounts_dedup_same_mapping(self) → None, call:_merge_git_mounts, call:len, method:test_merge_git_mounts_different_repos(self) → None, call:_merge_git_mounts, call:len, method:test_merge_git_mounts_different_branches(self) → None, call:_merge_git_mounts, call:len, call:m.get, class:TestResolveProfile, class:TestApplyResolvedProfile, method:test_mounts_directory_not_individual_files(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, call:len, call:Path(volumes[0]["source"]).is_dir, call:(Path(volumes[0]["source"]) / "config.json").exists, call:(Path(volumes[0]["source"]) / "nested" / "file.txt").exists, method:test_directory_mount_target(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, call:len, call:Path, call:(Path(volumes[0]["source"]) / "z.json").exists, method:test_empty_mount_produces_no_volumes(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, method:test_home_expansion_in_directory_mount_target(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, call:len, call:(Path(volumes[0]["source"]) / "app.toml").exists, call:Path, method:test_readonly_mount_sets_readonly_flag(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, call:len, call:volumes[0].get, method:test_writable_mount_does_not_set_readonly_flag(self, tmp_path) → None, call:ResolvedProfile, call:uuid.uuid4, call:ResolvedMount, call:apply_resolved_profile, call:str, call:len, call:volumes[0].get, class:TestCheckIncludeCycle | dep: uuid, pathlib, pytest, sqlalchemy.ext.asyncio, src.models.config.config_profile, src.services.config.config_profile_resolver, pathlib.Path, sqlalchemy.ext.asyncio.AsyncSession
+- test_docker_build.py | Unit tests for the `build_image` Docker build service function, verifying successful builds, error handling, file writing, and security. | exp: class:TestBuildImage | dep: subprocess, tempfile, pathlib, unittest.mock, pytest, src.services.build.docker_build, pathlib.Path
+- test_docker_service.py | Unit tests for Docker container utilities (ID/name lookup) and volume sorting by mount specificity. | exp: class:TestGetContainerId, class:TestGetContainerName, class:TestSortVolumesBySpecificity, method:test_parent_before_child(self) → None, call:sort_volumes_by_specificity, method:test_stable_sort_for_equal_depth(self) → None, call:sort_volumes_by_specificity, method:test_with_type_suffix(self) → None, call:sort_volumes_by_specificity, method:test_empty_list(self) → None, call:sort_volumes_by_specificity, method:test_single_volume(self) → None, call:sort_volumes_by_specificity, method:test_duplicate_target_warning(self, caplog) → None, call:caplog.at_level, call:sort_volumes_by_specificity | dep: unittest.mock, logging, src.services.docker.container, src.services.docker.compose, subprocess
+- test_event_bus.py | Unit tests for the InstanceEventBus pub/sub system, verifying event delivery, subscriber isolation, unsubscription, and async callback support. | exp: func:event_bus() → InstanceEventBus, call:InstanceEventBus, call:bus._reset_for_testing, func:sample_payload() → InstanceEventPayload, call:str, call:uuid.uuid4, func:test_publish_delivers_to_all_subscribers(event_bus: InstanceEventBus, sample_payload: InstanceEventPayload) → None, call:received.append, call:event_bus.subscribe, call:event_bus.publish, call:len, func:callback_1(payload: InstanceEventPayload) → None, call:received.append, func:callback_2(payload: InstanceEventPayload) → None, call:received.append, func:callback_3(payload: InstanceEventPayload) → None, call:received.append, func:test_subscriber_exception_isolation(event_bus: InstanceEventBus, sample_payload: InstanceEventPayload) → None, call:received.append, call:event_bus.subscribe, call:event_bus.publish, raise:RuntimeError, func:bad_callback(_payload: InstanceEventPayload) → None, raise:RuntimeError, func:good_callback(_payload: InstanceEventPayload) → None, call:received.append, func:test_unsubscribe_removes_callback(event_bus: InstanceEventBus, sample_payload: InstanceEventPayload) → None, call:received.append, call:event_bus.subscribe, call:unsubscribe, call:event_bus.publish, func:callback(_payload: InstanceEventPayload) → None, call:received.append, func:test_publish_to_empty_subscriber_list(event_bus: InstanceEventBus, sample_payload: InstanceEventPayload) → None, call:event_bus.publish, func:test_async_subscriber_supported(event_bus: InstanceEventBus, sample_payload: InstanceEventPayload) → None, call:asyncio.sleep, call:received.append, call:event_bus.subscribe, call:event_bus.publish, func:async_callback(_payload: InstanceEventPayload) → None, call:asyncio.sleep, call:received.append, func:test_unsubscribe_all_clears_subscribers(event_bus: InstanceEventBus, sample_payload: InstanceEventPayload) → None, call:received.append, call:event_bus.subscribe, call:event_bus.unsubscribe_all, call:event_bus.publish, func:callback(_payload: InstanceEventPayload) → None, call:received.append | dep: asyncio, uuid, typing, pytest, src.services.instance.event_bus
+- test_file_service.py | Unit tests for FileService covering directory listing, file reading/writing, binary file rejection, and path traversal prevention. | exp: class:TestFileService, method:test_list_directory_empty(self, temp_workspace: Workspace), call:FileService, call:service.list_directory, method:test_list_directory_with_files(self, temp_workspace: Workspace), call:os.makedirs, call:os.path.join, call:open, call:f.write, call:FileService, call:service.list_directory, call:len, method:test_read_file(self, temp_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:FileService, call:service.read_file, method:test_read_binary_file_rejected(self, temp_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:FileService, call:pytest.raises, call:service.read_file, method:test_write_file(self, temp_workspace: Workspace), call:FileService, call:service.write_file, call:os.path.exists, call:os.path.join, call:open, call:f.read, method:test_path_escapes_workspace(self, temp_workspace: Workspace), call:FileService, call:pytest.raises, call:service.list_directory, func:temp_workspace(), call:tempfile.TemporaryDirectory, call:Workspace | dep: os, tempfile, pytest, src.models, src.services.shared.file_service, src.models.Workspace, src.services.shared.file_service.FileService
+- test_git_operations.py | Unit tests for GitOperations methods including status, commit, history, and branch operations using temporary git repositories. | exp: class:TestGitOperationsStatus, method:test_status_clean(self, temp_workspace: Workspace), call:GitOperations, call:asyncio.run, call:git.status, method:test_status_modified(self, temp_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:GitOperations, call:asyncio.run, call:git.status, method:test_status_untracked(self, temp_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:GitOperations, call:asyncio.run, call:git.status, class:TestGitOperationsCommit, method:test_commit_stages_and_commits(self, temp_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:GitOperations, call:asyncio.run, call:git.commit, call:git.status, call:git.history, method:test_commit_fails_without_changes(self, temp_workspace: Workspace), call:GitOperations, call:pytest.raises, call:asyncio.run, call:git.commit, class:TestGitOperationsHistory, method:test_history_returns_commits(self, temp_workspace: Workspace), call:GitOperations, call:asyncio.run, call:git.history, call:len, method:test_history_filters_by_path(self, temp_workspace: Workspace), call:open, call:os.path.join, call:f.write, call:GitOperations, call:asyncio.run, call:git.commit, call:git.history, call:len, class:TestGitOperationsBranches, method:test_branches_lists_main(self, temp_workspace: Workspace), call:GitOperations, call:asyncio.run, call:git.branches, method:test_checkout_switches_branch(self, temp_workspace: Workspace), call:_run_git, call:GitOperations, call:asyncio.run, call:git.checkout, call:git.status, func:_run_git(*args: str, cwd: str) → None, call:subprocess.run, func:temp_workspace(), call:tempfile.TemporaryDirectory, call:_run_git, call:os.path.join, call:open, call:f.write, call:Workspace | dep: asyncio, os, subprocess, tempfile, pytest, src.models, src.services.git.git_operations, src.models.Workspace, src.services.git.git_operations.GitOperations
+- test_git_service.py | Unit tests for GitService methods including clone, fetch, pull, and branch_exists_remotely operations. | exp: class:TestGitServiceClone, class:TestGitServiceFetch, class:TestGitServicePull, class:TestGitServiceBranchExistsRemotely, method:test_branch_exists(self), call:MagicMock, call:patch, call:GitService.branch_exists_remotely, call:mock_run.assert_called_once_with, method:test_branch_not_exists(self), call:MagicMock, call:patch, call:GitService.branch_exists_remotely, method:test_ls_remote_fails(self), call:MagicMock, call:patch, call:GitService.branch_exists_remotely | dep: asyncio, unittest.mock, pytest, src.services.git.git_service, src.services.git.git_service.GitService
+- test_git_url_parser.py | Tests for git URL parsing utilities including base URL extraction, clone URL validation, and full URL parsing across multiple Git hosting platforms. | exp: class:TestExtractBaseRepoUrl, method:test_github_tree_url(self), call:extract_base_repo_url, method:test_github_blob_url(self), call:extract_base_repo_url, method:test_github_pull_url(self), call:extract_base_repo_url, method:test_github_issues_url(self), call:extract_base_repo_url, method:test_github_valid_url(self), call:extract_base_repo_url, method:test_github_url_with_query_params(self), call:extract_base_repo_url, method:test_gitlab_tree_url(self), call:extract_base_repo_url, method:test_gitlab_blob_url(self), call:extract_base_repo_url, method:test_gitlab_merge_request_url(self), call:extract_base_repo_url, method:test_gitlab_valid_url(self), call:extract_base_repo_url, method:test_bitbucket_src_url(self), call:extract_base_repo_url, method:test_bitbucket_valid_url(self), call:extract_base_repo_url, method:test_ssh_url(self), call:extract_base_repo_url, method:test_ssh_url_without_git_suffix(self), call:extract_base_repo_url, method:test_invalid_url(self), call:extract_base_repo_url, method:test_empty_url(self), call:extract_base_repo_url, class:TestIsValidCloneUrl, method:test_valid_ssh_url(self), call:is_valid_clone_url, method:test_valid_https_url(self), call:is_valid_clone_url, method:test_browser_url(self), call:is_valid_clone_url, method:test_url_without_git_suffix(self), call:is_valid_clone_url, method:test_invalid_url(self), call:is_valid_clone_url, class:TestParseGitUrl, method:test_valid_git_url(self), call:parse_git_url, method:test_browser_url(self), call:parse_git_url, method:test_invalid_url(self), call:parse_git_url, method:test_empty_url(self), call:parse_git_url, method:test_ssh_url(self), call:parse_git_url | dep: src.utils.git_url_parser
+- test_health_monitor.py | Unit tests for HealthMonitor state-transition logic, validating container crash detection, tunnel failure handling, recovery detection, and resilience to Docker exceptions. | exp: func:event_bus() → InstanceEventBus, call:InstanceEventBus, call:bus._reset_for_testing, func:health_monitor(event_bus: InstanceEventBus) → HealthMonitor, call:HealthMonitor, func:_create_running_instance(db_session) → ToolInstance, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, call:ToolInstance, func:test_detects_container_crash(db_session, event_bus: InstanceEventBus, health_monitor: HealthMonitor) → None, call:_create_running_instance, call:events_captured.append, call:event_bus.subscribe, call:patch, call:health_monitor._check_instance, call:db_session.refresh, call:len, call:db_session.execute, call:select(HealthCheck).where, call:result.scalar_one, func:capture_event(payload: InstanceEventPayload) → None, call:events_captured.append, func:test_detects_tunnel_failure(db_session, event_bus: InstanceEventBus, health_monitor: HealthMonitor) → None, call:_create_running_instance, call:events_captured.append, call:event_bus.subscribe, call:patch, call:health_monitor._check_instance, call:db_session.refresh, call:len, call:db_session.execute, call:select(HealthCheck).where, call:result.scalar_one, func:capture_event(payload: InstanceEventPayload) → None, call:events_captured.append, func:test_detects_recovery(db_session, event_bus: InstanceEventBus, health_monitor: HealthMonitor) → None, call:_create_running_instance, call:db_session.commit, call:HealthSnapshot, call:events_captured.append, call:event_bus.subscribe, call:patch, call:health_monitor._check_instance, call:db_session.refresh, call:len, call:db_session.execute, call:select(HealthCheck).where, call:result.scalar_one, func:capture_event(payload: InstanceEventPayload) → None, call:events_captured.append, func:test_skips_writes_when_no_state_change(db_session, event_bus: InstanceEventBus, health_monitor: HealthMonitor) → None, call:_create_running_instance, call:HealthSnapshot, call:patch, call:health_monitor._check_instance, call:db_session.execute, call:select(HealthCheck).where, call:len, call:result.scalars().all, func:test_docker_exception_resilience(db_session, event_bus: InstanceEventBus, health_monitor: HealthMonitor) → None, call:_create_running_instance, call:events_captured.append, call:event_bus.subscribe, call:patch, call:RuntimeError, call:health_monitor._check_instance, call:db_session.execute, call:select(HealthCheck).where, call:result.scalar_one_or_none, func:capture_event(payload: InstanceEventPayload) → None, call:events_captured.append, func:test_monitor_start_stop(health_monitor: HealthMonitor) → None, call:health_monitor.start, call:task.done, call:health_monitor.stop, call:suppress, call:task.cancelled | dep: asyncio, uuid, contextlib, unittest.mock, pytest, sqlalchemy, src.models.system.health_check, src.models.tool.tool_instance, src.models.user.user, src.services.instance.event_bus, src.services.instance.health_monitor
+- test_home_path_expansion.py | Unit tests verifying tilde (~) and $HOME path expansion and home directory resolution from container manifests. | exp: class:TestExpandContainerPath, method:test_tilde_slash_expands(self) → None, call:expand_container_path, method:test_tilde_alone_expands(self) → None, call:expand_container_path, method:test_dollar_home_slash_expands(self) → None, call:expand_container_path, method:test_dollar_home_alone_expands(self) → None, call:expand_container_path, method:test_absolute_path_unchanged(self) → None, call:expand_container_path, method:test_relative_path_unchanged(self) → None, call:expand_container_path, method:test_tilde_in_middle_unchanged(self) → None, call:expand_container_path, method:test_dollar_home_in_middle_unchanged(self) → None, call:expand_container_path, method:test_root_home(self) → None, call:expand_container_path, class:TestGetManifestHomeDir, method:test_with_user_block(self) → None, call:get_manifest_home_dir, method:test_without_user_block(self) → None, call:get_manifest_home_dir, method:test_with_empty_user_name(self) → None, call:get_manifest_home_dir, method:test_with_none_user_name(self) → None, call:get_manifest_home_dir | dep: pytest, src.services.config.config_profile_resolver, src.services.build.manifest_compiler
+- test_instance_service.py | Unit tests for tool instance service functions including compose file modification, repository mount name generation, profile/git mount stacking, and manifest instance preparation. | exp: class:TestModifyComposeFile, method:test_extra_volumes_expand_home_dir(self, tmp_path), call:compose_path.write_text, call:modify_compose_file, call:str, call:compose_path.read_text, method:test_working_directory_expands_home_dir(self, tmp_path), call:compose_path.write_text, call:modify_compose_file, call:str, call:compose_path.read_text, class:TestGetRepositoryMountName, method:test_uses_project_name(self), call:MagicMock, call:_get_repository_mount_name, method:test_slugifies_project_name(self), call:MagicMock, call:_get_repository_mount_name, class:TestStackProfileMountsWithGitMounts, method:test_exact_overlap_merges_profile_files_into_git_source(self, tmp_path) → None, call:git_source.mkdir, call:(git_source / "existing.txt").write_text, call:profile_source.mkdir, call:(profile_source / "settings.json").write_text, call:str, call:_stack_profile_mounts_with_git_mounts, call:(git_source / "existing.txt").read_text, call:(git_source / "settings.json").read_text, method:test_descendant_overlap_copies_into_subdirectory(self, tmp_path) → None, call:git_source.mkdir, call:(git_source / "README").write_text, call:profile_source.mkdir, call:(profile_source / "settings.json").write_text, call:str, call:_stack_profile_mounts_with_git_mounts, call:(git_source / "agent" / "settings.json").read_text, call:(git_source / "README").read_text, method:test_non_overlapping_mounts_left_untouched(self, tmp_path) → None, call:git_source.mkdir, call:profile_source.mkdir, call:(profile_source / "config").write_text, call:str, call:_stack_profile_mounts_with_git_mounts, method:test_git_source_file_does_not_consume_profile_mount(self, tmp_path) → None, call:git_source.write_text, call:profile_source.mkdir, call:(profile_source / "settings.json").write_text, call:str, call:_stack_profile_mounts_with_git_mounts, method:test_profile_source_file_copied_into_git_source(self, tmp_path) → None, call:git_source.mkdir, call:profile_source.write_text, call:str, call:_stack_profile_mounts_with_git_mounts, call:(git_source / "settings.json").read_text, class:Result, func:test_prepare_manifest_instance_uses_workspace_path_basename(), call:MagicMock, call:AsyncMock, call:Result, call:prepare_manifest_instance, func:session_get(model, obj_id), func:fake_run(cmd), call:Result, func:test_create_tool_instance_resolves_project_when_display_name_given(monkeypatch, tmp_path), call:uuid.uuid4, call:MagicMock, call:getattr, call:AsyncMock, call:monkeypatch.setattr, call:str, call:CreateInstanceRequest, call:instance_service.create_tool_instance, func:session_get(model, _obj_id), call:getattr | dep: uuid, unittest.mock, pytest, src.services.tool.instance_service, subprocess, src.services.tool, src.schemas.tool
 - test_lifecycle_hooks.py | Unit tests for lifecycle hook helper functions that derive notification titles and determine whether events should trigger notifications. | exp: class:TestDeriveTitle, method:test_known_event_types(self) → None, call:_derive_title, method:test_unknown_event_type(self) → None, call:_derive_title, class:TestShouldNotify, method:test_error_events_are_notified(self) → None, call:_should_notify, method:test_health_changed_running_is_notified(self) → None, call:_should_notify, method:test_created_started_stopped_restarted_deleted_filtered(self) → None, call:_should_notify, method:test_health_changed_non_running_filtered(self) → None, call:_should_notify | dep: pytest, src.services.instance.lifecycle_hooks
-- test_manifest_compiler.py | Unit tests for a manifest compiler that generates Dockerfiles, docker-compose files, and entrypoint scripts from configuration manifests. | exp: class:TestGetManifestHomeDir, method:test_home_directory_in_manifest_wins(self) → None, call:get_manifest_home_dir, method:test_user_name_derives_home(self) → None, call:get_manifest_home_dir, method:test_root_fallback(self) → None, call:get_manifest_home_dir, method:test_empty_home_directory_falls_back(self) → None, call:get_manifest_home_dir, class:TestCompileDockerfileHomeDirectory, method:test_env_home_and_workdir_use_home_directory(self) → None, call:compile_dockerfile, method:test_workspace_symlink_created(self) → None, call:compile_dockerfile, method:test_runtime_workspace_not_baked_into_image(self) → None, call:compile_dockerfile, method:test_runtime_working_dir_overrides_home_workdir(self) → None, call:compile_dockerfile, method:test_working_dir_expands_tilde(self) → None, call:compile_dockerfile, class:TestCompileComposeHomeDirectory, method:test_default_repo_mount_synthesized(self) → None, call:compile_compose, method:test_explicit_repo_mount_preserved(self) → None, call:compile_compose, method:test_workspace_name_substituted_in_mount_target(self) → None, call:compile_compose, method:test_working_dir_expands_home(self) → None, call:compile_compose, class:TestCompileEntrypoint, method:test_entrypoint_creates_home_and_workspace(self) → None, call:compile_entrypoint, method:test_entrypoint_removes_stale_placeholder_directory(self) → None, call:compile_entrypoint, method:test_entrypoint_uses_root_then_sudo_for_workspace_symlink(self) → None, call:compile_entrypoint, call:entrypoint.find, method:test_entrypoint_fixes_mount_owners(self) → None, call:compile_entrypoint, func:test_compile_dockerfile_creates_config_dirs_for_user() → None, call:compile_dockerfile, func:test_compile_dockerfile_no_user_does_not_create_home() → None, call:compile_dockerfile, func:test_compile_dockerfile_uses_user_npm_prefix() → None, call:compile_dockerfile, func:test_compile_dockerfile_starts_as_root_and_drops_privileges() → None, call:compile_dockerfile, call:compile_entrypoint, func:test_compile_compose_runs_as_root() → None, call:compile_compose | dep: pytest, src.services.build.manifest_compiler
-- test_migration_metadata.py | Validates Alembic database migration files by dynamically loading and verifying expected table names and revision chain metadata | exp: func:test_initial_migration_defines_all_core_tables() → None, call:Path(__file__).resolve, call:spec_from_file_location, call:module_from_spec, call:spec.loader.exec_module, func:test_refresh_tokens_migration_has_expected_revision_chain() → None, call:Path(__file__).resolve, call:spec_from_file_location, call:module_from_spec, call:spec.loader.exec_module | dep: pytest, importlib.util, pathlib
-- test_monitoring_models.py | Unit tests for monitoring models (InstanceEvent and HealthCheck) verifying creation, persistence, and querying capabilities with database migration compatibility. | exp: func:test_instance_event_creation(db_session) → None, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, call:ToolInstance, call:InstanceEvent, call:db_session.refresh, call:isinstance, func:test_health_check_creation(db_session) → None, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, call:ToolInstance, call:HealthCheck, call:db_session.refresh, call:isinstance, func:test_instance_event_query_by_instance(db_session) → None, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, call:ToolInstance, call:InstanceEvent, call:db_session.execute, call:select(InstanceEvent).where, call:result.scalar_one | dep: uuid, datetime, pytest, sqlalchemy, src.models.system.health_check, src.models.system.instance_event, src.models.tool.tool_instance, src.models.user.user
-- test_notification_service.py | Unit tests for NotificationService covering CRUD operations, filtering, pagination, and ownership validation for user notifications. | exp: func:notification_service() → NotificationService, call:NotificationService, func:user_a(db_session: AsyncSession) → User, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, func:user_b(db_session: AsyncSession) → User, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, func:test_create_notification(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:uuid.uuid4, func:test_list_notifications_orders_by_created_at_desc(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:datetime.now, call:timedelta, call:db_session.commit, call:db_session.refresh, call:notification_service.list_notifications, func:test_list_notifications_excludes_dismissed(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:notification_service.dismiss, call:notification_service.list_notifications, func:test_list_notifications_unread_only(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:notification_service.mark_read, call:notification_service.list_notifications, func:test_get_unread_count(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:range, call:notification_service.create_notification, call:notification_service.mark_read, call:notification_service.get_unread_count, func:test_mark_read_sets_read_at(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:notification_service.mark_read, func:test_mark_all_read_affects_all_unread(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:range, call:notification_service.create_notification, call:notification_service.mark_all_read, call:notification_service.get_unread_count, func:test_dismiss_sets_dismissed_at(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:notification_service.dismiss, call:db_session.execute, call:select(Notification).where, call:result.scalar_one, func:test_mark_read_wrong_owner_raises(db_session: AsyncSession, notification_service: NotificationService, user_a: User, user_b: User) → None, call:notification_service.create_notification, call:pytest.raises, call:notification_service.mark_read, func:test_dismiss_wrong_owner_raises(db_session: AsyncSession, notification_service: NotificationService, user_a: User, user_b: User) → None, call:notification_service.create_notification, call:pytest.raises, call:notification_service.dismiss, func:test_list_notifications_mute_categories(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:notification_service.list_notifications, func:test_get_unread_count_excludes_dismissed(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:notification_service.dismiss, call:notification_service.get_unread_count, func:test_dismiss_all_affects_all_non_dismissed(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:range, call:notification_service.create_notification, call:notification_service.dismiss_all, call:notification_service.list_notifications, func:test_dismiss_all_affects_only_caller(db_session: AsyncSession, notification_service: NotificationService, user_a: User, user_b: User) → None, call:range, call:notification_service.create_notification, call:notification_service.dismiss_all, call:notification_service.list_notifications, func:test_mark_all_read_affects_only_caller(db_session: AsyncSession, notification_service: NotificationService, user_a: User, user_b: User) → None, call:range, call:notification_service.create_notification, call:notification_service.mark_all_read, call:notification_service.get_unread_count | dep: uuid, datetime, pytest, sqlalchemy, sqlalchemy.ext.asyncio, src.models.system.notification, src.models.user.user, src.services.shared.notification_service
-- test_notifications_api_routes.py | Tests that FastAPI notification routes are ordered correctly so bulk DELETE /notifications matches before parameterized DELETE /notifications/{id} | exp: func:test_delete_notifications_route_order() → None, call:FastAPI, call:app.include_router, call:TestClient, call:client.delete | dep: fastapi, fastapi.testclient, src.api.system.notifications
-- test_permission_fixer.py | Unit tests for a Docker container permission fixer service that adjusts mount and SSH permissions via container exec commands. | exp: class:TestApplyMountPermissions, class:TestRunInContainer, class:TestApplySshPermissions, class:TestCheckRootUserAvailable | dep: unittest.mock, pytest, src.services.shared.permission_fixer, subprocess
-- test_readiness_probe.py | Unit tests for a Docker container readiness probe service that executes commands with retry logic and timeout handling | exp: class:TestExecuteProbe, class:TestIntegrationScenarios | dep: unittest.mock, src.services.shared.readiness_probe, subprocess
-- test_ssh_keys.py | Unit tests for SSH key preparation functionality including file creation, permissions, ownership, and error handling. | exp: class:TestPrepareSshKeyFiles | dep: os, pathlib, unittest.mock, pytest, src.services.shared.ssh_keys
+- test_manifest_compiler.py | Unit tests for a manifest compiler that generates Dockerfiles, docker-compose files, and entrypoint scripts from manifest configurations. | exp: class:TestGetManifestHomeDir, method:test_home_directory_in_manifest_wins(self) → None, call:get_manifest_home_dir, method:test_user_name_derives_home(self) → None, call:get_manifest_home_dir, method:test_root_fallback(self) → None, call:get_manifest_home_dir, method:test_empty_home_directory_falls_back(self) → None, call:get_manifest_home_dir, class:TestCompileDockerfileHomeDirectory, method:test_env_home_and_workdir_use_project_directory(self) → None, call:compile_dockerfile, method:test_project_directory_created(self) → None, call:compile_dockerfile, method:test_runtime_workspace_not_baked_into_image(self) → None, call:compile_dockerfile, method:test_runtime_working_dir_overrides_home_workdir(self) → None, call:compile_dockerfile, method:test_working_dir_expands_tilde(self) → None, call:compile_dockerfile, class:TestCompileComposeHomeDirectory, method:test_default_repo_mount_synthesized(self) → None, call:compile_compose, method:test_explicit_repo_mount_preserved(self) → None, call:compile_compose, method:test_workspace_name_substituted_in_mount_target(self) → None, call:compile_compose, method:test_working_dir_expands_home(self) → None, call:compile_compose, class:TestCompileEntrypoint, method:test_entrypoint_creates_home_and_project_directory(self) → None, call:compile_entrypoint, method:test_entrypoint_removes_stale_placeholder_directory(self) → None, call:compile_entrypoint, method:test_entrypoint_does_not_create_workspace_symlink(self) → None, call:compile_entrypoint, method:test_entrypoint_fixes_mount_owners(self) → None, call:compile_entrypoint, func:test_compile_dockerfile_creates_config_dirs_for_user() → None, call:compile_dockerfile, func:test_compile_dockerfile_no_user_does_not_create_home() → None, call:compile_dockerfile, func:test_compile_dockerfile_uses_user_npm_prefix() → None, call:compile_dockerfile, func:test_compile_dockerfile_starts_as_root_and_drops_privileges() → None, call:compile_dockerfile, call:compile_entrypoint, func:test_compile_compose_does_not_pin_root_user() → None, call:compile_compose, func:test_get_manifest_container_user_returns_name() → None, call:get_manifest_container_user, func:test_get_manifest_container_user_falls_back_to_uid_gid() → None, call:get_manifest_container_user, func:test_get_manifest_container_user_returns_none_without_user() → None, call:get_manifest_container_user | dep: pytest, src.services.build.manifest_compiler
+- test_migration_metadata.py | Unit tests that dynamically load and validate Alembic migration files for correct table definitions and revision chains. | exp: func:test_initial_migration_defines_all_core_tables() → None, call:Path(__file__).resolve, call:spec_from_file_location, call:module_from_spec, call:spec.loader.exec_module, func:test_refresh_tokens_migration_has_expected_revision_chain() → None, call:Path(__file__).resolve, call:spec_from_file_location, call:module_from_spec, call:spec.loader.exec_module | dep: pytest, importlib.util, pathlib
+- test_monitoring_models.py | Tests creation, persistence, and querying of monitoring models (InstanceEvent and HealthCheck) with related User and ToolInstance fixtures. | exp: func:test_instance_event_creation(db_session) → None, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, call:ToolInstance, call:InstanceEvent, call:db_session.refresh, call:isinstance, func:test_health_check_creation(db_session) → None, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, call:ToolInstance, call:HealthCheck, call:db_session.refresh, call:isinstance, func:test_instance_event_query_by_instance(db_session) → None, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, call:ToolInstance, call:InstanceEvent, call:db_session.execute, call:select(InstanceEvent).where, call:result.scalar_one | dep: uuid, datetime, pytest, sqlalchemy, src.models.system.health_check, src.models.system.instance_event, src.models.tool.tool_instance, src.models.user.user
+- test_notification_service.py | Unit tests for NotificationService covering creation, listing, filtering, reading, dismissing, and ownership validation of user notifications. | exp: func:notification_service() → NotificationService, call:NotificationService, func:user_a(db_session: AsyncSession) → User, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, func:user_b(db_session: AsyncSession) → User, call:User, call:uuid.uuid4, call:db_session.add, call:db_session.commit, func:test_create_notification(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:uuid.uuid4, func:test_list_notifications_orders_by_created_at_desc(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:datetime.now, call:timedelta, call:db_session.commit, call:db_session.refresh, call:notification_service.list_notifications, func:test_list_notifications_excludes_dismissed(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:notification_service.dismiss, call:notification_service.list_notifications, func:test_list_notifications_unread_only(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:notification_service.mark_read, call:notification_service.list_notifications, func:test_get_unread_count(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:range, call:notification_service.create_notification, call:notification_service.mark_read, call:notification_service.get_unread_count, func:test_mark_read_sets_read_at(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:notification_service.mark_read, func:test_mark_all_read_affects_all_unread(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:range, call:notification_service.create_notification, call:notification_service.mark_all_read, call:notification_service.get_unread_count, func:test_dismiss_sets_dismissed_at(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:notification_service.dismiss, call:db_session.execute, call:select(Notification).where, call:result.scalar_one, func:test_mark_read_wrong_owner_raises(db_session: AsyncSession, notification_service: NotificationService, user_a: User, user_b: User) → None, call:notification_service.create_notification, call:pytest.raises, call:notification_service.mark_read, func:test_dismiss_wrong_owner_raises(db_session: AsyncSession, notification_service: NotificationService, user_a: User, user_b: User) → None, call:notification_service.create_notification, call:pytest.raises, call:notification_service.dismiss, func:test_list_notifications_mute_categories(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:notification_service.list_notifications, func:test_get_unread_count_excludes_dismissed(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:notification_service.create_notification, call:notification_service.dismiss, call:notification_service.get_unread_count, func:test_dismiss_all_affects_all_non_dismissed(db_session: AsyncSession, notification_service: NotificationService, user_a: User) → None, call:range, call:notification_service.create_notification, call:notification_service.dismiss_all, call:notification_service.list_notifications, func:test_dismiss_all_affects_only_caller(db_session: AsyncSession, notification_service: NotificationService, user_a: User, user_b: User) → None, call:range, call:notification_service.create_notification, call:notification_service.dismiss_all, call:notification_service.list_notifications, func:test_mark_all_read_affects_only_caller(db_session: AsyncSession, notification_service: NotificationService, user_a: User, user_b: User) → None, call:range, call:notification_service.create_notification, call:notification_service.mark_all_read, call:notification_service.get_unread_count | dep: uuid, datetime, pytest, sqlalchemy, sqlalchemy.ext.asyncio, src.models.system.notification, src.models.user.user, src.services.shared.notification_service
+- test_notifications_api_routes.py | Tests that the FastAPI route ordering for notifications is correct so the bulk DELETE endpoint doesn't get intercepted by the single-item path parameter route. | exp: func:test_delete_notifications_route_order() → None, call:FastAPI, call:app.include_router, call:TestClient, call:client.delete | dep: fastapi, fastapi.testclient, src.api.system.notifications, FastAPI, TestClient
+- test_permission_fixer.py | Unit tests for the permission fixer module that validates Docker container permission management (chown/chmod operations on mounts and SSH directories). | exp: class:TestApplyMountPermissions, class:TestRunInContainer, class:TestApplySshPermissions, class:TestCheckRootUserAvailable | dep: unittest.mock, pytest, src.services.shared.permission_fixer, subprocess
+- test_readiness_probe.py | Unit tests for the readiness probe service that validates container health checks via Docker exec commands with retry logic. | exp: class:TestExecuteProbe, class:TestIntegrationScenarios | dep: unittest.mock, src.services.shared.readiness_probe
+- test_ssh_keys.py | Unit tests for the `prepare_ssh_key_files` function, verifying file creation, permissions, ownership setting, and error handling. | exp: class:TestPrepareSshKeyFiles | dep: os, pathlib, unittest.mock, pytest, src.services.shared.ssh_keys, pathlib.Path
+- test_terminal_container_user.py | Unit tests for resolving container user from tool type definitions, handling legacy tools, manifest-based tools, base definition inheritance, and missing definitions. | exp: func:test_resolve_container_user_legacy_tool_type(), call:MagicMock, call:AsyncMock, call:_resolve_container_user, call:session.get.assert_awaited_once, func:test_resolve_container_user_manifest_no_manifest_id(), call:MagicMock, call:AsyncMock, call:_resolve_container_user, func:test_resolve_container_user_manifest_with_user(), call:MagicMock, call:AsyncMock, call:_resolve_container_user, func:session_get(model, obj_id), func:test_resolve_container_user_manifest_with_base_definition(), call:MagicMock, call:AsyncMock, call:_resolve_container_user, func:session_get(model, obj_id), func:test_resolve_container_user_missing_manifest_definition(), call:MagicMock, call:AsyncMock, call:_resolve_container_user, func:session_get(model, obj_id) | dep: unittest.mock, pytest, src.api.system.terminal, src.api.system.terminal._resolve_container_user
+- test_terminal_session.py | Unit tests verifying TerminalSession passes container_user to docker exec --user flag when set, and omits it when not configured. | exp: func:test_start_passes_container_user_to_docker_exec() → None, call:TerminalSession, call:str, call:uuid.uuid4, call:patch, call:AsyncMock, call:session.start, call:args.index, func:test_start_omits_user_when_not_configured() → None, call:TerminalSession, call:str, call:uuid.uuid4, call:patch, call:AsyncMock, call:session.start | dep: uuid, unittest.mock, pytest, src.services.terminal.terminal_session
 ## arch
-Standard Python unittest/pytest pattern with isolated test modules per service, heavy use of mocking for external dependencies (Docker, Git, subprocess), and tests covering security constraints, error handling, and state transitions across asynchronous and synchronous operations.
+Standard Python unittest/pytest package structure with test files mirroring the source codebase; uses dependency injection, mocking (likely unittest.mock or pytest-mock), and temporary filesystem/git fixtures to test components in isolation.
 ## tags
-test, url, call:, git, call:notification, home, mounts, mount
+test, url, call:, git, user, call:notification, container, mounts
 ## symbols
 - TestMergeFunctions
 - TestResolveProfile
@@ -47,5 +49,7 @@ test, url, call:, git, call:notification, home, mounts, mount
   read: __init__.py, test_alembic_migrations.py, test_config.py
 - change unit config
   read: test_config.py, test_config_profile_resolver.py
+- explore unit subdirectories
+  index: apps/api/tests/unit/.ruff_cache/.pi-map.index.md
 ## dirty
 -

apps/api/tests/unit/test_alembic_migrations.py

@@ -67,3 +67,23 @@ def test_remove_pi_agent_repo_mount_migration_imports() -> None:
     assert module.down_revision == "2026_06_14_182955"
     assert callable(module.upgrade)
     assert callable(module.downgrade)
+
+
+@pytest.mark.unit
+def test_remove_pi_agent_workspace_symlink_migration_imports() -> None:
+    migration_path = Path(__file__).parent.parent.parent / (
+        "alembic/versions/2026_06_19_113000_remove_pi_agent_workspace_symlink.py"
+    )
+    assert migration_path.exists()
+
+    spec = importlib.util.spec_from_file_location(
+        "remove_workspace_symlink_migration", migration_path
+    )
+    assert spec is not None and spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+
+    assert module.revision == "2026_06_19_113000"
+    assert module.down_revision == "2026_06_15_090500"
+    assert callable(module.upgrade)
+    assert callable(module.downgrade)

apps/api/tests/unit/test_builtin_tool_users.py

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

apps/api/tests/unit/test_config_profile_refresh.py

@@ -0,0 +1,23 @@
+"""Tests for Config Profile refresh safety contracts."""
+
+import uuid
+from unittest.mock import AsyncMock
+
+import pytest
+from fastapi import HTTPException
+
+from src.api.config.config_profiles import refresh_profile_git_mounts
+
+
+@pytest.mark.unit
+async def test_git_refresh_requires_destructive_confirmation() -> None:
+    """The endpoint must not reset a writable working copy without consent."""
+    with pytest.raises(HTTPException) as exc_info:
+        await refresh_profile_git_mounts(
+            profile_id=str(uuid.uuid4()),
+            confirm_destructive_refresh=False,
+            current_user_id=uuid.uuid4(),
+            session=AsyncMock(),
+        )
+
+    assert exc_info.value.status_code == 409

apps/api/tests/unit/test_config_profile_resolver.py

@@ -36,7 +36,7 @@ class TestMergeFunctions:
 
     def test_merge_env_vars_tracks_overrides(self) -> None:
         """Test that env var overrides are tracked."""
-        overrides = {}
+        overrides: dict[str, str] = {}
         _merge_env_vars(
             {"A": "1"},
             {"A": "2"},
@@ -93,7 +93,7 @@ class TestMergeFunctions:
         """Test that mount mode conflicts are resolved (later wins)."""
         from src.services.config.config_profile_resolver import ResolvedMount
 
-        overrides = {}
+        overrides: dict[str, str] = {}
         result = _merge_mounts(
             {"/app": ResolvedMount(target="/app", mode="rw", files={})},
             [{"target": "/app", "mode": "ro", "files": {}}],
@@ -532,6 +532,107 @@ class TestApplyResolvedProfile:
         assert Path(volumes[0]["source"]).name == "workspace_x_y"
         assert (Path(volumes[0]["source"]) / "z.json").exists()
 
+    def test_top_level_files_use_profile_scoped_direct_bind_mounts(self, tmp_path) -> None:
+        """Top-level files are shared safely without mounting over a workspace."""
+        profile_id = uuid.uuid4()
+        resolved = ResolvedProfile(
+            profile_id=profile_id,
+            profile_name="test",
+            files={".tool/config.toml": "setting = true"},
+        )
+
+        instance_root = tmp_path / "instances"
+        _, files, volumes, _ = apply_resolved_profile(
+            str(instance_root / "instance-a"),
+            resolved,
+            working_dir="/workspace/project",
+        )
+
+        canonical_file = (
+            instance_root / "config-profiles" / str(profile_id) / "files" / ".tool" / "config.toml"
+        )
+        assert files == {}
+        assert volumes == [
+            {
+                "source": str(canonical_file),
+                "target": "/workspace/project/.tool/config.toml",
+                "type": "bind",
+                "readonly": False,
+            }
+        ]
+        assert canonical_file.read_text() == "setting = true"
+
+    def test_top_level_file_update_preserves_bind_mount_inode(self, tmp_path) -> None:
+        """An individually bind-mounted file must update in place."""
+        profile_id = uuid.uuid4()
+        instance_root = tmp_path / "instances"
+        resolved = ResolvedProfile(
+            profile_id=profile_id,
+            profile_name="test",
+            files={"settings.toml": "value = 1"},
+        )
+
+        apply_resolved_profile(str(instance_root / "instance-a"), resolved)
+        canonical_file = (
+            instance_root / "config-profiles" / str(profile_id) / "files" / "settings.toml"
+        )
+        original_inode = canonical_file.stat().st_ino
+
+        resolved.files["settings.toml"] = "value = 2"
+        apply_resolved_profile(str(instance_root / "instance-a"), resolved)
+
+        assert canonical_file.stat().st_ino == original_inode
+        assert canonical_file.read_text() == "value = 2"
+
+    def test_mounted_file_update_preserves_bind_mount_inode(self, tmp_path) -> None:
+        """A file inside a profile directory mount must update in place."""
+        profile_id = uuid.uuid4()
+        instance_root = tmp_path / "instances"
+        resolved = ResolvedProfile(
+            profile_id=profile_id,
+            profile_name="test",
+            mounts={
+                "/etc/tool": ResolvedMount(
+                    target="/etc/tool", mode="rw", files={"settings.toml": "value = 1"}
+                )
+            },
+        )
+
+        apply_resolved_profile(str(instance_root / "instance-a"), resolved)
+        canonical_file = (
+            instance_root
+            / "config-profiles"
+            / str(profile_id)
+            / "mounts"
+            / "etc_tool"
+            / "settings.toml"
+        )
+        original_inode = canonical_file.stat().st_ino
+
+        resolved.mounts["/etc/tool"].files["settings.toml"] = "value = 2"
+        apply_resolved_profile(str(instance_root / "instance-a"), resolved)
+
+        assert canonical_file.stat().st_ino == original_inode
+        assert canonical_file.read_text() == "value = 2"
+
+    def test_instances_share_profile_scoped_mount_sources(self, tmp_path) -> None:
+        """Different instance paths resolve a profile to one canonical source."""
+        profile_id = uuid.uuid4()
+        resolved = ResolvedProfile(
+            profile_id=profile_id,
+            profile_name="test",
+            mounts={"/app": ResolvedMount(target="/app", mode="rw", files={"config.ini": "x"})},
+        )
+
+        instance_root = tmp_path / "instances"
+        _, _, first_volumes, _ = apply_resolved_profile(str(instance_root / "instance-a"), resolved)
+        _, _, second_volumes, _ = apply_resolved_profile(str(instance_root / "instance-b"), resolved)
+
+        assert first_volumes[0]["source"] == second_volumes[0]["source"]
+        assert first_volumes[0]["source"] == str(
+            instance_root / "config-profiles" / str(profile_id) / "mounts" / "app"
+        )
+
     def test_empty_mount_produces_no_volumes(self, tmp_path) -> None:
         """A mount with no files should not produce any volume entries."""
         resolved = ResolvedProfile(
@@ -579,7 +680,7 @@ class TestApplyResolvedProfile:
 
         assert len(volumes) == 1
         assert volumes[0]["target"] == "/etc/app"
-        assert volumes[0].get("readonly") is True
+        assert volumes[0].get("readonly")
 
     def test_writable_mount_does_not_set_readonly_flag(self, tmp_path) -> None:
         """A mount with mode 'rw' should not set readonly on the volume entry."""
@@ -598,7 +699,7 @@ class TestApplyResolvedProfile:
 
         assert len(volumes) == 1
         assert volumes[0]["target"] == "/app"
-        assert volumes[0].get("readonly") is False
+        assert not volumes[0].get("readonly")
 
 
 class TestCheckIncludeCycle:

apps/api/tests/unit/test_instance_service.py

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

apps/api/tests/unit/test_manifest_compiler.py

@@ -6,6 +6,7 @@ from src.services.build.manifest_compiler import (
     compile_compose,
     compile_dockerfile,
     compile_entrypoint,
+    get_manifest_container_user,
     get_manifest_home_dir,
 )
 
@@ -273,13 +274,19 @@ def test_compile_dockerfile_starts_as_root_and_drops_privileges() -> None:
     entrypoint = compile_entrypoint(manifest)
 
     assert "USER dev" not in dockerfile
-    assert 'exec runuser -u dev -- /bin/bash -il' in entrypoint
+    assert "exec runuser -u dev -- /bin/bash -il" in entrypoint
     assert 'exec runuser -u dev -- "$@"' in entrypoint
 
 
 @pytest.mark.unit
-def test_compile_compose_runs_as_root() -> None:
-    """The compose service must start as root so the entrypoint can fix ownership."""
+def test_compile_compose_does_not_pin_root_user() -> None:
+    """The compose service must not override the user to root.
+
+    The Dockerfile intentionally omits USER so the entrypoint starts as root,
+    fixes mount ownership, and drops privileges internally. Setting a
+    compose-level user would pin docker exec sessions to root even after the
+    entrypoint drops privileges.
+    """
     manifest = {
         "base_image": "ubuntu:24.04",
         "interface_type": "terminal",
@@ -296,7 +303,32 @@ def test_compile_compose_runs_as_root() -> None:
     }
     compose = compile_compose(manifest, variables)
 
-    assert "user: 0:0" in compose
+    assert "user:" not in compose
+
+
+@pytest.mark.unit
+def test_get_manifest_container_user_returns_name() -> None:
+    """The container user helper returns the manifest user name."""
+    manifest = {
+        "user": {"name": "dev", "uid": 1000, "gid": 1000},
+    }
+    assert get_manifest_container_user(manifest) == "dev"
+
+
+@pytest.mark.unit
+def test_get_manifest_container_user_falls_back_to_uid_gid() -> None:
+    """When the user name is missing, return uid:gid."""
+    manifest = {
+        "user": {"uid": 1000, "gid": 1000},
+    }
+    assert get_manifest_container_user(manifest) == "1000:1000"
+
+
+@pytest.mark.unit
+def test_get_manifest_container_user_returns_none_without_user() -> None:
+    """When no user is declared, return None."""
+    manifest = {"base_image": "ubuntu:24.04"}
+    assert get_manifest_container_user(manifest) is None
 
 
 @pytest.mark.unit
@@ -314,7 +346,7 @@ class TestCompileEntrypoint:
 
         assert 'mkdir -p "$HOME_DIR"' in entrypoint
         assert 'mkdir -p "$WORKSPACE_TARGET"' in entrypoint
-        assert 'ln -sfn' not in entrypoint
+        assert "ln -sfn" not in entrypoint
         assert 'WORKSPACE_NAME="${WORKSPACE_NAME:-workspace}"' in entrypoint
 
     def test_entrypoint_removes_stale_placeholder_directory(self) -> None:

apps/api/tests/unit/test_terminal_container_user.py

@@ -0,0 +1,143 @@
+"""Unit tests for terminal container-user resolution."""
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from src.api.system.terminal import _resolve_container_user
+
+
+@pytest.mark.unit
+async def test_resolve_container_user_legacy_tool_type():
+    """Legacy tools have no manifest user."""
+    tool_type = MagicMock()
+    tool_type.definition_type = "legacy"
+    tool_type.manifest_id = None
+
+    instance = MagicMock()
+    instance.tool_type_id = "tool-type-uuid"
+
+    session = AsyncMock()
+    session.get = AsyncMock(return_value=tool_type)
+
+    result = await _resolve_container_user(session, instance)
+
+    assert result is None
+    session.get.assert_awaited_once()
+
+
+@pytest.mark.unit
+async def test_resolve_container_user_manifest_no_manifest_id():
+    """Manifest-based tools without a manifest_id return None."""
+    tool_type = MagicMock()
+    tool_type.definition_type = "manifest"
+    tool_type.manifest_id = None
+
+    instance = MagicMock()
+    instance.tool_type_id = "tool-type-uuid"
+
+    session = AsyncMock()
+    session.get = AsyncMock(return_value=tool_type)
+
+    result = await _resolve_container_user(session, instance)
+
+    assert result is None
+
+
+@pytest.mark.unit
+async def test_resolve_container_user_manifest_with_user():
+    """Manifest-based tools resolve the declared container user."""
+    manifest_id = "manifest-uuid"
+
+    tool_type = MagicMock()
+    tool_type.definition_type = "manifest"
+    tool_type.manifest_id = manifest_id
+
+    manifest_def = MagicMock()
+    manifest_def.manifest = {"user": {"name": "dev", "uid": 1000, "gid": 1000}}
+    manifest_def.base_definition_id = None
+
+    instance = MagicMock()
+    instance.tool_type_id = "tool-type-uuid"
+
+    session = AsyncMock()
+
+    async def session_get(model, obj_id):
+        if obj_id == "tool-type-uuid":
+            return tool_type
+        if obj_id == manifest_id:
+            return manifest_def
+        return None
+
+    session.get.side_effect = session_get
+
+    result = await _resolve_container_user(session, instance)
+
+    assert result == "dev"
+
+
+@pytest.mark.unit
+async def test_resolve_container_user_manifest_with_base_definition():
+    """Base-definition users are inherited and overridden by tool manifests."""
+    base_id = "base-uuid"
+    manifest_id = "manifest-uuid"
+
+    tool_type = MagicMock()
+    tool_type.definition_type = "manifest"
+    tool_type.manifest_id = manifest_id
+
+    manifest_def = MagicMock()
+    manifest_def.manifest = {"user": {"name": "override", "uid": 1001, "gid": 1001}}
+    manifest_def.base_definition_id = base_id
+
+    base_def = MagicMock()
+    base_def.manifest = {
+        "base_image": "ubuntu:24.04",
+        "user": {"name": "base", "uid": 1000, "gid": 1000},
+    }
+
+    instance = MagicMock()
+    instance.tool_type_id = "tool-type-uuid"
+
+    session = AsyncMock()
+
+    async def session_get(model, obj_id):
+        if obj_id == "tool-type-uuid":
+            return tool_type
+        if obj_id == manifest_id:
+            return manifest_def
+        if obj_id == base_id:
+            return base_def
+        return None
+
+    session.get.side_effect = session_get
+
+    result = await _resolve_container_user(session, instance)
+
+    assert result == "override"
+
+
+@pytest.mark.unit
+async def test_resolve_container_user_missing_manifest_definition():
+    """A manifest_id pointing to a missing definition returns None."""
+    manifest_id = "manifest-uuid"
+
+    tool_type = MagicMock()
+    tool_type.definition_type = "manifest"
+    tool_type.manifest_id = manifest_id
+
+    instance = MagicMock()
+    instance.tool_type_id = "tool-type-uuid"
+
+    session = AsyncMock()
+
+    async def session_get(model, obj_id):
+        if obj_id == "tool-type-uuid":
+            return tool_type
+        return None
+
+    session.get.side_effect = session_get
+
+    result = await _resolve_container_user(session, instance)
+
+    assert result is None

apps/api/tests/unit/test_terminal_session.py

@@ -0,0 +1,97 @@
+"""Unit tests for TerminalSession PTY handling."""
+
+import uuid
+from unittest.mock import AsyncMock, patch
+
+import pytest  # pyright: ignore[reportMissingImports]
+
+from src.services.terminal.terminal_session import TerminalSession
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_start_passes_container_user_to_docker_exec() -> None:
+    """When container_user is set, docker exec receives --user <user>."""
+    session = TerminalSession(
+        session_id=str(uuid.uuid4()),
+        instance_id=uuid.uuid4(),
+        container_id="container-123",
+        container_user="dev",
+    )
+
+    with (
+        patch(
+            "src.services.terminal.terminal_session.pty.openpty",
+            return_value=(1, 2),
+        ),
+        patch("src.services.terminal.terminal_session.os.set_blocking") as set_blocking,
+        patch("src.services.terminal.terminal_session.tty.setraw"),
+        patch(
+            "src.services.terminal.terminal_session.asyncio.create_subprocess_exec",
+            new=AsyncMock(),
+        ) as mock_exec,
+        patch("src.services.terminal.terminal_session.os.close"),
+    ):
+        await session.start()
+
+    args, _kwargs = mock_exec.call_args
+    assert "docker" in args
+    assert "exec" in args
+    assert "--user" in args
+    user_index = args.index("--user")
+    assert args[user_index + 1] == "dev"
+    assert "container-123" in args
+    set_blocking.assert_called_once_with(1, False)
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_start_omits_user_when_not_configured() -> None:
+    """Without container_user, docker exec does not receive --user."""
+    session = TerminalSession(
+        session_id=str(uuid.uuid4()),
+        instance_id=uuid.uuid4(),
+        container_id="container-123",
+    )
+
+    with (
+        patch(
+            "src.services.terminal.terminal_session.pty.openpty",
+            return_value=(1, 2),
+        ),
+        patch("src.services.terminal.terminal_session.os.set_blocking"),
+        patch("src.services.terminal.terminal_session.tty.setraw"),
+        patch(
+            "src.services.terminal.terminal_session.asyncio.create_subprocess_exec",
+            new=AsyncMock(),
+        ) as mock_exec,
+        patch("src.services.terminal.terminal_session.os.close"),
+    ):
+        await session.start()
+
+    args, _kwargs = mock_exec.call_args
+    assert "--user" not in args
+
+
+@pytest.mark.unit
+@pytest.mark.asyncio
+async def test_write_input_retries_partial_pty_writes() -> None:
+    """A large paste is fully written even when the PTY accepts it in chunks."""
+    session = TerminalSession(
+        session_id=str(uuid.uuid4()),
+        instance_id=uuid.uuid4(),
+        container_id="container-123",
+    )
+    session._master_fd = 42
+
+    with patch(
+        "src.services.terminal.terminal_session.os.write",
+        side_effect=[2, 2, 1],
+    ) as write:
+        await session.write_input(b"hello")
+
+    assert [bytes(call.args[1]) for call in write.call_args_list] == [
+        b"hello",
+        b"llo",
+        b"o",
+    ]

apps/web/.pi-map.index.md

@@ -2,7 +2,7 @@
 dir: apps/web
 
 ## role
-Frontend web application serving as the main user interface for the "Headquarter" project, built with React and Vite.
+Frontend web application for a terminal/code-editor interface named "Headquarter," built with React/TypeScript using Vite and served as a static single-page app.
 ## parent
 index: apps/.pi-map.index.md
 map: apps/.pi-map.md

apps/web/.pi-map.md

@@ -4,21 +4,21 @@ dir: apps/web
 index: apps/web/.pi-map.index.md
 
 ## role
-Frontend web application serving as the main user interface for the "Headquarter" project, built with React and Vite.
+Frontend web application for a terminal/code-editor interface named "Headquarter," built with React/TypeScript using Vite and served as a static single-page app.
 ## files
-- .env.example | Template file showing required environment variables for a Vite-based frontend application | dep: Vite
+- .env.example | Template/example file defining environment variables for a Vite-based application's API and OAuth configuration | dep: Vite
 - .eslintrc.cjs | Configures ESLint for a TypeScript browser project with modern ES2022 module support | dep: eslint, @typescript-eslint/parser, @typescript-eslint/eslint-plugin
-- Dockerfile | Multi-stage Docker build for a Vite/Node.js frontend application, compiling static assets and serving them via nginx as a non-root user | dep: node:20-alpine, nginx:alpine, npm, wget
-- index.html | Serves as the entry point HTML file for a React application named "Headquarter" that loads a TypeScript module and uses Google Fonts. | dep: Google Fonts (Inter, IBM Plex Mono), React (implied by root div and main.tsx)
+- Dockerfile | Multi-stage Docker build for a Node.js/Vite frontend application compiled to static assets and served by nginx as a non-root user | dep: node:20-alpine, nginx:alpine, npm, wget
+- index.html | Entry point HTML file for a React application named "Headquarter" that loads a TypeScript module and Google Fonts | dep: Google Fonts (Inter, IBM Plex Mono), main.tsx module
 - nginx.conf | Configures Nginx as a web server for a single-page application with gzip compression, client-side routing support, cache control for static assets, and a health check endpoint. | dep: nginx
-- package-lock.json | Auto-generated dependency lock file that records exact versions and resolved URLs of all npm packages for reproducible installs in the "headquarter-web" React web application. | dep: npm, Node.js, React, Vite, TailwindCSS, xterm, PrismJS, axios, react-router-dom, TypeScript, ESLint, Vitest, @testing-library/react, @phosphor-icons/react, react-simple-code-editor, jsdom, postcss, autoprefixer
-- package.json | Defines a React-based web application project named "headquarter-web" with configuration for building, development, testing, and linting using Vite and TypeScript. | dep: react, react-dom, react-router-dom, axios, tailwindcss, prismjs, xterm, @phosphor-icons/react, react-simple-code-editor, vite, typescript, vitest, eslint, @testing-library/react
-- tsconfig.json | Configures TypeScript compiler settings for a modern React project using Vite with ES modules | dep: TypeScript, Vite, React, DOM
-- vite.config.ts | Configures Vite build tool for a React project with custom dev server port and testing setup | dep: vite, @vitejs/plugin-react
+- package-lock.json | Records exact dependency versions for a React-based web application to ensure reproducible installs | dep: npm, React, React Router, Tailwind CSS, Vite, Vitest, TypeScript, ESLint, xterm, PrismJS, axios, phosphor-icons
+- package.json | Defines a React-based web application project named "headquarter-web" with build tooling, testing, and UI dependencies for a terminal/code editor interface. | dep: react, react-dom, react-router-dom, vite, typescript, tailwindcss, axios, prismjs, xterm, @phosphor-icons/react, react-simple-code-editor, vitest, eslint
+- tsconfig.json | Configures TypeScript compiler options for a modern React/Vite project with ES2020 target and strict type checking | dep: TypeScript, React, Vite
+- vite.config.ts | Configures Vite build tool with React support, dev server port, and Vitest testing settings | dep: vite, @vitejs/plugin-react
 ## arch
-Modern SPA architecture using React with TypeScript, Vite for build tooling, Docker multi-stage builds with nginx static serving, and environment-based configuration.
+Containerized single-page React/TypeScript app using Vite for build/dev, Vitest for testing, ESLint for linting, and nginx for static asset delivery with client-side routing support.
 ## tags
-react, vite, eslint, typescript, application, nginx, web, configures
+react, vite, eslint, application, typescript, nginx, configures, web
 ## symbols
 -
 ## workflows

apps/web/index.html

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

apps/web/public/favicon.svg

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

apps/web/src/.pi-map.index.md

@@ -2,7 +2,7 @@
 dir: apps/web/src
 
 ## role
-Frontend web application entry point and routing layer for a React-based collaborative development platform.
+Frontend web client that bootstraps and renders a React single-page application with routing, authentication, and session-driven UI.
 ## parent
 index: apps/web/.pi-map.index.md
 map: apps/web/.pi-map.md

apps/web/src/.pi-map.md

@@ -4,15 +4,15 @@ dir: apps/web/src
 index: apps/web/src/.pi-map.index.md
 
 ## role
-Frontend web application entry point and routing layer for a React-based collaborative development platform.
+Frontend web client that bootstraps and renders a React single-page application with routing, authentication, and session-driven UI.
 ## files
-- main.tsx | Entry point that bootstraps a React application with routing, authentication, and session management providers. | dep: react, react-dom/client, react-router-dom, ./router, ./state/auth, ./state/sessions, ./styles/tokens.css, ./styles/global.css, ./styles/utilities.css, ./styles/syntax-highlight.css, ./styles/pages/git-history.css, ./styles/pages/projects.css, ./styles/pages/sessions.css, ./styles/pages/ssh-keys.css, ./styles/pages/workspace-detail.css, ./styles/pages/workspaces.css, react-dom
-- router.tsx | Defines the client-side routing configuration for a React application using nested routes with authentication protection and redirects. | exp: AppRouter | dep: react-router-dom, ./components/app-shell, ./components/protected-route, ./pages/DashboardPage, ./pages/PlaceholderPage, ./pages/ProfilePage, ./pages/ProjectsPage, ./pages/GitRepositoriesPage, ./pages/GitHistoryPage, ./pages/ProjectSettingsPage, ./pages/SettingsPage, ./pages/TerminalPage, ./pages/ToolWorkshopPage, ./pages/SshKeysPage, ./pages/ConfigProfilesPage, ./pages/SessionsPage, ./pages/WorkspacesPage, ./pages/WorkspaceDetailPage
-- types.ts | Defines TypeScript type declarations for session users, projects, workspaces, and repositories in an application. | exp: SessionUser, SessionPayload, Project, WorkspaceSummary, RepositorySummary, ProjectWithRepos
+- main.tsx | Entry point that bootstraps a React SPA with routing, authentication, and session state management | dep: react, react-dom/client, react-router-dom, ./router, ./state/auth, ./state/sessions, ./styles/tokens.css, ./styles/global.css, ./styles/utilities.css, ./styles/syntax-highlight.css, ./styles/pages/git-history.css, ./styles/pages/projects.css, ./styles/pages/sessions.css, ./styles/pages/ssh-keys.css, ./styles/pages/workspace-detail.css, ./styles/pages/workspaces.css, react-dom
+- router.tsx | Defines the React Router configuration for a multi-page application with nested routes, protected authentication, and redirects. | exp: AppRouter | dep: react-router-dom, ./components/app-shell, ./components/protected-route, ./pages/DashboardPage, ./pages/PlaceholderPage, ./pages/ProfilePage, ./pages/ProjectsPage, ./pages/GitRepositoriesPage, ./pages/GitHistoryPage, ./pages/ProjectSettingsPage, ./pages/SettingsPage, ./pages/TerminalPage, ./pages/ToolWorkshopPage, ./pages/SshKeysPage, ./pages/ConfigProfilesPage, ./pages/SessionsPage, ./pages/WorkspacesPage, ./pages/WorkspaceDetailPage
+- types.ts | Defines TypeScript type declarations for user sessions, projects, repositories, and workspaces in an application. | exp: SessionUser, SessionPayload, Project, WorkspaceSummary, RepositorySummary, ProjectWithRepos
 ## arch
-Modular React SPA with provider-based dependency injection, nested route guards for authentication/authorization, and centralized TypeScript type definitions.
+React SPA built with a declarative React Router configuration, protected/nested routes, and centralized TypeScript types for users, sessions, projects, repositories, and workspaces.
 ## tags
-pages, styles, css, react, router, session, dom, project
+pages, styles, css, router, react, session, dom, project
 ## symbols
 - AppRouter
 - SessionUser

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

@@ -0,0 +1,31 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mockPost = vi.fn();
+
+vi.mock("./client", () => ({
+	apiClient: {
+		post: (...args: unknown[]) => mockPost(...args),
+	},
+}));
+
+import { refreshConfigProfileGitMounts } from "./config-profiles";
+
+describe("refreshConfigProfileGitMounts", () => {
+	beforeEach(() => {
+		mockPost.mockReset();
+	});
+
+	it("confirms the destructive refresh at the API boundary", async () => {
+		mockPost.mockResolvedValue({ data: { refresh_outcomes: [] } });
+
+		await expect(refreshConfigProfileGitMounts("profile-1")).resolves.toEqual({
+			refresh_outcomes: [],
+		});
+
+		expect(mockPost).toHaveBeenCalledWith(
+		"/config-profiles/profile-1/refresh-git-mounts",
+		undefined,
+		{ params: { confirm_destructive_refresh: true } },
+	);
+	});
+});

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

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

apps/web/src/components/.pi-map.index.md

@@ -2,7 +2,7 @@
 dir: apps/web/src/components
 
 ## role
-Reusable React UI components providing the application's shared visual elements, layout shell, authentication guards, and notification infrastructure.
+Package components
 ## parent
 index: apps/web/src/.pi-map.index.md
 map: apps/web/src/.pi-map.md

apps/web/src/components/.pi-map.md

@@ -4,22 +4,22 @@ dir: apps/web/src/components
 index: apps/web/src/components/.pi-map.index.md
 
 ## role
-Reusable React UI components providing the application's shared visual elements, layout shell, authentication guards, and notification infrastructure.
+Package components
 ## files
-- app-shell.tsx | Provides the main application shell layout with navigation, session management, and responsive mobile/desktop rendering for a React application. | exp: AppShell | dep: react-router-dom, ../api/sessions, ../hooks/use-theme, ../utils/open-session, ../state/auth, ../state/sessions, ../hooks/use-mobile-viewport, ../state/events, ../state/toast, ../state/notifications, ./features/notification/event-toast-bridge, ./features/notification/notification-center, ./icon, ./features/mobile/mobile-nav, ./features/tool/start-tool-fab, ../utils/icons
+- app-shell.tsx | Main application layout shell with responsive navigation, session management, and global state providers for notifications and toasts. | exp: AppShell | dep: react-router-dom, ../api/sessions, ../hooks/use-theme, ../utils/open-session, ../state/auth, ../state/sessions, ../hooks/use-mobile-viewport, ../state/events, ../state/toast, ../state/notifications, ./features/notification/event-toast-bridge, ./features/notification/notification-center, ./icon, ./features/mobile/mobile-nav, ./features/tool/start-tool-fab, ../utils/icons
 - code-editor.tsx | A React component that renders a syntax-highlighting code editor with line numbers using react-simple-code-editor. | exp: CodeEditor | dep: react, react-simple-code-editor, ../utils/language
-- data-states.tsx | Provides reusable React components for displaying loading, error, and empty data states in a UI. | exp: LoadingState, ErrorState, EmptyState | dep: ./icon, icon
-- icon.tsx | Provides a centralized, type-safe React icon component that maps semantic names to Phosphor icons with configurable size, weight, color, and accessibility properties. | exp: IconName, IconProps, Icon | dep: react, @phosphor-icons/react
-- loading-overlay.tsx | Renders an accessible loading overlay with optional label when visible prop is true | exp: func:LoadingOverlay({ visible, label }: LoadingOverlayProps) | dep: ./icon, icon
-- protected-route.test.tsx | Tests a ProtectedRoute component that guards private content based on authentication state | dep: @testing-library/react, react-router-dom, vitest, ./protected-route, ../state/auth
-- protected-route.tsx | A React component that conditionally renders children or redirects to login based on authentication state, preserving the intended destination URL. | exp: ProtectedRoute | dep: react-router-dom, ../state/auth
-- syntax-highlighter.tsx | Renders syntax-highlighted code blocks with optional line numbers, language badge, and copy-to-clipboard functionality. | exp: SyntaxHighlighter | dep: react, ./icon, ../utils/language, React, icon, language utilities
+- data-states.tsx | Provides reusable UI components for rendering loading, error, and empty data states. | exp: LoadingState, ErrorState, EmptyState | dep: ./icon, Icon
+- icon.tsx | Provides a centralized, type-safe React icon component that maps semantic names to Phosphor icons with configurable sizes, weights, and colors. | exp: IconName, IconProps, Icon | dep: react, @phosphor-icons/react
+- loading-overlay.tsx | Renders an accessible loading overlay with optional text label when visible | exp: func:LoadingOverlay({ visible, label }: LoadingOverlayProps) | dep: ./icon, icon
+- protected-route.test.tsx | Tests a ProtectedRoute component that guards content based on authentication state, showing loading or redirecting to login | dep: @testing-library/react, react-router-dom, vitest, ./protected-route
+- protected-route.tsx | Conditionally renders children or redirects to login based on authentication state | exp: ProtectedRoute | dep: react-router-dom, ../state/auth
+- syntax-highlighter.tsx | A React component that renders syntax-highlighted code with optional line numbers and a copy-to-clipboard button | exp: SyntaxHighlighter | dep: react, ./icon, ../utils/language, React, icon, language utils
 - toast-rules.test.ts | Unit tests for mapping instance events to toast notification categories and severities | dep: vitest, ./toast-rules, ../types/events
 - toast-rules.ts | Maps instance events to toast notifications with deduplication logic | exp: func:mapEventToCategory(event: InstanceEventPayload) → string, call:event.event.startsWith, func:mapEventToSeverity(event: InstanceEventPayload) → "info" | "warning" | "error" | "success", func:handleEventToast(event: InstanceEventPayload) → void, call:shouldShowToast, call:toast.info, call:toast.success, call:toast.warning, call:toast.error, func:clearToastDedup() → void, call:lastToastTime.clear | dep: ../state/toast, ../types/events, toast, InstanceEventPayload
 ## arch
-Component-based architecture with functional React patterns, separation of presentational components (data states, icons, syntax highlighting) from behavioral logic (toast rules, protected routes), and centralized design abstractions (icon mapping, code editor wrapping).
+Contains 10 files.
 ## tags
-toast, react, state, icon, code, loading, event, editor
+toast, state, icon, react, loading, code, event, editor
 ## symbols
 - LoadingOverlay
 - mapEventToCategory

apps/web/src/components/features/.pi-map.index.md

@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features
 
 ## role
-Reusable UI feature components that compose domain-specific functionality for the web application.
+Feature-specific UI components organized by business domain/capability for the web
 ## parent
 index: apps/web/src/components/.pi-map.index.md
 map: apps/web/src/components/.pi-map.md

apps/web/src/components/features/.pi-map.md

@@ -4,10 +4,10 @@ dir: apps/web/src/components/features
 index: apps/web/src/components/features/.pi-map.index.md
 
 ## role
-Reusable UI feature components that compose domain-specific functionality for the web application.
+Feature-specific UI components organized by business domain/capability for the web
 ## files
 ## arch
-Feature-based component organization with domain-driven design patterns, likely combining presentational components with localized state and business logic.
+Contains 0 files.
 ## tags
 -
 ## symbols

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

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

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

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

apps/web/src/components/features/terminal/.pi-map.index.md

@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features/terminal
 
 ## role
-Provides responsive, cross-platform terminal UI components with session management, virtual special keys, and WebSocket-backed xterm.js integration for web-based terminal access.
+Provides the UI components for a responsive, multi-session terminal interface in the web app, including desktop and mobile layouts, session tabs, and special-key input controls.
 ## parent
 index: apps/web/src/components/features/.pi-map.index.md
 map: apps/web/src/components/features/.pi-map.md

apps/web/src/components/features/terminal/.pi-map.md

@@ -4,19 +4,19 @@ dir: apps/web/src/components/features/terminal
 index: apps/web/src/components/features/terminal/.pi-map.index.md
 
 ## role
-Provides responsive, cross-platform terminal UI components with session management, virtual special keys, and WebSocket-backed xterm.js integration for web-based terminal access.
+Provides the UI components for a responsive, multi-session terminal interface in the web app, including desktop and mobile layouts, session tabs, and special-key input controls.
 ## files
-- DesktopTerminalView.tsx | Renders a desktop terminal view with session tabs, fullscreen controls, and multiple terminal instances | exp: DesktopTerminalView | dep: react, ./terminal, ./terminal-session-tabs, ../../../api/terminal
-- MobileTerminalView.tsx | Renders a mobile-optimized terminal interface with session tabs, toolbar controls, special keys input, and keyboard-aware layout adjustments. | exp: MobileTerminalView | dep: react, ./terminal, ./terminal-session-tabs, ../../icon, ./special-keys-strip, ./special-keys-panel, ../../../hooks/use-special-keys, ../../../api/terminal, terminal, terminal-session-tabs, icon, special-keys-strip, special-keys-panel, use-special-keys, api/terminal
-- special-keys-panel.tsx | Renders an overlay panel of special keyboard keys (Home, End, F1-F12, Ctrl+C, etc.) that sends terminal sequences when clicked and supports modifier key combinations. | exp: SpecialKeysPanel | dep: react, ../../../hooks/use-special-keys, React, use-special-keys hook
-- special-keys-strip.tsx | Renders a strip of virtual special keys (Esc, Tab, Ctrl, Alt, arrows, etc.) for sending terminal key sequences with optional modifier support. | exp: SpecialKeysStrip | dep: react, ../../../hooks/use-special-keys, use-special-keys hook
-- terminal-session-tabs.test.tsx | Tests a React terminal session tabs component for rendering, selection, closing with confirmation, renaming, session limits, and connection status display. | dep: @testing-library/react, vitest, ./terminal-session-tabs
-- terminal-session-tabs.tsx | Renders an interactive tab bar for managing multiple terminal sessions with selection, renaming, closing, and creation capabilities | exp: TerminalSessionInfo, TerminalSessionTabsProps, TerminalSessionTabs | dep: react, React, useState, useRef, useCallback
-- terminal.tsx | A React terminal component that provides an interactive xterm.js-based terminal with WebSocket connectivity, mobile touch support, and session management. | exp: TerminalProps, TerminalRef, TerminalComponent | dep: react, xterm, xterm-addon-fit, xterm-addon-web-links, xterm/css/xterm.css, ../../../hooks/use-special-keys, React
+- DesktopTerminalView.tsx | Renders the desktop layout for a multi-session terminal UI, managing tabs, fullscreen mode, font controls, and reset confirmation. | exp: DesktopTerminalView | dep: react, ./terminal, ./terminal-session-tabs, ../../../api/terminal, React, TerminalComponent, TerminalSessionTabs, TerminalSession
+- MobileTerminalView.tsx | Renders a mobile-specific terminal interface with session tabs, toolbar controls, special key inputs, and multiple terminal instances. | exp: MobileTerminalView | dep: react, ./terminal, ./terminal-session-tabs, ../../icon, ./special-keys-strip, ./special-keys-panel, ../../../hooks/use-special-keys, ../../../api/terminal, React, TerminalComponent, TerminalSessionTabs, Icon, SpecialKeysStrip, SpecialKeysPanel
+- special-keys-panel.tsx | Renders a modal overlay panel of special keyboard keys (Home, End, F1-F12, Ctrl+C, etc.) that sends escape sequences to a terminal when clicked. | exp: SpecialKeysPanel | dep: react, ../../../hooks/use-special-keys
+- special-keys-strip.tsx | Renders a touch-accessible strip of special keyboard keys (Esc, Tab, arrows, modifiers) that sends terminal escape sequences with optional modifier support. | exp: SpecialKeysStrip | dep: react, ../../../hooks/use-special-keys, React, use-special-keys hook
+- terminal-session-tabs.test.tsx | Unit tests for a TerminalSessionTabs React component covering tab rendering, selection, close confirmation, inline renaming, session limit enforcement, and connection status display. | dep: @testing-library/react, vitest, ./terminal-session-tabs
+- terminal-session-tabs.tsx | Renders a tabbed interface for managing multiple terminal sessions with support for switching, renaming, closing with confirmation, and creating new sessions. | exp: TerminalSessionInfo, TerminalSessionTabsProps, TerminalSessionTabs | dep: react, React
+- terminal.tsx |  | exp: TerminalProps, TerminalRef, TerminalComponent | dep: react, xterm, xterm-addon-fit, xterm-addon-web-links, xterm/css/xterm.css, ../../../hooks/use-special-keys
 ## arch
-Component-based architecture with platform-specific view layers (desktop/mobile), modular special keys subsystems (strip/overlay panel), tab-based session management with React state, and xterm.js integration via WebSocket abstraction with touch/mobile adaptations.
+Modular React component architecture organized by feature, with separate presentational components for desktop/mobile viewports, shared tab/session management, and helper components for terminal input handling.
 ## tags
-terminal, special, keys, session, tabs, react, view, strip
+terminal, special, session, keys, react, tabs, view, strip
 ## symbols
 - DesktopTerminalView
 - MobileTerminalView

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

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+
+import {
+	getTerminalScrollbackLimit,
+	isCurrentWebSocket,
+	shouldRetryWebSocketClose,
+	shouldShowTerminalCopyMenu,
+} from "./terminal.tsx";
+
+describe("getTerminalScrollbackLimit", () => {
+	it("retains normal-buffer history for custom mobile swipe scrolling", () => {
+		expect(getTerminalScrollbackLimit(true)).toBe(10_000);
+	});
+
+	it("keeps desktop scrollback disabled to prevent stale-frame wheel scrolling", () => {
+		expect(getTerminalScrollbackLimit(false)).toBe(0);
+	});
+
+	it("rejects stale WebSocket callbacks after a replacement connection", () => {
+		const current = {} as WebSocket;
+		const stale = {} as WebSocket;
+
+		expect(isCurrentWebSocket(current, current)).toBe(true);
+		expect(isCurrentWebSocket(current, stale)).toBe(false);
+	});
+
+	it("retries a heartbeat timeout but not a server socket replacement", () => {
+		expect(shouldRetryWebSocketClose(4000, "Heartbeat timeout")).toBe(true);
+		expect(shouldRetryWebSocketClose(4000, "New connection established")).toBe(
+			false,
+		);
+	});
+});
+
+describe("shouldShowTerminalCopyMenu", () => {
+	it("shows Copy for selected terminal output", () => {
+		expect(shouldShowTerminalCopyMenu("selected output")).toBe(true);
+	});
+
+	it("keeps the native context menu when no output is selected", () => {
+		expect(shouldShowTerminalCopyMenu("")).toBe(false);
+	});
+});

apps/web/src/components/features/tool/.pi-map.index.md

@@ -2,7 +2,7 @@
 dir: apps/web/src/components/features/tool
 
 ## role
-Provides UI components for managing containerized development tools, including instance lifecycle management, manifest configuration, and workspace-integrated tool launching.
+Provides UI components for managing containerized development tools, including starting, configuring, monitoring, and editing tool instances across workspaces.
 ## parent
 index: apps/web/src/components/features/.pi-map.index.md
 map: apps/web/src/components/features/.pi-map.md

apps/web/src/components/features/tool/.pi-map.md

@@ -4,18 +4,18 @@ dir: apps/web/src/components/features/tool
 index: apps/web/src/components/features/tool/.pi-map.index.md
 
 ## role
-Provides UI components for managing containerized development tools, including instance lifecycle management, manifest configuration, and workspace-integrated tool launching.
+Provides UI components for managing containerized development tools, including starting, configuring, monitoring, and editing tool instances across workspaces.
 ## files
-- instance-list.tsx | React component that displays and manages a list of tool instances with CRUD operations, real-time status updates, and configuration profile selection. | exp: InstanceList | dep: react, react-router-dom, ../../icon, ../../loading-overlay, ../../../api/sessions, ../../../api/tool-types, ../session/create-session-form, ../../../api/config-profiles, ../../../api/ssh-keys, ../../../state/events, ../../../state/sessions
-- manifest-editor.tsx | A React component that provides a form-based UI for editing container manifest configurations including base images, packages, environment variables, scripts, mounts, and runtime settings, with live preview generation capability. | exp: ManifestEditor | dep: react, ../../icon, ../../../utils/errors, ../../../api/tool-definitions, icon, errors utils, tool-definitions API
-- start-tool-fab.tsx | Renders a floating action button that opens a modal to select a workspace and start a tool. | exp: func:StartToolFAB(), call:useState, call:setOpen, call:setWorkspacesLoading, call:listAllWorkspaces, call:setWorkspaces, call:setSelectedWorkspace, call:e.stopPropagation, call:workspaces.find, call:workspaces.map | dep: react, ../../icon, ./tool-starter, ../../../types/workspace, ../../../api/workspaces, icon, tool-starter, workspace types, workspaces api
-- start-tool-modal.tsx | React modal component for selecting a tool type and optional config profile to start a tool on a workspace | exp: StartToolModalProps, func:StartToolModal({ workspace, onClose, onStart, }: StartToolModalProps), call:useState, call:useAsyncData, call:e.preventDefault, call:setError, call:setSubmitting, call:onStart, call:onClose, call:e.stopPropagation, call:setToolTypeId, call:toolTypes?.map, call:setConfigProfileId | dep: react, ../../icon, ../../../api/tool-types, ../../../hooks/use-async-data, ../../../types/workspace
-- tool-starter.tsx | React component for starting a tool instance within a workspace with configurable tool types, profiles, and SSH keys | exp: ToolStarterProps, func:ToolStarter({ workspace, onStarted, onCancel, }: ToolStarterProps), call:useSessions, call:useState, call:useEffect, call:listToolTypes, call:setToolTypes, call:setToolTypesError, call:setToolTypesLoading, call:load, call:setProfiles, call:setSelectedProfileId, call:setProfilesLoading, call:listConfigProfiles, call:data.find, call:listSSHKeys, call:setSshKeys, call:setSelectedSshKeyIds, call:console.error, call:setSshKeysLoading, call:sshKeys.find, call:useCallback, call:setError, call:setStarting, call:createInstance, call:displayName.trim, call:startInstance, call:addOrUpdateSession, call:onStarted, call:setSelectedToolTypeId, call:toolTypes.find, call:setDisplayName, call:toolTypes.map, call:setNameEdited, call:profiles.map, call:sshKeys.map, call:selectedSshKeyIds.includes, call:prev.filter | dep: react, ../../icon, ../../loading-overlay, ../../../api/tool-types, ../../../api/config-profiles, ../../../api/ssh-keys, ../../../state/sessions, ../../../types/workspace, ../../../api/sessions, icon, loading-overlay, tool-types, config-profiles, ssh-keys, sessions, workspace types, sessions api
+- instance-list.tsx | Displays and manages tool instances for a project/repo with start/stop/restart/delete actions, config profile selection, SSH key selection, and real-time status updates. | exp: InstanceList | dep: react, react-router-dom, ../../icon, ../../loading-overlay, ../../../api/sessions, ../../../api/tool-types, ../session/create-session-form, ../../../api/config-profiles, ../../../api/ssh-keys, ../../../state/events, ../../../state/sessions, Icon, LoadingOverlay, sessions API, config-profiles API, ssh-keys API, events state, sessions state
+- manifest-editor.tsx | A React component that provides a form-based UI for editing container manifest configurations including base images, packages, environment variables, scripts, mounts, and runtime settings, with live preview compilation. | exp: ManifestEditor | dep: react, ../../icon, ../../../utils/errors, ../../../api/tool-definitions, icon, errors utils, tool-definitions API
+- start-tool-fab.tsx | Renders a floating action button that opens a modal for selecting a workspace and starting a tool. | exp: func:StartToolFAB(), call:useState, call:setOpen, call:setWorkspacesLoading, call:listAllWorkspaces, call:setWorkspaces, call:setSelectedWorkspace, call:e.stopPropagation, call:workspaces.find, call:workspaces.map | dep: react, ../../icon, ./tool-starter, ../../../types/workspace, ../../../api/workspaces
+- start-tool-modal.tsx | A React modal component that allows users to select a tool type and optional configuration profile to start a tool on a specific workspace. | exp: StartToolModalProps, func:StartToolModal({ workspace, onClose, onStart, }: StartToolModalProps), call:useState, call:useAsyncData, call:e.preventDefault, call:setError, call:setSubmitting, call:onStart, call:onClose, call:e.stopPropagation, call:setToolTypeId, call:toolTypes?.map, call:setConfigProfileId | dep: react, ../../icon, ../../../api/tool-types, ../../../hooks/use-async-data, ../../../types/workspace, icon, tool-types, use-async-data, workspace
+- tool-starter.tsx | React component for starting a tool instance within a workspace context, fetching and configuring tool types, profiles, and SSH keys. | exp: ToolStarterProps, func:ToolStarter({ workspace, onStarted, onCancel, }: ToolStarterProps), call:useSessions, call:useState, call:useEffect, call:listToolTypes, call:setToolTypes, call:setToolTypesError, call:setToolTypesLoading, call:load, call:setProfiles, call:setSelectedProfileId, call:setProfilesLoading, call:listConfigProfiles, call:data.find, call:listSSHKeys, call:setSshKeys, call:setSelectedSshKeyIds, call:console.error, call:setSshKeysLoading, call:sshKeys.find, call:useCallback, call:setError, call:setStarting, call:createInstance, call:displayName.trim, call:startInstance, call:addOrUpdateSession, call:onStarted, call:setSelectedToolTypeId, call:toolTypes.find, call:setDisplayName, call:toolTypes.map, call:setNameEdited, call:profiles.map, call:sshKeys.map, call:selectedSshKeyIds.includes, call:prev.filter | dep: react, ../../icon, ../../loading-overlay, ../../../api/tool-types, ../../../api/config-profiles, ../../../api/ssh-keys, ../../../state/sessions, ../../../types/workspace, ../../../api/sessions, icon, loading-overlay, tool-types, config-profiles, ssh-keys, sessions, workspace
 - tools-bottom-sheet.tsx | Renders a mobile bottom sheet navigation menu for tools with active route highlighting | exp: ToolsBottomSheet | dep: react-router-dom, ../../icon, icon
 ## arch
-Feature-based React component architecture with modal/bottom-sheet mobile-responsive patterns, form-driven configuration editing with live preview, and workspace-contextual tool orchestration.
+React component-based architecture with feature-specific composition, using modal/bottom-sheet patterns for mobile-responsive navigation, form-based configuration editors with live preview, and real-time status polling for instance management.
 ## tags
-call:set, tool, types, start, call:use, ssh, react, loading
+call:set, tool, types, start, ssh, call:use, icon, loading
 ## symbols
 - StartToolFAB
 - StartToolModal

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

@@ -578,19 +578,23 @@ export const InstanceList = ({
 			{showCreate && (
 				<div className="dialog-overlay" role="dialog" aria-modal="true">
 					<div className="dialog">
-						<h2>Launch Tool</h2>
-						<CreateSessionForm
-							projects={[]}
-							repositories={[]}
-							toolTypes={toolTypes}
-							fixedProjectId={projectId}
-							fixedRepoId={repoId}
-							projectName={projectName}
-							repoName={repoName}
-							onSuccess={handleCreateSuccess}
-							onCancel={() => setShowCreate(false)}
-							submitLabel="Launch"
-						/>
+						<div className="dialog-header">
+							<h2>Launch Tool</h2>
+						</div>
+						<div className="dialog-body">
+							<CreateSessionForm
+								projects={[]}
+								repositories={[]}
+								toolTypes={toolTypes}
+								fixedProjectId={projectId}
+								fixedRepoId={repoId}
+								projectName={projectName}
+								repoName={repoName}
+								onSuccess={handleCreateSuccess}
+								onCancel={() => setShowCreate(false)}
+								submitLabel="Launch"
+							/>
+						</div>
 					</div>
 				</div>
 			)}

apps/web/src/components/features/tool/manifest-editor.tsx

@@ -49,7 +49,7 @@ export const ManifestEditor = ({
 	const [startupScripts, setStartupScripts] = useState<string[]>([""]);
 	const [mounts, setMounts] = useState<MountEntry[]>([]);
 	const [command, setCommand] = useState<string[]>([""]);
-	const [workingDir, setWorkingDir] = useState("/workspace");
+	const [workingDir, setWorkingDir] = useState("");
 	const [stdinOpen, setStdinOpen] = useState(true);
 	const [tty, setTty] = useState(true);
 
@@ -94,7 +94,7 @@ export const ManifestEditor = ({
 
 		const runtime = (manifest.runtime as Record<string, unknown>) || {};
 		setCommand((runtime.command as string[]) || [""]);
-		setWorkingDir((runtime.working_dir as string) || "/workspace");
+		setWorkingDir((runtime.working_dir as string) || "");
 		setStdinOpen((runtime.stdin_open as boolean) ?? true);
 		setTty((runtime.tty as boolean) ?? true);
 	}, [manifest]);
@@ -561,7 +561,8 @@ export const ManifestEditor = ({
 							<textarea
 								value={script}
 								onChange={(e) => updateStartupScript(idx, e.target.value)}
-								placeholder="chown -R user:user /workspace"
+								placeholder="chown -R user:user $HOME/$WORKSPACE_NAME"
+
 								className="form-input font-mono text-sm flex-1"
 								rows={2}
 							/>
@@ -723,7 +724,7 @@ export const ManifestEditor = ({
 							type="text"
 							value={workingDir}
 							onChange={(e) => setWorkingDir(e.target.value)}
-							placeholder="/workspace"
+							placeholder="e.g., /workspace or ~/code"
 							className="form-input"
 						/>
 					</div>

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

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

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

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

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

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

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

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

apps/web/src/hooks/use-terminal-page.ts

@@ -169,6 +169,10 @@ export const useTerminalPage = () => {
       const isAltShift = e.altKey && e.shiftKey && !e.ctrlKey && !e.metaKey;
       if (!isAltShift) return;
 
+      const activeSessionIndex = activeSessionId
+        ? sessions.findIndex((session) => session.id === activeSessionId)
+        : -1;
+
       switch (e.key.toLowerCase()) {
         case "n":
           e.preventDefault();
@@ -187,17 +191,14 @@ export const useTerminalPage = () => {
           break;
         case "arrowleft":
           e.preventDefault();
-          if (activeSessionId) {
-            const idx = sessions.findIndex((s) => s.id === activeSessionId);
-            if (idx > 0) setActiveSessionId(sessions[idx - 1].id);
+          if (activeSessionIndex > 0) {
+            setActiveSessionId(sessions[activeSessionIndex - 1].id);
           }
           break;
         case "arrowright":
           e.preventDefault();
-          if (activeSessionId) {
-            const idx = sessions.findIndex((s) => s.id === activeSessionId);
-            if (idx < sessions.length - 1)
-              setActiveSessionId(sessions[idx + 1].id);
+          if (activeSessionIndex >= 0 && activeSessionIndex < sessions.length - 1) {
+            setActiveSessionId(sessions[activeSessionIndex + 1].id);
           }
           break;
         case "r":
@@ -208,6 +209,8 @@ export const useTerminalPage = () => {
           e.preventDefault();
           setIsFullscreen((prev) => !prev);
           break;
+        default:
+          break;
       }
     };
 

apps/web/src/pages/ConfigProfilesPage.tsx

@@ -23,6 +23,8 @@ export const ConfigProfilesPage = () => {
 		error,
 		previewData,
 		previewingId,
+		isRefreshingGitMounts,
+		isReloadingWorkingCopy,
 		formData,
 		includedProfileIds,
 		dragOverIndex,
@@ -32,6 +34,8 @@ export const ConfigProfilesPage = () => {
 		handleSubmit,
 		handleDelete,
 		handlePreview,
+		handleReloadWorkingCopy,
+		handleRefreshGitMounts,
 		updateFormField,
 		addEnvVar,
 		updateEnvVar,
@@ -110,6 +114,8 @@ export const ConfigProfilesPage = () => {
 				availableProfiles={availableProfilesForInclude()}
 				previewData={previewData}
 				previewingId={previewingId}
+				isRefreshingGitMounts={isRefreshingGitMounts}
+				isReloadingWorkingCopy={isReloadingWorkingCopy}
 				saveStatus={saveStatus}
 				error={error}
 				onViewChange={setMobileView}
@@ -135,6 +141,8 @@ export const ConfigProfilesPage = () => {
 				onUpdateMountFile={updateMountFile}
 				onRemoveMountFile={removeMountFile}
 				onPreview={handlePreview}
+				onReloadWorkingCopy={() => void handleReloadWorkingCopy()}
+				onRefreshGitMounts={(id) => void handleRefreshGitMounts(id)}
 				onClosePreview={() => setPreviewData(null)}
 			/>
 		);
@@ -167,6 +175,8 @@ export const ConfigProfilesPage = () => {
 				saveStatus={saveStatus}
 				previewData={previewData}
 				previewingId={previewingId}
+				isRefreshingGitMounts={isRefreshingGitMounts}
+				isReloadingWorkingCopy={isReloadingWorkingCopy}
 				projects={projects}
 				toolTypes={toolTypes}
 				availableProfiles={availableProfilesForInclude()}
@@ -176,6 +186,10 @@ export const ConfigProfilesPage = () => {
 				onSubmit={handleSubmit}
 				onReset={handleReset}
 				onPreview={() => selectedProfile && handlePreview(selectedProfile.id)}
+				onReloadWorkingCopy={() => void handleReloadWorkingCopy()}
+				onRefreshGitMounts={() =>
+					selectedProfile && handleRefreshGitMounts(selectedProfile.id)
+				}
 				onAddInclude={addInclude}
 				onRemoveInclude={removeInclude}
 				onDragStart={handleDragStart}

apps/web/src/pages/ProjectsPage.test.tsx

@@ -1,17 +1,26 @@
+import "@testing-library/jest-dom/vitest";
 import { cleanup, fireEvent, render, screen, waitFor, within } from "@testing-library/react";
 import { MemoryRouter } from "react-router-dom";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 import { ProjectsPage } from "./ProjectsPage";
 import * as projectsApi from "../api/projects";
+import { SessionsProvider } from "../state/sessions";
+import type { ProjectWithRepos } from "../types";
 
-const mockProjects = [
+vi.mock("../api/sessions", () => ({
+  getUserSessions: vi.fn().mockResolvedValue([]),
+}));
+
+const mockProjects: ProjectWithRepos[] = [
   {
     id: "proj-1",
     name: "Alpha Project",
     description: "First project",
     owner_id: "user-1",
     default_ssh_key_id: null,
+    repositories: [],
+    created_at: "2026-07-01T00:00:00Z",
   },
   {
     id: "proj-2",
@@ -19,6 +28,8 @@ const mockProjects = [
     description: null,
     owner_id: "user-1",
     default_ssh_key_id: null,
+    repositories: [],
+    created_at: "2026-07-01T00:00:00Z",
   },
 ];
 
@@ -31,9 +42,7 @@ describe("ProjectsPage", () => {
   it("renders loading state initially", () => {
     vi.spyOn(projectsApi, "listProjects").mockImplementation(() => new Promise(() => {}));
     render(
-      <MemoryRouter>
-        <ProjectsPage />
-      </MemoryRouter>
+      <MemoryRouter><SessionsProvider><ProjectsPage /></SessionsProvider></MemoryRouter>
     );
     expect(screen.getByText(/loading projects/i)).toBeInTheDocument();
   });
@@ -41,9 +50,7 @@ describe("ProjectsPage", () => {
   it("renders project list after loading", async () => {
     vi.spyOn(projectsApi, "listProjects").mockResolvedValue(mockProjects);
     render(
-      <MemoryRouter>
-        <ProjectsPage />
-      </MemoryRouter>
+      <MemoryRouter><SessionsProvider><ProjectsPage /></SessionsProvider></MemoryRouter>
     );
 
     await waitFor(() => {
@@ -56,9 +63,7 @@ describe("ProjectsPage", () => {
   it("renders empty state when no projects", async () => {
     vi.spyOn(projectsApi, "listProjects").mockResolvedValue([]);
     render(
-      <MemoryRouter>
-        <ProjectsPage />
-      </MemoryRouter>
+      <MemoryRouter><SessionsProvider><ProjectsPage /></SessionsProvider></MemoryRouter>
     );
 
     await waitFor(() => {
@@ -69,9 +74,7 @@ describe("ProjectsPage", () => {
   it("renders error state with retry button", async () => {
     vi.spyOn(projectsApi, "listProjects").mockRejectedValue(new Error("fail"));
     render(
-      <MemoryRouter>
-        <ProjectsPage />
-      </MemoryRouter>
+      <MemoryRouter><SessionsProvider><ProjectsPage /></SessionsProvider></MemoryRouter>
     );
 
     await waitFor(() => {
@@ -85,9 +88,7 @@ describe("ProjectsPage", () => {
     const createMock = vi.spyOn(projectsApi, "createProject").mockResolvedValue(mockProjects[0]);
 
     render(
-      <MemoryRouter>
-        <ProjectsPage />
-      </MemoryRouter>
+      <MemoryRouter><SessionsProvider><ProjectsPage /></SessionsProvider></MemoryRouter>
     );
 
     await waitFor(() => {
@@ -118,9 +119,7 @@ describe("ProjectsPage", () => {
     vi.spyOn(projectsApi, "listProjects").mockResolvedValue([]);
 
     render(
-      <MemoryRouter>
-        <ProjectsPage />
-      </MemoryRouter>
+      <MemoryRouter><SessionsProvider><ProjectsPage /></SessionsProvider></MemoryRouter>
     );
 
     await waitFor(() => {
@@ -138,16 +137,14 @@ describe("ProjectsPage", () => {
     const updateMock = vi.spyOn(projectsApi, "updateProject").mockResolvedValue(mockProjects[0]);
 
     render(
-      <MemoryRouter>
-        <ProjectsPage />
-      </MemoryRouter>
+      <MemoryRouter><SessionsProvider><ProjectsPage /></SessionsProvider></MemoryRouter>
     );
 
     await waitFor(() => {
       expect(screen.getByText("Alpha Project")).toBeInTheDocument();
     });
 
-    const alphaCard = screen.getByText("Alpha Project").closest(".project-card") as HTMLElement | null;
+    const alphaCard = screen.getByText("Alpha Project").closest(".project-list-item") as HTMLElement | null;
     if (!alphaCard) throw new Error("Card not found");
 
     fireEvent.click(within(alphaCard).getByRole("button", { name: /edit/i }));
@@ -171,16 +168,14 @@ describe("ProjectsPage", () => {
     const deleteMock = vi.spyOn(projectsApi, "deleteProject").mockResolvedValue(undefined);
 
     render(
-      <MemoryRouter>
-        <ProjectsPage />
-      </MemoryRouter>
+      <MemoryRouter><SessionsProvider><ProjectsPage /></SessionsProvider></MemoryRouter>
     );
 
     await waitFor(() => {
       expect(screen.getByText("Alpha Project")).toBeInTheDocument();
     });
 
-    const alphaCard = screen.getByText("Alpha Project").closest(".project-card") as HTMLElement | null;
+    const alphaCard = screen.getByText("Alpha Project").closest(".project-list-item") as HTMLElement | null;
     if (!alphaCard) throw new Error("Card not found");
 
     fireEvent.click(within(alphaCard).getByRole("button", { name: /delete/i }));

apps/web/src/styles/global.css

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

apps/web/src/styles/utilities.css

@@ -152,7 +152,9 @@
 }
 
 .font-mono {
-	font-family: "IBM Plex Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+	font-family:
+		"IBM Plex Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas,
+		monospace;
 }
 
 .font-medium {
@@ -938,6 +940,14 @@ a.nav-item,
 	overscroll-behavior: auto;
 	max-height: 100% !important;
 	width: 100% !important;
+	/* Full-screen TUI tools repaint in place; scrollback is 0 (see terminal.tsx).
+	   Hide the viewport scrollbar so it never appears or captures input. */
+	scrollbar-width: none;
+	-ms-overflow-style: none;
+}
+
+.terminal-container .xterm-viewport::-webkit-scrollbar {
+	display: none;
 }
 
 /* On mobile the custom touch handler scrolls the buffer; disable native
@@ -2318,8 +2328,10 @@ a.nav-item,
 	width: 100%;
 	max-width: 600px;
 	max-height: 70vh;
+	max-height: 70dvh;
 	display: flex;
 	flex-direction: column;
+	min-height: 0;
 	animation: slide-up 0.2s ease-out;
 }
 
@@ -2355,8 +2367,12 @@ a.nav-item,
 }
 
 .mobile-bottom-sheet-content {
+	flex: 1;
+	min-height: 0;
 	padding: 8px 0;
 	overflow-y: auto;
+	overscroll-behavior: contain;
+	-webkit-overflow-scrolling: touch;
 }
 
 .mobile-bottom-sheet-item {
@@ -3230,7 +3246,10 @@ a:active,
 	width: 100%;
 	max-width: 500px;
 	max-height: 80vh;
+	max-height: 80dvh;
 	overflow-y: auto;
+	overscroll-behavior: contain;
+	-webkit-overflow-scrolling: touch;
 	animation: slideUp 0.3s ease;
 	padding-bottom: env(safe-area-inset-bottom, 0);
 }
@@ -3592,6 +3611,7 @@ a:active,
 		max-width: none;
 		border-radius: 12px;
 		max-height: 70vh;
+		max-height: 70dvh;
 	}
 }
 
@@ -3809,7 +3829,9 @@ a:active,
 	color: var(--muted);
 	cursor: pointer;
 	border-radius: var(--radius-md);
-	transition: background 0.12s ease, color 0.12s ease;
+	transition:
+		background 0.12s ease,
+		color 0.12s ease;
 }
 
 .delete-btn:hover {
@@ -3836,7 +3858,9 @@ a:active,
 	font-size: var(--font-size-sm);
 	font-weight: 500;
 	text-decoration: none;
-	transition: background 0.12s ease, border-color 0.12s ease;
+	transition:
+		background 0.12s ease,
+		border-color 0.12s ease;
 }
 
 .workspace-header-action-btn:hover {
@@ -3911,7 +3935,9 @@ a:active,
 	color: var(--muted);
 	font-size: var(--font-size-xs);
 	cursor: pointer;
-	transition: background 0.12s ease, color 0.12s ease;
+	transition:
+		background 0.12s ease,
+		color 0.12s ease;
 }
 
 .copy-button:hover {
@@ -4157,7 +4183,10 @@ a:active,
 }
 
 .drag-item-active {
-	background: var(--brand-light, color-mix(in srgb, var(--brand) 10%, transparent));
+	background: var(
+		--brand-light,
+		color-mix(in srgb, var(--brand) 10%, transparent)
+	);
 	border-color: var(--brand);
 }
 
@@ -4173,7 +4202,9 @@ a:active,
 	padding: var(--space-4);
 	border-radius: var(--radius-md);
 	overflow: auto;
-	font-family: "IBM Plex Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+	font-family:
+		"IBM Plex Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas,
+		monospace;
 	font-size: var(--font-size-sm);
 	line-height: var(--line-height-normal);
 }
@@ -4321,7 +4352,9 @@ a:active,
 	color: var(--muted);
 	cursor: pointer;
 	font-weight: 600;
-	transition: border-color 0.15s, color 0.15s;
+	transition:
+		border-color 0.15s,
+		color 0.15s;
 }
 
 .sidebar-create-button:hover {
@@ -4346,7 +4379,9 @@ a:active,
 	display: flex;
 	align-items: center;
 	justify-content: center;
-	transition: transform 0.15s ease, box-shadow 0.15s ease;
+	transition:
+		transform 0.15s ease,
+		box-shadow 0.15s ease;
 }
 
 .mobile-fab:hover {

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

openspec/changes/fix-mobile-terminal-scrolling/change.md

@@ -0,0 +1,30 @@
+# Restore Mobile Terminal Scrolling
+
+## Summary
+
+The recent terminal scrollback optimization disabled scrollback for every viewport. Mobile terminal swipe handling still scrolls xterm's normal buffer programmatically, so swipes in normal-buffer tools no longer have retained output to move through.
+
+## Root Cause
+
+`468f342` changed the terminal configuration to `scrollback: 0` globally to prevent stale repaint frames and wheel scrolling on desktop. The mobile touch handler calls `term.scrollLines()` when the normal buffer is active. With zero scrollback, that call has no scrollable history and becomes a no-op.
+
+## Scope
+
+- `apps/web/src/components/features/terminal/terminal.tsx`
+- Focused terminal configuration test
+
+## Fix
+
+Retain a bounded xterm scrollback buffer on mobile only (`10000` lines), while leaving desktop at zero scrollback and with wheel sensitivity disabled. Mobile's existing custom touch handler remains responsible for moving through normal-buffer history; alternate-screen swipes continue to send SGR wheel events to the active TUI.
+
+## Acceptance Criteria
+
+- [ ] A mobile terminal with normal-buffer output exceeding one screen scrolls via a vertical swipe.
+- [ ] Alternate-screen terminal scrolling continues to use the existing SGR wheel-event path.
+- [ ] Desktop keeps zero xterm scrollback and disabled native wheel scrolling, so stale repaint frames do not return.
+- [ ] Focused unit test and frontend quality gates pass.
+
+## Related
+
+- `468f342 fix(terminal): hide scrollbar and stop stale-frame wheel scroll for TUI tools`
+- `openspec/changes/fix-terminal-container-overflow`

openspec/changes/fix-mobile-terminal-scrolling/tasks.md

@@ -0,0 +1,9 @@
+# Restore Mobile Terminal Scrolling — Tasks
+
+- [x] Add a mobile-specific terminal scrollback limit while preserving zero scrollback on desktop.
+- [x] Reinitialize the terminal when the responsive mobile classification changes so its scrollback and touch handler match the active viewport.
+- [x] Add focused tests for the responsive scrollback configuration.
+- [x] Run the full frontend test suite (89 tests passed after repairing the `ProjectsPage` test setup).
+- [x] Run frontend typecheck, lint, focused tests, and production build.
+- [ ] Perform mobile normal-buffer and alternate-screen manual QA.
+- [ ] Update project maps for changed source files (the map patch tool currently fails with an unsupported `temperature` parameter).

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

@@ -12,14 +12,23 @@ After implementing configurable tool container home directories, new `pi-agent`
 4. `npm_global` packages are installed with `RUN npm install -g ...` as root into the system npm prefix, so the non-root container user cannot update them.
 5. Once the repo mount moves out of `/workspace`, the generated `/workspace` compatibility symlink is created in the image as root. The non-root entrypoint cannot replace it (write permission is required on `/`), so container startup fails.
 6. Older images baked a literal `{{WORKSPACE_NAME}}` directory into `/home/user`, which survives alongside the real repo-named mount directory.
+7. Config-profile file mounts use canonical profile storage owned by the API process. A non-root container user therefore cannot write to writable bind mounts. When a directory-level profile mount and a Git mount share or nest under the same target, Docker bind mounting masks the earlier source rather than merging their files.
 
 ## Fix
 
-1. Add an Alembic data migration that updates the built-in `pi-agent` manifest:
+1. Remove the compose-level `user: 0:0` override from `manifest_compiler.py`. The
+   Dockerfile intentionally omits `USER` so the entrypoint can start as root,
+   fix mount ownership, and drop privileges to the container user internally.
+   Pinning `user: 0:0` in the compose service forces `docker exec` sessions to
+   run as root even after the entrypoint drops privileges.
+2. Pass the manifest-declared container user into terminal sessions so
+   `docker exec` is invoked with `--user <user>`. This makes WebSocket terminal
+   sessions run as the same non-root user as the main container process.
+3. Add an Alembic data migration that updates the built-in `pi-agent` manifest:
    - Change the repo mount target to `~/{{WORKSPACE_NAME}}`.
    - Keep `runtime.working_dir` as `/workspace` (the compatibility symlink).
    - Update the startup script to chown the real mount path (`$HOME/$WORKSPACE_NAME`).
-2. Update `manifest_compiler.py`:
+4. Update `manifest_compiler.py`:
    - Substitute `{{WORKSPACE_NAME}}` in mount targets in `compile_compose`.
    - Pass `WORKSPACE_NAME` as a container environment variable.
    - Generate the entrypoint symlink from the runtime `WORKSPACE_NAME` environment variable.
@@ -28,25 +37,32 @@ After implementing configurable tool container home directories, new `pi-agent`
    - Start the container as root and drop privileges to the container user inside the entrypoint via `su`.
    - Do not create mount target directories or the `/workspace` symlink in the image when they depend on the runtime `{{WORKSPACE_NAME}}` placeholder.
    - Remove any stale literal `{{WORKSPACE_NAME}}` directory left over from older images at container startup.
-3. Update `instance_service.py` to pass `REPO_NAME` and `WORKSPACE_NAME` into manifest compilation.
-4. Remove the explicit repo mount from the built-in `pi-agent` manifest so the repo mount is synthesized by `compile_compose` rather than depending on tool config. Add a follow-up Alembic data migration that strips the `source_type: repo` mount from the manifest.
-5. Add `_get_repository_mount_name()` helper. When the instance is bound to a workspace, the helper returns the basename of `workspace.path`. For legacy repo-only instances it falls back to parsing the remote URL like `git clone` would, then to the user-provided repository name.
-6. Switch workspace storage layout to `/data/working-copies/{workspace_id}/{repo_name}/` so `git clone` creates the repo-named directory naturally, making `workspace.path.basename` the correct container mount name. This replaces the previous `/data/working-copies/{repo_id}/{workspace_name}/` layout.
-7. Update unit tests for the new behavior.
+5. Update `instance_service.py` to pass `REPO_NAME` and `WORKSPACE_NAME` into manifest compilation.
+6. Remove the explicit repo mount from the built-in `pi-agent` manifest so the repo mount is synthesized by `compile_compose` rather than depending on tool config. Add a follow-up Alembic data migration that strips the `source_type: repo` mount from the manifest.
+7. Add `_get_repository_mount_name()` helper. When the instance is bound to a workspace, the helper returns the basename of `workspace.path`. For legacy repo-only instances it falls back to parsing the remote URL like `git clone` would, then to the user-provided repository name.
+8. Switch workspace storage layout to `/data/working-copies/{workspace_id}/{repo_name}/` so `git clone` creates the repo-named directory naturally, making `workspace.path.basename` the correct container mount name. This replaces the previous `/data/working-copies/{repo_id}/{workspace_name}/` layout.
+9. Stage every config-profile bind-mount source into the instance directory before compose generation. This makes writable mounts user-owned without changing the shared canonical profile source.
+10. Replace overlapping profile and Git bind mounts with a per-instance composite source. The composite copies Git content first and profile content second, preserving Git siblings while allowing profile files to override matching paths; it is then chowned with the other staged mounts. This removes duplicate/nested Docker mounts rather than relying on mount order to merge them.
+11. Update unit tests for the new behavior.
 
 ## Affected files
 
 - `apps/api/alembic/versions/2026_06_14_182955_fix_pi_agent_home_directory_mount.py`
 - `apps/api/alembic/versions/2026_06_15_090500_remove_pi_agent_explicit_repo_mount.py`
 - `apps/api/src/services/build/manifest_compiler.py`
+- `apps/api/src/services/terminal/terminal_session.py`
+- `apps/api/src/services/terminal/terminal_manager.py`
+- `apps/api/src/api/system/terminal.py`
 - `apps/api/src/services/shared/workspace_manager.py`
 - `apps/api/src/services/tool/instance_service.py`
 - `apps/api/tests/unit/test_manifest_compiler.py`
+- `apps/api/tests/unit/test_terminal_session.py`
 - `apps/api/tests/unit/test_instance_service.py`
 - `apps/api/tests/unit/test_alembic_migrations.py`
 
 ## Verification
 
 - `pytest apps/api/tests/unit/test_manifest_compiler.py`
+- `pytest apps/api/tests/unit/test_terminal_session.py`
 - `pytest apps/api/tests/unit/test_alembic_migrations.py`
-- `ruff`, `mypy`, `npm run typecheck`, `npm run lint`
+- `ruff`, `mypy`, `npm run typecheck`, `npm run lint`

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

@@ -7,6 +7,13 @@
 - [x] Remove explicit repo mount from pi-agent manifest; synthesize mount in compile_compose
 - [x] Add _get_repository_mount_name() helper to derive workspace name from remote URL
 - [x] Switch workspace storage layout to /data/working-copies/{workspace_id}/{repo_name}/
-- [x] Update unit tests
-- [x] Run quality gates (pytest unit, ruff, mypy)
+- [x] Update unit tests for workspace/home-directory migration
+- [x] Run quality gates for workspace/home-directory migration
+- [x] Remove compose-level `user: 0:0` override so entrypoint can drop privileges
+- [x] Pass manifest-declared container user to terminal sessions via `docker exec --user`
+- [x] Update unit tests for container user/terminal changes
+- [x] Stage profile bind mounts per instance so writable sources are owned by the container user
+- [x] Composite overlapping profile and Git mounts into one per-instance bind source
+- [x] Add regression tests for mount composition, ownership staging, and mount order
+- [ ] Run quality gates for container user/terminal changes
 - [ ] Commit and push

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

@@ -0,0 +1,14 @@
+# Fix Web Terminal Clipboard
+
+## Problem
+
+Users cannot reliably copy terminal output from the browser terminal. Browser copy shortcuts may be forwarded to the terminal as input instead of copying the xterm selection, and paste behavior differs by bracketed-paste mode.
+
+## Required behavior
+
+- Right-clicking a selected terminal region presents an xterm-aware Copy action that writes the selection to the system clipboard.
+- Browser native context menus remain available when no terminal output is selected.
+- Terminal keyboard input, including `Ctrl+C`, remains unchanged.
+- Copy requests expose the xterm selection as plain text.
+- Pasting plain text is handled once and follows bracketed-paste mode when enabled.
+- Normal terminal interrupts still work when there is no active selection.

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

@@ -0,0 +1,6 @@
+# Web Terminal Clipboard Tasks
+
+- [x] Add selected-text copy interception without suppressing unselected terminal interrupts.
+- [x] Normalize browser paste handling through the existing paste transport.
+- [x] Add focused frontend coverage for copy shortcut decisions.
+- [x] Run frontend tests, typecheck/build, lint, and diagnostics.

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,34 @@
+# Live Config Profile Refresh — Tasks
+
+## Review Workload Forecast
+
+| Field | Value |
+| --- | --- |
+| Estimated changed lines | 500–750 |
+| 400-line budget risk | High |
+| Chained PRs recommended | Yes |
+| Suggested split | Container-user standardization → canonical profile mounts → API/UI feedback → verification |
+| Delivery strategy | feature-branch-chain |
+| Chain strategy | feature-branch-chain |
+
+Decision needed before apply: No
+Chained PRs recommended: Yes
+Chain strategy: feature-branch-chain
+400-line budget risk: High
+
+## Execution Plan
+
+1. [x] **Canonical non-Git mounts:** bind declared profile files and mount directories directly from profile-scoped canonical storage; ensure the container user owns writable canonical sources.
+2. [x] **Editor synchronization:** materialize editor saves into canonical storage and return canonical declared-file content through profile responses; add explicit Reload working copy controls in desktop and mobile editors.
+3. [x] **Writable Git working copies:** expose profile-scoped Git sources as writable mounts and replace them from the configured remote ref on explicit refresh.
+4. [x] **Server refresh contract:** require explicit destructive-refresh confirmation at the API boundary and return a typed outcome when confirmation is missing.
+5. [x] **Overlap safety:** replace profile/Git composite snapshots with child file-level canonical profile overlays so Git directory mounts remain intact.
+6. [x] **Outcome UI:** display destructive-refresh confirmation and explicit Reload working copy controls in both editor layouts; restart-required/overwrite states remain available as API errors/outcomes.
+7. [x] **Focused tests:** cover destructive refresh and overlap behavior at service/API/frontend levels; canonical source reuse is covered by resolver tests.
+8. [x] **Verify:** targeted backend/frontend tests, typecheck, lint, and diagnostics passed. Docker multi-instance validation remains skipped by user choice.
+
+## Verification Notes
+
+- Passed: frontend production build (`npm run build`), Python compilation for changed backend modules, and targeted LSP diagnostics.
+- Skipped: backend pytest and Ruff; this environment has no project-managed Python runner, system Python lacks those packages, and the user declined system-package installation.
+- Skipped: Docker/Compose and manual multi-instance checks; explicit Docker approval was not granted.

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

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

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

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

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

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

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

@@ -0,0 +1,16 @@
+# Live Git Config Mount Refresh — Tasks
+
+- [x] Add canonical profile-scoped Git clone source planning and clone identity helpers.
+- [x] Make Git Config Profile mounts profile-scoped writable working copies shared with compatible instances and the editor.
+- [x] Add lock-protected destructive refresh with an explicit local-edit replacement warning.
+- [x] Add save/refresh outcomes for live refresh, destructive-refresh confirmation, and failures; use file-level overlays to avoid live topology changes.
+- [x] Add an in-progress desktop/mobile indicator that disables duplicate Git-mount refresh requests.
+- [x] Replace instance-local composites with file-level canonical profile overlays, so live updates do not depend on composite synchronization.
+- [x] Add focused resolver/service/API/frontend tests.
+- [x] Run available verification and document skipped checks.
+
+## Verification Notes
+
+- Passed: 47 targeted backend tests, Ruff, mypy, frontend API test, and frontend production build.
+- Skipped: Docker/manual multi-instance checks were explicitly declined.
+- Known tooling limitation: project-map patching fails before execution because its runtime sends an unsupported `temperature` parameter.