[awf] Node.js not found in chroot when RUNNER_TOOL_CACHE is /home/runner/work/_tool

[lpcox]

Problem

When setup-node installs Node.js to /home/runner/work/_tool/node/22.22.3/x64/bin/ (instead of the standard /opt/hostedtoolcache/), the node binary is not accessible inside the AWF chroot. This causes the agent to fail with exit code 127:

[entrypoint][ERROR] Copilot CLI requires Node.js, but 'node' is not available inside AWF chroot.
[entrypoint][ERROR] Ensure Node.js is installed on the runner and reachable from PATH inside the chroot.
[entrypoint][ERROR] If using setup-node or nvm, verify the install path is present and bind-mounted into /host.

Root Cause

AWF bind-mounts /opt:ro into the chroot (which covers the standard /opt/hostedtoolcache location). It also mounts the workspace directory (/home/runner/work/<repo>/<repo>). However, some runners use RUNNER_TOOL_CACHE=/home/runner/work/_tool — a sibling of the workspace that falls outside AWF's default bind mounts.

The agent command already tries to handle this with:

export PATH="$(find /opt/hostedtoolcache /home/runner/work/_tool -maxdepth 5 -type d -name bin 2>/dev/null | tr '\n' ':')$PATH"

But /home/runner/work/_tool does not exist inside the chroot because it was never mounted.

Why it works on most runners

Standard GitHub-hosted runners use /opt/hostedtoolcache which is covered by AWF's /opt:ro bind mount. This issue only manifests on runners where the tool cache lives under /home/runner/work/_tool/.

Proposed Solution

Detect RUNNER_TOOL_CACHE (or fall back to known paths) and add an explicit --mount for the tool cache directory:

# In the AWF invocation script, before calling sudo awf:
GH_AW_TOOL_CACHE_MOUNT=""
TOOL_CACHE="${RUNNER_TOOL_CACHE:-/opt/hostedtoolcache}"
if [[ "$TOOL_CACHE" != /opt/* ]] && [[ -d "$TOOL_CACHE" ]]; then
  GH_AW_TOOL_CACHE_MOUNT="--mount ${TOOL_CACHE}:${TOOL_CACHE}:ro"
fi

Then include ${GH_AW_TOOL_CACHE_MOUNT} in the sudo -E awf ... invocation.

This ensures node (and python, go, etc.) installed via setup-* actions are accessible inside the AWF chroot regardless of where the runner places its tool cache.

Diagnostic Run

• Failed run: https://github.com/github/gh-aw/actions/runs/26630650601/job/78478394967#step:26:1
  • Runner uses /home/runner/work/_tool/ as tool cache
  • setup-node installs to /home/runner/work/_tool/node/22.22.3/x64/bin/
  • Node is available on the host (used by MCP gateway startup) but not inside AWF chroot

Additional Context

• AWF version: v0.25.56
• The GH_AW_NODE_BIN env var is set correctly on the host (command -v node resolves), but the path points into the unmounted tool cache directory
• The find /opt/hostedtoolcache /home/runner/work/_tool fallback in the agent command cannot find the directories because they don't exist in the chroot filesystem