[bpamiri]

Summary

maxRetries counts the retries after the first run: a job with maxRetries = 3 runs up to four times. That has been the behaviour since #3412, which changed the retry check from < to <= on purpose ("maxRetries=3 now means 4 tries"), pinned by JobHardenerSpec S9 ("S9: maxRetries=3 allows 4 tries (retries after first fail)").

The background-jobs guide was written before that (#3130) and still says maxRetries "counts total attempts, not retries", with examples that are one run short. This PR fixes the docs, not the code.

Changes

• Guides: the background-jobs guide's retries paragraph, in both the 4.1 and 4.2 trees (fix(jobs): honor timeout, allowlist jobClass, return real DML counts #3412 shipped in 4.1.0). The maxRetries=5 example now runs at most six times (retries at about 4, 8, 16, 32 and 64 s), and the default 3 means up to four runs.
• AI docs: docs/consumer-ai/.ai/jobs.md and the identical wheels new copy gain one line: maxRetries counts retries after the first run, so the default 3 means up to four runs.
• Job.cfc: the log line for a job that runs out of retries said "permanently failed after <maxRetries> attempts", one short of the real count. It now says "permanently failed after <runs> attempts (<maxRetries> retries)".
• Spec and changelog: jobs/JobRetryCountWordingSpec pins the log line and the guide wording; changelog fragment added.

Note on Rails

Rails' retry_on ..., attempts: N counts the total number of runs, first run included. Wheels' maxRetries is one more than that by design (#3412), so a value copied from a Rails job runs once more in Wheels. The guide now states the Wheels meaning explicitly.

Tests

• Before: develop has the old log wording and the old guide sentence, and lacks the new wording, so all three checks in the new spec fail there.
• With the change: the jobs specs give 110 / 0 / 0 on Lucee 7 + SQLite (JobHardenerSpec S9 unchanged).
• The consumer-docs sync check passes, and the guides site builds.

🤖 Generated with Claude Code

[bpamiri]

Source APPROVE at e79a5f7. Verified maxRetries+1 semantics in every 4.1.x tag and current source, identical consumer/template copies, and no scheduling change. New wording specs are source assertions; existing S9 covers runtime attempt behavior. Final gate pending matrix 37221076048.

[github-actions]

Wheels Test Results

216 679 tests   212 555 ✅  1h 7m 45s ⏱️
 16 576 suites    4 124 💤
     32 files          0 ❌

Results for commit 59f4f03.

♻️ This comment has been updated with latest results.

[bpamiri]

APPROVE at 59f4f03.

The merge preserves both documentation changes and keeps the consumer/template copies identical. The guide read now has the matching $requireRepoPath guard; the production change remains limited to the failure-log count.

Read all 32 result JSONs from matrix 37265788030 on this head: 518 bundles per leg, zero failures/errors. RequireRepoPathSpec is 4/4 Passed and JobRetryCountWordingSpec is 2/2 Passed on every leg, including Adobe 2025 + SQLite. No remaining blockers.