# 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`:
```bash
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

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