Target-repo toolchains in the sandbox

readme2demo runs OTHER projects' quickstarts. The base image ships common toolchains; the agent installs anything else. Two recurring hazards, both with agent-prompt rules AND code defenses.

Version currency (failure class 2)

The agent's training data is STALE — languages/tools newer than it remembers almost certainly exist. prompts/agent.md rule 4: never declare a version "unreleased"; CHECK the official source (curl -sL 'https://go.dev/VERSION?m=text', pyenv install --list, npm view <pkg> version) then download it. Keep the base image's Go current (built from the official tarball) so the common case needs no download.

Install patterns the agent uses (and that must survive verify)

• Python externally-managed sandbox → pip install --break-system-packages (and --no-input). Editable installs (pip install -e .) are cwd-sensitive — see below.
• Go: go build with a current toolchain; GOTOOLCHAIN pitfalls handled by shipping a new-enough Go.
• Binaries fetched by curl+unzip go to ~/.local/bin or ~/bin on PATH.

cwd drift (failure class 6)

cd persists across script lines. The classic bug: cd /tmp to unpack a binary, then pip install -e . editable-installs /tmp instead of the repo. prompts/distill.md rule 5b requires a cd on/before any relative-path line; verify.cwd_hints runs a static cwd simulation of a failing script and injects precise hints into the distiller retry. The repo is always at /work.

Findings tools (failure class 4)

Linters, drift detectors, scanners (tfdrift, etc.) exit NONZERO when they find what the demo exists to show. The assertion block uses set +e + pattern-as-criterion; normalize.mark_findings_success reclassifies such entries as successful so they count for grounding, the tape, and the payoff step. When adding language support, remember success ≠ exit 0 for this class.

Extending support

Add a toolchain to images/base/Dockerfile only if it's common across target repos (keep the image lean; the agent can install niche tools). Per-ecosystem slim images are a known future optimization, not the MVP.