diff --git a/docs/scratchpads/561-python-is-python3.md b/docs/scratchpads/561-python-is-python3.md new file mode 100644 index 0000000..a81db0e --- /dev/null +++ b/docs/scratchpads/561-python-is-python3.md @@ -0,0 +1,33 @@ +# Issue #561 — Bare python on agent hosts + +## Objective + +Make the durable bootstrap/provisioning guidance ensure agent hosts provide a bare `python` command that resolves to Python 3. + +## Scope + +- Add Debian/Ubuntu `python-is-python3` to agent-host prerequisites in bootstrap docs. +- Check for actual OS package provisioning scripts and update only if an existing agent-host package install path exists. +- Do not touch live host state. +- Do not update `docs/TASKS.md`; repo guidance says workers read it but never modify it. + +## Recon + +- Issue #561 confirms repeated `python: command not found` failures from fleet agents that emit `python foo.py`. +- `guides/BOOTSTRAP.md` and `packages/mosaic/framework/guides/BOOTSTRAP.md` are the source and packaged framework copies of the bootstrap guide. +- Targeted repo sweep found no agent-host Debian package provisioning script. Existing `apt-get install` hits are CI/test helper paths or unrelated deployment docs. + +## Plan + +1. Add a host prerequisite section to both bootstrap guide copies. +2. Include `python-is-python3` in the Debian/Ubuntu package list with an issue comment. +3. Note the non-Debian equivalent as a `/usr/bin/python -> python3` symlink. +4. Validate markdown/diff, run shell syntax checks where applicable, run required review, commit, queue guard, and push. + +## Validation Log + +- `rg` recon: no existing agent-host Debian package provisioning script; only CI/test helper `apt-get install` paths and unrelated deployment docs. +- `git diff --check`: passed. +- `bash -n packages/mosaic/framework/install.sh tools/install.sh packages/mosaic/framework/tools/bootstrap/init-project.sh packages/mosaic/framework/tools/_scripts/mosaic-bootstrap-repo`: passed. No touched shell scripts. +- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted`: approved, 0 findings. +- `pnpm format:check`: initially blocked because `node_modules` was absent and `prettier` was unavailable; `pnpm install --frozen-lockfile` initially hit an invalid `/root` pnpm store path. Reran install with `--store-dir /home/hermes/agent-work/.pnpm-store`, then `pnpm format:check` passed. diff --git a/guides/BOOTSTRAP.md b/guides/BOOTSTRAP.md index b750eb4..f80fd5d 100755 --- a/guides/BOOTSTRAP.md +++ b/guides/BOOTSTRAP.md @@ -15,6 +15,22 @@ This guide covers how to bootstrap a project so AI agents (Claude, Codex, etc.) 7. Branching/merging is consistent: `branch -> main` via PR with squash-only merges 8. Steered-autonomy execution is enabled so agents can run end-to-end with escalation-only human intervention +## Agent Host Prerequisites + +Agent hosts must provide the Python runtime shape that runtime agents and +Mosaic automation assume is present. + +For Debian/Ubuntu hosts: + +```bash +sudo apt-get update +# #561: bare python invocations from agents must resolve. +sudo apt-get install -y python3 python-is-python3 +``` + +For non-Debian hosts, install the equivalent Python 3 runtime and ensure +`/usr/bin/python` resolves to `python3` (for example, via a managed symlink). + ## Quick Start ```bash diff --git a/packages/mosaic/framework/guides/BOOTSTRAP.md b/packages/mosaic/framework/guides/BOOTSTRAP.md index d6b5c45..edf93cb 100755 --- a/packages/mosaic/framework/guides/BOOTSTRAP.md +++ b/packages/mosaic/framework/guides/BOOTSTRAP.md @@ -15,6 +15,22 @@ This guide covers how to bootstrap a project so AI agents (Claude, Codex, etc.) 7. Branching/merging is consistent: `branch -> main` via PR with squash-only merges 8. Steered-autonomy execution is enabled so agents can run end-to-end with escalation-only human intervention +## Agent Host Prerequisites + +Agent hosts must provide the Python runtime shape that runtime agents and +Mosaic automation assume is present. + +For Debian/Ubuntu hosts: + +```bash +sudo apt-get update +# #561: bare python invocations from agents must resolve. +sudo apt-get install -y python3 python-is-python3 +``` + +For non-Debian hosts, install the equivalent Python 3 runtime and ensure +`/usr/bin/python` resolves to `python3` (for example, via a managed symlink). + ## Quick Start ```bash