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

# Fix pi container repo mount and npm update permissions

## Problem

After implementing configurable tool container home directories, new `pi-agent` containers still bind-mount the git repository at `/workspace` instead of under `/home/user/{repo_name}`. In addition, users cannot run `npm update -g @earendil-works/pi-coding-agent` inside the container because the global npm prefix (`/usr/lib/node_modules`) is owned by root.

## Root cause

1. The built-in `pi-agent` manifest in `tool_definition_manifests` still declares an explicit repo mount with `"target": "/workspace"` and `"working_dir": "/workspace"`. This masks the generated `/workspace → /home/user/{repo}` compatibility symlink.
2. `manifest_compiler.py` does not substitute the instance-specific `{{WORKSPACE_NAME}}` placeholder in explicit mount targets, and `instance_service.py` does not pass `WORKSPACE_NAME`/`REPO_NAME` to `compile_compose` for manifest-based tools.
3. The generated entrypoint hardcodes the literal string `{{WORKSPACE_NAME}}` as the symlink target.
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. 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`).
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.
   - Install `npm_global` packages into a user-writable prefix (`{home_dir}/.npm-global`) and add it to `PATH`.
   - Use `sudo` or root to create the `/workspace` compatibility symlink, because `/` is owned by root and the non-root entrypoint cannot replace a root-owned symlink.
   - 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.
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`