[pithead-developer]

What's the problem

RigForge discards XMRig settings it does not map, so an operator's edits to the generated config disappear on apply. Tuning can also overwrite a deliberately pinned value, and apply does not ask XMRig to validate the result before restarting.

How I fixed it

Added the optional xmrig object, merged after tuning and before the thread ceiling. Protected keys are rejected; undocumented names warn. Manual and scheduled tuning preserve overlay pins, history and doctor identify them, and the read feed includes a nonempty overlay without adding control write access.

Apply and its preview validate a private staged copy with XMRig before publishing it or changing the unit. The validation copy cannot daemonize, write logs, or allocate the CPU memory pool; an all-disabled pool set is rejected before XMRig can fall back to another config. Publication preserves miner ownership before restart. Updated documentation, fixtures, and coverage inclusion for the new helper.

Here is the proof

Before/after regression commands:

baseline_script=$(mktemp /tmp/rigforge-526-baseline.XXXXXX)
git show HEAD:rigforge.sh > "$baseline_script"
BASELINE_SCRIPT="$baseline_script" bash tests/test-xmrig-overlay.sh "$baseline_script"
BASELINE_SCRIPT="$baseline_script" bash tests/test-xmrig-overlay.sh "$PWD/rigforge.sh"

Original code: exit 1, 17 passed, 57 failed. Updated code: exit 0, 74 passed, 0 failed, including byte-identical generated output without an overlay. The tests also cover protected keys, merge order, tuning seeds/grid (including array and named-profile pins), parser failures, preview isolation, ownership/publication failures, a missing validation executable, doctor, and feed visibility.

Additional checks:

• PATH="/tmp/rigforge-526-tools:$PATH" make test: passed, exit 0; 2,430 main-suite checks and 70 overlay checks, zero failures, plus passing credential, readiness, clone-pin, and tool-pin suites. The temporary tool directory supplies repository-pinned shfmt 3.14.1. The native run explicitly skips Linux-only timing cases. Three validator assertions were subsequently added and passed in the final before/after run above; product code was unchanged.
• make test-e2e: passed, 88 deployment checks and 28 appliance checks, zero failures.
• make coverage: not a pass on this Mac. The emulated image hit a pre-existing donation fixture failure; that run was stopped. The environment-adjusted run below passed.
• FILE_BUDGET_REQUIRE_BASE=1 bash scripts/lint-file-budget.sh: passed.
• shellcheck --severity=warning rigforge.sh util/xmrig-overlay.sh tests/test-xmrig-overlay.sh: passed.
• npm_config_cache=/tmp/rigforge-526-npm npx --yes markdownlint-cli2@0.23.3 --no-globs PR-BODY.md README.md tests/README.md docs/configuration.md docs/pithead-integration.md: passed, zero issues.
• make lint-actions: passed.
• UV_CACHE_DIR=/tmp/rigforge-526-uv UV_TOOL_DIR=/tmp/rigforge-526-uv-tools UV_TOOL_BIN_DIR=/tmp/rigforge-526-uv-bin uv tool run --from yamllint==1.38.0 yamllint --strict $(git ls-files '*.yml' '*.yaml'): passed. The Make target initially failed because yamllint was not installed; this temporary tool environment ran the same inputs successfully.
• jq empty config.reference.json, bash -n rigforge.sh tests/run.sh util/xmrig-overlay.sh tests/test-xmrig-overlay.sh, and git diff --check: passed.

The installed shfmt 3.13.1 reported unrelated formatting differences; the pinned version was used instead. Broad Markdown lint also reads the supplied untracked ISSUE.md, which has three existing lint errors; the changed documents pass the focused command above.

The donation fixture failure also occurs on untouched HEAD because the emulated image's lscpu omits Model name. Its existing test was left unchanged. Baseline command (exit 1):

BASE=/tmp/rigforge-526-head-baseline
mkdir -p "$BASE"
git archive HEAD rigforge.sh util tests/test-donation.sh tests/test-e2e-donation.sh tests/e2e-donation.sh | tar -x -C "$BASE"
docker run --rm -v "$BASE:/baseline:ro" -v "$PWD/.coverage-cache/jq-linux-amd64:/usr/local/bin/jq:ro" -w /baseline --entrypoint bash 'kcov/kcov@sha256:30c442617f3d8e040bf0ec2cba19cc2ee517b668f3a3d50b2d3de1c435138a8a' tests/test-donation.sh /baseline/rigforge.sh

For coverage, the same pinned container and full suite were rerun with a temporary CPU-model fallback confined to the container:

coverage_fixture=$(mktemp -d /tmp/rigforge-526-coverage-fixture.XXXXXX)
cat > "$coverage_fixture/lscpu" <<'SH'
#!/bin/sh
if [ "$#" -ne 0 ]; then exec /usr/bin/lscpu "$@"; fi
output=$(/usr/bin/lscpu) || exit "$?"
printf '%s\n' "$output"
if ! printf '%s\n' "$output" | grep -Eq '^Model name:[[:space:]]*[^[:space:]]'; then
    printf 'Model name: Fixture CPU\n'
fi
SH
chmod +x "$coverage_fixture/lscpu"
docker run --rm --security-opt seccomp=unconfined --cap-add SYS_PTRACE \
    -v "$PWD:/src" -v "$PWD/.coverage-cache/jq-linux-amd64:/usr/local/bin/jq:ro" \
    -v "$coverage_fixture/lscpu:/usr/local/bin/lscpu:ro" -w /src \
    --entrypoint kcov kcov/kcov@sha256:30c442617f3d8e040bf0ec2cba19cc2ee517b668f3a3d50b2d3de1c435138a8a \
    --include-pattern=/src/rigforge.sh,/src/util/ --clean /src/coverage ./tests/run.sh

The full Linux suite passed, exit 0: 2,349 main-suite checks and 69 overlay checks, zero failures. The final overlay module was then rerun under kcov and merged with that report; this includes the three subsequently added missing-executable assertions without changing product code:

extra_coverage=$(mktemp -d /tmp/rigforge-526-extra-coverage.XXXXXX)
docker run --rm --security-opt seccomp=unconfined --cap-add SYS_PTRACE \
    -v "$PWD:/src:ro" -v "$PWD/.coverage-cache/jq-linux-amd64:/usr/local/bin/jq:ro" \
    -v "$extra_coverage:/extra" -w /src --entrypoint kcov \
    kcov/kcov@sha256:30c442617f3d8e040bf0ec2cba19cc2ee517b668f3a3d50b2d3de1c435138a8a \
    --include-pattern=/src/rigforge.sh,/src/util/ --clean /extra \
    ./tests/test-xmrig-overlay.sh /src/rigforge.sh
merged_coverage=$(mktemp -d /tmp/rigforge-526-merged-coverage.XXXXXX)
docker run --rm -v "$PWD:/src:ro" -v "$extra_coverage:/extra:ro" \
    -v "$merged_coverage:/merged" --entrypoint kcov \
    kcov/kcov@sha256:30c442617f3d8e040bf0ec2cba19cc2ee517b668f3a3d50b2d3de1c435138a8a \
    --merge /merged /src/coverage /extra
cov_json="$merged_coverage/kcov-merged/coverage.json"
coverage_floor=$(tr -d '[:space:]' < tests/coverage-floor.txt)
jq -e --argjson floor "$coverage_floor" '(.total_lines > 0) and ((.percent_covered | tonumber) >= $floor)' "$cov_json"
sed -e 's#/src/##g' -e 's#<source>/src</source>#<source>.</source>#g' "$merged_coverage/kcov-merged/cobertura.xml" > coverage/cobertura.xml
UV_CACHE_DIR=/tmp/rigforge-526-uv UV_TOOL_DIR=/tmp/rigforge-526-uv-tools UV_TOOL_BIN_DIR=/tmp/rigforge-526-uv-bin \
    uv tool run --from diff-cover==10.6.0 diff-cover coverage/cobertura.xml \
    --compare-branch=HEAD --include-untracked --fail-under=90

Final module: 72 passed, 0 failed, exit 0. Merge and both gates passed, exit 0: 95.12% overall coverage (3,238/3,404 lines; floor 80%) and 90.30% patch coverage (121/134 lines; floor 90%). Report parsing used native jq on macOS. No coverage thresholds or exclusions were weakened.

The pinned image lacks Python, so it explicitly skipped the overlay receiver allowlist, API wire/IPv6, receiver/applier lockstep, control-server wire, and server-driven contract checks. Those passed in the native suite. The Linux-only tune timing checks passed in the coverage run.

Bench proof on the pre-merge head (eba5d0d), phase worker-api, which carries the overlay rows (overlay merged into the generated config, unit restarted by the apply, worker mining afterwards, feed carries the overlay, removal restores the generated config). Printed by bench-ci evidence 3509@eba5d0d90569cdbef55ede98afc2f808c2b86385:

bench-ci job 3509@eba5d0d90569cdbef55ede98afc2f808c2b86385 · rigforge · tier4-e2e

• options: {"phases": ["worker-api"]}
• status: completed · conclusion: success · exit 0 · 2m 47s
• 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: 10 pass · 0 fail · 0 skip
  Generated by bench-ci evidence 3509@eba5d0d90569cdbef55ede98afc2f808c2b86385; re-run it to check.

The base branch then grew the shared-host profile, which conflicted with this branch's apply path. Head 5b1611b merges the base in; the staged overlay apply and the shared-host unit lifecycle coexist (profile preparation before the runtime apply, the staged config validated before the unit is re-rendered, the reload through the shared-host helper), and the worker-api overlay rows moved byte-identically into a split file to respect the file budget. On the merged head the offline suite passes 2,446 checks with zero failures. A fresh bench job 3567@5b1611bc99c03e5cc90cce1666e340bffbf4cfd8 (same phase and options as the block above) covers this head; its evidence block will be pasted here when it completes. The block above is from the pre-merge head and does not cover it.

The apply ran against the rig's real XMRig and the unit restarted, so the staged --dry-run validation was accepted by the real binary. Not run: other tier4-e2e phases (the change touches only the worker-api feed and apply path), KVM, and the Pithead editor /apply allowlist round trip for xmrig (companion side, not exercised here).

Closes #526

Draft from an operator-run gpt-6-astra session (owner request, 2026-11-01). The operator reviews and gates it before it leaves draft.

🤖 Generated with Claude Code

[pithead-developer]

Operator: this v2.x enhancement stays a held draft until RigForge 1.18.1 is tagged (due Fri 2026-11-06, Sat 11-07 at the latest). 1.18.1 is cut from develop, so merging this first would widen that release. After the tag: rebase on develop, run the agent review, and request the owner's approval.

[pithead-developer]

Operator: released to the runner (owner 2026-11-06). New work goes to the local Flash-Next model first; Claude only after three local rounds or for sensitive work.

[pithead-reviewer]

FAIL

What I investigated

Reviewed rigforge PR 604 (head 551c922) against issue 526. The tier 1-3 evidence holds: the new overlay test fails on develop's rigforge.sh and passes on the head, and CI at the head is green. The PR is a RETURN because it has no bench-ci tier4-e2e job on the head, and the PR body says that proof is still needed.

• gh pr view 604 / gh issue view 526: issue 526 asks for an xmrig overlay in config.json merged after tune-overrides and before the threads cap, protected keys refused, tune/autotune pins, xmrig --dry-run before restart in apply and apply --dry-run, doctor and feed visibility, and no control-path write access. The PR body says 'Closes No way to set an XMRig key RigForge does not map: add an xmrig overlay to config.json, validated with xmrig --dry-run #526'. Its last paragraph says 'Still needed: a real pinned-XMRig hardware run and the worker-to-coordinator tier4-e2e bench proof'. It quotes no bench-ci job.

• bench-ci list --all --repo rigforge --commit 551c922 printed 'queued 0, in progress 0, completed 0'. No job exists on the head.

• gh pr checks 604 --json: all 10 checks SUCCESS (Test suite, Coverage, End-to-end (Docker), shellcheck+shfmt, markdownlint, yamllint, gitleaks, zizmor, both Stock home setup). gh run view 42356486522: headSha 551c922, conclusion success. The base develop-v1.19.0 is the same commit as develop (git ls-remote).

• bash tests/test-xmrig-overlay.sh against develop's rigforge.sh without BASELINE_SCRIPT: exit 1, '16 passed, 57 failed'. With BASELINE_SCRIPT set (the PR's own command): '17 passed, 57 failed'. Against the head with BASELINE_SCRIPT set: exit 0, '74 passed, 0 failed'. This matches the numbers in the PR body.

• FILE_BUDGET_REQUIRE_BASE=1 bash scripts/lint-file-budget.sh: 'file budget OK'. rigforge.sh is 6302 lines against a ceiling of 6303.

• make test: lint stopped at shfmt 3.13.1 on tests/run.sh and tests/test-xmrig-overlay.sh. develop's own tests/run.sh also fails under this local shfmt, so it is a local tool-version difference. The head's CI shfmt job passes, and CI is authoritative here.

• make test-suite: started locally, not finished when I stopped waiting. It showed 0 failure marks and printed 'test-xmrig-overlay 73 passed, 0 failed' (the overlay module). I rely on the head's CI Test suite job for the full-suite result.

• detect-topology.py over the PR body and comments, and over the issue comments: 'clean', exit 0 for both.

• git diff origin/develop...HEAD -U0 | grep added comment lines: only shellcheck directives and shebangs (rigforge.sh:68, util/xmrig-overlay.sh:2, tests/test-xmrig-overlay.sh:2). No explanatory comment was added.

• ponytail-review pass over the diff: no stdlib reimplementation, no new dependency, no unrequested knob. Only notes below.

• Docker was not started and no container tier was reproduced. The only bench-ci command I ran was list (the evidence/log commands need a quoted job id, and the PR quotes none).

• rigforge.sh:5266 (_api_config_json); rigforge.sh:5242-5246 comment; rigforge.sh:4282-4288 (_control_commit allowlist); util/control-server.py:21: The feed's config now holds xmrig, but /apply rejects any key outside the six writable ones ('rejected non-writable-keys:xmrig'). The docs say Worker Inspect prefills its editor from rigforge.config. If the stack POSTs the prefilled object back whole, its own apply would be refused. I inferred this from the code and did not verify it against the Pithead consumer, so the tier4 worker-api/network phases should show it. config_meta.revision also does not cover the overlay, so a poller cannot see an overlay-only change. Issue 526 asks for the feed to carry the overlay. This is a contract risk, not a deviation.

• rigforge.sh:2549, 2558, 2763, 2934: Explanatory comments survive inside functions whose lines the PR edits: the _tune_knobs_json header, the _tune_config header, the 'tune: hashrate-per-watt is measured wrong — watts sampled at idle in --bench, single sample, no built-in RAPL delta #81: watts is the median...' block inside _measure, and the _gridsearch header. The comment rule says explanatory comments in edited hunks are deleted. The author already removed other such comments (the _apply_runtime header, the ci.yml and coverage.sh lines).

• util/xmrig-overlay.sh:41-45 (_xmrig_knob_lines) vs rigforge.sh:2791 (_knob_values): The pinned-value branch exists twice: _knob_values already returns the pinned value, and _xmrig_knob_lines repeats the check. It is needed because array pins such as cpu.rx break word splitting, and the PR tests it. Smaller option: make _knob_values itself emit one value per line. Not blocking.

• util/xmrig-overlay.sh:6-18 (_parse_xmrig_overlay): Only the top-level protected roots are refused. An overlay can still set live-unit-breaking keys such as background: true, dry-run: true or autosave: true. The validation copy forces dry-run true and background false, so validation cannot catch them. The issue says not to forbid such keys, so I did not raise this as a defect. The PR body 'How I fixed it' should state this known limit.

Reviewed head: 551c922f3f6e98ad973f4ec468d0b9ea516e665e.

What are the gaps

• PR body 'Still needed' paragraph; util/xmrig-overlay.sh:104-130 (_stage_xmrig_config), util/xmrig-overlay.sh:78-100 (_validate_xmrig_config), rigforge.sh:4156 and 4181 (apply and the apply --dry-run preview), rigforge.sh:5266 (_api_config_json); bench-ci list on 551c922 shows 0 jobs: No tier4-e2e bench-ci job on the head. The diff changes config rendering and the apply/restart path. It invokes the real XMRig binary with --dry-run for the first time. It changes the worker-to-stack feed (rigforge.config now carries xmrig). The runner's tier rule needs a tier4-e2e job on the head for these paths. The PR body admits this proof is missing and says it has no real-XMRig run. Issue 526's investigation brief also required tier4-e2e and flagged as unverified whether the pinned XMRig supports --dry-run. Nothing here shows the real parser accepts the staged validation copy: dry-run set to true, background false, log-file null, syslog false, title false, colors false, and cpu.memory-pool false. Nothing here shows --dry-run exits 0 while the live miner is running, or that apply still restarts cleanly. The local tests use a stub XMRig that returns exit 0. Fix: submit a rigforge tier4-e2e job (targeted or matrix) on the final head covering apply with a real overlay, and quote its evidence block in the PR body, unedited.

[pithead-reviewer]

PASS

What I investigated

Re-review of PR 604 (issue 526) at head eba5d0d: the worker's commits since 551c922 are 342ae6e, cfd1f3e and eba5d0d. They delete the four flagged comments and add five xmrig-overlay rows to the worker-api tier4 phase. The round-1 RETURN (no tier4-e2e job on the head) is fixed: bench-ci job 3509 ran on eba5d0d and every row is green. That includes the overlay apply through the real XMRig validation and a unit restart. The remaining round-1 items are notes and stay notes.

• git cat-file -e 551c922…: present. git log --no-merges 551c922..eba5d0d shows 342ae6e, cfd1f3e and eba5d0d. git diff --stat: rigforge.sh -9 (comment lines only), tests/e2e-pithead.sh +15.

• Round 1 [return] no tier4-e2e on the head: FIXED. bench-ci evidence 3509@eba5d0d90569cdbef55ede98afc2f808c2b86385 exits 0 and prints a block identical to the PR body's: rigforge tier4-e2e, phases [worker-api], completed, conclusion success, exit 0, baseline verified yes, rig restored yes, all steps success, rows 10 pass, 0 fail, 0 skip.

• bench-ci log 3509 (51 lines) shows checkout of eba5d0d into the rig's install tree, then these rows: 'xmrig overlay merged into the generated config', 'unit restarted by the overlay apply', 'worker mining after the overlay restart', 'feed config carries the xmrig overlay', 'overlay removal restored the generated config'. It ends with 'phase worker-api: passed (10 assertions, 0 skipped)'.

• Real-XMRig --dry-run acceptance: set_cfg (tests/e2e-pithead.sh:135) runs rigforge.sh apply and dies on failure. _apply_runtime (rigforge.sh:4147) returns 1 when _stage_xmrig_config fails. _stage_xmrig_config (util/xmrig-overlay.sh:104-130) always calls _validate_xmrig_config, which runs $bin --config validation --dry-run (util/xmrig-overlay.sh:95). The overlay row could therefore pass only if the rig's real XMRig accepted the staged copy.

• The overlay rows are not vacuous: the Linux default MEMORY_POOL is true (rigforge.sh:1062) and only Darwin forces false (rigforge.sh:1090), so .cpu."memory-pool" == false holds only because the overlay merged.

• bench-ci tiers: rigforge/tier4-e2e accepts only phases, not modes. The worker-api phase is the phase that covers the apply path and the feed, and the job built the branch on the rig.

• Round 1 [note] feed round-trip with the /apply allowlist: answered in the body. It lists the Pithead editor round trip as not exercised (companion side). The note stands and does not block.

• Round 1 [note] comments in edited tune hunks: FIXED by 342ae6e, which removes the comments at the four flagged lines (_tune_knobs_json header, _tune_config header, the tune: hashrate-per-watt is measured wrong — watts sampled at idle in --bench, single sample, no built-in RAPL delta #81 block in _measure, _gridsearch header).

• Round 1 [note] _knob_values / _xmrig_knob_lines duplication: unchanged. The note stands and does not block.

• Round 1 [note] overlay can still set background/dry-run/autosave: unchanged, and the body's 'How I fixed it' still does not state this limit. The note stands and does not block.

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

• FILE_BUDGET_REQUIRE_BASE=1 bash scripts/lint-file-budget.sh: exit 0, 'file budget OK'.

• bash tests/test-xmrig-overlay.sh $PWD/rigforge.sh on macOS: exit 0, '73 passed, 0 failed'. The body's 74 and 72 come from other runs; the count differs by platform-specific cases.

• bash -n tests/e2e-pithead.sh: exit 0. shellcheck --severity=warning tests/e2e-pithead.sh: exit 0.

• Comment discipline: the new test hunk adds no comments.

• detect-topology.py over the PR body, the PR comments, the PR review comments and reviews, and the issue 526 comments: 'clean' on every file, exit 0.

• Base develop-v1.19.0: git ls-remote shows it at the same SHA as develop (b1c25d6). This is an operator-run session; not a finding.

• util/xmrig-overlay.sh:6-18; PR body 'How I fixed it': Standing from round 1: an overlay can still set keys that break the live unit, such as background, dry-run or autosave. The validation copy overrides background and dry-run, so validation cannot catch them. State this known limit in the body under 'How I fixed it'.

• rigforge.sh _api_config_json; util/control-server.py writable-key allowlist: Standing from round 1: the feed config now carries xmrig, but /apply refuses that key. The Pithead editor round trip is unverified; the body says so. Cover it on the companion side before the editor prefills from rigforge.config.

• util/xmrig-overlay.sh:41-45 vs rigforge.sh _knob_values: Standing from round 1: the pinned-value branch exists twice. The smaller option is to make _knob_values emit one value per line.

Reviewed head: eba5d0d90569cdbef55ede98afc2f808c2b86385.

[pithead-reviewer]

Owner brief for eba5d0d90569

What it does. Adds an optional xmrig object to config.json so operators can set XMRig keys RigForge does not map. It is merged after tuning and before the thread cap, and tuning leaves pinned keys alone. Apply and apply --dry-run now check a private staged copy with XMRig's own --dry-run parser before publishing it or restarting the unit. Doctor, tune history and the read feed show the overlay.

Why. Closes issue 526 (milestone v2.x post-GA, the foundational XMRig-surface item). Before, unmapped XMRig settings were dropped, hand-edits to the generated config were overwritten on the next apply, and tuning could only sweep a knob, never pin it. Apply also never asked XMRig to validate the result.

Risk. Apply now requires a built XMRig binary and fails if validation fails, so a rig that previously applied without one will stop doing so. It also rewrites the apply path, the unit re-render and the tune grid loops, which every rig uses. An overlay can still set keys like background, dry-run or autosave that break the live unit, because validation overrides them. The feed now carries xmrig, but the control path refuses to write it, so a Pithead editor that posts the prefilled config back whole may be refused. That has not been verified against Pithead. Nothing irreversible; the overlay is opt-in.

Proof. CI: 11 success. Reviewer: PASS at eba5d0d by pithead-reviewer, round 2 (recorded 2026-11-07T12:24:48Z). Bench: job 3509: success on the head.

What to check.

• rigforge.sh:4137-4200 (_apply_runtime and apply): apply now stages and validates first, then refreshes the unit. Check that a deliberately stopped rig stays stopped and that a failed validation leaves the live config untouched.
• util/xmrig-overlay.sh:6-18 and 78-130: the protected-key list, the validation copy's overrides, and the stage and publish steps with ownership.
• rigforge.sh _api_config_json (around line 5257) and util/control-server.py: the feed adds xmrig, but /apply refuses that key. Decide whether that gap is acceptable before the Pithead side prefills from it.
• rigforge.sh:2784-2955 (_knob_values and _gridsearch): the grid loops were rewritten to read one value per line, so check that tuning without an overlay behaves exactly as before.

Verdict. merge: the reviewer's remaining notes are non-blocking. If you want the overlay limits stated, ask for a line in the docs about overlay keys that can break the live unit