[awf] agent: Hardcoded /home/runner path breaks self-hosted runners with non-standard home directories

[lpcox]

Problem

gh-aw assumes the runner service account home is /home/runner and that Copilot CLI state lives at /home/runner/.copilot. On self-hosted runners where the service account has a different home (e.g., /home/actions, /var/lib/runner), the agent either fails to find config or attempts to chroot/bind-mount paths that don't exist.

The current workaround requires users to create a compatibility shim that manufactures /home/runner/.copilot and symlinks back to the real runner account — adding fragile infrastructure complexity.

Context

Reported in github/gh-aw#27260.

Root Cause

Several places hardcode /home/runner:

• containers/agent/entrypoint.sh — home directory used for chroot bind mounts and UID/GID remapping
• src/docker-manager.ts — generateDockerCompose() likely hard-codes whitelisted $HOME subdirs (.copilot, .cache, etc.) under /home/runner
• Ownership reset logic assumes runner:runner as the target user

Proposed Solution

1. In src/docker-manager.ts: Replace the hardcoded /home/runner with a runtime-derived value. Read HOME env var (or os.homedir()) at AWF startup and pass it into the Docker Compose config as an env var (e.g., AWF_RUNNER_HOME).
2. In containers/agent/entrypoint.sh: Replace hardcoded /home/runner references with \$\{AWF_RUNNER_HOME:-/home/runner} so the fallback preserves existing behavior.
3. In src/cli.ts: Add a --runner-home <path> CLI flag as an optional override for cases where auto-detection isn't sufficient.
4. Update bind mount list in src/docker-manager.ts: Construct the whitelisted $HOME subdirs dynamically using the resolved runner home path.
5. Add a test in src/docker-manager.test.ts verifying that a non-default HOME value propagates correctly through the generated Docker Compose config.

Generated by Firewall Issue Dispatcher · ● 436.3K · ◷

[lpcox]

Closing — already addressed by PR #2114 (merged), which handles non-standard runner HOME and missing ~/.copilot in the agent mount setup. The code now:

• Uses os.homedir() / HOME env var instead of hardcoding /home/runner
• Gracefully skips .copilot mount when the directory doesn't exist
• Dynamically constructs whitelisted $HOME subdirs based on the actual home path

Included in firewall v0.25.29+.