feat(runtime): cap spawned child agents

[ousamabenyounes]

Fixes #222.

Summary

• Adds STRIX_MAX_CHILD_AGENTS as a runtime setting (0 means unlimited).
• Enforces the cap in the shared child-spawn path before factory/session work starts.
• Returns a structured tool error when the limit is reached, leaving the existing agent graph unchanged.
• Documents the new environment variable.

Test verification (RED -> GREEN)

RED on origin/main with only the regression test added:

$ uv run pytest tests/test_execution.py::test_spawn_child_agent_respects_child_limit -q
E   TypeError: spawn_child_agent() got an unexpected keyword argument 'max_child_agents'
1 failed

GREEN after the fix:

$ uv run pytest tests/test_execution.py::test_spawn_child_agent_respects_child_limit tests/test_config_loader.py::test_max_child_agents_env_alias -q
2 passed

Fix-reverted proof:

$ git apply -R /tmp/strix-issue-222-fix.patch && uv run pytest tests/test_execution.py::test_spawn_child_agent_respects_child_limit -q
E   TypeError: spawn_child_agent() got an unexpected keyword argument 'max_child_agents'
1 failed

Validation

• uv run pytest tests/test_execution.py tests/test_config_loader.py tests/test_runner_root_prompt.py tests/test_runner_rate_limit.py -q -> 51 passed, 2 warnings
• uv run ruff check strix/core/execution.py strix/core/runner.py strix/config/settings.py tests/test_execution.py tests/test_config_loader.py tests/test_runner_root_prompt.py tests/test_runner_rate_limit.py -> pass
• uv run ruff format --check strix/core/execution.py strix/core/runner.py strix/config/settings.py tests/test_execution.py tests/test_config_loader.py tests/test_runner_root_prompt.py tests/test_runner_rate_limit.py -> pass
• uv run mypy strix/core/execution.py strix/core/runner.py strix/config/settings.py tests/test_execution.py tests/test_config_loader.py tests/test_runner_root_prompt.py tests/test_runner_rate_limit.py -> pass
• uv run bandit -q -c pyproject.toml strix/core/execution.py strix/core/runner.py strix/config/settings.py -> pass

[greptile-apps]

Greptile Summary

Adds a configurable scan-wide child-agent spawn cap.

• Defines and documents STRIX_MAX_CHILD_AGENTS, with zero representing unlimited spawning.
• Threads the setting through the runner into the shared child-spawn path.
• Rejects over-limit spawn requests before factory and session setup.
• Adds configuration and execution regression coverage and updates runner test fixtures.

Confidence Score: 3/5

The child-agent cap needs atomic capacity enforcement before this PR is safe to merge because concurrent spawn requests can exceed the configured limit.

The implementation checks graph size separately from coordinator-locked registration, allowing multiple asynchronous agents to approve requests against the same available slot.

Files Needing Attention: strix/core/execution.py

Important Files Changed

Filename	Overview
strix/core/execution.py	Adds cap enforcement to child spawning, but the count and registration are not atomic and concurrent requests can exceed the cap.
strix/core/runner.py	Threads the validated runtime setting into the shared spawn closure.
strix/config/settings.py	Adds a non-negative runtime setting with the documented environment alias and unlimited default.
tests/test_execution.py	Covers sequential rejection at the limit but does not exercise concurrent boundary requests.
docs/advanced/configuration.mdx	Documents the new environment variable and its zero-as-unlimited behavior.

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
strix/core/execution.py:240-242
**Non-atomic child capacity check**

When two agents request children near the configured limit, both calls can count the graph before either awaited registration records its child, causing the scan to spawn more child agents than `STRIX_MAX_CHILD_AGENTS` permits.

_{Reviews (1): Last reviewed commit: "feat(runtime): cap spawned child agents" | Re-trigger Greptile}

[ousamabenyounes]

Fixed Greptile's concurrency finding in 9d32b75.

What changed:

• Moved the child-agent capacity check and registration into a single coordinator method guarded by the coordinator lock.
• Added a regression test that starts two concurrent spawn requests while STRIX_MAX_CHILD_AGENTS=1; only one can reserve/register now.

Validation:

• uv run pytest tests/test_execution.py::test_concurrent_spawn_child_agent_reserves_limit_atomically tests/test_execution.py::test_spawn_child_agent_respects_child_limit -q -> 2 passed
• uv run pytest tests/test_execution.py tests/test_config_loader.py tests/test_runner_root_prompt.py tests/test_runner_rate_limit.py -q -> 52 passed, 2 warnings
• uv run ruff check strix/core/agents.py strix/core/execution.py strix/core/runner.py strix/config/settings.py tests/test_execution.py tests/test_config_loader.py tests/test_runner_root_prompt.py tests/test_runner_rate_limit.py -> passed
• uv run ruff format --check strix/core/agents.py strix/core/execution.py strix/core/runner.py strix/config/settings.py tests/test_execution.py tests/test_config_loader.py tests/test_runner_root_prompt.py tests/test_runner_rate_limit.py -> passed
• uv run mypy strix/core/agents.py strix/core/execution.py strix/core/runner.py strix/config/settings.py tests/test_execution.py tests/test_config_loader.py tests/test_runner_root_prompt.py tests/test_runner_rate_limit.py -> passed
• uv run bandit -q -c pyproject.toml strix/core/agents.py strix/core/execution.py strix/core/runner.py strix/config/settings.py -> passed

[ousamabenyounes]

Rebased this branch on top of current main and resolved the tests/test_execution.py conflict by preserving the newer upstream imports and the child-agent limit tests from this PR.

Validation after rebase:

uv run pytest tests/test_execution.py::test_concurrent_spawn_child_agent_reserves_limit_atomically tests/test_execution.py::test_spawn_child_agent_respects_child_limit -q
2 passed in 5.74s

uv run pytest tests/test_execution.py tests/test_config_loader.py tests/test_runner_root_prompt.py tests/test_runner_rate_limit.py -q
56 passed, 2 warnings in 5.23s

uv run ruff check strix/core/agents.py strix/core/execution.py strix/core/runner.py strix/config/settings.py tests/test_execution.py tests/test_config_loader.py tests/test_runner_root_prompt.py tests/test_runner_rate_limit.py
All checks passed!

uv run ruff format --check strix/core/agents.py strix/core/execution.py strix/core/runner.py strix/config/settings.py tests/test_execution.py tests/test_config_loader.py tests/test_runner_root_prompt.py tests/test_runner_rate_limit.py
8 files already formatted

uv run mypy strix/core/agents.py strix/core/execution.py strix/core/runner.py strix/config/settings.py tests/test_execution.py tests/test_config_loader.py tests/test_runner_root_prompt.py tests/test_runner_rate_limit.py
Success: no issues found in 8 source files

uv run bandit -q -c pyproject.toml strix/core/agents.py strix/core/execution.py strix/core/runner.py strix/config/settings.py