[Lesereingrape]

Fixes #5608

Why

SubagentBatchService.submit() resolved the two caller-supplied limits with or (batch_service.py:134-135), which reads an explicit 0 as "not supplied" and substitutes the configured default — so the 1 <= … <= … guards on the very next lines never see the value the caller actually asked for. Measured on main 71087f2f:

{'max_running_items': 0}                        -> accepted, persisted {'max_live_items': 100, 'max_running_items': 3}
{'max_live_items': 1, 'max_running_items': 0}   -> ValueError: max_running_items must not exceed max_live_items
{'max_live_items': -1}                          -> ValueError: max_live_items must be between 1 and 1000

The pain is twofold: a batch_task call that asked for zero concurrent items silently runs three at a time and stores the substituted number as the batch's own limit, and when the caller pairs the 0 with a small max_live_items the request is refused for a reason it did not violate. The third row is the tell — the adjacent negative is reported correctly, so 0 was an accident of or, not a documented "0 means unset" convention (and SubagentBatchesConfig itself declares these knobs ge=1, so the config layer already treats 0 as out of range).

This is the same falsy-vs-unset class as #5555, which this account filed and which is now merged: timeout_seconds written as an explicit 0 there also had to be handled as a value rather than as a blank, and the guard added in that PR deliberately does not swallow 0 (config.py:52 tests value is None or blank-string). This brings submit() to the same rule.

What changed

• Both resolutions now compare against None, so 0 reaches the guard that names it: max_running_items must be between 1 and 64 / max_live_items must be between 1 and 1000. None (absent key, YAML null, the tool's own default) keeps meaning "use the configured default", which is the only behaviour any existing caller depends on.
• Added a four-line comment recording why is None matters here, because the or form is otherwise locally indistinguishable and invites the same regression.
• Tests: test_submit_reports_an_explicit_zero_limit_by_name (3 cases, including the one whose message used to blame the wrong field) and test_submit_defaults_only_the_limits_the_caller_omitted (3 cases pinning that None still defaults and a valid explicit value still wins), next to the existing test_submit_keeps_batch_running_limit_separate_from_one_process_capacity which already asserts the persisted kwargs.

Surface area

submit()'s limit resolution in subagents/batch_service.py (+5/-2) and its test file (+46), nothing else. No schema, persistence, prompt or dependency change: the values written to the batch row are the same fields, and no other function reads request.max_live_items / request.max_running_items. Callers are unaffected for every input that produced a working batch before — the only inputs whose outcome changes are the ones where a 0 was being silently replaced, and both callers (batch_task via batch_task_tool.py:230-231, and the Gateway submit path) already map ValueError from submit() to an error tool result, so the new refusal surfaces as the message the caller can act on rather than as a crash.

Bug fix verification

Reproduction is tests/test_subagent_batch_service.py::test_submit_reports_an_explicit_zero_limit_by_name, which goes red on main and green here. Both runs were done on this branch's base main at 71087f2f, reverting only batch_service.py in place and keeping the new tests:

# main 71087f2f + new tests, fix reverted      (-k "explicit_zero or defaults_only")
3 failed, 3 passed, 5 deselected in 5.84s
FAILED ...::test_submit_reports_an_explicit_zero_limit_by_name[overrides0-max_running_items must be between 1 and 64]
FAILED ...[overrides1-max_running_items must be between 1 and 64]
FAILED ...[overrides2-max_live_items must be between 1 and 1000]
   (DID NOT RAISE <class 'ValueError'>)
# the 3 "defaults only what the caller omitted" cases pass before and after, which is the point

# this branch ebf3c75b
62 passed in 25.54s

The scripted repro in the issue was also re-run against the fix: case 1 and case 2 now both raise max_running_items must be between 1 and 64, case 3 is unchanged.

Validation

cd backend
pytest tests/test_subagent_batch_service.py tests/test_batch_task_tool.py tests/test_subagent_capacity_config.py tests/test_subagent_batch_repository.py tests/test_batch_acceptance.py -q
  -> 62 passed in 25.54s     (56 on main before this PR + the 6 new cases)
ruff check packages/harness/deerflow/subagents/batch_service.py tests/test_subagent_batch_service.py            -> All checks passed!
ruff format --check <those two files>   -> 2 files already formatted

I did not run make test (the whole backend suite): on this Windows machine it has pre-existing environmental failures unrelated to this diff, documented in a comment on #5553, so I ran the five durable-batch suites that cover batch_service.py instead. Related work I checked for overlap: #5253 also edits backend/packages/harness/deerflow/subagents/batch_service.py (+109) — its hunks are in the item teardown/cancel path and none of them touch lines 129-141, so this diff and that one do not overlap in content.

AI assistance

• Tool(s) used: Claude Code (Anthropic), plus a code-search agent pass over subagents/.
• How you used it: the candidate came out of that search. Its claims were then re-checked line by line by the agent against main (batch_service.py:134-135, batch_runtime.py:26-27, batch_task_tool.py:143-144/230-231, subagent_batches_config.py:13-16), and the repro, the fix, both tests and every number above were produced by commands the agent ran on this branch. No human has read this diff yet — it was opened during an unattended contribution run, so the box below is deliberately left unticked; the account owner will read it before this PR is marked ready for review.
• I've read and understand every line of this change and take responsibility for it — it's not unreviewed AI output.

Follow-up (a523818)

Took the non-blocking suggestion from review: the two batch_task arg docstrings now say
when set it must be >= 1, so the constraint is visible in the tool schema the model
reads rather than only in the runtime ValueError.

Re-measured at this head: the same five files still give 62 passed, and ruff check /
ruff format --check over all three changed files
(batch_service.py, batch_task_tool.py, test_subagent_batch_service.py) report
All checks passed! and 3 files already formatted.

[willem-bd]

Reviewed at ebf3c75. The fix is correct and minimal: BatchSubmitRequest.max_live_items/max_running_items are typed int | None (batch_runtime.py), so is None is the right "unset" test and an explicit 0 now reaches the range guard that names it, matching the ge=1 stance SubagentBatchesConfig already takes at the config layer. Independently verified on this head:

• Red/green: with base batch_service.py restored and the new tests kept, all three test_submit_reports_an_explicit_zero_limit_by_name cases fail (DID NOT RAISE ValueError); at head, all 62 tests across test_subagent_batch_service.py, test_batch_task_tool.py, test_subagent_capacity_config.py, test_subagent_batch_repository.py, and test_batch_acceptance.py pass.
• ruff check and ruff format --check are clean on both changed files.
• Blast radius confirmed: the only production caller is batch_task (batch_task_tool.py:221-231), which passes the int | None values through unchanged and already wraps submit() in try/except, so the new refusal surfaces as an error tool result rather than a crash, and no other code reads these two request fields.

Non-blocking: the batch_task arg docstrings ("Optional queued-plus-running item window" / "Optional per-batch real execution concurrency") could eventually state that both values must be >= 1 so a model learns the constraint from the tool schema too — the ValueError message already covers the runtime path. No inline findings; nothing to change in this diff.

[Lesereingrape]

Took the non-blocking suggestion in a523818: both batch_task arg docstrings now say the value must be >= 1 when set, so a model sees the constraint in the tool schema and not only in the runtime ValueError. No functional change — tests/test_subagent_batch_service.py, test_batch_task_tool.py, test_subagent_capacity_config.py, test_subagent_batch_repository.py and test_batch_acceptance.py still give 62 passed, ruff check/format clean. Thanks for running the red/green comparison independently.