A test that runs agac runs the tree it lives in (1270)

[Muizzkolapo]

Description

Stacked on #1313 (#1275).

Validated, not trusted

• Several integration tests run Path(sys.executable).parent / "agac": true. Nine launches in six files; _agac in test_retry_selection_under_batch.py serves three more.
• That script imports agent_actions from wherever the editable install points: true. With PYTHONVERBOSE, the console script run from a worktree loads agent_actions/__init__ from the main checkout, and the worktree's once PYTHONPATH names it. From a neutral cwd, import agent_actions resolves to the main checkout too.
• With the main checkout behind, all four tests of test_a_batch_action_keeps_no_row_its_guard_filters.py fail on a worktree that holds their fix: true. The main checkout was 41 commits behind. With PYTHONPATH unset, the files that run agac gave 4 failed, exactly those, 155 passed and 1 xfailed. With it set, the four pass.
• In-process CliRunner tests are unaffected: true. They use the pytest process's path, which pytest.ini sets.
• "The subprocess gets no PYTHONPATH": partly. The launches inherit os.environ, so a PYTHONPATH set on the command line reaches them. pytest.ini's pythonpath never becomes an environment variable.
• The suggested [sys.executable, "-m", "agent_actions.cli.main"] would not fix it. The tests run the CLI from a copy of the project, and -m puts that directory on the path, not the tree. From a directory outside the tree, python -m agent_actions.cli.main --version loads the main checkout.

Root cause

A console script's path is its bin directory, then site-packages, where the editable install's .pth names the main checkout. pytest.ini's pythonpath = . changes only the pytest process's path and never reaches a subprocess.

The fix

• One launcher. tests/_support/agac_cli.py::run_agac runs the console script with the tree the tests live in first on PYTHONPATH. All nine launches call it, and the shared _agac and _run_workflow helpers wrap it. The console script stays: -m would not help, and it is what users run.
• A PYTHONPATH already set stays, behind the tree, whether inherited or passed in env=.
• A probe. agac list-udfs imports a tool that records agent_actions.__file__ from inside the CLI process, and the test asserts it is this tree's. It runs with PYTHONPATH cleared, and with a decoy agent_actions on PYTHONPATH that raises on import. A PYTHONPATH entry outranks the editable install, so this fails in CI too if the tree is not first or the entry is lost.
• An audit. An AST walk fails on any test outside tests/manual that names agac or agent_actions.cli.main as a string of its own, or hands a call a command line starting with agac, positionally or as args=. A positive control shows it finds nine launch shapes.

Behaviour changes, stated

• Test-only: no package code changed. The changelog entry is filed under "Under the Hood".
• A test that runs agac as a subprocess now imports agent_actions from its own tree, with or without PYTHONPATH. In CI and the main checkout the tree is the editable install, so nothing changes there.
• Launches that passed no env now get os.environ plus PYTHONPATH. The timeout stays 300 s.
• A test outside tests/manual that launches agac without run_agac fails the audit.

Not covered here

• Tests that start sys.executable -c subprocesses (in test_topological_sort_is_deterministic.py, test_inferred_dependency_order_is_deterministic.py and test_cli_hardening.py) get the tree only from the cwd; two also drop PYTHONPATH. Run from another directory, they import the editable install.
• The tests/manual smoke runner runs the agac on PATH. It is exempt from the audit because it is run by hand.

Related Issue

Fixes #1270

Type of Change

• Bug fix

Checklist

• I have added a changelog entry (task changelog:new)
• I have added/updated tests as needed
  • tests/integration/test_a_cli_test_runs_the_tree_it_lives_in.py:
    • the agac a test runs imports agent_actions from this tree;
    • a PYTHONPATH already set, inherited or passed, stays on the path behind this tree;
    • the audit finds agac launched in each of nine shapes;
    • no test launches agac but through the shared launcher.
  • The six files that launched agac themselves now call run_agac.
• task check passes (ruff, format, mypy)
• task test passes on this stack (12687 passed at the top of A retry resumes a halted action in full instead of narrowing it (1267) #1327 (agac retry completes a halted action on the records it names, never answering the ones past the halt #1267); only the 8 known sandbox failures; agac subprocess tests run with PYTHONPATH set). At this branch's tip, its own tests and the cli, workflow, processing and llm/batch unit suites pass.

Verification

• RED first: on the parent, with PYTHONPATH unset, the probe fails because the CLI process imported the main checkout's agent_actions/__init__.py. With PYTHONPATH set it passes, which is the masking the issue describes. With the fix, every file that runs agac passes with PYTHONPATH unset, where four tests failed before.
• Mutation: each mutant was run with PYTHONPATH unset, set to the tree, and set to the main checkout, and each is killed in all three:
  • removing the fix;
  • putting an inherited entry first, or dropping it;
  • applying the caller's env after PYTHONPATH;
  • resolving the tree one level too shallow;
  • an audit that never matches (all nine shape cases fail), the old one-line regex (six fail), and one that ignores args=.
• Review (two lenses): YES_WITH_ISSUES from both. Addressed:
  • the audit was a regex that missed with_name("agac"), -m agent_actions.cli.main, a wrapped list and a shell string, while the docs said it caught any other launch;
  • the audit had no positive control;
  • a regression inside the launcher was caught only in a second worktree with PYTHONPATH unset, and a dropped PYTHONPATH not at all;
  • a PYTHONPATH passed in env= was dropped;
  • the tests/manual exemption matched any folder named manual.
  • Declined: filing the changelog as "Bug Fix", since no package user sees a difference and the repo files test-infrastructure changes under the hood; and the python -c subprocesses, which are outside this issue's console-script scope.

Restacked onto #1313

• One commit added. tests/unit/cli/test_a_documented_command_exists.py (The run-modes page retries a batch action with agac retry (1279) #1310, The run-modes page documents an agac batch retry command that does not exist #1279) names agac as a string while it walks the command tree in-process, and launches nothing. The audit read that as a launch and failed on it (1 failed, 12 passed). The commit exempts that one file, and tests/integration/README.md says why. The audit is not weakened otherwise; if the file is renamed, the audit fails again.