[pithead-developer]

What's the problem

Closes #530

RigForge set only log-file among XMRig's logging keys, so every Linux rig ran XMRig's desktop defaults: ANSI colours in the journal and xmrig.log (the cause of the #483 and #477 workarounds), and no recorded values for the cadence and verbosity keys. The xmrig overlay (#526, merged in #604) already carries the five keys, so this builds the issue on it as ruled by the owner (no one-off key path, no branch on the unmerged overlay).

How I fixed it

• generate_xmrig_config emits colors: false on Linux and keeps XMRig's print-time: 60 and health-print-time: 60. The overlay merges after them, so colors, print-time, health-print-time, verbose and syslog all round-trip through "xmrig": {...}; verbose and syslog stay unset by default.
• support-bundle adds xmrig-logging.json with the five values in effect, filling XMRig's defaults for absent keys (_xmrig_logging_in_effect in util/xmrig-overlay.sh, so rigforge.sh stays under its file budget).
• Docs: docs/configuration.md lists the new static defaults; docs/operations.md documents the five keys, a longer cadence for the capped appliance journal, and verbose as the pool-handshake debugging path. logs --verbose is not added, as the issue specifies.
• Shortcut: macOS keeps XMRig's default colours and has no render test; upgrade if macOS support (Deprecate macOS as a supported platform #493) is revived.

Here is the proof

• bash tests/run.sh: 2695 passed, 0 failed (local, before the review fixes). GitHub CI on head 7eb1a7a: all ten checks pass, including Test suite, Coverage (kcov + diff-cover), End-to-end (Docker) and Lint (shellcheck + shfmt). New tests/test-xmrig-logging.sh (11 rows: Linux defaults, overlay round-trip of all five keys, bundle values including false and 0); a bundle row in tests/run.sh; plain and ANSI journal rows for _msr_log_status (doctor) and the e2e journal matcher.
• After the review fixes I re-ran tests/test-xmrig-logging.sh (11 passed), bash -n tests/run.sh, FILE_BUDGET_REQUIRE_BASE=1 bash scripts/lint-file-budget.sh (OK) and make lint-topology (OK). The one plain-journal doctor row added after the full run was not re-run on its own; GitHub CI covers it.
• make lint fails locally only on shfmt diffs that also exist on unmodified HEAD files (local shfmt 3.13.1); shellcheck on changed files reported nothing new.
• Not run as red-without-fix: the rows assert keys the old generator never emitted, so they cannot pass on develop.
• Reviewer return (no tier4-e2e on a real miner): phase_connect in tests/e2e-pithead.sh now asserts that the config rendered by this branch carries colors: false, print-time: 60 and health-print-time: 60, and that the xmrig.log the live XMRig wrote (truncated before the restart) holds no ANSI escape. tests/worker-proof.py and tests/test-worker-proof.sh carry the new pass counts (connect 10, replay groups 11). Submitted tier4-e2e phases=connect as job 4000 at head 7eb1a7a; its unedited bench-ci evidence block follows. Rows 45 and 46 of the job log are the two new (#530) assertions, both passing on the live miner.

bench-ci job 4000@7eb1a7ae5e49a77bf85e69a21aca404812ed37f6 · rigforge · tier4-e2e

• options: {"phases": ["connect"]}

• status: completed · conclusion: success · exit 0 · 3m 08s

• 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 4000@7eb1a7ae5e49a77bf85e69a21aca404812ed37f6; re-run it to check.

• The mktemp stderr noise in the new tests/test-xmrig-logging.sh is fixed with a mkdir of the build directory in its fixture; tests/test-xmrig-overlay.sh still prints it and is not touched here.

• Verifier review: the duplicated parse_case and the vacuous parse assertion were fixed and the doctor plain-journal row added. Left as is: hardcoded XMRig defaults in the bundle fallback (they describe XMRig's own behaviour), and no macOS render test.

• Ponytail pass: nothing cut; no new CLI flag or abstraction.

[pithead-reviewer]

FAIL

What I investigated

The code and unit-tier proof for #530 hold at head 63b27eb. I am returning it because the diff changes the XMRig config RigForge renders for a real miner and no tier4-e2e job on the head shows real XMRig accepting it.

• Claim: rigforge#530 asks for colors: false on Linux, print-time and health-print-time kept at 60 and settable, all five keys through the xmrig overlay, the five values in support-bundle, doctor journal parsing tested with colours on and off, and appliance cadence docs. The pithead-architect ruling of 2026-11-09 says to build the whole issue on the overlay after Add validated XMRig configuration overlays #604 merges. gh pr view 604 shows MERGED into develop on 2026-11-14, so the PR respects the sequencing.

• gh pr view 693 and git rev-parse HEAD: the head is 63b27eb, the base is develop, and the PR is a draft (not a finding).

• gh pr checks 693: all ten checks pass at the head (Test suite, Coverage kcov + diff-cover, End-to-end Docker, Lint shellcheck + shfmt, markdownlint, yamllint, gitleaks, zizmor, both Stock home setup jobs).

• Ran bash tests/test-xmrig-logging.sh at the head: 11 passed, 0 failed.

• Reverted rigforge.sh and util/xmrig-overlay.sh to 910f107 in a scratch worktree under $TMPDIR and ran the same module: 5 passed, 6 failed. The failures are colors null, print-time null, health-print-time null, and three rows with _xmrig_logging_in_effect: command not found. The overlay round-trip rows pass on the base because Add validated XMRig configuration overlays #604 already supplied the overlay. I removed the worktree afterwards.

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

• /Users/vijit/code/pithead-developer/private/detect-topology.py over the PR body, the PR comments and the issue Logging is the XMRig desktop default on a headless rig: ANSI colours in the log, 60 s report lines, no verbose/syslog control #530 comments: clean on all three, exit 0.

• Comment discipline: the only added # line in the diff is # shellcheck disable=SC1090,SC2034,SC2329 in the new test, which is a functional directive. rigforge.sh and util/xmrig-overlay.sh gained no explanatory comments.

• Consumers of the log: the ANSI-stripping sed calls in _msr_log_status (rigforge.sh:4937), miner_log in tests/e2e-real.sh:41 and util/benchmark.sh:166 are no-ops on plain text. I found no code that requires ANSI codes. Plain-journal rows were added for _msr_log_status and for the e2e miner_log_has.

• The rendered keys colors, print-time and health-print-time appear in util/xmrig-overlay-keys.jq with verbose and syslog, so none of the five triggers the 'undocumented key' warning. _xmrig_logging_in_effect treats false and 0 correctly: has("colors") for colors, and jq's // only replaces null or false, so 0 survives for the numeric keys.

• Not run: the full tests/run.sh suite, because the Test suite check at the head is green. Docker, the e2e and any bench job were not run, because this Mac runs no Docker and no tier4-e2e job is quoted for this PR.

• PR body, 'Here is the proof': The body quotes '2695 passed, 0 failed' from a local run made before the last review fixes. It says the plain-journal doctor row was not run on its own. CI at the head is green, so this does not block, but the body should quote the head's check results or a fresh run.

• tests/test-xmrig-logging.sh (generate_case): The test prints mktemp: mkstemp failed ... .rigforge-apply.json to stderr while it passes. tests/test-xmrig-overlay.sh, which the PR copied, prints the same noise (4 lines when I ran it), so it predates this PR. It is worth fixing with a mkdir of the build directory in the fixture, but it is not this PR's defect.

• rigforge.sh:1173: The ponytail pass found nothing to cut. It adds one --arg, two static keys and a four-line jq helper in util/ that exists to keep rigforge.sh under the file budget. The bundle fallback hardcodes XMRig's own defaults, which is acceptable.

Reviewed head: 63b27ebc2610614907689518506b751c8700984b.

What are the gaps

• rigforge.sh:1173 (generate_xmrig_config); PR body, 'Here is the proof': "No bench job: no worker-to-Pithead contract change; the unit tier covers it.": The diff changes config rendering for a real miner, and no tier4-e2e job on the head 63b27eb shows real XMRig accepting it. The reviewer rule 'tier follows the path' and the shared rule 8 apply whatever the body says about the change being static or config-only. Every row in the PR is tier-1 or the GitHub Docker e2e. The assertions read the rendered JSON and never start XMRig with it, which is the gap that let a one-line template change through tier 1 in PR #2327. The pithead-architect comment 'These are all unit-tier rows' is not the owner's waiver, because rule 8 says only the owner waives. The issue's own investigation brief also named tier4-e2e for this change. To clear it, submit a rigforge tier4-e2e job (targeted or matrix, not check) on the pushed head. It must deploy the branch to a rig so XMRig starts on the rendered colors: false, print-time: 60 and health-print-time: 60, and a doctor or MSR check reads the plain journal. Then paste the unedited bench-ci evidence <id>@<sha> block into the body. A tier-4 job whose own rows are green satisfies this even if the overall conclusion is failure, provided every other red row has an owning issue. Alternatively, record the owner's own waiver of rule 8 for this PR.

[pithead-reviewer]

PASS

What I investigated

This is a round-2 re-review of the worker's two new commits, 63b27eb..7eb1a7a: two #530 assertions in phase_connect of tests/e2e-pithead.sh, the matching worker-proof pass counts, and a mkdir in the fixture of tests/test-xmrig-logging.sh. The round-1 return is fixed. tier4-e2e job 4000 ran head 7eb1a7a and concluded success. On it, real XMRig ran the config this branch rendered, got a share accepted, and the new config row checked colors false and print-time/health-print-time 60. The new xmrig.log no-ANSI row cannot fail, as XMRig's own source shows (note below), but the required proof holds without it.

• git cat-file -e 63b27eb: present. git log --no-merges 63b27eb..7eb1a7a lists two worker commits, f22eb93 and 7eb1a7a. git diff --stat shows 4 test files, +11/-5.

• gh pr view 693: head 7eb1a7a, base develop, OPEN. The draft state is not a finding.

• gh pr checks 693 --json: all 10 checks SUCCESS (zizmor, yamllint, gitleaks, markdownlint, shellcheck+shfmt, Test suite, two stock home setups, End-to-end (Docker), Coverage). None skipped.

• bench-ci evidence 4000@7eb1a7ae5e49a77bf85e69a21aca404812ed37f6 (exit 0) is identical to the block in the PR body: tier4-e2e, phases connect, completed, conclusion success, exit 0, 10 pass / 0 fail / 0 skip, rig restored.

• bench-ci status 4000: commit 7eb1a7a, which is the PR head. bench-ci log 4000 (63 lines): it checks out 7eb1a7a in the rig's install tree. Then 'share accepted by the stack (1 so far)', '✓ generated config carries colors false and the 60 s report cadence (Logging is the XMRig desktop default on a headless rig: ANSI colours in the log, 60 s report lines, no verbose/syslog control #530)', '✓ xmrig.log written by the live miner carries no ANSI escapes (Logging is the XMRig desktop default on a headless rig: ANSI colours in the log, 60 s report lines, no verbose/syslog control #530)', 'e2e-pithead: 10 ok, 0 failed', the rig restored, and 'conclusion: success'. The first attempt was deferred on a rig lock and retried in the same job. That is a scheduling event, not a fault.

• Round-1 [return] finding (no tier4-e2e on a real miner): FIXED by job 4000 above. Real XMRig accepted and mined with the rendered config at the head.

• Round-1 [note] (stale '2695 passed' local count): still stands as a note. The body still quotes it, but it now also cites green CI at 7eb1a7a.

• Round-1 [note] (mktemp noise): FIXED in tests/test-xmrig-logging.sh:49. Running bash tests/test-xmrig-logging.sh exits 0 with 'xmrig logging: 11 passed, 0 failed' and writes 0 lines to stderr.

• Round-1 [note] (ponytail): this delta adds two assertions and count bumps, with nothing to cut.

• bash tests/test-worker-proof.sh exits 0 with 'worker proof integration: 22 passed'. tests/e2e-control-replay.sh:152 calls phase_connect, so the replay groups going from 9 to 11 matches the 2 new connect rows.

• FILE_BUDGET_REQUIRE_BASE=1 bash scripts/lint-file-budget.sh exits 0 ('file budget OK'). make lint-topology reports OK. bash -n tests/e2e-pithead.sh is OK.

• shellcheck on the 3 changed shell tests prints only info-level SC1091/SC2015/SC2016, all on lines this delta does not touch. CI Lint is green.

• XMRig source, in the local v6.24.0 checkout: src/base/io/log/Log.cpp:103-113 strips CSI escapes into txt and passes the backends colors=false with the stripped text. backends/FileLog.cpp print() returns early when colors is true. So xmrig.log is always free of ANSI. I am inferring that the pinned v6.26.0 behaves the same.

• detect-topology.py over the PR body, the PR comments and the Logging is the XMRig desktop default on a headless rig: ANSI colours in the log, 60 s report lines, no verbose/syslog control #530 comments: clean on all three.

• No added explanatory comments in the delta. The '(Logging is the XMRig desktop default on a headless rig: ANSI colours in the log, 60 s report lines, no verbose/syslog control #530)' strings are assertion output, which affects runtime.

• tests/e2e-pithead.sh:207: The 'xmrig.log … carries no ANSI escapes' row cannot fail. XMRig's file backend always receives text with the CSI escapes already stripped (Log.cpp:103-113, FileLog.cpp print skips the colored call), whatever 'colors' is set to. The colors setting only changes stdout, that is, the journal. The PR body cites this row as live proof of the fix. The real proof is row 45 (the config keys) plus XMRig accepting a share. To make the check meaningful, point it at the unit's journal output since the restart, or drop it. The issue's premise that colors put ANSI escapes in xmrig.log looks wrong for the same reason. Not blocking.

• PR body, 'Here is the proof': The body still quotes '2695 passed, 0 failed' from a local run made before the review fixes. The head's CI is green, so this does not block. Refresh the count or drop it.

Reviewed head: 7eb1a7ae5e49a77bf85e69a21aca404812ed37f6.