fix: use sudo/root to create /workspace symlink in manifest entrypoint

The previous commit moved the pi-agent repo mount from /workspace to
/home/user/{repo_name}. This exposed a permission bug: the Dockerfile
creates /workspace as a root-owned symlink in the image, and the
non-root entrypoint could not replace it because / is owned by root.

- Update compile_entrypoint to recreate /workspace via sudo when running
  as the container user, or directly when running as root
- Add unit test covering sudo/root symlink creation
- Update OpenSpec change docs with the additional root cause

Quality gates:
- pytest tests/unit: 208 passed
- ruff: clean on changed files
- mypy: clean on changed files
- alembic heads: single head

openspec/.pi-map.index.md

@@ -2,7 +2,7 @@
 dir: openspec
 
 ## role
-Defines a living documentation methodology and configuration for managing software requirements, specifications, and development workflows within a project repository.
+Defines the OpenSpec methodology and configuration for managing software requirements, specifications, and task tracking as living documentation within a project repository.
 ## parent
 index: ./.pi-map.index.md
 map: ./.pi-map.md

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

@@ -2,7 +2,7 @@
 dir: openspec/changes
 
 ## role
-Manages change tracking and versioning for OpenAPI specification modifications
+Manages and tracks specification changes, diffs, and versioning history for OpenAPI documents.
 ## parent
 index: openspec/.pi-map.index.md
 map: openspec/.pi-map.md

openspec/changes/fix-pi-container-mount-permissions/.pi-map.index.md

@@ -2,7 +2,7 @@
 dir: openspec/changes/fix-pi-container-mount-permissions
 
 ## role
-Documents a bug fix for resolving permission issues with Pi container repository mounts and npm updates in a development environment.
+Documents a bug fix for resolving permission issues with Pi container repository mounts and npm updates in a configurable home directory environment.
 ## parent
 index: openspec/changes/.pi-map.index.md
 map: openspec/changes/.pi-map.md

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

@@ -4,14 +4,14 @@ dir: openspec/changes/fix-pi-container-mount-permissions
 index: openspec/changes/fix-pi-container-mount-permissions/.pi-map.index.md
 
 ## role
-Documents a bug fix for resolving permission issues with Pi container repository mounts and npm updates in a development environment.
+Documents a bug fix for resolving permission issues with Pi container repository mounts and npm updates in a configurable home directory environment.
 ## files
-- change.md | Documents a bug fix for pi-agent container repository mounting and npm update permissions in a development environment system. | dep: Alembic, manifest_compiler.py, instance_service.py, pytest, ruff, mypy, npm
+- change.md | Documents a bug fix for pi-agent container repository mount paths and npm update permissions in a configurable home directory system. | dep: Alembic, manifest_compiler.py, instance_service.py, Docker compose, npm, pytest
 - tasks.md | Tracks completion status of tasks for fixing a Pi container repository mount and npm update permissions issue
 ## arch
-Simple documentation-based change tracking using markdown files for issue description (change.md) and task checklist (tasks.md) without code implementation.
+Change-request documentation pattern using markdown files for specification (change.md) and task tracking (tasks.md) with checkbox-based completion status.
 ## tags
-npm, tasks, container, repository, update, permissions, py, change
+npm, tasks, container, repository, mount, update, permissions, py
 ## symbols
 -
 ## workflows

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

@@ -10,6 +10,7 @@ After implementing configurable tool container home directories, new `pi-agent`
 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.
 
 ## Fix
 
@@ -22,6 +23,7 @@ After implementing configurable tool container home directories, new `pi-agent`
    - 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.
 3. Update `instance_service.py` to pass `REPO_NAME` and `WORKSPACE_NAME` into manifest compilation.
 4. Update unit tests for the new behavior.