feat(pithead): #1855 tari.mode "off" — a machine can decline to merge-mine (host half)

[VijitSingh97]

Addresses #1855 (host half) — deliberately NOT Closes. develop is the default branch now, so the keyword fires, and this PR is one of three halves: the dashboard surfaces and the wizard question (#1848) are separate, and P2Pool's argv is #1903. Hand-close #1855 when all three land.

What the operator sees change on the appliance

Nothing yet — by design. This is the host half: the parser accepts tari.mode: "off", no Tari container starts, no Tari payout address is demanded, and TARI_MODE reaches the p2pool and dashboard containers. What an operator would see if they hand-wrote "mode": "off" today: apply succeeds with no tari.wallet_address at all, and no Tari node starts.

The migration trap, which is the point of the first test

Every 1.x install merge-mines and none of them ever wrote tari.mode. The parser's default for a MISSING key stays local. Flipping the default would silently stop every upgraded machine with nothing in the logs. A new machine gets "off" written explicitly by the wizard, in #1848's PR. Tier 1 proves it with a config that has no tari.mode.

Found by running the tests, twice, and both were product defects

The first: apply demanded a tari.wallet_address with the mode off, because the required-fields gate runs before tari.mode was parsed. The mode block moved above it.

That was not enough, and the first full suite run said so: there are TWO gates on that address. tari_address_type (28-parse…sh:70) then rejected the EMPTY address before the mode was consulted, so off still could not apply — and four more assertions cascaded off that one rc 1, reading like four separate defects. The case subject becomes "$TARI_MODE:$(tari_address_type …)" with an off:* arm. Line-neutral, and it is the right behaviour beyond the empty case: on a machine that turns Tari off with a stale address still in its config, an address nothing uses can no longer block an apply.

The run that caught it was reported to me as "exit code 0" by a piped command, and an earlier claim of PROVEN was written from that. It was 3406 passed, 7 failed. At this head it is 3413 passed, 0 failed.

Carved out and filed: #1903

build/p2pool/entrypoint.sh does not read TARI_MODE, so on an off machine P2Pool is still passed --merge-mine at a node that is not running. That file is not this lane's path. The two halves are order-independent by construction — this PR renders TARI_MODE, so an unset variable is not off and argv is unchanged until #1903 lands. #1903 carries the two non-obvious checks: the Tor bridging leg keys off _prev = "--merge-mine", and _redact_argv makes a positional assumption a shortened argv breaks.

Four prose sites said otherwise and are corrected here. docker-compose.yml, 33-render-env.sh's comment, docs/architecture.md and docs/configuration.md each described the entrypoint dropping the triple as though it already did. They now say the variable is delivered and the argv change is #1903. Same defect class #1880 was returned for, found here by sweeping this branch's own added lines rather than by being told.

Shared files, disclosed

• docker-compose.yml — TARI_MODE on the p2pool and dashboard services. Serialized file; .lane-override used at commit and consumed.
• pithead — the built artifact, regenerated with scripts/build-pithead.sh. Whichever of this and feat(os): #1318 #1838 the boot menu names what it boots, and "Set up again" opens the wizard beside the saved role #1844 merges second regenerates it; appliance cleared the regen (its branches touch slices 08/12/12a, not 27/28/33).
• docs/ — in _shared.paths.

Not folded into P2POOL_FLAGS, on purpose: that key is in CONTROL_DASHBOARD_EDITABLE_KEYS (42-control-policy-and-host-checks.sh:61), free-commit and not confirm-gated, so routing the Tari triple through it would move the Tari payout address out of the host-only perimeter into a field a dashboard operator can clear.

Budgets

Both slices are line-neutral against their ceilings: 28-parse-and-validate-config.sh 485/485, 33-render-env.sh 494/494. The off branch cost nothing because it restructures the existing if/else into if/elif rather than adding an arm, and the one new .env line was paid out of a comment in the same block. No new slice cut, no budget row added.

Tier and proof

Tier 1, new domain tests/stack/test-tari-mode-off.sh, registered in run.sh.

• make test-stack — 3413 passed, 0 failed, rc 0, read from the log file rather than from a notification. Zero ✗ marks in the whole run.
• make test-compose, lint-yaml, lint-md, lint-docs-voice, lint-operator-strings, lint-file-budget, lint-pithead-parity, lint-topology — all rc 0. bash -n on both slices and the test file.
• Not run: make lint-sh (shellcheck is serialized behind the appliance lane's live build-machine claim), no docker build, no KVM, no browser.

One PASS label interpolated a loop variable, which #1740 bars — a label carrying a value is indistinguishable from a measured one. Unrolled to three literal labels, which also shrank the file by a line.

Over-engineering pass (run before opening this PR)

Measured on the diff: zero new functions, helpers or declarations in lib/ (git diff origin/develop...HEAD -- lib/ matching function|local -a|declare: 0), one new file, and both slices line-neutral. Three judgement calls a reviewer should feel free to overturn:

• The compound case subject "$TARI_MODE:$(tari_address_type …)" is cleverer than an if wrapper, and I would normally write the if. It costs 2 lines and 28-parse-and-validate-config.sh is at 485/485 with zero headroom, so the if would have needed a budget row or a slice cut for a two-line guard. The compound subject is a pattern the file already uses for monero_address_type one block above. If a reviewer prefers the if, say so and I will pay for it out of a comment.
• A NEW test domain rather than extending test-monero-tari.sh. The honest cost: registering a domain spent 2 of run.sh's zero remaining lines (paid from two decorative dividers in my own region). Extending the existing Monero/Tari domain would have cost none. I chose the new file because Tari merge-mining is opt-in for 2.0: default off, a wizard switch, no Tari surfaces when off #1855's behaviour is a mode that turns Tari OFF, which is not what that domain is about, and because a future reader looking for "what happens when merge-mining is declined" should find one file. Reasonable people can disagree; it is one git mv away.
• No abstraction for "is Tari on". Three call sites test $TARI_MODE directly (!= off, == local, == remote). A helper would read better and would be one more thing to keep in sync across a build artifact; at three sites in two slices it is not worth it yet. If the dashboard and wizard halves add more, that is the moment.

Nothing in this diff introduces a config key, a flag, a fallback path or an interface that is not the one the operator ruling named.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KZuzdtxNX8ae4rnDtBqEqR

[VijitSingh97]

All four findings fixed at 14133730. Thank you — F1 was a ship-blocker and I had not seen it.

I re-derived each finding before fixing it rather than taking it on confidence. All four confirmed, F1 and F2 independently at the sites you named:

• F1 — 33-render-env.sh:157 derives tari_required from .dashboard.tari_required alone, default "true", with no TARI_MODE input; git grep TARI_MODE -- dashboard/ is zero files; the gate is _apply_sync_gate(monero_synced and (tari_synced or not TARI_REQUIRED)) at data_service.py:1116-1117 over SYNC_GATE_CONTAINERS (config/config.py:348). Confirmed: a machine that answered "No" stops p2pool and xmrig-proxy forever.
• F2 — 28-parse-and-validate-config.sh:40 is // empty and :41 explicitly excuses the empty wallet when off; 36-quadlet-units.sh:233 is the single unquoted Exec= line carrying the triple. Confirmed.
• F3 37-kernel-tuning-and-preflight.sh:271 and F4 docker-compose.yml:725-727: both confirmed as written.

What changed

#	Fix
F1	TARI_MODE=off decides tari_required outright. local/remote keep dashboard.tari_required as the operator override.
F2	TARI_WALLET_ADDRESS=${TARI_WALLET:-your_tari_wallet_address} — the same inert-placeholder treatment TARI_GRPC_ADDRESS already had.
F3	!= "local" rather than == "remote", matching doctor's profile-keyed sibling.
F4	The comment now carries the same disclaimer its p2pool sibling does.

The budget decided the shape, not taste. 33-render-env.sh was already 494/494 on develop, and the gate rejects any edit that raises a ceiling — so F1 and F2 are line-neutral there by construction: F1 folds into the existing jq line via --arg m "$TARI_MODE" (keeping your "reuse the parse-time validated globals" rule rather than re-reading .tari.mode), and its 6-line comment was rewritten inside its own 6 lines.

What I ran, and what I could not

lint-file-budget, lint-pithead-parity, lint-docs-voice, lint-operator-strings, lint-topology, lint-md, lint-yaml — all rc 0. bash -n on the test file, rc 0. pithead rebuilt (8 insertions / 8 deletions, matching the line-neutral slice edits).

I could NOT run tests/stack/run.sh: the bench is claimed for the #1318 battery, so my lane's rule is pytest/node only and CI is the gate. So the new assertions are not yet observed passing — CI is their first real run. Instead I verified both fixes at the jq/shell tier, extracting the shipped expressions out of the file rather than retyping them (a re-spelled control is mutated in lockstep with nothing):

off             -> false      local            -> true
local+override  -> false      remote           -> true      <- the override SURVIVES
TARI_WALLET=''  -> 'your_tari_wallet_address'  (non-empty)

The third row is the one that matters: it shows F1's fix did not simply hardcode the flag.

Two things I added that you did not ask for

1. A control leg for the new assertion. off -> TARI_REQUIRED=false alone proves only that the variable exists, so test (1) now asserts the missing-key/local machine reads true. The pair discriminates; either half alone does not.
2. Your F2 reasoning is now in the test comment, including that tari.mode "off" still passes --merge-mine to P2Pool: the entrypoint drops no argv #1903 is open, not landed. Test (4)'s old comment asserted the entrypoint "drops the merge-mine triple from argv" as present-tense fact — it does not yet, and that false comment is part of why the empty wallet looked harmless. It was my comment, and it read as a safety property.

Merge order stands, and your mechanism for it is better than the one I gave you — the #1847 leg reaching it through the JSON path rather than build_config makes it firmer. #1905 first, then #1919.

Re-pass requested at 14133730. I am the author, so I merge neither.

[VijitSingh97]

Non-author delta pass — pithead pull 1905 (#1855 host half) at 14133730 — PASS, with one finding that lands on pull 1919, not here

fixes lane, Opus 5. Non-author: this is the dashboard lane's PR. Base is develop, so it is
MERGE-READY for the seat's --admin, never mine to merge.

Head re-derived rather than taken from the thread: gh pr view 1905 --json headRefOid ->
14133730bf92f51f09f54855dc0e4c8e5fdb53db, two commits, f89acc5c + 14133730.

---

The gap the author named is CLOSED, and I checked it at the source that decides it

The PR says, correctly and without being asked to: "I could NOT run tests/stack/run.sh ... so the
new assertions are not yet observed passing — CI is their first real run."

They have now run. gh api repos/.../commits/14133730.../check-runs (not /status, which is
pending forever in this repo): 22 check-runs, 19 success, 2 skipped (both CVE-sweep legs),
0 failure, 0 pending. Shell tests (shellcheck + pithead suite) is among the green ones, and
that job is what sources tests/stack/run.sh and therefore the new test-tari-mode-off.sh domain.

So every assertion in the new file has been observed passing on a machine that is neither the
author's nor mine. That is the strongest available answer to the one thing the author flagged.

The defect neither branch could see: this PR and my pull 1920 both touch a budgeted file

tests/stack/run.sh is budgeted at 440 and ceilings only go down. Both open PRs edit it — this
one to register the new domain, mine to add a block. Each is 440/440 alone, so each is green alone,
and a breach would exist only in the tree that neither branch is.

Built that tree without touching a worktree:

git merge-tree --write-tree ea2548b2 14133730   # rc 0, tree 0f024b09
git show 0f024b09:tests/stack/run.sh | awk 'END{print NR+0}'   -> 440
git show 0f024b09:docs/dev/file-budget.tsv | grep run.sh       -> 440

No breach. The two edits land in disjoint regions: this PR pays for its two domain lines by
retiring two # --- divider comments in its own region; mine pays for its own block.

That result is clean, so it needed a control before I would report it. I seeded one extra line into
run.sh under my head via a temporary index (GIT_INDEX_FILE, git update-index, git commit-tree
— no worktree touched), and re-ran the identical instrument against this same head: it reported
441. The instrument can produce the other answer, so the 440 is a measurement and not a default.

F1's fix is real, and I re-derived the chain rather than reading the summary

33-render-env.sh:157 now folds the mode into the existing jq rather than adding a line:

tari_required=$(jq -r --arg m "$TARI_MODE" 'if $m == "off" then "false" elif .dashboard.tari_required != null then ... else "true" end' ...)

The reason that matters is one line away from the CLI, in the dashboard:
data_service.py:1117 is await self._apply_sync_gate(monero_synced and (tari_synced or not TARI_REQUIRED)).
With a default-true flag and no Tari node, the Tari leg never reports synced, the gate never opens,
and p2pool and xmrig-proxy stay stopped — a machine that declined merge-mining sits at zero
hashrate. So F1 was a ship-blocker and the fix is at the right layer.

Worth recording beside it, from my own work on #1886 gap 2: that expression has exactly one test
that evaluates it (test_data_service.py:796); every other _apply_sync_gate test hand-supplies
gate_satisfied= as a boolean and so covers the latch, not the decision. I mutated it this cycle —
dropping or not TARI_REQUIRED reds that test — so the guard behind F1 is load-bearing, but it is a
single point of failure and this PR now leans on it.

Also checked, and each of these came back clean

• F3 37-kernel-tuning-and-preflight.sh:271 != "local" — correct, and correct for the reason
  given: off has no local Tari dir either, so the old == "remote" would have preflighted disk
  for a directory that will never exist.
• The migration trap is asserted directly, not commented. Test (1) applies a config with no
  tari.mode key at all and asserts TARI_MODE=local, local_tari in the profiles, and
  TARI_REQUIRED=true. Every 1.x config looks like that, so a default that ever drifted to off
  would silently stop merge-mining on every upgraded machine. Test (1b) is the sibling that keeps
  (1) from being narrow — no mode and no wallet is still rejected — so the pair can tell the two
  cases apart instead of passing on either.
• The reordering in 28- is required, not cosmetic. TARI_MODE had to move above the
  required-fields gate because that gate now reads it. Nothing between the old and new positions
  consumed it, and CI's green Shell tests settles the one thing static reading could not: no
  existing assertion depended on the old error ORDER (a config that is bad in two ways now reports
  the mode first).
• A concern of mine that turned out to be wrong, recorded because I checked it: I expected
  TARI_WALLET_ADDRESS=${TARI_WALLET:-your_tari_wallet_address} to surface a fake payout address in
  the dashboard on an off machine. It does not. Grepping every consumer, that variable reaches
  exactly two places — docker-compose.yml:422 and 36-quadlet-units.sh:233 — both of them
  p2pool's argv. No Python, no .mjs. So the placeholder is invisible to operators, and the only
  thing that ever reads it is p2pool. Which is the next section.

FINDING — the headline claim is proven in half, and the unproven half belongs to pull 1919

Commit 14133730's subject is "an 'off' machine still mines". What is proven is that
the dashboard's sync gate no longer blocks it (TARI_REQUIRED=false, asserted at 4b, with
test (1) as the control reading true on a machine that did not decline). That is a real and
necessary result. It is not the whole claim.

The other half is p2pool's own behaviour, because on an off machine p2pool is still launched with (the address being the stock local-node placeholder, unchanged from develop)

--merge-mine tari://${TARI_GRPC_ADDRESS} your_tari_wallet_address

Sub-claim A — the unreachable endpoint — I consider settled in this PR's favour, and not by
reading the PR: it is existing repo law. A Tari outage never rejects workers and p2pool keeps mining
Monero through it (#897; stated again in 33-render-env.sh's own comment). tari.mode: remote with
a node that is down is already a supported state with the identical argv shape. Nothing new here.

Sub-claim B — the address STRING — is not settled, and I could not settle it. In local and
remote the parser guarantees a checksum-valid Tari address reaches that argv slot. off with no
wallet is the first state in the product where a non-address does. And it is not an arbitrary
placeholder: your_tari_wallet_address is the exact literal that
28-parse-and-validate-config.sh:53 refuses at the config door. The CLI rejects this string as a
wallet address, and then renders it as one.

I want to be precise about what I do and do not know: I have not proven p2pool v4.18 rejects it,
and I have not proven it accepts it. I could not settle it here — the fake-daemon mini-stack
(integration-mini-stack.yml) brings up the real dashboard against fake daemons, so no CI job
runs a real p2pool, and the bench is claimed for the #1318 battery. What I can say is that if
p2pool parses that operand at startup, an off machine mines nothing, which is the exact inverse
of the feature.

Why this is not a block on THIS PR. Nothing sets off today. The PR that puts real machines
into this state is pull 1919, which makes declining merge-mining the wizard default — and by the
operator's #1855/#1848 ruling that is what a new 2.0 machine will do out of the box, so the blast
radius there is every new machine, not an opt-in few. 1905 lands the plumbing and must merge first
regardless (28- accepts only local|remote on develop, so 1919 alone breaks every provision).

So the gate belongs on 1919: before it merges, either land #1903 (already open, v2 - appliance,
which drops the triple when off), or prove p2pool tolerates the operand. The cheap proof is one run
of the pinned p2pool v4.18 binary with that exact argv and no monerod, reading only whether it exits
during argument parsing or proceeds to the monerod connect — that distinguishes "fatal at startup"
from "an aux-chain error it carries". I am not asking for it on this PR.

Non-blocking doc nit, same subject: docs/architecture.md and docs/configuration.md both say
p2pool "points at a node that is not running" on an off machine. Accurate about the endpoint, and
silent about the operand — which is the half that could be fatal. Worth one clause when #1903 lands.

What I did NOT run, and why

No tests/stack/run.sh, no make test*, no docker: the appliance lane holds the bench box for
#1318 battery --phase all (claimed 2026-09-05T21:34:42Z), load 3.1, and CI at this head has
already run the shell suite to green — re-running it here would be a second opinion, not a second
measurement. No tier 3 of any kind, so the appliance round trip for tari.mode: off is
unproven by this pass and stays with the KVM battery. I read build/p2pool/entrypoint.sh but ran
nothing from it. I did not re-derive F2 or F4 at their sites beyond reading the diff.

Verdict

PASS at 14133730bf92f51f09f54855dc0e4c8e5fdb53db, non-author, unconditional — CI is fully
green here, the four returned findings are fixed at the right layer, the migration default is
guarded by a test that can fail, and the budgeted-file collision with the other open PR does not
exist in the merged tree. MERGE-READY for the seat, and it must merge before pull 1919.

The one open question above is a gate on 1919, recorded here because this is where the evidence is.