From 4e87d9d1f9df51d76acf761a53c86bc49c0ff9fd Mon Sep 17 00:00:00 2001
From: Vijit Singh <vijit.n.singh@gmail.com>
Date: Sun, 2 Aug 2026 10:51:16 -0500
Subject: [PATCH 1/2] =?UTF-8?q?feat(wizard):=20the=20role=20select=20?=
 =?UTF-8?q?=E2=80=94=20one=20stick,=20three=20machines?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The installer page's first disclosure, above the disk, is now what the
machine IS: Pithead / Pithead + RigForge / RigForge. One page, three
shapes, everything downstream reshaping exactly the way the disk choice
already does.

- Pithead: today's flow byte for byte — the default and the regression
  bar; every existing wizard test passes unchanged.
- Pithead + RigForge: Pithead's form with the local-miner switch preset
  to Yes. The role IS local_miner.enabled, so this leg is fully live end
  to end on the shipped boot contract.
- RigForge: the form collapses to a pool address (pre-filled by the
  host's LAN discovery of a Pithead at pithead.local:3333, published to
  the spool like the disk inventory, failing open to an empty field), a
  worker name defaulting to the machine's own, and an optional stratum
  password. The disk section gains "Run from this USB stick" as a
  first-class target for this role only; the card shows the worker name
  and where it points — a rig has no dashboard and no login.

Validation-before-erase (the host dials the pool before anything
irreversible), keep semantics (keep means KEEP in every role — no role
change crosses a survivor), the card-then-ack gate, self-power-off and
the headless first boot are identical in every role.

The accepted role lands under the machine-role contract the boot path
reads: /data/pithead/machine-role plus rig.json for the rig role; a
disk install stages pithead-rig.json on the ESP (carried by
pithead-install beside the other pre-seeds) and the target's first boot
lands and scrubs it. The rig BOOT LEG belongs to the next phase: a
rig-marked machine states its role on the console and stops — nothing
mines yet, and the message says so.

Also: _console now narrates every line to the journal, not just the
first — messages that lived only on a physical console cost a bench
session an hour once.

Covered at the owning tiers: wizard pytest server contracts (73),
frontend render probes (35), stack tests for the discovery publisher,
rig consumption, the marker and the boot stub (1935 suite total), plus
docs in docs/dev/appliance-wizard.md.

Part of #797 (phase R3).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../mining_dashboard/web/static/wizard.mjs    | 202 +++++++++++++++---
 build/dashboard/mining_dashboard/wizard.py    | 100 +++++++--
 .../dashboard/tests/frontend/wizard.test.mjs  | 147 +++++++++++++
 build/dashboard/tests/web/test_wizard.py      | 134 ++++++++++++
 docs/dev/appliance-wizard.md                  |  43 +++-
 os/installer/pithead-install                  |   2 +-
 pithead                                       | 196 ++++++++++++++++-
 tests/stack/run.sh                            |  92 ++++++++
 8 files changed, 866 insertions(+), 50 deletions(-)

diff --git a/build/dashboard/mining_dashboard/web/static/wizard.mjs b/build/dashboard/mining_dashboard/web/static/wizard.mjs
index fc349f9b..c68a0236 100644
--- a/build/dashboard/mining_dashboard/web/static/wizard.mjs
+++ b/build/dashboard/mining_dashboard/web/static/wizard.mjs
@@ -87,7 +87,16 @@ export const Gate = ({ error, onSubmit }) => html`<div class="card">
 // right — bench screenshots cut off exactly the erase/keep words), and is restated in full
 // below the control, red when destructive. The server re-validates the choice against the
 // inventory the HOST published; a browser can never name a disk the host did not offer.
-export const InstallSection = ({ disks, chosen, confirm, wipe, onPick, onConfirm, onWipe }) => {
+export const InstallSection = ({
+  disks,
+  chosen,
+  confirm,
+  wipe,
+  allowStick,
+  onPick,
+  onConfirm,
+  onWipe,
+}) => {
   const picked = disks.find((d) => d.name === chosen);
   const verdictText = (d) =>
     d.state === "pithead-with-data"
@@ -100,6 +109,13 @@ export const InstallSection = ({ disks, chosen, confirm, wipe, onPick, onConfirm
     <${Field} label="Target disk">
         <select value=${chosen} onChange=${onPick}>
             <option value="" disabled selected=${!chosen}>Choose a disk…</option>
+            ${
+              // A rig holds almost no state, so for that role the stick itself is a
+              // first-class place to live — no erase, no commitment on machines whose
+              // disks belong to something else.
+              allowStick &&
+              html`<option value="usb">Run from this USB stick — nothing is erased</option>`
+            }
             ${disks.map(
               (d) =>
                 html`<option value=${d.name}>
@@ -108,6 +124,11 @@ export const InstallSection = ({ disks, chosen, confirm, wipe, onPick, onConfirm
             )}
         </select>
     <//>
+    ${
+      chosen === "usb" &&
+      html`<${Note}>The stick stays in the machine and is the system: the rig's settings ride
+        on it, no disk is touched, and pulling it out just stops the miner.<//>`
+    }
     ${
       picked &&
       picked.state === "pithead-with-data" &&
@@ -158,10 +179,19 @@ export const Installing = ({ status }) => html`<div class="card">
     }
 </div>`;
 
-export const Done = ({ status, handoff, installer, onAck }) => html`<div class="card">
+export const Done = ({ status, handoff, installer, stick, rig, onAck }) => html`<div class="card">
     ${
-      handoff
-        ? html`<h3>Save this before anything else</h3>
+      handoff && handoff.role === "rig"
+        ? html`<h3>Check this rig</h3>
+            <p>This is what the machine will be.</p>
+            <${Field} label="Worker name"><code class="wizard-mono">${handoff.worker}</code><//>
+            <${Field} label="Mines toward"><code class="wizard-mono">${handoff.stratum}</code><//>
+            <${Note}>A rig has no dashboard and no login — nothing to save. It appears by this
+            name in the Pithead's Workers view.<//>
+            <button type="button" onClick=${onAck}>
+                ${installer && !stick ? "Looks right — erase the disk and install" : "Looks right — save it"}</button>`
+        : handoff
+          ? html`<h3>Save this before anything else</h3>
             <p>This is shown once, here.</p>
             <${Field} label="Dashboard user"><code class="wizard-mono">${handoff.username}</code><//>
             <${Field} label="Dashboard password"><code class="wizard-mono">${handoff.password}</code><//>
@@ -177,7 +207,12 @@ export const Done = ({ status, handoff, installer, onAck }) => html`<div class="
                 : html`Provisioning waits for this confirmation (up to 10 minutes), because the
                   page goes dark while the machine builds itself.`
             }<//>`
-        : html`<p><strong>Provisioning.</strong> The machine is pulling and starting the stack —
+          : rig
+            ? html`<p><strong>Saved.</strong> This machine now carries the rig role — the worker
+            name and pool address are stored on it. Rig provisioning lands with the next phase
+            of the system; nothing mines yet, and the machine's console says the same.</p>
+            <p class="text-muted">${status || ""}</p>`
+            : html`<p><strong>Provisioning.</strong> The machine is pulling and starting the stack —
             10 to 30 minutes on a home connection. <strong>This page will stop responding</strong>
             while it happens; that is the machine working, not failing. Its console narrates, and
             when it finishes the dashboard is at
@@ -201,6 +236,14 @@ export class WizardApp extends Component {
     jsonText: "",
     jsonError: "",
     authMode: "auto", // auto | set | none — travels beside the config (see wizard.py submit)
+    // What this machine IS — the first disclosure, above the disk. pithead | both | rig.
+    // "both" rides the existing local_miner switch; "rig" collapses the form to three answers
+    // that travel beside the config exactly like authMode does.
+    role: "pithead",
+    rigPool: "",
+    rigWorker: "",
+    rigPassword: "",
+    rigDefaults: {},
     status: "",
     handoff: null,
   };
@@ -222,8 +265,15 @@ export class WizardApp extends Component {
       reference: s.reference,
       disks: s.disks,
       error: s.error || "",
+      rigDefaults: s.rig_defaults || {},
       handoff: s.handoff || null,
     };
+    // The host's discovery pre-fills the rig fields, but only while they are untouched — the
+    // form polls, and a half-typed pool address must survive it (same rule as cfg below).
+    if (!this.state.rigPool && !this.state.rigWorker) {
+      next.rigPool = (s.rig_defaults || {}).pool || "";
+      next.rigWorker = (s.rig_defaults || {}).worker || "";
+    }
     // The wait is over once the server either moved on or rejected: both end "Validating…".
     if (this.state.submitting && (next.stage !== "setup" || next.error)) next.submitting = false;
     // Do not clobber in-progress editing with the server's copy once the form is up.
@@ -272,6 +322,26 @@ export class WizardApp extends Component {
     this.setState({ cfg, jsonText: JSON.stringify(cfg, null, 2) });
   };
 
+  // The role reshapes the page the way the disk choice does. "Both" IS the existing
+  // local_miner switch — the role presets it and the switch below stays live; back to plain
+  // Pithead resets it to the documented default so the submitted config is byte-for-byte
+  // today's. The rig role never touches the config at all.
+  setRole = (e) => {
+    const role = e.target.value;
+    const cfg = this.state.cfg;
+    const next = { role, cfg, jsonText: JSON.stringify(cfg, null, 2) };
+    if (role !== "rig") {
+      pathSet(cfg, "local_miner.enabled", role === "both");
+      next.jsonText = JSON.stringify(cfg, null, 2);
+      // "usb" only exists for rigs — a coordinator switching back must re-pick a real disk.
+      if (this.state.chosen === "usb") {
+        next.chosen = "";
+        next.confirm = "";
+      }
+    }
+    this.setState(next);
+  };
+
   // JSON pane edit → config → fields. Hand-edited JSON wins; shape errors show as typed.
   editJson = (e) => {
     const text = e.target.value;
@@ -285,31 +355,53 @@ export class WizardApp extends Component {
 
   submit = async (e) => {
     e.preventDefault();
+    const rig = this.state.role === "rig";
     const keepEverything =
       this.state.installer &&
       (this.state.disks.find((d) => d.name === this.state.chosen) || {}).state ===
         "pithead-with-data" &&
       this.state.wipe === "keep";
+    // keep means KEEP in every role: no config, no role — the survivor wins.
     const body = keepEverything
       ? {} // the preserved config wins — sending one would only mislead
-      : {
-          config: JSON.stringify(this.state.cfg),
-          auth_mode: this.state.authMode,
-        };
+      : rig
+        ? {
+            role: "rig",
+            rig_pool: this.state.rigPool.trim(),
+            rig_worker: this.state.rigWorker.trim(),
+            rig_password: this.state.rigPassword,
+          }
+        : {
+            config: JSON.stringify(this.state.cfg),
+            auth_mode: this.state.authMode,
+          };
+    if (rig && !keepEverything && !body.rig_pool) {
+      this.setState({ error: "Enter the pool address (host:port)." });
+      return;
+    }
     // One page, one submission: on the installation medium the disk choice rides beside the
-    // config, and the server gates both before anything is written.
+    // config, and the server gates both before anything is written. "usb" (rig role only) is
+    // not a disk: nothing is erased, so the retyped-name gate does not apply.
     if (this.state.installer) {
       if (!this.state.chosen) {
-        this.setState({ error: "Choose the disk to install onto." });
+        this.setState({
+          error: rig
+            ? "Choose a disk — or run from this USB stick."
+            : "Choose the disk to install onto.",
+        });
         return;
       }
-      if (this.state.confirm !== this.state.chosen) {
-        this.setState({ error: `Type ${this.state.chosen} exactly to confirm the erase.` });
-        return;
+      if (this.state.chosen === "usb") {
+        body.disk = "usb";
+      } else {
+        if (this.state.confirm !== this.state.chosen) {
+          this.setState({ error: `Type ${this.state.chosen} exactly to confirm the erase.` });
+          return;
+        }
+        body.disk = this.state.chosen;
+        body.confirm = this.state.confirm;
+        body.wipe = this.state.wipe;
       }
-      body.disk = this.state.chosen;
-      body.confirm = this.state.confirm;
-      body.wipe = this.state.wipe;
     }
     const res = await fetch("/submit", { method: "POST", body: new URLSearchParams(body) });
     if (!res.ok) {
@@ -332,6 +424,39 @@ export class WizardApp extends Component {
     await this.loadState(); // the server drops out of the handoff stage; the view follows
   };
 
+  // The rig role's whole form: where the pool is, what to call the machine, an optional
+  // stratum password. No payout addresses (the Pithead holds those), no nodes, no dashboard
+  // login — a rig has none of them.
+  renderRigFields() {
+    const { rigPool, rigWorker, rigPassword, rigDefaults } = this.state;
+    return html`<h3>Where it mines</h3>
+        <${Field} label="Pool address (host:port)">
+            <input class="wizard-mono" value=${rigPool}
+                onInput=${(e) => this.setState({ rigPool: e.target.value })}
+                autocomplete="off" autocapitalize="off" spellcheck=${false}
+                placeholder="pithead.local:3333" required />
+        <//>
+        <${Note}>${
+          rigDefaults.pool
+            ? html`A Pithead answered at ${" "}<code>${rigDefaults.pool}</code>${" "}on this
+              network — already filled in.`
+            : html`No Pithead answered on this network — enter the coordinator's address by
+              hand. Its own setup card names it, as ${" "}
+              <code>stratum+tcp://…</code>${" "}under "Point miners at".`
+        }<//>
+        <${Field} label="Worker name">
+            <input value=${rigWorker} onInput=${(e) => this.setState({ rigWorker: e.target.value })}
+                autocomplete="off" autocapitalize="off" spellcheck=${false} />
+        <//>
+        <${Field} label="Stratum password (leave blank unless the Pithead set one)">
+            <input type="password" value=${rigPassword}
+                onInput=${(e) => this.setState({ rigPassword: e.target.value })}
+                autocomplete="new-password" />
+        <//>
+        <${Note}>That is everything a rig needs. It has no dashboard and no login of its own —
+        it appears by this name in the Pithead's Workers view.<//>`;
+  }
+
   renderSetup() {
     const { cfg, error, jsonText, jsonError } = this.state;
     const v = (name) => pathGet(cfg, FIELDS[name].path);
@@ -341,44 +466,64 @@ export class WizardApp extends Component {
     const remoteMonero = v("moneroMode") === "remote";
     const remoteTari = v("tariMode") === "remote";
     const { installer, disks, chosen, confirm, wipe } = this.state;
+    const rig = this.state.role === "rig";
     // Keep-everything reinstall: the machine's settings, wallets, login and chains all survive,
     // so there is nothing to ask — the config half of the page would collect answers the
     // machine will ignore (its preserved config wins). Only the disk half renders.
     const pickedState = (disks.find((d) => d.name === chosen) || {}).state;
     // Progressive disclosure: the DISK decides what gets asked (keep = nothing, keep-chains =
     // a trimmed form, fresh = everything), so until one is chosen the page asks only that.
-    const diskPicked = !installer || Boolean(pickedState);
+    // The rig role's "usb" target counts as picked: running from the stick is a full answer.
+    const diskPicked = !installer || Boolean(pickedState) || chosen === "usb";
     const keepEverything = installer && pickedState === "pithead-with-data" && wipe === "keep";
     return html`<div class="card">
         <p>${
           installer && !diskPicked
-            ? html`Choose the disk to install onto — what happens next depends on what is
+            ? rig
+              ? html`Choose where this rig runs — one of the disks, or straight from this USB
+                stick. The rest of the page appears once you pick.`
+              : html`Choose the disk to install onto — what happens next depends on what is
               already on it, so the rest of the page appears once you pick.`
             : keepEverything
               ? html`This disk keeps everything — settings, wallets, dashboard login and the
               synced chains. Only the system is replaced, so there is nothing to configure:
               the machine comes back exactly as it was, on a fresh install.`
-              : installer
-                ? html`Choose the disk to install onto and answer the questions below — the
+              : rig
+                ? html`A rig needs almost nothing: where the pool is, and what to call this
+                machine. It mines toward a Pithead and appears in that machine's dashboard.`
+                : installer
+                  ? html`Choose the disk to install onto and answer the questions below — the
                 machine validates everything, shows you the login to save, and only then erases
                 the disk. After it switches itself off, remove the stick and power it on: it
                 provisions itself with exactly this configuration.`
-                : html`Only the answers that cannot be guessed for you. Everything else keeps its
-                documented default and stays editable from the dashboard.`
+                  : html`Only the answers that cannot be guessed for you. Everything else keeps
+                its documented default and stays editable from the dashboard.`
         }</p>
         <${Err}>${error}<//>
         <form onSubmit=${this.submit}>
+            <${Field} label="What is this machine?">
+                <select value=${this.state.role} onChange=${this.setRole}>
+                    <option value="pithead">Pithead</option>
+                    <option value="both">Pithead + RigForge</option>
+                    <option value="rig">RigForge</option>
+                </select>
+            <//>
+            <${Note}>A Pithead coordinates the mine — nodes, pool and dashboard. A RigForge rig
+            only mines, pointed at a Pithead. The middle choice is a Pithead that also mines
+            with its own CPU.<//>
             ${
               installer &&
               html`<${InstallSection} disks=${disks} chosen=${chosen} confirm=${confirm}
-                wipe=${wipe}
+                wipe=${wipe} allowStick=${rig}
                 onPick=${(e) => this.setState({ chosen: e.target.value, wipe: "keep" })}
                 onConfirm=${(e) => this.setState({ confirm: e.target.value })}
                 onWipe=${(e) => this.setState({ wipe: e.target.value })} />`
             }
+            ${diskPicked && !keepEverything && rig && this.renderRigFields()}
             ${
               diskPicked &&
               !keepEverything &&
+              !rig &&
               html`<h3>Payout addresses</h3>
             <${Note}>Paste these — they are far too long to type, and a typo pays a stranger.<//>
             <${Field} label="Monero payout address">
@@ -561,14 +706,16 @@ export class WizardApp extends Component {
 
             ${
               diskPicked &&
-              html`<button type="submit" disabled=${!!jsonError || this.state.submitting}>
+              html`<button type="submit" disabled=${(!rig && !!jsonError) || this.state.submitting}>
                 ${
                   this.state.submitting
                     ? "Validating…"
                     : keepEverything
                       ? "Reinstall the system — keep everything"
                       : installer
-                        ? "Validate, then install"
+                        ? chosen === "usb"
+                          ? "Validate, then save to this stick"
+                          : "Validate, then install"
                         : "Apply"
                 }</button>`
             }
@@ -583,7 +730,8 @@ export class WizardApp extends Component {
     else if (stage === "installing") view = html`<${Installing} status=${status} />`;
     else if (stage === "done")
       view = html`<${Done} status=${status} handoff=${this.state.handoff}
-        installer=${this.state.installer} onAck=${this.ack} />`;
+        installer=${this.state.installer} stick=${this.state.chosen === "usb"}
+        rig=${this.state.role === "rig"} onAck=${this.ack} />`;
     else view = this.renderSetup();
     return html`<h1>Pithead setup</h1>${view}`;
   }
diff --git a/build/dashboard/mining_dashboard/wizard.py b/build/dashboard/mining_dashboard/wizard.py
index c46772a9..d27a2f65 100644
--- a/build/dashboard/mining_dashboard/wizard.py
+++ b/build/dashboard/mining_dashboard/wizard.py
@@ -121,6 +121,18 @@ def _last_attempt() -> dict:
         return {}
 
 
+def _rig_defaults() -> dict:
+    """The rig role's pre-fill, published by the HOST like the disk inventory: a Pithead pool
+    discovered on the LAN (when one answered) and this machine's own name for the worker
+    field. Fail open — absent or unparseable means the fields open empty, nothing blocked."""
+    raw = _spool_read("rig-defaults.json")
+    try:
+        d = json.loads(raw) if raw else {}
+    except ValueError:
+        d = {}
+    return d if isinstance(d, dict) else {}
+
+
 def wizard_stage() -> str:
     """Which step this machine is actually on, decided by the SPOOL — never by the client.
 
@@ -211,6 +223,7 @@ async def wizard_state(request: web.Request) -> web.Response:
             "reference": ref,
             "error": _spool_read("error.txt"),
             "disks": _disks(),
+            "rig_defaults": _rig_defaults(),
             "handoff": json.loads(raw_handoff) if raw_handoff else None,
         }
     )
@@ -305,6 +318,60 @@ def _spool_write_config(cfg: dict) -> None:
     os.replace(tmp, os.path.join(sd, "config.json"))
 
 
+def _gate_install_request(form: dict) -> str | None:
+    """Three independent gates before anything is written, because this leads to erasing a
+    disk — identical for every role: the target must be one the HOST offered (never a name the
+    browser invented), the operator must retype it exactly, and the wipe mode must be from the
+    fixed set — with anything other than "keep" allowed only on a disk that actually carries
+    data to wipe. Writes the install request and returns None, or returns the error text."""
+    disk = str(form.get("disk", "")).strip()
+    confirm = str(form.get("confirm", "")).strip()
+    wipe = str(form.get("wipe", "keep")).strip() or "keep"
+    by_name = {d["name"]: d for d in _disks()}
+    if disk not in by_name:
+        return "choose a disk from the list"
+    if confirm != disk:
+        return f"type {disk} exactly to confirm"
+    if wipe not in ("keep", "data", "all"):
+        return "unknown wipe mode"
+    if wipe != "keep" and by_name[disk]["state"] != "pithead-with-data":
+        wipe = "keep"  # nothing on the disk to keep or wipe — normalize silently
+    _spool_write_text("install-request", f"{disk}\t{wipe}")
+    return None
+
+
+def _submit_rig(form: dict) -> web.Response:
+    """The RigForge role's submission: no pithead config at all — a pool address, a worker
+    name, an optional stratum password, on their own spool channel. The coordinator flow stays
+    byte-for-byte untouched because nothing here goes near config.json; the HOST dials the
+    pool and owns everything after. On the installation medium the disk gates are the same as
+    every other role, with one extra first-class target: "usb" means run from this stick —
+    nothing is erased, so no gates apply to it."""
+    pool = str(form.get("rig_pool", "")).strip()
+    host, _, port = pool.rpartition(":")
+    if not host or not port.isdigit():
+        return web.json_response(
+            {"error": "enter the pool address as host:port — a Pithead answers on port 3333"},
+            status=400,
+        )
+    if installer_mode() and str(form.get("disk", "")).strip() != "usb":
+        err = _gate_install_request(form)
+        if err:
+            return web.json_response({"error": err}, status=400)
+    rig = {"pool": pool}
+    worker = str(form.get("rig_worker", "")).strip()
+    if worker:
+        rig["worker"] = worker
+    password = str(form.get("rig_password", "")).strip()
+    if password:
+        rig["stratum_password"] = password
+    _spool_clear_error()
+    # The role rides beside the request so /status can narrate honestly after it is consumed.
+    _spool_write_text("role", "rig")
+    _spool_write_text("rig-request.json", json.dumps(rig))
+    return web.json_response({"status": "accepted"})
+
+
 async def submit(request: web.Request) -> web.Response:
     if not _authed(request):
         raise web.HTTPFound("/")
@@ -336,6 +403,10 @@ async def submit(request: web.Request) -> web.Response:
         # through unconditionally. The no-JS path submits individual form FIELDS, not a config
         # blob, so "no config present" cannot distinguish a bare keep from a form submit; the
         # host's validation names what is missing either way.
+    # The rig role, AFTER the keep gate on purpose: keep means KEEP in every role — a rig
+    # submission against a preserved install must not smuggle a role change past the survivor.
+    if str(form.get("role", "")).strip() == "rig":
+        return _submit_rig(dict(form))
     # The JSON pane IS the configuration — what the operator can see is exactly what gets
     # applied. build_config remains the fallback for a client with no JavaScript.
     try:
@@ -350,25 +421,12 @@ async def submit(request: web.Request) -> web.Response:
     mode = str(form.get("auth_mode", "")).strip()
     if mode in ("auto", "set", "none"):
         _spool_write_text("auth-mode", mode)
-    # On the installation medium, config and disk arrive TOGETHER — one page, one submission.
-    # Three independent gates before anything is written, because this leads to erasing a disk:
-    # the target must be one the HOST offered (never a name the browser invented), the operator
-    # must retype it exactly, and the wipe mode must be from the fixed set — with anything
-    # other than "keep" allowed only on a disk that actually carries data to wipe.
+    # On the installation medium, config and disk arrive TOGETHER — one page, one submission,
+    # gated before anything is written (see _gate_install_request).
     if installer_mode():
-        disk = str(form.get("disk", "")).strip()
-        confirm = str(form.get("confirm", "")).strip()
-        wipe = str(form.get("wipe", "keep")).strip() or "keep"
-        by_name = {d["name"]: d for d in _disks()}
-        if disk not in by_name:
-            return web.json_response({"error": "choose a disk from the list"}, status=400)
-        if confirm != disk:
-            return web.json_response({"error": f"type {disk} exactly to confirm"}, status=400)
-        if wipe not in ("keep", "data", "all"):
-            return web.json_response({"error": "unknown wipe mode"}, status=400)
-        if wipe != "keep" and by_name[disk]["state"] != "pithead-with-data":
-            wipe = "keep"  # nothing on the disk to keep or wipe — normalize silently
-        _spool_write_text("install-request", f"{disk}\t{wipe}")
+        err = _gate_install_request(dict(form))
+        if err:
+            return web.json_response({"error": err}, status=400)
     # Keep the full attempt for a retry, write only what differs from the defaults.
     _spool_write_text("last-attempt.json", json.dumps(cfg))
     _spool_write_config(strip_defaults(cfg, ref) if ref else cfg)
@@ -410,6 +468,12 @@ async def status(request: web.Request) -> web.Response:
             return web.Response(text=f"Install failed: {err}")
         return web.Response(text="Copying the system to the disk…")
     if _spool_read("applied") is not None:
+        if _spool_read("role") == "rig":
+            # Honest by design: the rig's boot leg arrives with the next phase of the system.
+            return web.Response(
+                text="Rig settings saved on this machine. Rig provisioning lands with the "
+                "next phase of the system — nothing mines yet."
+            )
         return web.Response(text="Provisioned — the dashboard is coming up now.")
     err = _spool_read("error.txt")
     if err is not None:
diff --git a/build/dashboard/tests/frontend/wizard.test.mjs b/build/dashboard/tests/frontend/wizard.test.mjs
index 30fdb0f0..a37d248c 100644
--- a/build/dashboard/tests/frontend/wizard.test.mjs
+++ b/build/dashboard/tests/frontend/wizard.test.mjs
@@ -403,6 +403,153 @@ test("saying yes promises the built-in miner, never a manual install", async ()
   restore();
 });
 
+// --- the role select (#797 R3): one page, three shapes ---------------------------------------
+
+test("the role select is the FIRST disclosure, above the disk, reading exactly three names", async () => {
+  const { inst, restore } = await appOn([stateFor("installer", { disks: DISKS })]);
+  const out = renderToString(inst.render());
+  assert.ok(out.indexOf("What is this machine?") < out.indexOf("Install onto"));
+  assert.match(out, /Pithead \+ RigForge/);
+  assert.match(out, /"rig">RigForge</);
+  assert.match(out, /"pithead">Pithead</);
+  restore();
+});
+
+test("role Pithead + RigForge presets the local-miner switch and keeps the full form", async () => {
+  const { inst, restore } = await appOn([stateFor("setup")]);
+  inst.setRole({ target: { value: "both" } });
+  assert.equal(inst.state.cfg.local_miner.enabled, true);
+  const out = renderToString(inst.render());
+  assert.match(out, /Payout addresses/); // still Pithead's form — no new UI beyond the select
+  assert.match(out, /Nothing to install/); // the preset shows as the live switch's Yes note
+  // Back to plain Pithead: the documented default returns — today's config, byte for byte.
+  inst.setRole({ target: { value: "pithead" } });
+  assert.equal(inst.state.cfg.local_miner.enabled, false);
+  restore();
+});
+
+test("role RigForge collapses the form to pool, worker, password — none of the coordinator", async () => {
+  const { inst, restore } = await appOn([stateFor("setup")]);
+  inst.setRole({ target: { value: "rig" } });
+  const out = renderToString(inst.render());
+  assert.match(out, /Pool address/);
+  assert.match(out, /Worker name/);
+  assert.match(out, /Stratum password/);
+  assert.doesNotMatch(out, /Payout addresses/);
+  assert.doesNotMatch(out, /Dashboard login/);
+  assert.doesNotMatch(out, /Advanced/);
+  assert.doesNotMatch(out, /First sync/);
+  restore();
+});
+
+test("the rig fields open on the host's discovery, and say when nothing answered", async () => {
+  const found = await appOn([
+    stateFor("setup", { rig_defaults: { pool: "pithead.local:3333", worker: "hp-tower" } }),
+  ]);
+  found.inst.setRole({ target: { value: "rig" } });
+  assert.equal(found.inst.state.rigPool, "pithead.local:3333");
+  assert.equal(found.inst.state.rigWorker, "hp-tower");
+  assert.match(renderToString(found.inst.render()), /already filled in/);
+  found.restore();
+  const none = await appOn([stateFor("setup")]);
+  none.inst.setRole({ target: { value: "rig" } });
+  assert.match(renderToString(none.inst.render()), /No Pithead answered/);
+  none.restore();
+});
+
+test("run-from-this-stick appears beside the disks for the rig role ONLY", async () => {
+  const { inst, restore } = await appOn([stateFor("installer", { disks: DISKS })]);
+  assert.doesNotMatch(renderToString(inst.render()), /Run from this USB stick/);
+  inst.setRole({ target: { value: "rig" } });
+  const out = renderToString(inst.render());
+  assert.match(out, /Run from this USB stick — nothing is erased/);
+  // Picking it discloses the rig form with no retype gate — nothing is erased.
+  inst.setState({ chosen: "usb" });
+  const after = renderToString(inst.render());
+  assert.match(after, /Pool address/);
+  assert.doesNotMatch(after, /Type the disk name to confirm/);
+  assert.match(after, /Validate, then save to this stick/);
+  restore();
+});
+
+test("a rig submit carries the role and answers — never a config", async () => {
+  const { inst, restore } = await appOn([stateFor("installer", { disks: DISKS })]);
+  inst.setRole({ target: { value: "rig" } });
+  inst.setState({ chosen: "usb", rigPool: "10.0.0.5:3333", rigWorker: "shed-3" });
+  let sentBody = null;
+  const real = globalThis.fetch;
+  globalThis.fetch = async (url, opts) => {
+    if (String(url).includes("/submit")) {
+      sentBody = String(opts.body);
+      return { ok: true, status: 200, json: async () => ({}) };
+    }
+    return { ok: true, status: 200, json: async () => stateFor("handoff"), text: async () => "" };
+  };
+  await inst.submit({ preventDefault() {} });
+  globalThis.fetch = real;
+  assert.match(sentBody, /role=rig/);
+  assert.match(sentBody, /rig_pool=10.0.0.5%3A3333/);
+  assert.match(sentBody, /disk=usb/);
+  assert.doesNotMatch(sentBody, /config=/);
+  restore();
+});
+
+test("an empty pool address is stopped client-side with a named reason", async () => {
+  const { inst, restore } = await appOn([stateFor("setup")]);
+  inst.setRole({ target: { value: "rig" } });
+  let fetched = false;
+  const real = globalThis.fetch;
+  globalThis.fetch = async () => {
+    fetched = true;
+    return { ok: true, status: 200, json: async () => ({}) };
+  };
+  await inst.submit({ preventDefault() {} });
+  globalThis.fetch = real;
+  assert.equal(fetched, false);
+  assert.match(inst.state.error, /pool address/);
+  restore();
+});
+
+test("the rig card shows the worker and where it points — no credentials, no login", () => {
+  const handoff = { role: "rig", worker: "shed-3", stratum: "stratum+tcp://pithead.local:3333" };
+  const card = renderToString(
+    html`<${Done} status="" handoff=${handoff} installer=${true} stick=${false} onAck=${() => {}} />`,
+  );
+  assert.match(card, /shed-3/);
+  assert.match(card, /stratum\+tcp:\/\/pithead\.local:3333/);
+  assert.match(card, /erase the disk and install/); // the ack still releases the erase
+  assert.doesNotMatch(card, /Dashboard password/);
+  assert.doesNotMatch(card, /Save this before anything else/);
+  const stick = renderToString(
+    html`<${Done} status="" handoff=${handoff} installer=${true} stick=${true} onAck=${() => {}} />`,
+  );
+  assert.doesNotMatch(stick, /erase the disk/); // run-from-stick erases nothing
+});
+
+test("after the ack, the rig's done view is honest: saved, not mining yet", async () => {
+  const { inst, restore } = await appOn([stateFor("setup")]);
+  inst.setRole({ target: { value: "rig" } });
+  Object.assign(inst.state, { stage: "done", handoff: null });
+  const out = renderToString(inst.render());
+  assert.match(out, /nothing mines yet/);
+  assert.doesNotMatch(out, /pulling and starting the stack/);
+  restore();
+});
+
+test("keep on a preserved disk still collapses everything — the rig role included", async () => {
+  const { inst, restore } = await appOn([
+    stateFor("installer", {
+      disks: [{ name: "sda", size: "1T", model: "M", serial: "S", state: "pithead-with-data" }],
+    }),
+  ]);
+  inst.setRole({ target: { value: "rig" } });
+  inst.setState({ chosen: "sda", wipe: "keep" });
+  const out = renderToString(inst.render());
+  assert.doesNotMatch(out, /Pool address/);
+  assert.match(out, /keeps everything/);
+  restore();
+});
+
 test("before a disk is chosen, the page asks ONLY that", async () => {
   const { inst, restore } = await appOn([
     stateFor("installer", {
diff --git a/build/dashboard/tests/web/test_wizard.py b/build/dashboard/tests/web/test_wizard.py
index 9386a551..ab20bfca 100644
--- a/build/dashboard/tests/web/test_wizard.py
+++ b/build/dashboard/tests/web/test_wizard.py
@@ -634,6 +634,140 @@ async def test_ack_on_the_installer_means_installing_not_provisioning(client, in
     assert (await (await client.get("/api/wizard-state")).json())["stage"] == "installing"
 
 
+# --- the role select (#797 R3): the RigForge role travels on its own channel -----------------
+# Pithead is the default and the absence of a role field — every submit above this section IS
+# the regression bar for it. The rig role never touches config.json: three answers on their own
+# spool file, the HOST validates reachability and owns everything after.
+
+
+async def test_rig_submit_writes_the_request_and_role_and_no_config(client, seeded):
+    await _auth(client)
+    r = await client.post(
+        "/submit",
+        data={
+            "role": "rig",
+            "rig_pool": "pithead.local:3333",
+            "rig_worker": "shed-3",
+            "rig_password": "fixture-stratum-pw",
+        },
+    )
+    assert r.status == 200
+    req = json.loads((seeded / "rig-request.json").read_text())
+    assert req == {
+        "pool": "pithead.local:3333",
+        "worker": "shed-3",
+        "stratum_password": "fixture-stratum-pw",
+    }
+    assert (seeded / "role").read_text() == "rig"
+    # None of the coordinator machinery: no config candidate, no retry attempt.
+    assert not (seeded / "config.json").exists()
+    assert not (seeded / "last-attempt.json").exists()
+
+
+async def test_rig_pool_must_look_like_host_port(client, seeded):
+    await _auth(client)
+    for bad in ("", "pithead.local", "pithead.local:", ":3333", "pithead.local:zzz"):
+        r = await client.post("/submit", data={"role": "rig", "rig_pool": bad})
+        assert r.status == 400, bad
+        assert "host:port" in (await r.json())["error"]
+    assert not (seeded / "rig-request.json").exists()
+
+
+async def test_rig_empty_worker_and_password_are_omitted(client, seeded):
+    # The HOST fills the worker default (its own hostname); an empty password is no password.
+    await _auth(client)
+    await client.post("/submit", data={"role": "rig", "rig_pool": "10.0.0.5:3333"})
+    assert json.loads((seeded / "rig-request.json").read_text()) == {"pool": "10.0.0.5:3333"}
+
+
+async def test_rig_on_the_installer_takes_the_same_disk_gates(client, installer):
+    # Identical erase discipline in every role: offered target, exact retype, fixed wipe set.
+    await _auth(client)
+    base = {"role": "rig", "rig_pool": "10.0.0.5:3333"}
+    assert (
+        await client.post("/submit", data={**base, "disk": "sdz", "confirm": "sdz"})
+    ).status == 400
+    r = await client.post("/submit", data={**base, "disk": "nvme0n1", "confirm": "nvme0n"})
+    assert r.status == 400
+    # A rejected disk half-accepts nothing — one page, one atomic answer.
+    assert not (installer / "install-request").exists()
+    assert not (installer / "rig-request.json").exists()
+    r = await client.post("/submit", data={**base, "disk": "nvme0n1", "confirm": "nvme0n1"})
+    assert r.status == 200
+    assert (installer / "install-request").read_text() == "nvme0n1\tkeep"
+    assert (installer / "rig-request.json").exists()
+
+
+async def test_run_from_this_stick_is_first_class_for_the_rig_role_only(client, installer):
+    # "usb" is not a disk: nothing is erased, so NO install request — the answers still travel.
+    await _auth(client)
+    r = await client.post(
+        "/submit", data={"role": "rig", "rig_pool": "10.0.0.5:3333", "disk": "usb"}
+    )
+    assert r.status == 200
+    assert not (installer / "install-request").exists()
+    assert (installer / "rig-request.json").exists()
+    # Any other role naming "usb" hits the inventory gate: the host never offered it.
+    r = await client.post("/submit", data={"config": _CFG, "disk": "usb", "confirm": "usb"})
+    assert r.status == 400
+
+
+async def test_rig_keep_on_a_preserved_disk_stays_a_keep(client, installer):
+    # keep means KEEP in every role: the survivor config wins, no role change crosses.
+    await _auth(client)
+    r = await client.post(
+        "/submit",
+        data={
+            "role": "rig",
+            "rig_pool": "10.0.0.5:3333",
+            "disk": "sda",
+            "confirm": "sda",
+            "wipe": "keep",
+        },
+    )
+    assert r.status == 200
+    assert (installer / "install-request").read_text() == "sda\tkeep"
+    assert not (installer / "rig-request.json").exists()
+    assert not (installer / "role").exists()
+
+
+async def test_state_carries_the_hosts_rig_defaults_and_fails_open(client, seeded):
+    await _auth(client)
+    s = await (await client.get("/api/wizard-state")).json()
+    assert s["rig_defaults"] == {}  # nothing published — the fields open empty
+    seeded.joinpath("rig-defaults.json").write_text(
+        '{"pool": "pithead.local:3333", "worker": "hp"}'
+    )
+    s = await (await client.get("/api/wizard-state")).json()
+    assert s["rig_defaults"] == {"pool": "pithead.local:3333", "worker": "hp"}
+    seeded.joinpath("rig-defaults.json").write_text("{broken")
+    s = await (await client.get("/api/wizard-state")).json()
+    assert s["rig_defaults"] == {}
+
+
+async def test_status_narrates_the_rig_save_without_promising_a_dashboard(client, spool):
+    spool.joinpath("role").write_text("rig")
+    spool.joinpath("applied").write_text("1")
+    body = await (await client.get("/status")).text()
+    assert "Rig settings saved" in body
+    assert "dashboard" not in body.lower()
+
+
+async def test_rig_submit_clears_a_previous_error(client, seeded):
+    seeded.joinpath("error.txt").write_text("old error")
+    await _auth(client)
+    await client.post("/submit", data={"role": "rig", "rig_pool": "10.0.0.5:3333"})
+    assert not (seeded / "error.txt").exists()
+
+
+async def test_unauthed_rig_submit_writes_nothing(client, seeded):
+    r = await client.post(
+        "/submit", data={"role": "rig", "rig_pool": "10.0.0.5:3333"}, allow_redirects=False
+    )
+    assert r.status == 302
+    assert not (seeded / "rig-request.json").exists()
+
+
 # --- the dashboard-login choice -------------------------------------------------------------
 
 
diff --git a/docs/dev/appliance-wizard.md b/docs/dev/appliance-wizard.md
index c67b5770..0fcfa0db 100644
--- a/docs/dev/appliance-wizard.md
+++ b/docs/dev/appliance-wizard.md
@@ -71,6 +71,47 @@ wins and no config crosses.
 Never a client flag. `/api/wizard-state` carries the handoff payload inline for the same
 reason — a separate fetch is a separate race.
 
+## The role select — one stick, three machines
+
+The page's FIRST disclosure, above the disk, is what the machine IS. One select, reading
+exactly **Pithead** / **Pithead + RigForge** / **RigForge**, and everything downstream
+reshapes to the answer the same way the disk choice already reshapes the form:
+
+| Role | The form | What lands |
+|---|---|---|
+| Pithead | today's flow, byte for byte — the default, and the regression bar | `config.json` (the whole contract above) |
+| Pithead + RigForge | Pithead's form with the mine-on-this-machine switch preset to Yes. The role IS `local_miner.enabled` — the switch below stays live, and flipping it back submits today's config unchanged | `config.json` with `local_miner.enabled: true`; the boot contract's step 5 starts the miner |
+| RigForge | collapses to a pool address, a worker name and an optional stratum password. The pool field opens pre-filled when the host found a Pithead answering `pithead.local:3333` — dialed HOST-side and published to the spool as `rig-defaults.json`, the way the disk inventory travels, failing open to an empty field. The disk section gains **Run from this USB stick** as a first-class target: a rig holds almost no state, so the stick can BE the system — no erase, no commitment on machines whose disks belong to something else. The card shows the worker name and where it points; a rig has no dashboard and no login | `machine-role` + `rig.json` (below) |
+
+Validation-before-erase, the keep semantics, the card-then-ack gate, self-power-off and the
+headless first boot are identical in every role — one flow, three shapes. And keep means KEEP
+whatever the role says: the survivor config wins, and no role change crosses.
+
+The rig submission travels on its own spool channel (`rig-request.json`; the server never
+writes a `config.json` candidate for it), and the host dials the pool BEFORE anything
+irreversible — the same discipline `preflight_remote_nodes` gives remote nodes.
+
+### The machine-role contract
+
+What the boot path reads, written by the host at the moment a role is accepted:
+
+| File (under `/data/pithead`) | Meaning |
+|---|---|
+| `machine-role` | `pithead`, `both` or `rig`. Absent means `pithead` — every machine provisioned before this contract. The coordinator values are derivable from `config.json` (both IS `local_miner.enabled`); the rig value is load-bearing, because a rig has no `config.json` at all. |
+| `rig.json` | rig role only: `pool`, `worker`, and `stratum_password` when one was set. |
+
+A rig install to a disk stages the accepted answers as `pithead-rig.json` on the ESP —
+carried to the target by `pithead-install` beside the config and token pre-seeds — and the
+installed machine's first boot lands them as the two files above, scrubbing the ESP copy the
+way the config pre-seed is scrubbed. The stick keeps neither copy after a disk install: a
+stick whose own `/data` carries the rig marker IS a rig (run-from-USB), and that marker
+outranks installer mode on every later boot.
+
+**The rig boot leg belongs to the next phase.** Today a machine carrying `machine-role: rig`
+states its role on the console and stops — nothing mines yet, and the message says exactly
+that. The Both role is fully live end to end: the boot contract's step 5 already honours
+`local_miner.enabled`.
+
 ## The certificate lifecycle
 
 **One certificate for the machine's whole life**, at `appliance_tls_dir()`
@@ -168,7 +209,7 @@ had a gap between it and the next one.
 | pure logic | `tests/frontend/configsync.test.mjs` | path access, typed coercion, address/pair guidance |
 | view rendering | `tests/frontend/wizard.test.mjs` (probes) | each view given its props |
 | **app orchestration** | `tests/frontend/wizard.test.mjs` (stubbed server) | **stage mapping, the handoff arriving through the poll, refresh-mid-provision, rejection round-trip, request bodies** |
-| host logic | `tests/stack/run.sh` | cert minting + idempotence, remote-node preflight, pre-seed, install requests, the digest-keyed image loader, reinstall pre-fill (secret strip + fail-open), the local-miner legs (derived config, sync seeding, boot-leg wiring) |
+| host logic | `tests/stack/run.sh` | cert minting + idempotence, remote-node preflight, pre-seed, install requests, the digest-keyed image loader, reinstall pre-fill (secret strip + fail-open), the local-miner legs (derived config, sync seeding, boot-leg wiring), the rig-role legs (pool discovery publisher, rig request consumption, the role marker + boot stub) |
 | the real thing | `tests/os/run.sh --phase provision` | token from the console → submit → handoff → ack → running stack → built-in miner up and its shares accepted → reboot through a corrupted Caddyfile → no failed units → slot self-commit → miner back |
 
 The orchestration row is the one that was missing. pytest proved the endpoint published the
diff --git a/os/installer/pithead-install b/os/installer/pithead-install
index 18e33b7e..d08d0585 100755
--- a/os/installer/pithead-install
+++ b/os/installer/pithead-install
@@ -239,7 +239,7 @@ main() {
     # the first reboot: the installer builds a fresh ESP, and the operator's config — the whole
     # point of pre-seeding — would stay behind on the stick.
     local seed
-    for seed in pithead-config.json pithead-token.txt; do
+    for seed in pithead-config.json pithead-token.txt pithead-rig.json; do
         [ -f "/boot/efi/$seed" ] && install -m 600 "/boot/efi/$seed" "$mnt/boot/efi/$seed"
     done
 
diff --git a/pithead b/pithead
index 2122f982..19a031a2 100755
--- a/pithead
+++ b/pithead
@@ -1285,6 +1285,75 @@ firstboot_consume_spool() { # <spool-dir>
     return 1
 }
 
+# --- the machine role (one stick, three machines) -------------------------------------------
+# What a machine IS is the wizard's first question: a Pithead coordinator, a coordinator that
+# also mines (Both), or a RigForge rig. config.json states the coordinator roles exactly — Both
+# IS local_miner.enabled — so the marker is derived from it there. The rig role has no
+# config.json at all, which is why the marker, with rig.json beside it, exists: the boot path
+# reads machine-role to know which leg to start. Absent marker = pithead (every machine
+# provisioned before this contract).
+
+record_machine_role() { # <pithead|both|rig>
+    printf '%s\n' "$1" >"$PWD/machine-role" 2>/dev/null || true
+}
+
+machine_role_from_config() { # <config-file>
+    if [ "$(jq -r '.local_miner.enabled // false' "$1" 2>/dev/null)" = "true" ]; then
+        printf 'both'
+    else
+        printf 'pithead'
+    fi
+}
+
+# The rig role's pool pre-fill: a Pithead on the LAN answers pithead.local:3333. The HOST
+# dials — the container never touches the network — and publishes the finding to the spool the
+# way the disk inventory travels. Fail open: no answer publishes only this machine's name, and
+# the pool field opens empty. PITHEAD_RIG_PROBE overrides the target for tests.
+publish_rig_defaults() { # <spool-dir>
+    local probe="${PITHEAD_RIG_PROBE:-pithead.local:3333}" tmp="$1/.rig-defaults.json.$$" pool=""
+    if timeout 3 bash -c "</dev/tcp/${probe%:*}/${probe##*:}" 2>/dev/null; then
+        pool="$probe"
+    fi
+    jq -n --arg pool "$pool" --arg worker "$(hostname)" \
+        '{worker: $worker} + (if $pool == "" then {} else {pool: $pool} end)' >"$tmp" 2>/dev/null || : >"$tmp"
+    chown 1000:1000 "$tmp" 2>/dev/null || true
+    mv -f "$tmp" "$1/rig-defaults.json"
+}
+
+# Consume one rig-role submission: shape-check the pool address, dial it BEFORE anything
+# irreversible — the same validate-before-erase discipline the coordinator flow gets — and
+# land the accepted answers as $PWD/rig.json, host-side and outside the spool (the same trust
+# move firstboot_consume_spool makes: what got validated is what gets used, whatever the
+# container writes afterwards). rc: 0 accepted, 1 rejected, 2 none.
+firstboot_consume_rig() { # <spool-dir>
+    local spool="$1" req="$1/rig-request.json" pool worker host port
+    [ -f "$req" ] || return 2
+    pool=$(jq -r '.pool // ""' "$req" 2>/dev/null | tr -d '[:cntrl:]')
+    worker=$(jq -r '.worker // ""' "$req" 2>/dev/null | tr -d '[:cntrl:]')
+    host="${pool%:*}"
+    port="${pool##*:}"
+    if [ -z "$host" ] || [ "$host" = "$pool" ] || ! [[ "$port" =~ ^[0-9]+$ ]]; then
+        printf 'the pool address must look like host:port — a Pithead answers on port 3333' >"$spool/error.txt"
+        rm -f "$req"
+        return 1
+    fi
+    if ! timeout 5 bash -c "</dev/tcp/$host/$port" 2>/dev/null; then
+        printf 'cannot reach a pool at %s:%s — check the address, and that the Pithead is up' "$host" "$port" >"$spool/error.txt"
+        rm -f "$req"
+        return 1
+    fi
+    if ! jq --arg w "${worker:-$(hostname)}" '{pool: .pool, worker: $w}
+        + (if (.stratum_password // "") == "" then {} else {stratum_password: .stratum_password} end)' \
+        "$req" >"$PWD/rig.json" 2>/dev/null; then
+        rm -f "$req" "$PWD/rig.json"
+        printf 'could not record the rig settings — submit again' >"$spool/error.txt"
+        return 1
+    fi
+    chmod 600 "$PWD/rig.json" 2>/dev/null || true
+    rm -f "$req"
+    return 0
+}
+
 # --- disk installer (appliance only) -------------------------------------------------------
 # The appliance can boot from the installation medium itself. When it does, the wizard leads with
 # a disk picker instead of the setup form: the operator installs first, reboots, and configures
@@ -1554,6 +1623,34 @@ firstboot_wizard() {
         *) error "Unknown option for firstboot-wizard: $arg. Run '$0 help'." ;;
         esac
     done
+    # A machine already carrying the rig role: state it and stop — even on a stick that could
+    # offer the installer, because a run-from-USB rig's stick IS that rig's system, not a
+    # fleet tool. The rig boot leg lands with the next phase; until it does, an honest console
+    # line beats a coordinator's setup page collecting answers a rig can never use.
+    if [ "$(tr -d '[:space:]' <"$PWD/machine-role" 2>/dev/null)" = "rig" ]; then
+        _console "This machine carries the RigForge rig role ($(jq -r '.worker // "unnamed"' "$PWD/rig.json" 2>/dev/null) -> $(jq -r '.pool // "no pool recorded"' "$PWD/rig.json" 2>/dev/null))." \
+            "Rig provisioning lands with the next phase of the system — nothing mines yet."
+        return 0
+    fi
+    # A rig install staged its answers on this ESP (the disk-install leg below): land them on
+    # /data and stop, the same one-move consumption as the config pre-seed — never on the
+    # installation medium, where staged files are cleaned up by the installer itself.
+    if [ -f "$PRESEED_DIR/pithead-rig.json" ] && ! installer_mode_available; then
+        if jq -e 'type == "object" and ((.pool // "") | length > 0)' "$PRESEED_DIR/pithead-rig.json" >/dev/null 2>&1 &&
+            install -m 600 "$PRESEED_DIR/pithead-rig.json" "$PWD/rig.json" 2>/dev/null; then
+            record_machine_role rig
+            # Spent: the settings (possibly a stratum password) must not sit on the ESP forever.
+            if ! boot_is_removable; then
+                mount -o remount,rw "$PRESEED_DIR" 2>/dev/null || true
+                rm -f "$PRESEED_DIR/pithead-rig.json" 2>/dev/null ||
+                    warn "Could not remove the consumed rig settings from $PRESEED_DIR — they may hold a password; delete the file."
+            fi
+            _console "This machine is now a RigForge rig ($(jq -r '.worker // "unnamed"' "$PWD/rig.json" 2>/dev/null))." \
+                "Rig provisioning lands with the next phase of the system — nothing mines yet."
+            return 0
+        fi
+        warn "The staged rig settings at $PRESEED_DIR/pithead-rig.json are unusable — opening the setup page."
+    fi
     # A configuration dropped on the medium beats opening a browser at all — but never on the
     # INSTALLATION medium: pre-seeding covers configuration, not the erase decision (the docs'
     # exact promise), and a fleet stick that provisioned ITSELF instead of offering the
@@ -1577,6 +1674,7 @@ firstboot_wizard() {
             # not mean skipping the login.
             ensure_appliance_dashboard_password || true
             apply_appliance_defaults || true
+            record_machine_role "$(machine_role_from_config "$PWD/config.json")"
             setup
             return
         fi
@@ -1601,6 +1699,9 @@ firstboot_wizard() {
     cp /opt/pithead/config.reference.json "$spool/config.reference.json" 2>/dev/null ||
         cp "$PWD/config.reference.json" "$spool/config.reference.json" 2>/dev/null || true
     chown 1000:1000 "$spool/config.reference.json" 2>/dev/null || true
+    # The rig role's pre-fill rides beside the reference — derived fresh each boot, like the
+    # disk inventory, so machine 2 on a fleet stick never opens on machine 1's discovery.
+    publish_rig_defaults "$spool"
 
     local installer=0 operator_preseed=0
     [ -f "$PRESEED_DIR/pithead-config.json" ] && operator_preseed=1
@@ -1645,7 +1746,8 @@ firstboot_wizard() {
         # error.txt and last-attempt.json survive on purpose: they are the retry context the
         # failed-provisioning path just wrote for the reopened page.
         rm -f "$spool/handoff.json" "$spool/handoff-ack" "$spool/installing" \
-            "$spool/installed" "$spool/applied" "$spool/install-request"
+            "$spool/installed" "$spool/applied" "$spool/install-request" \
+            "$spool/rig-request.json" "$spool/role"
         # A pre-seeded token is the operator's own choice and stays fixed across restarts of
         # this loop; without one, mint a fresh secret every round.
         token=$(preseed_token) || token=$(wizard_mint_token)
@@ -1718,6 +1820,86 @@ firstboot_wizard() {
                 systemctl poweroff
                 return
             fi
+            # The rig role's submission travels on its own channel — no pithead config exists
+            # to validate. Same discipline, different shape: dial the pool BEFORE anything
+            # irreversible, card before commitment, the ack releases the erase.
+            local rrc=0
+            firstboot_consume_rig "$spool" || rrc=$?
+            if [ "$rrc" -eq 1 ]; then
+                warn "Rig settings rejected — the page shows the reason."
+                sleep 2
+                continue
+            fi
+            if [ "$rrc" -eq 0 ]; then
+                log "Rig settings accepted."
+                local rig_worker rig_pool
+                rig_worker=$(jq -r '.worker // ""' "$PWD/rig.json" 2>/dev/null)
+                rig_pool=$(jq -r '.pool // ""' "$PWD/rig.json" 2>/dev/null)
+                # The rig's card: the worker name and where it points. No dashboard, no login —
+                # a rig serves neither, so there is nothing to save; the same ack still gates
+                # the erase on the installation medium.
+                jq -n --arg w "$rig_worker" --arg s "stratum+tcp://$rig_pool" \
+                    '{role: "rig", worker: $w, stratum: $s}' >"$spool/handoff.json"
+                chown 1000:1000 "$spool/handoff.json" 2>/dev/null || true
+                local hwait=0
+                while [ ! -f "$spool/handoff-ack" ] && [ "$hwait" -lt 600 ]; do
+                    sleep 2
+                    hwait=$((hwait + 2))
+                done
+                if [ "$installer" -eq 1 ] && [ -f "$spool/install-request" ]; then
+                    # Rig onto a disk: identical erase discipline to the coordinator install —
+                    # the ack releases it, and a missing human hands the form back intact.
+                    if [ ! -f "$spool/handoff-ack" ]; then
+                        rm -f "$spool/handoff.json" "$spool/install-request" "$PWD/rig.json"
+                        printf 'The rig card was never confirmed — nothing was installed. Submit again when you are ready.' >"$spool/error.txt"
+                        chown 1000:1000 "$spool/error.txt" 2>/dev/null || true
+                        continue
+                    fi
+                    touch "$spool/installing"
+                    chown 1000:1000 "$spool/installing" 2>/dev/null || true
+                    # Stage the accepted settings onto the running ESP: the installer carries
+                    # them to the target's ESP, and the first boot from disk lands them on its
+                    # /data (the top of this function). The stick keeps NEITHER copy — rig.json
+                    # on its /data would turn the stick itself into a rig at the next boot, and
+                    # a leftover ESP file would seed every later machine.
+                    mount -o remount,rw /boot/efi 2>/dev/null || true
+                    if ! install -m 600 "$PWD/rig.json" /boot/efi/pithead-rig.json; then
+                        rm -f "$spool/installing" "$spool/handoff.json" "$spool/handoff-ack" "$spool/install-request" "$PWD/rig.json"
+                        printf 'Could not stage the rig settings for the installed system — nothing was installed.' >"$spool/error.txt"
+                        chown 1000:1000 "$spool/error.txt" 2>/dev/null || true
+                        continue
+                    fi
+                    local irc=0
+                    consume_install_request "$spool" || irc=$?
+                    rm -f "$PWD/rig.json" /boot/efi/pithead-rig.json
+                    if [ "$irc" -ne 0 ]; then
+                        rm -f "$spool/installing" "$spool/handoff.json" "$spool/handoff-ack"
+                        publish_disk_inventory "$spool"
+                        warn "Install failed — the page shows the reason."
+                        sleep 2
+                        continue
+                    fi
+                    _console "" "Installation complete — switching off now." \
+                        "When the machine is dark, remove the USB stick and switch it back on." \
+                        "It will come up as the rig you just confirmed."
+                    sleep 8
+                    "$engine" rm -f pithead-wizard >/dev/null 2>&1 || true
+                    _console "" "Shutting down. Remove the USB stick, then switch the machine on."
+                    sleep 3
+                    systemctl poweroff
+                    return
+                fi
+                # Run from this medium — or an installed machine choosing the rig role: the
+                # answers stay on THIS machine's /data and the marker closes the wizard window.
+                record_machine_role rig
+                touch "$spool/applied"
+                chown 1000:1000 "$spool/applied" 2>/dev/null || true
+                sleep 8 # long enough for the page's poll to show the saved state
+                "$engine" rm -f pithead-wizard >/dev/null 2>&1 || true
+                _console "Rig settings saved: $rig_worker -> stratum+tcp://$rig_pool." \
+                    "Rig provisioning lands with the next phase of the system — nothing mines yet."
+                return 0
+            fi
             if firstboot_consume_spool "$spool"; then
                 # Reachability before commitment: a remote node that cannot be dialed fails HERE,
                 # on the page, with the attempt kept for editing — not minutes into provisioning.
@@ -1821,6 +2003,9 @@ firstboot_wizard() {
                     systemctl poweroff
                     return
                 fi
+                # Installed machine, config accepted: record what it IS. The installer path
+                # above never reaches here — its role lands on the TARGET, at its first boot.
+                record_machine_role "$(machine_role_from_config "$PWD/config.json")"
                 sleep 2
                 "$engine" rm -f pithead-wizard >/dev/null 2>&1 || true
                 rm -rf "$spool"
@@ -3482,8 +3667,13 @@ ensure_onion_password() {
 # operator watching the other. Between power-on and the setup page there is a minute or more of
 # image loading, and silence there reads as a broken machine.
 _console() { # $1... lines
-    local dev
-    log "$@"
+    local dev line
+    # Every line reaches the journal too — a message that lives only on a physical console
+    # cost a bench session an hour once (see firstboot's teed setup log for the same lesson).
+    for line in "$@"; do
+        # if, not '&&': an empty spacer line under set -e must not become the exit status.
+        if [ -n "$line" ]; then log "$line"; fi
+    done
     for dev in /dev/tty1 /dev/ttyS0; do
         [ -w "$dev" ] || continue
         printf '  %s\n' "$@" >"$dev" 2>/dev/null || true
diff --git a/tests/stack/run.sh b/tests/stack/run.sh
index 94bb8f18..8d04ebf3 100755
--- a/tests/stack/run.sh
+++ b/tests/stack/run.sh
@@ -8100,6 +8100,98 @@ assert_rc "no install on any disk -> rc 1" "$?" "1"
 rm -rf "$PFSB"
 unset PFSB PF_TREE
 
+echo "== unit: publish_rig_defaults — host-side pool discovery, fail open (#797 R3) =="
+# The rig role's pre-fill: the HOST dials for a Pithead and publishes the finding to the spool
+# like the disk inventory. The dial is 'timeout N bash -c </dev/tcp/...' — timeout is a PATH
+# stub here (like mount in the pre-fill tests), so the probe answers deterministically.
+RDSB=$(mktemp -d)
+mkdir -p "$RDSB/bin" "$RDSB/spool"
+printf '#!/bin/bash\nexit 0\n' >"$RDSB/bin/timeout"
+chmod +x "$RDSB/bin/timeout"
+PITHEAD_RIG_PROBE="coordinator.lan:3333" PATH="$RDSB/bin:$PATH" \
+    run_sourced "$SANDBOX" publish_rig_defaults "$RDSB/spool" >/dev/null 2>&1
+assert_eq "a Pithead answering -> pool published" "$(jq -r '.pool' "$RDSB/spool/rig-defaults.json")" "coordinator.lan:3333"
+assert_eq "the worker default is this machine's own name" "$(jq -r '.worker' "$RDSB/spool/rig-defaults.json")" "$(hostname)"
+printf '#!/bin/bash\nexit 1\n' >"$RDSB/bin/timeout"
+PITHEAD_RIG_PROBE="coordinator.lan:3333" PATH="$RDSB/bin:$PATH" \
+    run_sourced "$SANDBOX" publish_rig_defaults "$RDSB/spool" >/dev/null 2>&1
+assert_eq "no answer -> NO pool key, the field opens empty" "$(jq -r 'has("pool")' "$RDSB/spool/rig-defaults.json")" "false"
+assert_eq "no temp file beside the atomic target" "$(find "$RDSB/spool" -name '.rig-defaults*' | wc -l | tr -d ' ')" "0"
+rm -rf "$RDSB"
+unset RDSB
+
+echo "== unit: firstboot_consume_rig — the pool is dialed BEFORE anything irreversible (#797 R3) =="
+RCSB=$(mktemp -d)
+mkdir -p "$RCSB/bin" "$RCSB/spool"
+printf '#!/bin/bash\nexit 0\n' >"$RCSB/bin/timeout"
+chmod +x "$RCSB/bin/timeout"
+
+run_sourced "$RCSB" firstboot_consume_rig "$RCSB/spool" >/dev/null 2>&1
+assert_rc "no request -> rc 2 (nothing submitted)" "$?" "2"
+
+printf '{"pool":"not-an-address"}' >"$RCSB/spool/rig-request.json"
+PATH="$RCSB/bin:$PATH" run_sourced "$RCSB" firstboot_consume_rig "$RCSB/spool" >/dev/null 2>&1
+assert_rc "shapeless pool -> rc 1, rejected" "$?" "1"
+assert_contains "the rejection names the format" "$(cat "$RCSB/spool/error.txt")" "host:port"
+[ -f "$RCSB/rig.json" ] && bad "a rejected request lands nothing" "rig.json exists" || ok "a rejected request lands nothing"
+
+printf '{"pool":"10.0.0.5:3333","worker":"shed-3","stratum_password":"pw-fixture"}' >"$RCSB/spool/rig-request.json"
+printf '#!/bin/bash\nexit 1\n' >"$RCSB/bin/timeout"
+PATH="$RCSB/bin:$PATH" run_sourced "$RCSB" firstboot_consume_rig "$RCSB/spool" >/dev/null 2>&1
+assert_rc "unreachable pool -> rc 1 (validate before erase)" "$?" "1"
+assert_contains "the failure names the endpoint" "$(cat "$RCSB/spool/error.txt")" "10.0.0.5:3333"
+
+printf '{"pool":"10.0.0.5:3333","worker":"shed-3","stratum_password":"pw-fixture"}' >"$RCSB/spool/rig-request.json"
+printf '#!/bin/bash\nexit 0\n' >"$RCSB/bin/timeout"
+PATH="$RCSB/bin:$PATH" run_sourced "$RCSB" firstboot_consume_rig "$RCSB/spool" >/dev/null 2>&1
+assert_rc "reachable pool -> rc 0, accepted" "$?" "0"
+assert_eq "the accepted answers land host-side" "$(jq -r '.worker' "$RCSB/rig.json")" "shed-3"
+assert_eq "the password rides along" "$(jq -r '.stratum_password' "$RCSB/rig.json")" "pw-fixture"
+[ -f "$RCSB/spool/rig-request.json" ] && bad "the request is consumed" "still present" || ok "the request is consumed"
+
+printf '{"pool":"10.0.0.5:3333"}' >"$RCSB/spool/rig-request.json"
+PATH="$RCSB/bin:$PATH" run_sourced "$RCSB" firstboot_consume_rig "$RCSB/spool" >/dev/null 2>&1
+assert_eq "no worker named -> this machine's own name" "$(jq -r '.worker' "$RCSB/rig.json")" "$(hostname)"
+assert_eq "no password -> the key is omitted, not written empty" "$(jq -r 'has("stratum_password")' "$RCSB/rig.json")" "false"
+rm -rf "$RCSB"
+unset RCSB
+
+echo "== unit: the machine-role marker + the rig boot stub (#797 R3; the boot leg is R4's) =="
+MRSB=$(mktemp -d)
+printf '{"local_miner":{"enabled":true}}' >"$MRSB/config.json"
+assert_eq "local_miner on -> both (the role IS the switch)" "$(run_sourced "$MRSB" machine_role_from_config "$MRSB/config.json")" "both"
+printf '{}' >"$MRSB/config.json"
+assert_eq "no local_miner -> pithead" "$(run_sourced "$MRSB" machine_role_from_config "$MRSB/config.json")" "pithead"
+rm -f "$MRSB/config.json"
+run_sourced "$MRSB" record_machine_role rig >/dev/null 2>&1
+assert_eq "the marker lands where the boot path reads it" "$(cat "$MRSB/machine-role")" "rig"
+
+# A machine already marked rig: firstboot states the role and STOPS — no wizard container, no
+# coordinator questions, an honest console line until the rig boot leg lands with R4.
+printf '{"pool":"10.0.0.5:3333","worker":"shed-3"}' >"$MRSB/rig.json"
+out=$(PITHEAD_INSTALL_BIN=/nonexistent run_sourced "$MRSB" firstboot_wizard 2>&1)
+assert_rc "rig-marked machine -> firstboot returns 0, no wizard" "$?" "0"
+assert_contains "the console states the role and the worker" "$out" "RigForge rig role"
+assert_contains "the stub is honest about what does not run yet" "$out" "nothing mines yet"
+assert_not_contains "no wizard container is started" "$out" "Setup wizard is up"
+rm -rf "$MRSB"
+unset MRSB out
+
+echo "== unit: a staged rig install lands on /data at the target's first boot (#797 R3) =="
+RPSB=$(mktemp -d)
+RPESP=$(mktemp -d)
+export PITHEAD_PRESEED_DIR="$RPESP"
+printf '{"pool":"10.0.0.5:3333","worker":"shed-3"}' >"$RPESP/pithead-rig.json"
+out=$(PITHEAD_INSTALL_BIN=/nonexistent run_sourced "$RPSB" firstboot_wizard 2>&1)
+assert_rc "staged rig settings -> consumed, rc 0" "$?" "0"
+assert_eq "the answers land beside the program" "$(jq -r '.worker' "$RPSB/rig.json")" "shed-3"
+assert_eq "the role marker is written" "$(cat "$RPSB/machine-role")" "rig"
+assert_contains "the stub message narrates the wait" "$out" "nothing mines yet"
+# Spent, like the config pre-seed: settings (possibly a password) must not sit on the ESP.
+[ -f "$RPESP/pithead-rig.json" ] && bad "the consumed settings leave the ESP" "still there" || ok "the consumed settings leave the ESP"
+rm -rf "$RPSB" "$RPESP"
+unset PITHEAD_PRESEED_DIR RPSB RPESP out
+
 echo "== unit: render_local_miner_config — the built-in miner's config is DERIVED (#796) =="
 # On the appliance, RigForge's config.json is a pure function of pithead's config.json + .env,
 # rebuilt on every render like the Caddyfile: the stack's own stratum over loopback, the stratum

From 9bf9fcac634dd07b5ff74507aa2222f4f05301c1 Mon Sep 17 00:00:00 2001
From: Vijit Singh <vijit.n.singh@gmail.com>
Date: Sun, 2 Aug 2026 10:52:08 -0500
Subject: [PATCH 2/2] refactor(wizard): serialize the role select's json pane
 once

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 build/dashboard/mining_dashboard/web/static/wizard.mjs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/build/dashboard/mining_dashboard/web/static/wizard.mjs b/build/dashboard/mining_dashboard/web/static/wizard.mjs
index c68a0236..ecea3722 100644
--- a/build/dashboard/mining_dashboard/web/static/wizard.mjs
+++ b/build/dashboard/mining_dashboard/web/static/wizard.mjs
@@ -329,16 +329,16 @@ export class WizardApp extends Component {
   setRole = (e) => {
     const role = e.target.value;
     const cfg = this.state.cfg;
-    const next = { role, cfg, jsonText: JSON.stringify(cfg, null, 2) };
+    const next = { role, cfg };
     if (role !== "rig") {
       pathSet(cfg, "local_miner.enabled", role === "both");
-      next.jsonText = JSON.stringify(cfg, null, 2);
       // "usb" only exists for rigs — a coordinator switching back must re-pick a real disk.
       if (this.state.chosen === "usb") {
         next.chosen = "";
         next.confirm = "";
       }
     }
+    next.jsonText = JSON.stringify(cfg, null, 2);
     this.setState(next);
   };