fix(bin): cut lint partition wall time with per-root source views and up to four workers

[RajeshRajendiran]

Intent

fix the lint first. Fix the lint before merging the Telegram formatting change. CI's 'Lint 1 (partition 1of2)' is killed by SIGTERM after about eight minutes with no diagnostics, so no pull request in this repository can reach green checks. It is pre-existing on main and not caused by the Telegram change (reproduced on the primary checkout with no branch changes). Cause, measured: same file, same machine, shellcheck 0.11.0, one flag apart: 'shellcheck --norc --external-sources -- bin/fm-afk-launch.sh' takes 13.5s real versus 0.57s without --external-sources, a 24x difference in user CPU on a single file. Partition 1of2 holds roughly forty shell files, about nine minutes, matching the eight-minute kill. So --external-sources follows every source directive and re-parses this repository's shared bin/ library graph once per dependent script. A finished reviewed change is parked at its CI gate waiting on this, and all planned pull request work is behind it. Make the lint fast enough to finish comfortably inside its budget WITHOUT losing what it currently checks: removing --external-sources or otherwise stopping shellcheck following sourced files is not the fix, because that silently drops cross-file coverage. bin/fm-lint.sh is the single owner of the lint definition used by both CI and the no-mistakes pre-push gate, so the fix belongs there. CI and the pre-push gate must keep behaving identically, partitioning must still shard completely with no file unchecked, the refusal to run under an unexpected linter version must survive, bin/*.sh must stay shellcheck-clean, and tests must pin behaviour rather than wall-clock. Out of scope: the Telegram changes, rebalancing partitions purely to hide the cost, and raising the CI timeout.

What Changed

• bin/fm-lint.sh now runs shellcheck --external-sources on each root separately, inside a private view of the repository. In that view each shared library is included by directive once, at its first top-level site. Later top-level sites in non-test files become source=/dev/null. Indented sites and test files keep every site, because their scoping affects findings. If the view build fails, that root falls back to the real tree. FM_LINT_DEDUPE_SOURCES=0 turns the view off. The flags, the pinned-version refusal and the partition inventory are not changed.
• The lint now uses four stable logical shards on one to four bounded workers. The default is the CPU count, clamped to between 2 and 4. --jobs accepts 1-4, and telemetry adds shard 3 and 4 weights. Diagnostics still replay in stable shard/root order.
• tests/fm-lint.test.sh is updated for the new shard and worker behaviour, and docs/fm-test-portable-shards.md is updated to describe the per-root views and up to four workers.

Risk Assessment

✅ Low: The fix stays inside bin/fm-lint.sh, keeps --external-sources and the version pin, and the prior scope finding is resolved: only column-0 include sites are deduped or counted as a first site, and tests/ keeps every site. I found no wrong-result path, but I did not run the lint or the tests, so the speedup and the diagnostic parity on the real bin/ tree are unmeasured.

Testing

I ran both canonical CI partitions live with the real ShellCheck 0.11.0 and actionlint. Both exited 0 with no diagnostics, the version pin was reported, and workflow lint passed. Partition 1of2 took 326s when run alone. The lint owner's test file passed. The dedupe-scope behavior was checked by reading code only, with no dedicated live parity run against the base. I did not time the base commit, so the speedup is not measured directly.

• Live validation: ✅ go - 3 of 4 scenarios driven live against the product

Scenario	Result	Live	Evidence
CI partition 1of2 lints its whole file set with source following and exits 0 without a timeout	✅ pass	live	/tmp/q1.out; rc=0 elapsed=326s
CI partition 2of2 lints its whole file set with source following and exits 0	✅ pass	live	/tmp/p2.out; rc=0
Pinned ShellCheck version check runs and passes, and the lint owner's test suite passes	✅ pass	live	bash tests/fm-lint.test.sh output all ok; partition output shows 'ShellCheck 0.11.0 (pinned 0.11.0)'
Source dedupe view only rewrites top-level include sites (round-1 review fix)	⏸️ untested	no	The prior payload established this only by reading the FM_LINT_VIEW_PERL code and inferring from passing partitions and tests. No dedicated live scope-parity comparison against the base was run, so no…

Evidence: partition 1of2 output

fm-lint.sh: ShellCheck 0.11.0 (pinned 0.11.0)
fm-lint.sh: full ShellCheck extended analysis enabled
fm-lint-workflows.sh: actionlint 1.7.12 (pinned 1.7.12)
fm-lint-workflows.sh: 3 workflow files valid

- Outcome: ⚠️ 1 warning across 1 run (22m24s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 1 issue found → auto-fixed ✅

• ⚠️ bin/fm-lint.sh:109 - Source dedupe view (FM_LINT_VIEW_PERL) rewrites every later include site of a library in non-test files to source=/dev/null, regardless of scope. The comment claims findings are identical, but this is only true if the first site is at an equivalent scope. If the first site is inside a subshell, function, or conditional and a later top-level site is dropped, scope-dependent diagnostics (SC2031, SC2154, SC2218 and similar) can be missed or spuriously produced. Only tests/ is exempted. The added test covers only two top-level includes. Fix the smallest honest way: dedupe only when the first site is a plain top-level include, or verify parity across the real bin/ tree in the test.

🔧 Fix applied.
✅ Re-checked - no issues remain.

⚠️ **Test** - 1 warning

• ⚠️ Partition 1of2 alone took 326s wall on a 12-CPU host (max 4 workers), so it lands under the 8-minute kill but with only about 2.5 minutes of margin. A 2-vCPU CI runner may still be tight. I did not time the base commit for comparison.
• Live validation: ✅ go - 3 of 4 scenarios driven live against the product

Scenario	Result	Live	Evidence
CI partition 1of2 lints its whole file set with source following and exits 0 without a timeout	✅ pass	live	/tmp/q1.out; rc=0 elapsed=326s
CI partition 2of2 lints its whole file set with source following and exits 0	✅ pass	live	/tmp/p2.out; rc=0
Pinned ShellCheck version check runs and passes, and the lint owner's test suite passes	✅ pass	live	bash tests/fm-lint.test.sh output all ok; partition output shows 'ShellCheck 0.11.0 (pinned 0.11.0)'
Source dedupe view only rewrites top-level include sites (round-1 review fix)	⏸️ untested	no	The prior payload established this only by reading the FM_LINT_VIEW_PERL code and inferring from passing partitions and tests. No dedicated live scope-parity comparison against the base was run, so no…

• CI=true bin/fm-lint.sh --partition 1of2 (rc=0, 326s wall alone, 12 CPUs)
• CI=true bin/fm-lint.sh --partition 2of2 (rc=0)
• bash tests/fm-lint.test.sh (all output lines ok)
• Read the view-builder code in bin/fm-lint.sh to confirm only top-level # shellcheck source= sites are deduped and tests/ files keep every site (code reading only)

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.