fix(job): scope lock to --run, fix exit code, remove dead code

[icciaaron]

Summary

Three issues in fwconsole job that combine to silently prevent time-sensitive jobs (like time condition BLF updates) from executing.

1. Lock scope too broad

The LockableTrait lock is acquired at the top of execute(), blocking all operations — including --list, --enable, and --disable — when a --run is already in progress. These non-destructive operations do not modify job state or interfere with running jobs.

Fix: Move the lock to immediately before the --run dispatch. --list, --enable, and --disable now execute without contention.

2. Lock contention returns exit code 0

When a second fwconsole job --run cannot acquire the lock, it returns 0 (success). Cron, scripts, and monitoring cannot distinguish a successful run from a completely skipped one.

Fix: Return 1 (failure) and wrap the message in <error> tags for console visibility.

3. Dead code block

Lines 61–64 contain a duplicate if(\$input->getOption('disable')) check that is identical to the block at lines 56–59 — making it unreachable. The body references \$input->getOption('run') suggesting it was intended as the --run dispatch but was never corrected.

Fix: Remove the dead block.

Impact

On busy PBXact/FreePBX systems with 27+ registered jobs, a single slow job (calendar sync, firewall update, SangomaConnect keepalive) can hold the process-wide lock past the 60-second cron interval. The next fwconsole job --run silently exits with code 0, skipping all jobs including time-sensitive ones like the timeconditions schedtc job that updates BLF hint states.

With the lock scoped to --run only, administrators can still query and manage jobs (--list, --enable, --disable) during a long-running job execution.

Environment

• FreePBX 17 / PBXact 17
• Symfony Console 6.2.x (LockableTrait)
• PHP 8.1+ (Debian 12)

Related

• Companion PRs for the downstream timeconditions crash: fix(schedtc): guard against empty calendar event in debug output timeconditions#23 and fix(calendar): getNextEventByGroup returns false instead of empty array calendar#31
• Community thread (same symptom chain): https://community.freepbx.org/t/freepbx-bug-blf-subscriptions/106007

---

Discovered during fleet maintenance by Aaron Salsitz (Master Bitherder) at ICCI, LLC. Analysis and fix developed with Claude Code.

[icciaaron]

Hi @jissphilip @kapilgupta01 — this one scopes the --run lock so it doesn't block other fwconsole job operations, fixes an incorrect exit code, and drops some dead code. We hit this while debugging a cron issue on customer systems. Happy to adjust anything that doesn't match your preferences.

[icciaaron]

Hi @jissphilip @kapilgupta01 — gentle bump in case this slipped past triage. No rush at all, and happy to wait.

Sharing some context to help prioritization: this PR is the keystone of a four-PR fix series for a fleet-wide BLF-on-time-condition bug we've been hitting on PBXact 17:

• framework#238 (this one) — scopes the --run lock so other fwconsole job operations aren't blocked; without it, schedtc silently never runs once another job holds the lock past 60s
• timeconditions#23 — schedtc debug-output guard against empty calendar events
• calendar#31 — sibling: getNextEventByGroup() returning false instead of []
• calendar#32 — RECURRENCE-ID exception handling + sync-failure notifications

They're each small and standalone, but functionally they land together. Happy to rebase, split further, expand tests, or hop on a quick call if any of it is easier to discuss live — whatever's least friction for the team.

Thanks for everything you do on this codebase.