feat(cron): per-job max_turns and wall-clock timeout caps for cron jobs

[fabiosiqueira]

What does this PR do?

Adds optional per-job max_turns and wall-clock timeout ceilings to cron jobs.

Today a cron session has no per-job ceiling: max_turns is global-only (config.yaml agent.max_turns) and the only runtime guard — the HERMES_CRON_TIMEOUT inactivity watcher — never fires during retry storms, because every retry touches the activity tracker ("API error recovery"). An unattended agentic cron job stuck retrying can therefore keep calling the API for hours with no ceiling. These caps give each job an independent, opt-in budget.

Related Issue

Implements #63267 (feat: per-job max_turns for cron jobs).

Also relevant to #82813 / #82815: the turn ceiling here now resolves through hermes_cli.config.resolve_turn_limit() at both the per-job and the global level, so max_turns: none / unlimited / an explicit 0 are honored in the cron path too rather than being swallowed by an or chain.

Type of Change

• ✨ New feature (non-breaking change that adds functionality)
• ♻️ Robustness (retry-storm / runaway-session guard)

Changes Made

• tools/cronjob_tools.py + cron/jobs.py: optional max_turns (int) and timeout (seconds) per job in the schema/tool and create_job / update_job; 0 clears the cap on update; bool/invalid values are rejected (fall back to global config rather than capping at a bogus value).
• cron/scheduler.py: _resolve_job_max_iterations (precedence: per-job > agent.max_turns > max_turns, each normalized by resolve_turn_limit(), so an absent global stays unlimited and the per-job knob never introduces a cron-only default) and _resolve_job_wall_clock_limit; the inactivity watcher gains a wall-clock branch that interrupts the run when total elapsed exceeds the job cap, regardless of activity (so a retry loop that keeps the inactivity watcher alive is still bounded).
• Opt-in: behaviour is unchanged when both fields are unset.
• tests/cron/test_cron_job_caps.py: coverage.

How to Test

1. Create a cron job with max_turns: 5 and timeout: 30.
2. Verify a long / stuck agentic run is interrupted at the wall-clock cap regardless of activity, and turns are capped at the per-job value.
3. Run: pytest tests/cron/test_cron_job_caps.py -q → 26 passed.

Checklist

• Conventional Commits
• PR contains only changes related to this feature
• pytest tests/cron/test_cron_job_caps.py -q passes (26 passed)
• Added tests
• Tool schema descriptions updated for the new fields

[fabiosiqueira]

Rebased onto current main (was conflicting; now mergeable, single commit).

Two notes on the rebase, and one on overlap with other open PRs.

Rebase

The conflict was in cron/scheduler.py, in the run-watchdog block. Upstream had
added the one-shot run_claim heartbeat path there; this PR had added the
wall-clock cap. Resolved as a union rather than a side-pick: the unlimited branch
now requires both limits to be unset (_cron_inactivity_limit is None and _wall_clock_limit is None) and keeps the upstream one-shot polling/heartbeat
behaviour, while the watcher loop keeps _heartbeat_run_claim_if_due() and checks
the wall-clock cap before inactivity. No behaviour dropped from either side.

Also: #72176 raised the default turn ceiling 90 → 500 while this PR sat. The
_resolve_job_max_iterations fallback and its tests were still pinned to 90, which
would have silently reverted that default for every cron job. Both now resolve to
500, so the per-job cap is purely additive over current main.

Verified: tests/cron/test_cron_job_caps.py 23 passed; full tests/cron clean apart
from 8 pre-existing failures that reproduce identically on unmodified upstream/main
(missing croniter in the local env), plus py_compile on the touched modules.

Overlap

For maintainer triage — several open PRs cover parts of this, and I only spotted
them properly now:

• Per-job turn cap: feat(scheduler): per-job max_iterations override from jobs.json #33323 (@inquistiff, 2026-05-27) is the oldest and has priority
  on that half; also feat(cron): per-job max_turns override + record budget stops as PARTIAL #45322 (@colingreig) and feat(cron): honor a per-job max_turns cap in the scheduler #57285 (@riesvriend).
• Per-job wall-clock cap: feat(cron): per-job runtime_cap_seconds with wall-clock cap enforcement #50268 (@noodlemctwoodle), opened after this one.

The part of this PR that isn't covered elsewhere is the wall-clock cap and its
rationale: the existing inactivity watchdog can't stop a retry storm, because every
retry attempt touches the activity tracker, so the job never looks idle. That's the
regression test ActiveFakeAgent covers here.

If you'd rather land the turn-cap half from #33323, I'm happy to close this and
re-open the wall-clock cap alone on top of it — say the word and I'll do the split
rather than have four PRs competing over the same knob.

— 🤖 Claude Opus 5

[fabiosiqueira]

Rebased onto current main (was conflicting again after the turn-limit refactor). Single commit, mergeable.

The conflict was in cron/scheduler.py, where main had replaced the or-chain that read agent.max_turns with resolve_turn_limit(). Rather than keeping this PR's own chain, _resolve_job_max_iterations now normalizes both levels through resolve_turn_limit():

• per-job max_turns wins when it resolves to a real ceiling;
• anything that isn't one (non-int, <= 0, none, unlimited) falls through to the global config instead of capping the job at a bogus value or silently uncapping it;
• an absent global stays TURN_LIMIT_UNLIMITED, so the per-job knob no longer introduces a cron-only default of its own (this PR previously hardcoded one).

That keeps agent.max_turns: none working in the cron path too — same class of bug as #82813.

This implements #63267; I've linked it in the description (the PR predated that issue).

Verification: pytest tests/cron/test_cron_job_caps.py -q → 26 passed. Full pytest tests/cron/ → 8 failures, identical by name to a clean main checkout at the same commit (test_blueprint_catalog, test_inflight_stale_guard, test_ticker_stall_60703) — pre-existing, not from this branch.

— 🤖 Claude Opus 5