Files

T

Developer ddd92e3dd4 feat: implement configurable tool container home directory

- Add ToolType.home_directory column with default /home/user
- Add Alembic migration to add column, set existing rows, and rewrite
  /workspace to /home/user/{{WORKSPACE_NAME}} in legacy templates
- Add merge migration fc8f1a20cbf6 to resolve Alembic multiple heads
- Update manifest compiler to honor manifest.home_directory for HOME,
  WORKDIR, /workspace symlink, and default repo mount target
- Update legacy dockerfile/compose instance generation to use
  tool_type.home_directory
- Thread resolved home_dir through config profile and git mount expansion
- Generate entrypoint permission fixer to chown home/mounts at startup
- Update base.dockerfile with sudo/passwordless sudo for permission fixer
- Add unit tests for manifest compiler, instance service, and migrations
- Add placeholder integration test for container lifecycle
- Update openspec/tasks/home-path-expansion.md task checkboxes
- Update project maps for modified files

Quality gates: py_compile, ruff, mypy, pytest tests/unit (205 passed),
pytest tests/integration (110 passed, 35 skipped). Alembic round-trip
and container lifecycle integration tests require Docker/PostgreSQL.

2026-06-14 13:09:41 +00:00

3.7 KiB

Raw Blame History

Handoff: Tool Container Home Directory

Session context

Original request: make tool container workspace/home directory default to /home/user, keep it user-writable, and preserve repo root directory name in the mount target.
Completed a Grill Me session that resolved design decisions.
Phase 1 implementation was started but blocked by persistent Grill Me read-only guard.

Current branch

feat/tool-container-home-directory (created from dev)

Committed artifacts on `dev`

docs: tool container home directory design, plan, and test plan
chore: update project maps for tool container home directory artifacts

Files already created/edited on `feat/tool-container-home-directory`

apps/api/src/models/tool/tool_type.py
- Added home_directory: Mapped[str] column, default "/home/user".
apps/api/alembic/versions/2026_06_14_104415_add_tool_type_home_directory.py
- Adds column, sets existing rows to /home/user.
- Rewrites /workspace to /home/user/{{WORKSPACE_NAME}} in compose_template and dockerfile_template.
- Provides reversible downgrade.

Design decisions resolved

Area	Decision
Config surface	`home_directory` field on ToolType / manifest schema
Default	`/home/user`
Runtime user	Still `manifest.user.name`
Mount target	`{home_directory}/{repo_name}` or `{home_directory}/{workspace_name}`
Precedence	Explicit manifest repo mount target wins; `home_directory` fills in default
Migration	Alembic data migration for legacy ToolType templates
Compatibility	`/workspace` symlink to actual repo/workspace target
Permissions	Entrypoint permission fixer at container startup
Tests	Unit + integration tests

Pending work

Phase 1 verification

Run in apps/api:

python -m alembic current
python -m alembic upgrade head
python -m alembic downgrade -1
python -m alembic upgrade head

Phase 2: Manifest compiler

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

Honor manifest.home_directory in get_manifest_home_dir().
Set ENV HOME={home_directory}, ENV USER={user.name}, WORKDIR {home_directory}.
Create /workspace symlink step.
Use {home_directory}/{repo_name} as default repo mount target when no explicit repo mount exists.

Phase 3: Legacy instance generation

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

Use tool_type.home_directory for dockerfile tool mounts.
Add WORKSPACE_NAME/HOME_DIRECTORY template variables for compose tools.

Phase 4: Config-profile / git mount expansion

Files: apps/api/src/services/tool/instance_service.py, apps/api/src/services/config/config_profile_resolver.py

Thread resolved home_dir through startup.

Phase 5: Entrypoint permission fixer

Files: apps/api/src/services/build/manifest_compiler.py, apps/api/src/services/shared/permission_fixer.py, tool-images/base.dockerfile

Generate startup script that chowns {home_directory} and key mounts to container user.

Phase 6: Tests

Create/expand:

apps/api/tests/unit/test_home_path_expansion.py
apps/api/tests/unit/test_manifest_compiler.py
apps/api/tests/unit/test_instance_service.py
apps/api/tests/unit/test_alembic_migrations.py
apps/api/tests/integration/test_tool_instance_lifecycle.py

Reference docs

openspec/designs/tool-container-home-directory.md
docs/superpowers/plans/tool-container-home-directory.md
docs/superpowers/specs/tool-container-home-directory-test-plan.md
openspec/tasks/home-path-expansion.md

Next action for fresh session

Ensure you are on feat/tool-container-home-directory.
Verify Phase 1 migration round-trip.
Continue with Phase 2 (manifest compiler).

3.7 KiB Raw Blame History