Mount repo at its exact host path instead of /workspace

On Linux and macOS the repo is now bind-mounted at its real absolute
path (e.g. /home/user/src/myrepo) with the container workdir set to
match. This makes git worktrees work correctly — git stores absolute
host paths in worktree metadata, which now resolve identically inside
the container. It also allows running construct against multiple repos
or worktrees simultaneously without path conflicts.

CONSTRUCT_WORKSPACE_PATH is injected as an env var and expanded into
~/.config/opencode/AGENTS.md at container start so the agent knows
which directory is shared. On Windows Docker Desktop cannot mirror host
paths into the Linux VM, so /workspace is kept as a fallback.

Requires --rebuild to pick up the updated entrypoint in the tool image.

Generated by construct

Author: mtsfoni

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## [Unreleased]
 
+### Changed
+- **Path mirroring: repo mounted at its exact host path** — the container no longer mounts the repo at the fixed path `/workspace`. On Linux and macOS the repo is now mounted at its real absolute path (e.g. `/home/user/src/myrepo`), and the container's working directory is set to that same path. This makes git worktrees work correctly (git stores absolute host paths in worktree metadata, which now resolve identically inside the container), and allows running `construct` against multiple repos or worktrees simultaneously without path conflicts. The agent is informed of the shared path via the `CONSTRUCT_WORKSPACE_PATH` environment variable, which is expanded into `~/.config/opencode/AGENTS.md` at container start. On Windows, Docker Desktop cannot mirror host paths into the Linux VM, so the previous `/workspace` fallback is retained.
+
 ---
 
 ## [v0.9.0] — 2026-03-12

docs/spec/construct-agents-md.md

@@ -35,19 +35,24 @@ You are running inside a construct container.
 
 ## Workspace
 
-`/workspace` is the user's repository, bind-mounted from their machine.
+`<CONSTRUCT_WORKSPACE_PATH>` is the directory shared with the user,
+bind-mounted from their machine at its exact host path.
 Changes you make there are immediately visible to the user.
-This is the only directory shared with the user.
 
 ## Isolation
 
-Everything outside `/workspace` is isolated inside the container.
+Everything outside the shared directory is isolated inside the container.
 Your home directory (`/home/agent`) persists across sessions via a named Docker
 volume, so shell history, tool caches, and config files survive container
 restarts. The user's machine is separate — you cannot reach their localhost and
 they cannot reach yours.
 ```
 
+`CONSTRUCT_WORKSPACE_PATH` is injected as an env var by the runner and expanded
+by the entrypoint shell when writing the file. On Linux/macOS it holds the real
+absolute host path (e.g. `/home/user/src/myrepo`); on Windows it is
+`/workspace` (Docker Desktop fallback).
+
 The networking section (see below) is appended after this block.
 
 ### When `--port` is used (`CONSTRUCT_PORTS` is set)

docs/spec/global-commands.md

@@ -4,7 +4,7 @@
 
 OpenCode loads custom slash commands from two locations:
 
-- **Per-project:** `.opencode/commands/` in the repo root (already works — the repo is bind-mounted at `/workspace`)
+- **Per-project:** `.opencode/commands/` in the repo root (already works — the repo is bind-mounted at its exact host path)
 - **Global:** `~/.config/opencode/commands/` in the user's home directory
 
 The construct agent container has an isolated named Docker volume for `/home/agent`, so the host's `~/.config/opencode/commands/` directory is never visible to the agent. Global slash commands defined on the host are silently absent.

docs/spec/path-mirror.md

@@ -0,0 +1,101 @@
+# Path mirroring: mount the host path at its exact container location
+
+## Problem
+
+The previous approach always mounted the user's repository at the fixed path
+`/workspace` inside the container:
+
+```
+-v /home/user/src/myrepo:/workspace:z  -w /workspace
+```
+
+This creates two related problems:
+
+**1. Git worktrees break.** Git worktrees store their metadata using absolute
+host paths (`/home/user/src/myrepo/.git/worktrees/feature/gitdir`,
+`/home/user/src/myrepo-feat/.git` → `/home/user/src/myrepo/.git`). When the
+container only sees the path as `/workspace`, git cannot resolve these
+cross-references and operations like `git status`, `git log`, and branch
+switching fail.
+
+**2. Multi-repo workflows require re-mounting.** With the serve/client
+architecture, users want to open multiple workspaces (separate repos or
+worktrees) without stopping the host client. The fixed `/workspace` path makes
+it impossible to work in two containers simultaneously where both paths need
+to coexist on the filesystem.
+
+## Solution
+
+On Linux and macOS, mount the host path at its exact absolute location inside
+the container:
+
+```
+-v /home/user/src/myrepo:/home/user/src/myrepo:z  -w /home/user/src/myrepo
+```
+
+The container's working directory is set to the same path. Git's internal path
+references now resolve correctly because the container filesystem mirrors the
+host layout for the mounted subtree.
+
+A `CONSTRUCT_WORKSPACE_PATH` environment variable is injected into the
+container, carrying the container-side path. The entrypoint uses it when
+writing `~/.config/opencode/AGENTS.md` to tell the agent which directory is
+shared with the user.
+
+No `/workspace` symlink or alias is created. The fixed path `/workspace` is
+gone from the container filesystem entirely (on Linux/macOS).
+
+## Windows
+
+On Windows, `os.Getuid()` returns `-1` (Docker Desktop runs containers through
+a Linux VM where host UID/GID have no meaning). Windows paths (`C:\Users\...`)
+have no valid equivalent Linux path, so path mirroring is not applied.
+Windows falls back to the previous behaviour: the repo is mounted at
+`/workspace` and `CONSTRUCT_WORKSPACE_PATH=/workspace`.
+
+## Behaviour
+
+| Platform     | Host path                         | Container mount point             | `-w` workdir                      |
+|---|---|---|---|
+| Linux/macOS  | `/home/user/src/myrepo`           | `/home/user/src/myrepo`           | `/home/user/src/myrepo`           |
+| Linux/macOS  | `/home/user/src/myrepo-feat`      | `/home/user/src/myrepo-feat`      | `/home/user/src/myrepo-feat`      |
+| Windows      | `C:\Users\user\src\myrepo`        | `/workspace`                      | `/workspace`                      |
+
+### Git worktree example
+
+```
+# Host layout
+/home/user/src/
+  myrepo/          ← main worktree  (construct /home/user/src/myrepo)
+  myrepo-feat/     ← linked worktree (construct /home/user/src/myrepo-feat)
+```
+
+Both containers now see the paths that git's worktree metadata references, so
+all git operations work correctly. Each container gets its own home volume
+(home volume name is keyed by SHA256 of the repo path, so they are always
+distinct).
+
+### Opening multiple workspaces
+
+Because each container's working directory is the real host path, users can
+run `construct` against different repos or worktrees simultaneously without
+path conflicts:
+
+```
+construct /home/user/src/projectA    # workdir inside container: /home/user/src/projectA
+construct /home/user/src/projectB    # workdir inside container: /home/user/src/projectB
+```
+
+## Persistence
+
+No changes to persistence. Home volume naming (`construct-home-<tool>-<hex8>`,
+where `hex8` is SHA256 of the absolute repo path) is unchanged.
+
+## Files changed
+
+| File | Change |
+|---|---|
+| `docs/spec/path-mirror.md` | This spec |
+| `internal/runner/runner.go` | Add `containerWorkdir` helper; replace hardcoded `:/workspace:z` + `-w /workspace` in `buildRunArgs`, `buildServeArgs`, `buildDebugArgs`; inject `CONSTRUCT_WORKSPACE_PATH` env var |
+| `internal/runner/runner_test.go` | Tests for `containerWorkdir`; verify `-v` and `-w` flags in build*Args; verify env var injection |
+| `CHANGELOG.md` | Entry under `[Unreleased]` |

internal/runner/runner.go

@@ -353,9 +353,11 @@ func buildRunArgs(cfg *Config, dindInst *dind.Instance, image, sessionID, homeVo
 	// context into ~/.config/opencode/AGENTS.md.
 	args = append(args, "-e", "CONSTRUCT_DOCKER_MODE="+cfg.DockerMode)
 
+	workdir := containerWorkdir(cfg.RepoPath)
 	args = append(args,
-		"-v", cfg.RepoPath+":/workspace:z",
-		"-w", "/workspace",
+		"-v", cfg.RepoPath+":"+workdir+":z",
+		"-w", workdir,
+		"-e", "CONSTRUCT_WORKSPACE_PATH="+workdir,
 	)
 
 	// Mount the host's global opencode commands directory read-only so the
@@ -484,9 +486,11 @@ func buildServeArgs(cfg *Config, dindInst *dind.Instance, image, sessionID, home
 
 	args = append(args, "-e", "CONSTRUCT_DOCKER_MODE="+cfg.DockerMode)
 
+	workdir := containerWorkdir(cfg.RepoPath)
 	args = append(args,
-		"-v", cfg.RepoPath+":/workspace:z",
-		"-w", "/workspace",
+		"-v", cfg.RepoPath+":"+workdir+":z",
+		"-w", workdir,
+		"-e", "CONSTRUCT_WORKSPACE_PATH="+workdir,
 	)
 
 	if cfg.Tool.Name == "opencode" {
@@ -589,9 +593,11 @@ func buildDebugArgs(cfg *Config, dindInst *dind.Instance, image, sessionID, home
 
 	args = append(args, "-e", "CONSTRUCT_DOCKER_MODE="+cfg.DockerMode)
 
+	workdir := containerWorkdir(cfg.RepoPath)
 	args = append(args,
-		"-v", cfg.RepoPath+":/workspace:z",
-		"-w", "/workspace",
+		"-v", cfg.RepoPath+":"+workdir+":z",
+		"-w", workdir,
+		"-e", "CONSTRUCT_WORKSPACE_PATH="+workdir,
 	)
 
 	if cfg.Tool.Name == "opencode" {
@@ -901,21 +907,21 @@ func generatedEntrypoint() string {
 		"# to inform the agent that it is running inside a construct container.\n" +
 		"# The networking section depends on CONSTRUCT_DOCKER_MODE.\n" +
 		"mkdir -p \"${HOME}/.config/opencode\"\n" +
-		"cat > \"${HOME}/.config/opencode/AGENTS.md\" << 'AGENTSEOF'\n" +
+		"cat > \"${HOME}/.config/opencode/AGENTS.md\" << AGENTSEOF\n" +
 		"# Construct container context\n" +
 		"\n" +
 		"You are running inside a construct container.\n" +
 		"\n" +
 		"## Workspace\n" +
 		"\n" +
-		"`/workspace` is the user's repository, bind-mounted from their machine.\n" +
+		"\\`${CONSTRUCT_WORKSPACE_PATH}\\` is the directory shared with the user,\n" +
+		"bind-mounted from their machine at its exact host path.\n" +
 		"Changes you make there are immediately visible to the user.\n" +
-		"This is the only directory shared with the user.\n" +
 		"\n" +
 		"## Isolation\n" +
 		"\n" +
-		"Everything outside `/workspace` is isolated inside the container.\n" +
-		"Your home directory (`/home/agent`) persists across sessions via a named Docker\n" +
+		"Everything outside the shared directory is isolated inside the container.\n" +
+		"Your home directory (\\`/home/agent\\`) persists across sessions via a named Docker\n" +
 		"volume, so shell history, tool caches, and config files survive container\n" +
 		"restarts. The user's machine is separate — you cannot reach their localhost and\n" +
 		"they cannot reach yours.\n" +