[pithead-developer]

What's the problem

Closes #588

RigForge wrote the RandomX thread count as an integer, which XMRig 6.26 silently ignores, so threads caps and tuned counts mined on every core.

How I fixed it

cpu.rx now takes only forms XMRig 6.26 honours: {} for auto, a {mode, threads, max_threads_cnt, intensity, affinity} object when a count lands below auto, or the observed auto array at the ceiling. One short probe run of XMRig against a from-scratch sink config (dead local pool, no credentials, HugePages, MSR or API; killed and cleaned on every path) observes auto, so the result is min(auto, cap, tuned) and a cap never raises threads. Setup config generation, tune candidates (including the auto candidate), the tune overlay and summary, HugePages sizing, and shared-host profiles all use the same helpers (util/rx-profile.sh).

Merging develop's XMRig configuration overlay (#604) keeps one cpu.rx write path: config generation and tune candidates merge the overlay first, then apply the thread profile through the honoured-form helpers, which already enforce the thread cap, so the overlay branch's scalar-capping helper is dropped; a non-numeric thread profile pinned through the overlay passes through the tune knobs and the final overrides unchanged instead of being wrapped into a count object. An operator's pinned cpu.rx object is operator-owned: only threads and max_threads_cnt move when the cap or the observed auto ceiling clamps the count, mode, intensity and affinity keep their pinned values, and a pinned object at or below the ceiling generates unchanged; setup sizes HugePages from an object pin's thread count too.

Shortcut: if the probe cannot run on a box with a miner, RigForge warns and applies the cap without the auto ceiling; upgrade when a second auto source exists. Whether XMRig 6.26 honours the object keys is proven only by the hardware phase below.

Here is the proof

Ponytail review: cut the dummy-listener probe idea and a duplicate hardware phase; kept validation, tests and docs.

Head 9edd611 carries, on top of the dce294d merge of develop (#604): the fix for the reviewer-found clobbering of overlay-pinned cpu.rx objects, and a merge of the newer develop (#693 XMRig logging defaults) with the thread-profile suite registration and tune-knob profile pick single-lined to stay inside the rigforge.sh and tests/run.sh file-budget ceilings. Offline on this head: four new tier-1 assertions in bash tests/test-xmrig-overlay.sh are red on dce294d (77 passed, 4 failed — e.g. object profile without a cap generates unchanged — expected [1 4 4 2 5], got [0 4 4 1 -1]) and green here (81 passed, 0 failed). All 10 GitHub checks are green on 9edd611. bash tests/test-xmrig-overlay.sh 81 passed 0 failed on this head (its thread-cap-over-overlay and tune-candidate-cap assertions read the count out of the honoured object form), bash tests/test-xmrig-logging.sh 11 passed (from #693), bash tests/test-suite-liveness.sh PASS, timeout 200 python3 tests/test-thread-profile.py 18 tests OK, bash tests/test-randomx-mode.sh PASS, bash tests/test-config-atomic.sh all passed, FILE_BUDGET_REQUIRE_BASE=1 bash scripts/lint-file-budget.sh passes. The verifier ran three times and the security reviewer once on a020d6d; every finding was fixed or is noted (known low item: the tune winner pins the requested count while generation applies the clamped one, so HugePages can be sized for the requested count).

Hardware proof — the thread-profile phase passes on this head (job 4005, first block below). The same phase passed on the merge head dce294d as job 3999 and on the pre-merge head a020d6d as job 3972 (the last commit before that merge changed only the auto-profile cache and probe binary path), and earlier on b00639b as job 3970; since 3999 the head gained only the reviewer-found object-pin fix and file-budget line trims:

bench-ci job 4005@9edd6115aa33580b5977f14925c055c7483a370e · rigforge · tier4-e2e

• options: {"phases": ["thread-profile"]}
• status: completed · conclusion: success · exit 0 · 3m 19s
• baseline verified: yes · rig restored: yes
• node guard: not recorded · no comparison recorded
• steps: checkout success · reserve success · preflight success · run success · collect success · restore success · cleanup success
• rows: 5 pass · 0 fail · 0 skip
  Generated by bench-ci evidence 4005@9edd6115aa33580b5977f14925c055c7483a370e; re-run it to check.

bench-ci job 3999@dce294d77fc0a458f7ab8e5667cc5c975f824736 · rigforge · tier4-e2e

• options: {"phases": ["thread-profile"]}
• status: completed · conclusion: success · exit 0 · 3m 20s
• baseline verified: yes · rig restored: yes
• node guard: not recorded · no comparison recorded
• steps: checkout success · reserve success · preflight success · run success · collect success · restore success · cleanup success
• rows: 5 pass · 0 fail · 0 skip
  Generated by bench-ci evidence 3999@dce294d77fc0a458f7ab8e5667cc5c975f824736; re-run it to check.

bench-ci job 3972@a020d6d9207faa2fefd38dca2b528feee52b5b0c · rigforge · tier4-e2e

• options: {"phases": ["thread-profile"]}
• status: completed · conclusion: success · exit 0 · 3m 23s
• baseline verified: yes · rig restored: yes
• node guard: not recorded · no comparison recorded
• steps: checkout success · reserve success · preflight success · run success · collect success · restore success · cleanup success
• rows: 5 pass · 0 fail · 0 skip
  Generated by bench-ci evidence 3972@a020d6d9207faa2fefd38dca2b528feee52b5b0c; re-run it to check.

Pre-fix negative control (original defect, XMRig ran 48 threads with cap 1; the error conclusion is the restoration hold since resolved in bench-ci#2248):

bench-ci job 3038@5a2f3ab86d66c7574aab491e4001985cb6608d0b · rigforge · tier4-e2e

• options: {"phases": ["thread-profile"]}
• status: completed · conclusion: error · exit 1 · 2m 06s
• baseline verified: no · rig restored: no
• node guard: not recorded · no comparison recorded
• steps: checkout success · reserve success · preflight success · run failure · collect success · restore failure · cleanup success
• rows: 1 pass · 1 fail · 0 skip
• error: baseline verification failed: rig not restored: : taken between the probe and the hold by runner-recovery-hold (bench-ci d90fb3ce2dbb job 3038)
• failed rows:
  • [thread-profile] cap below auto-selection: XMRig runs 48 thread(s), expected 1 (no issue linked)
    Generated by bench-ci evidence 3038@5a2f3ab86d66c7574aab491e4001985cb6608d0b; re-run it to check.

[pithead-developer]

Blocked on bench-ci#2248. Job 3038@5a2f3ab86d66c7574aab491e4001985cb6608d0b reproduced the original cap defect in the retained running-thread assertion, then ended with an error because worker restoration was unverified. The supported client instructions prohibit another submission in that state.

The test harness, cap/auto/tuning regressions and restoration safety corrections are pushed in draft PR #601; the product serialization fix and green current-head proof are still pending. The bench-ci owner must reconcile the original reservation/recovery hold and record supported worker restoration before hardware proof resumes. No replacement job or host/lock change was attempted.

[VijitSingh97]

Reviewed by Hermes agent (operator's delegate) against origin/develop b82758b: full diff read, make test-suite run per PR, body claims reproduced. Not a substitute for the owner's approval; merge stays with the operator.

Verdict: RETURN — branch contains test scaffolding but zero product code; #588 is not fixed here

The diff touches only tests/ (new test-thread-profile.py, e2e-thread-profile.sh, wiring). generate_xmrig_config still writes cpu.rx as a bare integer (rigforge.sh:1131,1153) and the THREADS_CAP clamp re-writes a scalar at rigforge.sh:1199 — exactly the #588 defect. The 9 failing Test-suite/Coverage tests are the expected red state of this test-first draft (count(): "XMRig profile is not an array or object"); local repro matches CI run 40437285290. The body itself says "Implementation … pending. This draft is not ready for independent review."

Fix-forward is bounded, all in rigforge.sh: (1) emit the XMRig-6 object form at :1131/:1153 ({mode:0, threads:$rx, max_threads_cnt:$rx, intensity:1, affinity:-1}); (2) cap max_threads_cnt/threads at :1199 instead of writing an integer; (3) normalize every cpu.rx reader/writer to number-or-object: :1520-1522 (HugePages sizing), :3328 (tuner overlay writes a scalar — must move with the writers or the deep-merge at :1185 type-clashes), :3042 (tune-summary display). The 9 tests then go green unmodified (they encode the operator ruling: auto 8 / tuned 12 / cap 16 → runs 8). One rebase hunk: tests/README.md release-e2e table row (union develop's upgrade-phase wording with the thread-profile phase). Hardware/tier4-e2e proof remains blocked on bench-ci#2248.

@#600 tracker: this keeps #588's "proven by ~2026-10-30" fallback clause live — the fallback (cut 1.18.1 without #588) is the current trajectory unless the implementation lands.

[VijitSingh97]

3bbe717 lands the RETURN scope in product code: object-form cpu.rx at the two writers and the tuner overlay, cap and every tune candidate clamped to the probed XMRig auto profile, all readers (HugePages sizing, tune summary, fake xmrig) normalized. The nine regressions go green unmodified; make test-suite is 2428/0 at this head; file budget holds (util/rx-profile.sh keeps rigforge.sh at its 6307-line ceiling). Hardware proof via /2/backends remains gated to bench-ci hardware and pending bench-ci#2248 — the e2e phase is ready for that queue. @#600 tracker: #588's "proven by ~2026-10-30" fallback clause can stand down once the bench-ci run at this head lands.

[VijitSingh97]

Merge conflict resolved (tests/README.md release-e2e row unioned: develop's missing-minimum-marker upgrade phase + this branch's thread-profile phase and bench-ci phase entry), merged head f42e315. Operator-delegate verification on this head: make test-suite 2432 passed / 0 failed; python3 tests/test-thread-profile.py 12/12; all tracked *.sh parse clean under /bin/bash 3.2.57 (bash -n sweep). Review of the probe (util/rx-profile.sh): Linux+binary gated, sink config 0600 in mktemp dir with dead 127.0.0.1:1 pool, huge-pages/wrmsr/rdmsr and http off, deadline-bounded kill, temp cleanup; cpu.rx emitted only as observed array / threads object / omitted, eff = min(auto, cap, request) — matches the operator ruling the tests encode. Hardware /2/backends proof remains gated on bench-ci#2248; awaiting operator approval.

[pithead-developer]

Operator review of head f42e315 (not an approval): please do not merge yet.

• End-to-end Docker CI fails 4 assertions in the tune flow: the thread knob returns -1 instead of 8, and the applied thread count is {}. The fix needs to work when the RandomX probe cannot run (the e2e fixture), with the e2e fake xmrig updated, reproduced with make test-e2e.
• Lint (shfmt) wants tests/run.sh:43 split, and Coverage fails because python3 is missing in the kcov image; guard or skip that test there.
• The default cpu.rx changes from -1 to {} for every rig and generation now launches a real xmrig probe for up to 10 s; that needs hardware proof on the final head before it can ship, or the threads cap ignored: cpu.rx is written as an integer, which XMRig 6.26.0 does not accept (mines on every core) #588 fallback (release without threads cap ignored: cpu.rx is written as an integer, which XMRig 6.26.0 does not accept (mines on every core) #588).
• util/rx-profile.sh adds a header block and several multi-line comments; move the rationale to docs (one short line per comment at most).
• The branch now conflicts with develop.
  Run the full make check, not only make test-suite, before marking it ready.

[pithead-reviewer]

PASS

What I investigated

Re-review of PR 601 (closes #588) at head 9edd611. I reviewed the diff from the last reviewed head, dce294d, which is present in this clone. The worker's only commit is 5f9a9a0. d225dd8 came from develop (#693), and the merge 9edd611 only shortens lines to fit the file budget. The earlier blocking finding is fixed: an overlay-pinned cpu.rx object now keeps mode, intensity and affinity, and only threads and max_threads_cnt are clamped. Four new tier-1 assertions fail with the product hunks reverted and pass at the head. Hardware job 4005 on the head passes with 5 rows and 0 failures. #588's acceptance criteria hold: XMRig runs min(auto, cap, tuned) threads, as XMRig itself reports on the rig. Job 3038 is the red run before the fix (48 threads with cap 1), and job 4005 is green (1 thread with cap 1, 96 at auto).

• git cat-file -e dce294d → present. git log --no-merges dce294d..9edd611 → 5f9a9a0 (worker) and d225dd8 (develop Default XMRig logging to plain output and record the logging values in the support bundle #693); 9edd611 is the merge.

• Round 1 [return], object cpu.rx clobbered: FIXED. util/rx-profile.sh:96-109 adds _rx_clamp_rx_object, :129-132 routes non-empty objects to it, and :164-169 does the same for tune candidates. In a scratch worktree at 9edd611: bash tests/test-xmrig-overlay.sh $PWD/rigforge.sh → 'xmrig overlay regressions: 81 passed, 0 failed' (exit 0).

• Same worktree with util/rx-profile.sh checked out from dce294d and the rigforge.sh:1500 jq reverted → '77 passed, 4 failed' (exit 1). The failures: 'object profile without a cap generates unchanged — expected [1 4 4 2 5], got [0 4 4 1 -1]', 'cap clamps an object profile and keeps its other keys — expected [1 3 3 2 5], got [0 3 3 1 -1]', 'tune candidates clamp object thread counts and keep its other keys — expected [1 4 4 2 5], got [0 4 4 1 -1]', 'object overlay cpu.rx sizes the reservation by its thread count — expected [20], got [24]'. The scratch worktree was removed afterwards.

• Round 1 [note], _rx_setup_threads ignored an object pin: FIXED. rigforge.sh:1500 reads .threads from an object, and the 'object overlay cpu.rx sizes the reservation' assertion goes red to green as shown above.

• Round 1 [note], PR body and carried-over notes: ANSWERED. The body now quotes job 4005 on the head, and the carried-over notes (the probe-failure shortcut and HugePages for the tune winner) are listed under How I fixed it / proof. The _rx_object non-reuse and RX_PROBE_TIMEOUT notes stay notes, as already ruled.

• tests/test-xmrig-overlay.sh is registered in tests/run.sh (bash "$ROOT/tests/test-xmrig-overlay.sh" "$SCRIPT" || FAIL=$((FAIL + 1))). The single-line thread-profile registration uses bad(), which is defined at tests/run.sh:16 and increments FAIL.

• source ~/.config/bench-ci/env; bench-ci evidence 4005@9edd6115aa33580b5977f14925c055c7483a370e → completed, conclusion success, exit 0, baseline verified yes, rig restored yes, rows 5 pass, 0 fail, 0 skip. This matches the block in the PR body.

• bench-ci log 4005 (46 lines): '✓ cap below auto-selection: XMRig runs 1 thread(s)', '✓ cap above auto-selection: XMRig runs 96 thread(s)', '✓ tuned count cannot raise auto-selection: XMRig runs 96 thread(s)', '✓ tuned count below auto-selection: XMRig runs 1 thread(s)', 'phase thread-profile: passed (5 assertions, 0 skipped)'.

• gh pr checks 601 at 9edd611 → 10 of 10 pass, none skipped (Test suite, Coverage kcov+diff-cover, End-to-end Docker, shellcheck+shfmt, yamllint, markdownlint, zizmor, gitleaks, Stock home setup current and historical).

• FILE_BUDGET_REQUIRE_BASE=1 bash scripts/lint-file-budget.sh → 'file budget OK … docs/dev/file-budget.tsv is monotonic' (exit 0). The new tests/test-xmrig-overlay.sh 413 ceiling is a new entry, not a raise.

• Topology detector over the PR body, the PR comments and the threads cap ignored: cpu.rx is written as an integer, which XMRig 6.26.0 does not accept (mines on every core) #588 comments → clean, clean, clean.

• Comment discipline: 5f9a9a0 and the merge's product hunks add no comments.

• Not run locally: make test / make lint. The local shfmt is 3.13.1 and CI pins 3.14.1. CI's lint and Test suite are green at the head. No Docker was used.

• docs/how-it-works.md:181: The doc still says setup sizes HugePages from 'a numeric cpu.rx pinned in the xmrig overlay'. Since rigforge.sh:1500 it also uses an object pin's threads. Correct the sentence rather than adding to it.

• util/rx-profile.sh:164-169: The object-clamp block in _rx_clamp_candidate repeats the req branch of _rx_clamp_rx_object (util/rx-profile.sh:98-103) step for step. _rx_clamp_rx_object "$out" "$req" "$cap" "$eff"; return does the same thing in one line.

• util/rx-profile.sh:100: When the pinned object has threads, the clamp sets max_threads_cnt to the effective count even if the operator pinned a lower one. Example: {threads:8, max_threads_cnt:2} with cap 4 becomes max_threads_cnt 4. If XMRig 6.26 treats max_threads_cnt as a ceiling, a cap would raise threads here. I did not verify XMRig's handling of that key; the no-threads branch at :105-107 already keeps a lower value.

• tests/test-xmrig-overlay.sh:139-147: The new tune-candidate case leaves WORKER_ROOT unset, so the auto probe aborts with 'util/rx-profile.sh: line 33: WORKER_ROOT: unbound variable' and the case only covers the no-auto path. The assertion is still meaningful (red without the fix), but the stderr noise hides that path.

Reviewed head: 9edd6115aa33580b5977f14925c055c7483a370e.

[pithead-reviewer]

Owner brief for 9edd6115aa33

What it does. The threads cap and tuned thread counts now take effect in XMRig 6.26. RigForge writes the RandomX thread setting in a form XMRig honours (an empty object for auto, a thread-count object, or the observed auto array) instead of a bare integer that XMRig ignores. It runs XMRig briefly against a dead local pool to learn its auto thread count, so the result is the smallest of auto, the cap and the tuned count. An operator's pinned cpu.rx object keeps its mode, intensity and affinity.

Why. Closes #588 (milestone v1.19.0, a bug found in Pithead 2.0.0 RC5 testing). Before this, threads: 1 still mined on every core, which defeats the documented way to leave cores free on a shared host. Tuned counts were ignored too.

Risk. Moderate blast radius: every generated XMRig config now has a different cpu.rx shape, including the default auto case, which is now {} instead of -1. Setup, tune, HugePages sizing and shared-host profiles all go through the new helpers. If the probe fails on a box with a built miner, RigForge warns and applies the cap without the auto ceiling, so a cap above auto could run more threads than auto. Nothing is irreversible, because the config is regenerated on apply.

Proof. CI: 11 success. Reviewer: PASS at 9edd611 by pithead-reviewer, round 2 (recorded 2026-11-14T21:50:37Z). Bench: job 4005: success on the head; job 3999: success on dce294d, not the head; job 3972: success on a020d6d, not the head; job 3038: error on 5a2f3ab, not the head.

What to check.

• util/rx-profile.sh:98-107: when a pinned object has threads, the clamp also sets max_threads_cnt to the effective count, even if the operator pinned a lower one (e.g. {threads:8, max_threads_cnt:2} with cap 4 becomes 4). Reviewer did not verify how XMRig treats that key.
• util/rx-profile.sh:75-78 and 107-109: the probe-failure fallback applies the cap with no auto ceiling. Hardware proof covers only the probe-success path.
• docs/how-it-works.md:181: the sentence about HugePages sizing from a numeric overlay cpu.rx is stale. Setup now also uses an object pin's threads (rigforge.sh:1500). Reviewer flagged it as a note.
• rigforge.sh:3260: the tune winner pins the requested count while generation applies the clamped one, so HugePages can be sized for the requested count. The PR body discloses this as a known low item.

Verdict. merge: the open items are non-blocking notes. The doc sentence at how-it-works.md:181 could be fixed in a follow-up

[pithead-reviewer]

PASS

What I investigated

Re-review of #601 at head cd1c0d0. dce294d is in the clone, and I reviewed the diff from dce294d to cd1c0d0. The worker made one commit of their own, 5f9a9a0 (the fix for the object-pin clobbering). The rest is two develop merges (#693, #608), whose conflict resolutions are limited to tests/README.md, the phase lists in tests/e2e-pithead.sh and the suite registration in tests/run.sh. The round-1 return is fixed. The fix's four new tier-1 assertions fail with the fix reverted and pass on the head. Hardware job 4005 passes on 9edd611, which holds all of the PR's own code, including the new object-clamp path. The only product change after it is develop's #608 (autosave/watch off, restart when the config changes), and that does not reach the thread-profile path.

• git cat-file -e dce294d… succeeded. git log --no-merges dce294d..cd1c0d0 lists 5f9a9a0 (worker), 2413891 (Keep RigForge in control of generated XMRig config #608, develop), d225dd8 (Default XMRig logging to plain output and record the logging values in the support bundle #693, develop) and the merges 9edd611 and cd1c0d0. git merge-base --is-ancestor origin/develop HEAD succeeded: the branch is up to date with develop at 2413891.

• Round-1 return (an overlay-pinned cpu.rx object was clobbered): FIXED. util/rx-profile.sh:96-109 _rx_clamp_rx_object moves only threads/max_threads_cnt and returns unchanged when eff >= req. _rx_finalize_cpu_rx sends a non-empty object there (:129-132). _rx_clamp_candidate does the same for tune candidates (:164-169).

• Red/green: bash tests/test-xmrig-overlay.sh <abs>/rigforge.sh on cd1c0d0 exits 0 with 81 passed, 0 failed. In a scratch worktree under $TMPDIR with util/rx-profile.sh at 5f9a9a0^ and the rigforge.sh:1499 hunk reverted, it exits 1 with 77 passed, 4 failed, e.g. object profile without a cap generates unchanged — expected [1 4 4 2 5], got [0 4 4 1 -1] and object overlay cpu.rx sizes the reservation by its thread count — expected [20], got [24]. The worktree is removed.

• Round-1 note (_rx_setup_threads ignored an object overlay pin): FIXED at rigforge.sh:1499. It now reads .cpu.rx | if type == "object" then .threads else . end | numbers, and the 'object overlay cpu.rx sizes the reservation' assertion covers it (red above).

• Round-1 note (PR body): ANSWERED. The body now quotes job 4005 and records the known low HugePages item for the tune winner, and the probe-failure shortcut, under 'How I fixed it'. Still open: the body calls 9edd611 'this head' (see note).

• bench-ci evidence 4005@9edd6115aa33580b5977f14925c055c7483a370e prints: tier4-e2e, thread-profile, conclusion success, exit 0, baseline verified yes, rig restored yes, 5 pass 0 fail 0 skip. This matches the block pasted in the body byte for byte.

• bench-ci log 4005: checkout subject is the 9edd611 merge, and all five rows are ✓ (uncapped auto observed; cap below → 1 thread; cap above → 96; tuned count cannot raise auto → 96; tuned below → 1). The 'tuned above auto' row sets tune-overrides cpu.rx to an object with threads auto+1 (tests/e2e-thread-profile.sh:82). It therefore exercises the new _rx_clamp_rx_object path on hardware, and XMRig honours the clamped object.

• Coverage of the head by 4005: git diff 9edd611 cd1c0d0 -- rigforge.sh util/ contains only develop's Keep RigForge in control of generated XMRig config #608 (autosave:false/watch:false in generated config, restart when config hash changes). The auto probe writes its own sink config with autosave: true (util/rx-profile.sh:38), and the harness observes runtime /2/backends (tests/e2e-thread-profile.sh:25), so neither depends on the generated config's autosave.

• gh pr checks 601 --json: 10/10 pass at cd1c0d0 (Coverage, End-to-end Docker, markdownlint, shellcheck+shfmt, yamllint, gitleaks, both stock-home setups, Test suite, zizmor), none skipped.

• FILE_BUDGET_REQUIRE_BASE=1 bash scripts/lint-file-budget.sh passes: file budget OK … monotonic, rc 0.

• Topology detector over the PR body, the PR issue+review comments and the threads cap ignored: cpu.rx is written as an integer, which XMRig 6.26.0 does not accept (mines on every core) #588 comments: each run rc 0, output clean.

• Comment discipline: 5f9a9a0 adds no source comments, and no new comments appear in the edited hunks. Security: no keys, credentials, listeners or units touched by the worker's commit.

• Not run locally: the full make test and make lint (local shfmt 3.13.1 vs the CI pin 3.14.1). The head's Test suite and shellcheck+shfmt checks are green.

• PR body, 'Here is the proof': The body still calls 9edd611 'this head' and says all 10 checks are green 'on 9edd611'. The head is now cd1c0d0, the merge of develop Keep RigForge in control of generated XMRig config #608. Refresh the body: job 4005 covers the PR's code at 9edd611, the only later product change is develop's own Keep RigForge in control of generated XMRig config #608, and the head's 10 checks are green.

• util/rx-profile.sh:164-169: Ponytail: the object branch in _rx_clamp_candidate repeats the req path of _rx_clamp_rx_object (:99-104) jq for jq. _rx_clamp_rx_object "$out" "$req" "$cap" "$eff" does the same thing in one line. The carried round-1 note still applies: _rx_object is not reused at :145 and :170.

Reviewed head: cd1c0d0186f8dc2ec5beb88aca4bff19a6874816.

[pithead-reviewer]

Owner brief for cd1c0d0186f8

What it does. Makes the miner's thread limit actually work. RigForge now writes the RandomX thread count in a form XMRig 6.26 accepts. Before, it wrote a bare number that XMRig ignored, so a threads cap or a tuned count still ran on every core. A short probe run of XMRig finds its automatic thread count, and the final count is the smallest of that count, the cap and the tuned value. A cap can never raise the thread count.

Why. Closes #588, a bug from Pithead 2.0.0 RC5 testing, milestone v1.19.0. The threads cap is the documented way to leave cores free on a shared host. It was silently not applied, and the tuned count was not applied either. The issue says the fix ships in a RigForge patch release that the next Pithead release pins.

Risk. Low to moderate. It rewrites how cpu.rx is generated in setup, tune, apply and shared-host mode, so a mistake would change mining thread counts on every rig. The probe runs XMRig briefly against a dead local pool. If it fails on a box with a built miner, the cap is applied without the auto ceiling, so a cap above auto could run more threads than auto. Nothing is irreversible: the config is regenerated on apply. The test hardware job passed on an earlier commit (9edd611), not on the current head. The only later product change is develop's #608, which the reviewer says does not touch this path.

Proof. CI: 11 success. Reviewer: PASS at cd1c0d0 by pithead-reviewer, round 2 (recorded 2026-11-15T01:49:56Z). Bench: job 4005: success on 9edd611, not the head; job 3999: success on dce294d, not the head; job 3972: success on a020d6d, not the head; job 3038: error on 5a2f3ab, not the head.

What to check.

• util/rx-profile.sh:98-107: when an operator pins an object with threads and max_threads_cnt, the clamp sets max_threads_cnt to the effective count even if the operator pinned a lower one. Example: {threads:8, max_threads_cnt:2} with cap 4 becomes 4. Check this can't raise threads in XMRig 6.26.
• util/rx-profile.sh:164-169: the object-clamp block repeats _rx_clamp_rx_object. This is a style nit only, not a bug.
• docs/how-it-works.md:181: still says setup sizes HugePages only from a numeric cpu.rx pin. rigforge.sh:1500 now also uses an object pin's threads, so the sentence is out of date.
• The PR body still calls 9edd611 'this head', but the head is cd1c0d0. The reviewer asked for a refresh. The bench job proves the PR's code at 9edd611, and only develop's Keep RigForge in control of generated XMRig config #608 came after it.

Verdict. merge: the reviewer passed round 2 and the checks are green. The open items are small notes: one doc sentence, a duplicated block, and the pinned-object edge case