Non-GitHub CI recipes run python -m pip from the untrusted checkout, so a PR-supplied pip/ package can execute before install

[pengfei-threemoonslab]

Observed

Found in review of #786 (#780) on 2026-09-14. The composite GitHub Action ran python -m pip install "agents-shipgate==${SHIPGATE_VERSION}" with the PR checkout as the working directory; python -m puts the current directory first on sys.path, so a pip/__main__.py added by the change executed before the engine was installed (reproduced with the published 1.0.0 venv). #786 fixes the Action with python -P; this issue covers the same pattern in the other recipes, which #786 deliberately does not change.

On main (45d6ca7a) the same command runs from the repository checkout in:

• examples/gitlab-ci/01-advisory.yml, 02-strict-with-baseline.yml, 03-sarif-or-artifact.yml, 04-multi-config-workspace.yml (python -m pip install "agents-shipgate==1.0.0")
• examples/circleci/01-advisory.yml … 04-multi-config-workspace.yml (same)
• docs/integrations.md GitLab, CircleCI and Jenkins snippets (python -m pip install --pre "agents-shipgate==1.0.0", sh 'python -m pip install agents-shipgate')

Not reproduced on those CI systems; the mechanism is the Python start-up behaviour already reproduced for the Action.

Why it matters — and its limit

A change can replace pip (or later shadow agents_shipgate in any python -m/python - step run from the checkout) and forge the review output. The practical reach is narrower than the Action's: on GitLab and CircleCI the pipeline definition itself usually comes from the proposed change, so an untrusted contributor can often edit the job directly. The exposure matters where the configuration is trusted but the checkout is not (protected/parent pipelines, pipeline-from-default-branch setups, Jenkins shared libraries). The recipes should not add a code-execution path the maintainer did not choose.

Proposed

Use python -P -m pip install … (Python ≥ 3.11; the CLI requires 3.12) or pipx/uv tool from a neutral working directory in every non-GitHub recipe and integration snippet, and say in docs/integrations.md which file must come from a trusted source. Keep the pinned versions and the existing pin-sweep tests.

Acceptance

• Every CI recipe and integration snippet that installs or runs Agents Shipgate from a checkout avoids importing from the working directory (-P or an equivalent neutral cwd).
• A test fails if a recipe reintroduces python -m pip / python - without -P in a checkout directory (mirroring the static rule Add a host-only advisory PR recipe with no manifest or baseline (#780) #786 adds for action.yml).
• The integration docs state the trust assumption (pipeline configuration vs checkout contents) for each CI system.

Sequencing

P2 under #778's reliability reserve; not a prerequisite for the advisory pilot, which uses the local CLI or the GitHub Action. Related #780, #786.

[pengfei-threemoonslab]

Days 1–5 implementation is in PR #870. All eight GitLab/CircleCI recipes and the installation snippets use safe-path Python installation; current pins are preserved. The integration docs explain trusted GitLab/CircleCI/Jenkins configuration, PATH/PYTHONPATH and editable-build limits. Fourteen focused tests pass, including quoted/qualified command regression controls and actual synthetic pip.py shadowing controls. Two coding-agent review/address rounds completed; committed-ref verifier and current-control read pass. All applicable hosted CI checks now pass on final head 0201577, and the PR is ready for maintainer review. The isolated 41-test replay also passes; the original local failure was the machine-wide Git ignore rule, with no product change required. This closes the recipe scope on merge, not a claim of hosted security validation for those CI services.