From f393a5011834c7c6906065ca7945ea3b8fcc6dbe Mon Sep 17 00:00:00 2001 From: jwbron <8340608+jwbron@users.noreply.github.com> Date: Tue, 17 Feb 2026 06:40:32 +0000 Subject: [PATCH] docs: Document host path translation in orchestrator [doc-updater] Update orchestrator architecture doc to explain the HOST_HOME-based path translation introduced in #806 and add HOST_HOME to the environment variables table. Authored-by: egg --- docs/architecture/orchestrator.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/architecture/orchestrator.md b/docs/architecture/orchestrator.md index bbc24d5e36..4e7a45117d 100644 --- a/docs/architecture/orchestrator.md +++ b/docs/architecture/orchestrator.md @@ -96,6 +96,8 @@ During the `implement` phase, certain `.egg-state/` subdirectories are mounted r The orchestrator calls `ensure_egg_state_dirs()` before spawning containers to create the required directories (bind mounts require existing source paths) and place `.egg-readonly` marker files explaining the restriction and current phase. Then `phase_readonly_mounts()` generates the readonly `MountSpec` entries, which are added alongside the existing `.git` shadow mounts. Only directories that exist on the host are mounted (missing directories are skipped). See `shared/egg_container/__init__.py` and `orchestrator/container_spawner.py`. +**Host path translation:** The gateway returns worktree paths relative to the Docker host (e.g., `/home/jwies/.egg-worktrees/...`), but the orchestrator container only mounts these via `/home/egg/...`. The `_host_to_local_volumes()` helper in `container_spawner.py` uses the `HOST_HOME` env var to translate host paths to orchestrator-accessible local paths for `is_dir()` checks and `ensure_egg_state_dirs()`. Docker mount sources still use the original host paths unchanged. + This architecture ensures the orchestrator reads artifacts from the correct isolated workspace rather than the main repository, preventing cross-contamination between pipelines. See `orchestrator/routes/pipelines.py:WORKTREE_BASE_DIR` and `gateway/worktree_manager.py` for implementation details. @@ -417,6 +419,7 @@ if is_orchestrator_mode(): | `EGG_PIPELINE_ID` | Current pipeline identifier | None | | `EGG_AGENT_ROLE` | Agent role for multi-agent mode | None | | `EGG_PRIVATE_MODE` | Private network mode (set by host wrapper, detected by `egg-sdlc`) | None | +| `HOST_HOME` | Docker host's home directory (e.g., `/home/jwies`); used to translate host worktree paths to orchestrator-accessible paths | None | ### Constants