[bpamiri]

Problem

wheels jobs work cut every job off at 300 seconds. The jobsProcessNext bridge command it polls defaulted to timeout=300, and the worker runs a job for Min(its own timeout, the poll's timeout), so a job with this.timeout = 900 was stopped at 300 s. There was no option to change it.

Fix

• CliBridge.jobsProcessNext sets up the worker the way processQueue() does: perJobTimeout = true, so each job is claimed and run with its own class's timeout, recorded on the row as claimTimeout. A timeout param is now a cap (timeoutCap). A row that recorded no claimTimeout is still never reaped inside 300 seconds (legacyReapTimeout). JobWorker is unchanged.
• wheels jobs work --job-timeout=<seconds> is the new cap option. It isn't --timeout: that is the LuCLI runtime's own root option, which on runtimes without the module-timeout fix is taken before dispatch and stops the whole worker (the same reason wheels test uses --test-timeout). 0 (the default) sends nothing, so each job uses its own timeout. A negative value is rejected with Wheels.InvalidArguments. The worker banner prints which mode is in effect, and the option shows in wheels jobs --help and in the usage line.
• Docs: the background-jobs guide (v4.2) and the consumer AI jobs.md (plus its wheels new template copy). Also a changelog.d fragment.

Existing jobs with the default 300-second timeout behave as before.

Tests

• vendor/wheels/tests/specs/jobs/CliJobsProcessNextTimeoutSpec.cfc calls the bridge command directly and asserts the timeout each claim records (scaled: no 300-second wait):
  • with no cap, a this.timeout = 900 job records 900 (RED on develop: 300);
  • with timeout=120, it records 120;
  • a default-timeout job stays at 300.
• JobsCommandSpec adds --job-timeout parsing and validation, and checks that the worker sends &timeout=N only when the option is given (RED on develop: 4 of the 5 new specs fail). A guard spec checks that no jobs option is named after a LuCLI root option (--timeout, --env, --envfile, …) and that --help lists --job-timeout.
• Checked by hand on the real wheels runtime: wheels jobs work --job-timeout=-1 reaches the module and is rejected with the module's own message; --job-timeout=5 gets through parsing to server detection.

Local results:

• Lucee 7 + SQLite, full core suite: 7234 pass / 0 fail / 0 error (592 bundles, internal included).
• Adobe 2023 + SQLite, jobs + cli: 242 + 258 pass, 0 fail / 0 error.
• CLI suite: 2445 pass / 0 fail / 0 error (after the rename; core cli + jobs + internal on Lucee 7 re-run green too).
• Complexity gates (vendor/wheels and cli/lucli): pass.

Fixes #4517

🤖 Generated with Claude Code

[bpamiri]

Review: head 2baac3c. REQUEST CHANGES: one HIGH, the option name. The server-side fix is right.

HIGH: --timeout collides with LuCLI's global --timeout

• The collision. LuCLI's picocli root owns a global option (LuCLI.java: @Option(names = {"--timeout"}, … description = "Fail if the command runs longer than this many seconds (0 = no timeout)")). On runtimes without the module-timeout fix (LuCLI REGEX to Match Email Addresses Fails (/wheels/view/text.cfm) #130), it consumes --timeout before the module is dispatched. wheels test already works around exactly this: it documents and accepts --test-timeout because a plain --timeout "only reaches this command on LuCLI builds that include the module-timeout fix" (Module.cfc ~511–521, wheels test --timeout=N on the terminal never reaches the command (LuCLI's global --timeout takes it) #3678).

• What a user gets. On such a runtime, wheels jobs work --timeout=600, as the new docs, changelog and .ai/jobs.md show, does not cap jobs at 600 s:

  • the module never sees the option, so jobs run with their own timeout;
  • LuCLI applies it as a whole-command limit, so the long-lived worker loop is killed after 600 s.

  That's the opposite of what the option promises, and it's silent.

• Why the specs don't catch it. JobsCommandSpec calls $parseJobsArgs() / jobs() directly, below LuCLI's dispatcher.

• Fix: follow the wheels test precedent:

  • name the terminal option something the root parser doesn't own (e.g. --job-timeout=<seconds>, via .accept("job-timeout") or as the primary name);
  • keep timeout only as the MCP / fixed-runtime spelling, if at all;
  • update the usage line, the description, the docs, .ai/jobs.md (both copies) and the changelog to the new spelling;
  • add an argv-level check if the CLI suite has one for --test-timeout.

Verified

• The original bug is closed. CliBridge.jobsProcessNext() sets perJobTimeout = true, timeoutCap (from the timeout param, > 0 only) and legacyReapTimeout = Max(cap, 300), as processQueue() does.
  • JobWorker claims with the candidate's own class timeout, capped by timeoutCap, and records it as claimTimeout.
  • $runClaimedJob passes that through as the run's timeout, so a this.timeout = 900 job runs 900 s and is reaped on a 900-based window.
  • The spec asserts the recorded claimTimeout (900 with no cap, 120 with a 120 cap, 300 for a default job). That's the right observable: the same value drives the run cap and the reaper.
• Reaper. pollTimeout (300, or the cap) only matters for rows with no claimTimeout, and legacyReapTimeout keeps those from being reaped inside 300 s.
• CLI. It sends &timeout= only when > 0, rejects negatives, prints the effective policy, and defaults to 0, meaning each job's own.
• Conflict. feat(job): token-gated /wheels/jobs/tick route and wheels jobs tick #4516 edits the same usage line, a one-line conflict for whichever lands second.

Evidence: I haven't read narrowed matrix 37854150638 and PR CI yet. I'll read them on the next head, since the rename touches the CLI surface. This verdict rests on the source.

[bpamiri]

Final review: head 7b3d934. APPROVE (ready).

• HIGH resolved. The terminal option is now --job-timeout, in the argspec, the parser (parsed["job-timeout"] → opts.jobTimeout), the usage line, the startup banner, the specs, the 4.2 jobs guide, both .ai/jobs.md copies and the changelog. Its description says why it isn't --timeout (that's the runtime's own option and stops the whole worker). LuCLI's root parser therefore can't take it before dispatch, on any runtime.
• Bridge parameter. It stays timeout (&timeout=<n> to jobsProcessNext). That's server-side, not argv, so there's no collision. jobs is hidden from MCP, so no second spelling is needed.
• Guard spec. jobs --help lists --job-timeout, and no jobs option is named after a LuCLI root option (timeout, env, envfile, verbose, debug, timing, whitespace). That closes the class of bug, not just this instance.
• Server-side fix unchanged since 2baac3c, and verified then.
  • jobsProcessNext runs each job with its own class timeout (perJobTimeout), capped by timeoutCap, and records it as claimTimeout for the reaper;
  • legacyReapTimeout = Max(cap, 300) covers rows without one.
  • So fix(cli): wheels jobs work caps every job at 300 seconds instead of its own timeout #4517's bug is closed: a this.timeout = 900 job runs, and is reaped, on 900.

Evidence:

• Narrowed matrix 37854150638 at 2baac3c. The vendor code is identical at 7b3d934; the delta is CLI and docs only.
  • 20/20 legs green, 0 fail / 0 error, 592 bundles;
  • CliJobsProcessNextTimeoutSpec 3/3 on every leg;
  • RustCFML 7210/0/0.
• PR CI at 7b3d934: 28 pass, 0 fail, 2 skipped.
  • Deploy CLI tests + verb smoke: 2446 pass, 0 fail, 0 error, including the renamed JobsCommandSpec cases and the root-option guard;
  • CLI suite and Lucee 7 + SQLite (LuCLI) both pass.
• Conflict. feat(job): token-gated /wheels/jobs/tick route and wheels jobs tick #4516 edits the same usage line, a one-line conflict for whichever lands second.