fix: run tool terminal sessions as container user instead of root

- Remove compose-level user: 0:0 override from manifest_compiler.py so the
  entrypoint can start as root, fix mount ownership, and drop privileges to
  the container user internally.
- Add get_manifest_container_user() helper to resolve the manifest-declared
  container user (with uid:gid fallback).
- Pass container user through TerminalSession, TerminalManager, and the
  terminal WebSocket handler so docker exec is invoked with --user <user>.
- Update and add unit tests for the manifest compiler and terminal session.
- Record the additional root-user fix in the fix-pi-container-mount-permissions
  OpenSpec change/tasks.

Quality gates: pytest tests/unit/ (226 passed), pytest tests/services/test_terminal_manager_multi.py (7 passed), ruff check on changed files (clean), mypy on changed files (clean)

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/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

@@ -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
@@ -105,6 +107,19 @@ class TerminalSession:
 
     async def start(self, startup_command: str | None = None) -> None:
         """Start the docker exec process with a shell using a PTY."""
+        # 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
         self._master_fd, slave_fd = pty.openpty()
 
@@ -131,16 +146,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,