claw-store/src/cluster.rs

@@ -26,6 +26,7 @@ pub mod refs;
 pub mod repo_ensure;
 pub mod rpc;
 pub mod services;
+pub mod shutdown_prep;
 pub mod snapshot;
 pub mod tags;
 pub mod tailscale;

claw-store/src/cluster/rpc.rs

@@ -217,6 +217,22 @@ pub enum Method {
     /// `payload`: JSON [`crate::cluster::repo_ensure::RepoReleaseRequest`].
     /// Reply: JSON [`crate::cluster::repo_ensure::RepoReleaseReply`].
     RepoRelease = 0x1f,
+    /// Runs `safe-shutdown-prep.sh --dry-run` to completion on this
+    /// node and returns the full report. Never stops anything —
+    /// dry-run only, safe to call repeatedly.
+    ///
+    /// `payload`: JSON [`crate::cluster::shutdown_prep::ShutdownPrepCheckRequest`].
+    /// Reply: JSON [`crate::cluster::shutdown_prep::ShutdownPrepCheckReply`].
+    ShutdownPrepCheck = 0x20,
+    /// Starts the real `safe-shutdown-prep.sh` run in a detached
+    /// systemd scope and returns immediately — the script's own step
+    /// stops `claw-store.service`, so this RPC connection cannot
+    /// outlive full completion. See
+    /// [`crate::cluster::shutdown_prep`] module docs.
+    ///
+    /// `payload`: JSON [`crate::cluster::shutdown_prep::ShutdownPrepExecuteRequest`].
+    /// Reply: JSON [`crate::cluster::shutdown_prep::ShutdownPrepExecuteReply`].
+    ShutdownPrepExecute = 0x21,
 }
 
 impl Method {
@@ -255,6 +271,8 @@ impl Method {
             0x1d => Some(Method::DashboardStorage),
             0x1e => Some(Method::RepoEnsure),
             0x1f => Some(Method::RepoRelease),
+            0x20 => Some(Method::ShutdownPrepCheck),
+            0x21 => Some(Method::ShutdownPrepExecute),
             _ => None,
         }
     }
@@ -1176,6 +1194,26 @@ impl RpcRouter {
                     .context("encoding RepoReleaseReply as JSON")?;
                 Ok(HandlerOutcome::Reply(json))
             }
+            Method::ShutdownPrepCheck => {
+                let reply = crate::cluster::shutdown_prep::check().await?;
+                let json = serde_json::to_vec(&reply)
+                    .context("encoding ShutdownPrepCheckReply as JSON")?;
+                Ok(HandlerOutcome::Reply(json))
+            }
+            Method::ShutdownPrepExecute => {
+                let req: crate::cluster::shutdown_prep::ShutdownPrepExecuteRequest =
+                    match serde_json::from_slice(payload) {
+                        Ok(r) => r,
+                        Err(_) => {
+                            return Ok(HandlerOutcome::Error(ErrorCode::InvalidRequest))
+                        }
+                    };
+                let reply =
+                    crate::cluster::shutdown_prep::execute(&self.local_name, &req).await?;
+                let json = serde_json::to_vec(&reply)
+                    .context("encoding ShutdownPrepExecuteReply as JSON")?;
+                Ok(HandlerOutcome::Reply(json))
+            }
             Method::BlobStat => {
                 let store = match &self.blob_store {
                     Some(s) => s,

claw-store/src/cluster/rpc/client.rs

@@ -229,6 +229,45 @@ pub async fn call_repo_release(
     serde_json::from_slice(&reply).context("decoding RepoReleaseReply JSON")
 }
 
+/// Convenience wrapper for [`Method::ShutdownPrepCheck`]. Runs
+/// `safe-shutdown-prep.sh --dry-run` on the connected peer and waits
+/// for the full report. Never stops anything on the peer.
+pub async fn call_shutdown_prep_check(
+    conn: &Connection,
+) -> Result<crate::cluster::shutdown_prep::ShutdownPrepCheckReply> {
+    let req = crate::cluster::shutdown_prep::ShutdownPrepCheckRequest {};
+    let payload = serde_json::to_vec(&req).context("encoding ShutdownPrepCheckRequest")?;
+    let reply = rpc_call(conn, Method::ShutdownPrepCheck, &payload).await?;
+    if reply.len() == 1 {
+        if let Some(code) = decode_error(reply[0]) {
+            bail!("peer replied with error: {}", code.describe());
+        }
+    }
+    serde_json::from_slice(&reply).context("decoding ShutdownPrepCheckReply JSON")
+}
+
+/// Convenience wrapper for [`Method::ShutdownPrepExecute`]. Starts the
+/// real shutdown-prep run on the connected peer (detached — this call
+/// returns as soon as the peer confirms it started, not when it
+/// finishes, since the peer's own daemon stops itself partway
+/// through).
+pub async fn call_shutdown_prep_execute(
+    conn: &Connection,
+    confirm_node_name: &str,
+) -> Result<crate::cluster::shutdown_prep::ShutdownPrepExecuteReply> {
+    let req = crate::cluster::shutdown_prep::ShutdownPrepExecuteRequest {
+        confirm_node_name: confirm_node_name.to_string(),
+    };
+    let payload = serde_json::to_vec(&req).context("encoding ShutdownPrepExecuteRequest")?;
+    let reply = rpc_call(conn, Method::ShutdownPrepExecute, &payload).await?;
+    if reply.len() == 1 {
+        if let Some(code) = decode_error(reply[0]) {
+            bail!("peer replied with error: {}", code.describe());
+        }
+    }
+    serde_json::from_slice(&reply).context("decoding ShutdownPrepExecuteReply JSON")
+}
+
 /// Recognise a single-byte reply as one of our error codes. Returns
 /// `None` for any other single-byte value (which is a valid reply,
 /// just an unusually short one).

claw-store/src/cluster/shutdown_prep.rs

@@ -0,0 +1,166 @@
+//! Peer-side wiring for `deploy/scripts/safe-shutdown-prep.sh`,
+//! surfaced through the RPC layer so the dashboard-v2 aggregator can
+//! offer a "prepare this node for shutdown" action.
+//!
+//! Split into two RPCs deliberately:
+//!
+//! - [`Method::ShutdownPrepCheck`] runs the script's `--dry-run` mode
+//!   and waits for it to finish. Dry-run never stops this node's own
+//!   daemon, so the RPC connection survives to deliver the full
+//!   report — this is the part a browser can meaningfully show.
+//! - [`Method::ShutdownPrepExecute`] runs the real script, which (by
+//!   design) stops `claw-store.service` — i.e. the very process
+//!   handling this RPC. There is no way to stream a live result past
+//!   that point, so this RPC detaches the script into its own
+//!   transient systemd scope (outside this daemon's service cgroup,
+//!   so `systemctl stop claw-store.service` doesn't take the script
+//!   down with it) and returns immediately. The full report lands in
+//!   `SHUTDOWN_PREP_LOG` for whoever is physically at the machine (or
+//!   over SSH) to read once the node has gone dark.
+//!
+//! [`Method::ShutdownPrepCheck`]: crate::cluster::rpc::Method::ShutdownPrepCheck
+//! [`Method::ShutdownPrepExecute`]: crate::cluster::rpc::Method::ShutdownPrepExecute
+
+use anyhow::{bail, Context, Result};
+use serde::{Deserialize, Serialize};
+use std::path::PathBuf;
+use std::time::Duration;
+use tokio::process::Command;
+use tokio::time::timeout;
+
+/// Dry-run does a real snapshot + replicate, which can legitimately
+/// take a while on a large delta. Generous but bounded so a stuck
+/// peer connection doesn't hang the RPC forever.
+const CHECK_TIMEOUT: Duration = Duration::from_secs(300);
+
+/// Where the real run's output lands once this node's daemon (and
+/// therefore this RPC connection) is gone.
+pub const SHUTDOWN_PREP_LOG: &str = "/var/lib/claw-store/shutdown-prep.log";
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct ShutdownPrepCheckRequest {}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct ShutdownPrepCheckReply {
+    /// True iff the script exited 0 (every guard passed, "SAFE TO
+    /// POWER OFF" printed for the checked steps).
+    pub ready: bool,
+    /// Full combined stdout+stderr from `--dry-run`.
+    pub output: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct ShutdownPrepExecuteRequest {
+    /// Defense in depth beyond RPC targeting: the caller must name
+    /// the exact node it thinks it's shutting down. Checked against
+    /// this node's own configured name before anything runs.
+    pub confirm_node_name: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct ShutdownPrepExecuteReply {
+    pub started: bool,
+    pub message: String,
+    pub log_path: String,
+}
+
+fn script_path() -> PathBuf {
+    if let Ok(p) = std::env::var("CLAWSTOR_SHUTDOWN_SCRIPT") {
+        if !p.is_empty() {
+            return PathBuf::from(p);
+        }
+    }
+    if let Ok(home) = std::env::var("HOME") {
+        if !home.is_empty() {
+            return PathBuf::from(home)
+                .join("clawstor-deploy/scripts/safe-shutdown-prep.sh");
+        }
+    }
+    PathBuf::from("/usr/local/share/claw-store/safe-shutdown-prep.sh")
+}
+
+/// Run `safe-shutdown-prep.sh --dry-run` to completion and report the
+/// full output. Never stops anything on this node — safe to call any
+/// time, including repeatedly.
+pub async fn check() -> Result<ShutdownPrepCheckReply> {
+    let script = script_path();
+    if !script.exists() {
+        bail!("shutdown-prep script not found at {}", script.display());
+    }
+    let run = Command::new("bash")
+        .arg(&script)
+        .arg("--dry-run")
+        .output();
+    let output = timeout(CHECK_TIMEOUT, run)
+        .await
+        .context("shutdown-prep --dry-run timed out")?
+        .context("spawning shutdown-prep --dry-run")?;
+    let mut combined = String::from_utf8_lossy(&output.stdout).into_owned();
+    combined.push_str(&String::from_utf8_lossy(&output.stderr));
+    Ok(ShutdownPrepCheckReply {
+        ready: output.status.success(),
+        output: combined,
+    })
+}
+
+/// Kick off the real (non-dry-run) script in a transient systemd
+/// scope detached from this daemon's own service cgroup, then return
+/// immediately without waiting for it. The script's own step 6 stops
+/// `claw-store.service` — waiting for it to exit here would mean
+/// waiting for our own process to be killed.
+pub async fn execute(local_node_name: &str, req: &ShutdownPrepExecuteRequest) -> Result<ShutdownPrepExecuteReply> {
+    if req.confirm_node_name != local_node_name {
+        bail!(
+            "confirm_node_name '{}' does not match this node ('{}') — refusing",
+            req.confirm_node_name,
+            local_node_name
+        );
+    }
+    let script = script_path();
+    if !script.exists() {
+        bail!("shutdown-prep script not found at {}", script.display());
+    }
+    let unit = format!(
+        "clawstor-shutdown-prep-{}",
+        std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .map(|d| d.as_secs())
+            .unwrap_or(0)
+    );
+    // `--user --scope` places this under the user session's cgroup
+    // tree (/user.slice/...), a sibling of — not a descendant of —
+    // /system.slice/claw-store.service. `systemctl stop
+    // claw-store.service` only tears down its own cgroup, so this
+    // keeps running (and completes step 6, which stops that very
+    // service) unaffected.
+    // Deliberately no --force: the real run re-checks active builds
+    // and the sync queue itself, even though `check()` may have run
+    // moments ago — state can change between the two clicks, and
+    // re-validating is cheap.
+    let cmd = format!(
+        "{} >> {} 2>&1",
+        script.display(),
+        SHUTDOWN_PREP_LOG
+    );
+    let spawn = Command::new("systemd-run")
+        .arg("--user")
+        .arg("--scope")
+        .arg("--collect")
+        .arg(format!("--unit={unit}"))
+        .arg("bash")
+        .arg("-c")
+        .arg(&cmd)
+        .spawn();
+    match spawn {
+        Ok(_child) => Ok(ShutdownPrepExecuteReply {
+            started: true,
+            message: format!(
+                "shutdown-prep started on {local_node_name} as transient unit {unit}. \
+                 This node's daemon (and dashboard) will go offline as part of the \
+                 process — that is expected. Full output: {SHUTDOWN_PREP_LOG}."
+            ),
+            log_path: SHUTDOWN_PREP_LOG.to_string(),
+        }),
+        Err(e) => Err(e).context("spawning systemd-run for shutdown-prep"),
+    }
+}

claw-store/src/serve_v2.rs

@@ -570,6 +570,19 @@ impl AuthedCaller {
     /// in the request body. Explicit user-supplied workspace is only
     /// honored for admin/open — a namespaced caller supplying a
     /// mismatched workspace is a forbidden write.
+    /// Gate for fleet-infrastructure actions (shutdown-prep) that
+    /// have nothing to do with a tag/repo namespace — a namespaced
+    /// per-app token has no business stopping a node's services.
+    pub fn require_admin(&self) -> Result<(), (StatusCode, String)> {
+        match self {
+            AuthedCaller::Admin | AuthedCaller::Open => Ok(()),
+            AuthedCaller::Namespaced { .. } => Err((
+                StatusCode::FORBIDDEN,
+                "this action requires an admin token".to_string(),
+            )),
+        }
+    }
+
     pub fn resolve_workspace(&self, requested: Option<&str>) -> Result<String, (StatusCode, String)> {
         match self {
             AuthedCaller::Admin | AuthedCaller::Open => match requested {
@@ -866,6 +879,93 @@ async fn handle_repos_release(
     }))
 }
 
+// ── shutdown-prep (targets one specific node, not a fan-out) ──────
+
+#[derive(Serialize)]
+pub struct ShutdownPrepCheckResponse {
+    pub node: String,
+    pub ready: bool,
+    pub output: String,
+}
+
+async fn handle_shutdown_prep_check(
+    State(s): State<Arc<V2State>>,
+    Path(name): Path<String>,
+    axum::extract::Extension(caller): axum::extract::Extension<AuthedCaller>,
+) -> Result<Json<ShutdownPrepCheckResponse>, (StatusCode, String)> {
+    caller.require_admin()?;
+    let peer = s
+        .peers
+        .iter()
+        .find(|p| p.name == name)
+        .cloned()
+        .ok_or((StatusCode::NOT_FOUND, format!("no peer named {name}")))?;
+    let conn = s
+        .dial(&peer)
+        .await
+        .map_err(|e| (StatusCode::BAD_GATEWAY, format!("connecting to {name}: {e:#}")))?;
+    let reply = crate::cluster::rpc::call_shutdown_prep_check(&conn).await;
+    conn.close(quinn::VarInt::from_u32(0), b"done");
+    let reply = reply.map_err(|e| (StatusCode::BAD_GATEWAY, format!("{e:#}")))?;
+    Ok(Json(ShutdownPrepCheckResponse {
+        node: name,
+        ready: reply.ready,
+        output: reply.output,
+    }))
+}
+
+#[derive(Deserialize)]
+pub struct ShutdownPrepExecuteBody {
+    /// Must equal the target node's own name — a second, server-side
+    /// confirmation beyond "the operator clicked the right button in
+    /// the UI". Checked again on the peer itself in
+    /// `shutdown_prep::execute`.
+    pub confirm_node_name: String,
+}
+
+#[derive(Serialize)]
+pub struct ShutdownPrepExecuteResponse {
+    pub node: String,
+    pub started: bool,
+    pub message: String,
+}
+
+async fn handle_shutdown_prep_execute(
+    State(s): State<Arc<V2State>>,
+    Path(name): Path<String>,
+    axum::extract::Extension(caller): axum::extract::Extension<AuthedCaller>,
+    Json(body): Json<ShutdownPrepExecuteBody>,
+) -> Result<Json<ShutdownPrepExecuteResponse>, (StatusCode, String)> {
+    caller.require_admin()?;
+    if body.confirm_node_name != name {
+        return Err((
+            StatusCode::BAD_REQUEST,
+            format!(
+                "confirm_node_name '{}' does not match target node '{name}'",
+                body.confirm_node_name
+            ),
+        ));
+    }
+    let peer = s
+        .peers
+        .iter()
+        .find(|p| p.name == name)
+        .cloned()
+        .ok_or((StatusCode::NOT_FOUND, format!("no peer named {name}")))?;
+    let conn = s
+        .dial(&peer)
+        .await
+        .map_err(|e| (StatusCode::BAD_GATEWAY, format!("connecting to {name}: {e:#}")))?;
+    let reply = crate::cluster::rpc::call_shutdown_prep_execute(&conn, &name).await;
+    conn.close(quinn::VarInt::from_u32(0), b"done");
+    let reply = reply.map_err(|e| (StatusCode::BAD_GATEWAY, format!("{e:#}")))?;
+    Ok(Json(ShutdownPrepExecuteResponse {
+        node: name,
+        started: reply.started,
+        message: reply.message,
+    }))
+}
+
 async fn fanout_repo_ensure(
     s: &V2State,
     req: &crate::cluster::repo_ensure::RepoEnsureRequest,
@@ -1347,6 +1447,14 @@ pub fn build(state: Arc<V2State>) -> Router {
         .route("/api/v2/sessions/:id/commit", post(handle_commit_session))
         .route("/api/v2/repos/ensure", post(handle_repos_ensure))
         .route("/api/v2/repos/release", post(handle_repos_release))
+        .route(
+            "/api/v2/node/:name/shutdown-prep/check",
+            post(handle_shutdown_prep_check),
+        )
+        .route(
+            "/api/v2/node/:name/shutdown-prep/execute",
+            post(handle_shutdown_prep_execute),
+        )
         .route_layer(axum::middleware::from_fn_with_state(state.clone(), v2_auth))
         .with_state(state)
 }

dashboard-v2/src/components/ShutdownPrepPanel.js

@@ -0,0 +1,44 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useState } from 'react';
+import { api } from '../lib/api';
+/**
+ * Node-maintenance panel: runs `safe-shutdown-prep.sh --dry-run` on
+ * demand (safe, read-mostly, never stops anything) and — only once
+ * that comes back ready — unlocks a type-to-confirm button that
+ * starts the real run.
+ *
+ * The real run is fire-and-forget by necessity: its own steps stop
+ * this node's daemon, which is what's serving this very page, so
+ * there is no way to stream a live result past that point. Once
+ * started, the UI says so plainly and points at the on-disk log for
+ * the full report.
+ */
+export function ShutdownPrepPanel({ name }) {
+    const [check, setCheck] = useState({ phase: 'idle' });
+    const [exec, setExec] = useState({ phase: 'idle' });
+    const [confirmText, setConfirmText] = useState('');
+    const runCheck = () => {
+        setCheck({ phase: 'checking' });
+        setExec({ phase: 'idle' });
+        setConfirmText('');
+        api
+            .shutdownPrepCheck(name)
+            .then((r) => setCheck({ phase: 'done', ready: r.ready, output: r.output }))
+            .catch((e) => setCheck({ phase: 'error', message: String(e) }));
+    };
+    const runExecute = () => {
+        if (confirmText !== name)
+            return;
+        setExec({ phase: 'starting' });
+        api
+            .shutdownPrepExecute(name, confirmText)
+            .then((r) => setExec({ phase: 'started', message: r.message }))
+            .catch((e) => setExec({ phase: 'error', message: String(e) }));
+    };
+    const ready = check.phase === 'done' && check.ready;
+    return (_jsxs("div", { className: "rounded border border-slate-800 bg-slate-900/40 p-4 text-sm space-y-3", children: [_jsxs("div", { className: "flex items-center justify-between", children: [_jsx("div", { className: "text-slate-500 uppercase text-xs tracking-wider", children: "shutdown prep" }), _jsx("button", { onClick: runCheck, disabled: check.phase === 'checking', className: "px-3 py-1.5 rounded bg-slate-800 hover:bg-slate-700 text-slate-200 text-xs disabled:opacity-50", children: check.phase === 'checking' ? 'checking…' : 'check readiness for shutdown' })] }), _jsxs("p", { className: "text-xs text-slate-500", children: ["Runs a dry-run of the pre-shutdown checklist on ", _jsx("span", { className: "font-mono", children: name }), ' ', "\u2014 active builds, pending peer sync, a final snapshot + replicate to cold. Nothing is stopped or unmounted by this check."] }), check.phase === 'error' && (_jsx("div", { className: "rounded border border-red-800 bg-red-950/40 p-3 text-red-300 text-xs", children: check.message })), check.phase === 'done' && (_jsxs(_Fragment, { children: [_jsx("div", { className: `rounded border p-3 text-xs ${check.ready
+                            ? 'border-emerald-800 bg-emerald-950/40 text-emerald-300'
+                            : 'border-amber-800 bg-amber-950/40 text-amber-300'}`, children: check.ready
+                            ? '✓ ready — safe to start the real shutdown-prep run'
+                            : '! not ready — see output below (active build or un-synced changes are the usual cause)' }), _jsx("pre", { className: "max-h-72 overflow-auto rounded bg-slate-950 border border-slate-800 p-3 text-[11px] leading-relaxed text-slate-300 whitespace-pre-wrap", children: check.output })] })), ready && exec.phase !== 'started' && (_jsxs("div", { className: "rounded border border-red-900 bg-red-950/30 p-3 space-y-2", children: [_jsxs("div", { className: "text-red-300 text-xs", children: ["This starts the real run: stops maintenance timers, the dashboard, the storage daemon (gossip announces departure to peers), and unmounts FUSE on", ' ', _jsx("span", { className: "font-mono", children: name }), ". The node's dashboard connection will drop partway through \u2014 that's expected, not an error. It does ", _jsx("strong", { children: "not" }), " power the machine off; do that yourself once it's gone dark."] }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx("input", { value: confirmText, onChange: (e) => setConfirmText(e.target.value), placeholder: `type "${name}" to confirm`, className: "flex-1 rounded bg-slate-900 border border-slate-700 px-2 py-1.5 text-xs font-mono text-slate-200 placeholder:text-slate-600" }), _jsx("button", { onClick: runExecute, disabled: confirmText !== name || exec.phase === 'starting', className: "px-3 py-1.5 rounded bg-red-900 hover:bg-red-800 text-red-100 text-xs disabled:opacity-40 disabled:cursor-not-allowed whitespace-nowrap", children: exec.phase === 'starting' ? 'starting…' : `stop services on ${name}` })] })] })), exec.phase === 'error' && (_jsx("div", { className: "rounded border border-red-800 bg-red-950/40 p-3 text-red-300 text-xs", children: exec.message })), exec.phase === 'started' && (_jsx("div", { className: "rounded border border-sky-800 bg-sky-950/30 p-3 text-sky-300 text-xs", children: exec.message }))] }));
+}

dashboard-v2/src/components/ShutdownPrepPanel.tsx

@@ -0,0 +1,144 @@
+import { useState } from 'react';
+import { api } from '../lib/api';
+
+interface Props {
+  name: string;
+}
+
+type CheckState =
+  | { phase: 'idle' }
+  | { phase: 'checking' }
+  | { phase: 'done'; ready: boolean; output: string }
+  | { phase: 'error'; message: string };
+
+type ExecState =
+  | { phase: 'idle' }
+  | { phase: 'starting' }
+  | { phase: 'started'; message: string }
+  | { phase: 'error'; message: string };
+
+/**
+ * Node-maintenance panel: runs `safe-shutdown-prep.sh --dry-run` on
+ * demand (safe, read-mostly, never stops anything) and — only once
+ * that comes back ready — unlocks a type-to-confirm button that
+ * starts the real run.
+ *
+ * The real run is fire-and-forget by necessity: its own steps stop
+ * this node's daemon, which is what's serving this very page, so
+ * there is no way to stream a live result past that point. Once
+ * started, the UI says so plainly and points at the on-disk log for
+ * the full report.
+ */
+export function ShutdownPrepPanel({ name }: Props) {
+  const [check, setCheck] = useState<CheckState>({ phase: 'idle' });
+  const [exec, setExec] = useState<ExecState>({ phase: 'idle' });
+  const [confirmText, setConfirmText] = useState('');
+
+  const runCheck = () => {
+    setCheck({ phase: 'checking' });
+    setExec({ phase: 'idle' });
+    setConfirmText('');
+    api
+      .shutdownPrepCheck(name)
+      .then((r) => setCheck({ phase: 'done', ready: r.ready, output: r.output }))
+      .catch((e) => setCheck({ phase: 'error', message: String(e) }));
+  };
+
+  const runExecute = () => {
+    if (confirmText !== name) return;
+    setExec({ phase: 'starting' });
+    api
+      .shutdownPrepExecute(name, confirmText)
+      .then((r) => setExec({ phase: 'started', message: r.message }))
+      .catch((e) => setExec({ phase: 'error', message: String(e) }));
+  };
+
+  const ready = check.phase === 'done' && check.ready;
+
+  return (
+    <div className="rounded border border-slate-800 bg-slate-900/40 p-4 text-sm space-y-3">
+      <div className="flex items-center justify-between">
+        <div className="text-slate-500 uppercase text-xs tracking-wider">
+          shutdown prep
+        </div>
+        <button
+          onClick={runCheck}
+          disabled={check.phase === 'checking'}
+          className="px-3 py-1.5 rounded bg-slate-800 hover:bg-slate-700 text-slate-200 text-xs disabled:opacity-50"
+        >
+          {check.phase === 'checking' ? 'checking…' : 'check readiness for shutdown'}
+        </button>
+      </div>
+
+      <p className="text-xs text-slate-500">
+        Runs a dry-run of the pre-shutdown checklist on <span className="font-mono">{name}</span>{' '}
+        — active builds, pending peer sync, a final snapshot + replicate to cold. Nothing is
+        stopped or unmounted by this check.
+      </p>
+
+      {check.phase === 'error' && (
+        <div className="rounded border border-red-800 bg-red-950/40 p-3 text-red-300 text-xs">
+          {check.message}
+        </div>
+      )}
+
+      {check.phase === 'done' && (
+        <>
+          <div
+            className={`rounded border p-3 text-xs ${
+              check.ready
+                ? 'border-emerald-800 bg-emerald-950/40 text-emerald-300'
+                : 'border-amber-800 bg-amber-950/40 text-amber-300'
+            }`}
+          >
+            {check.ready
+              ? '✓ ready — safe to start the real shutdown-prep run'
+              : '! not ready — see output below (active build or un-synced changes are the usual cause)'}
+          </div>
+          <pre className="max-h-72 overflow-auto rounded bg-slate-950 border border-slate-800 p-3 text-[11px] leading-relaxed text-slate-300 whitespace-pre-wrap">
+            {check.output}
+          </pre>
+        </>
+      )}
+
+      {ready && exec.phase !== 'started' && (
+        <div className="rounded border border-red-900 bg-red-950/30 p-3 space-y-2">
+          <div className="text-red-300 text-xs">
+            This starts the real run: stops maintenance timers, the dashboard, the storage
+            daemon (gossip announces departure to peers), and unmounts FUSE on{' '}
+            <span className="font-mono">{name}</span>. The node's dashboard connection will drop
+            partway through — that's expected, not an error. It does <strong>not</strong> power
+            the machine off; do that yourself once it's gone dark.
+          </div>
+          <div className="flex items-center gap-2">
+            <input
+              value={confirmText}
+              onChange={(e) => setConfirmText(e.target.value)}
+              placeholder={`type "${name}" to confirm`}
+              className="flex-1 rounded bg-slate-900 border border-slate-700 px-2 py-1.5 text-xs font-mono text-slate-200 placeholder:text-slate-600"
+            />
+            <button
+              onClick={runExecute}
+              disabled={confirmText !== name || exec.phase === 'starting'}
+              className="px-3 py-1.5 rounded bg-red-900 hover:bg-red-800 text-red-100 text-xs disabled:opacity-40 disabled:cursor-not-allowed whitespace-nowrap"
+            >
+              {exec.phase === 'starting' ? 'starting…' : `stop services on ${name}`}
+            </button>
+          </div>
+        </div>
+      )}
+
+      {exec.phase === 'error' && (
+        <div className="rounded border border-red-800 bg-red-950/40 p-3 text-red-300 text-xs">
+          {exec.message}
+        </div>
+      )}
+
+      {exec.phase === 'started' && (
+        <div className="rounded border border-sky-800 bg-sky-950/30 p-3 text-sky-300 text-xs">
+          {exec.message}
+        </div>
+      )}
+    </div>
+  );
+}

dashboard-v2/src/lib/api.js

@@ -23,6 +23,19 @@ async function get(path) {
     }
     return resp.json();
 }
+async function post(path, body) {
+    const full = `${API_BASE}${path}`;
+    const resp = await fetch(full, {
+        method: 'POST',
+        headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+        body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    if (!resp.ok) {
+        const text = await resp.text().catch(() => '');
+        throw new Error(`${full} → ${resp.status} ${resp.statusText}${text ? `: ${text}` : ''}`);
+    }
+    return resp.json();
+}
 export const api = {
     fleet: () => get('/v2/fleet'),
     projects: () => get('/v2/projects'),
@@ -32,6 +45,10 @@ export const api = {
     refs: (limit = 200, offset = 0) => get(`/v2/storage/refs?limit=${limit}&offset=${offset}`),
     snapshots: () => get('/v2/storage/snapshots'),
     refTracking: (repo = '') => get(`/v2/storage/ref-tracking?repo=${encodeURIComponent(repo)}`),
+    shutdownPrepCheck: (name) => post(`/v2/node/${name}/shutdown-prep/check`),
+    shutdownPrepExecute: (name, confirmNodeName) => post(`/v2/node/${name}/shutdown-prep/execute`, {
+        confirm_node_name: confirmNodeName,
+    }),
 };
 /** Format bytes as MB / GB / TB as needed. */
 export function fmtBytes(n) {

dashboard-v2/src/lib/api.ts

@@ -119,6 +119,20 @@ async function get<T>(path: string): Promise<T> {
   return resp.json();
 }
 
+async function post<T>(path: string, body?: unknown): Promise<T> {
+  const full = `${API_BASE}${path}`;
+  const resp = await fetch(full, {
+    method: 'POST',
+    headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => '');
+    throw new Error(`${full} → ${resp.status} ${resp.statusText}${text ? `: ${text}` : ''}`);
+  }
+  return resp.json();
+}
+
 // All paths are relative to API_BASE. E.g. '/v2/fleet' becomes
 // '/api/v2/fleet' locally or '/clawstor/api/v2/fleet' via Tailscale.
 export interface ProjectRow {
@@ -145,8 +159,26 @@ export const api = {
   snapshots: () => get<SnapshotSummary[]>('/v2/storage/snapshots'),
   refTracking: (repo = '') =>
     get<RefTrackingItem[]>(`/v2/storage/ref-tracking?repo=${encodeURIComponent(repo)}`),
+  shutdownPrepCheck: (name: string) =>
+    post<ShutdownPrepCheckResponse>(`/v2/node/${name}/shutdown-prep/check`),
+  shutdownPrepExecute: (name: string, confirmNodeName: string) =>
+    post<ShutdownPrepExecuteResponse>(`/v2/node/${name}/shutdown-prep/execute`, {
+      confirm_node_name: confirmNodeName,
+    }),
 };
 
+export interface ShutdownPrepCheckResponse {
+  node: string;
+  ready: boolean;
+  output: string;
+}
+
+export interface ShutdownPrepExecuteResponse {
+  node: string;
+  started: boolean;
+  message: string;
+}
+
 /** Format bytes as MB / GB / TB as needed. */
 export function fmtBytes(n: number): string {
   if (n < 1024) return `${n} B`;

dashboard-v2/src/pages/NodeDetail.js

@@ -3,6 +3,7 @@ import { useEffect, useState } from 'react';
 import { Link } from 'wouter';
 import { api, fmtBytes } from '../lib/api';
 import { StatTile } from '../components/StatTile';
+import { ShutdownPrepPanel } from '../components/ShutdownPrepPanel';
 export function NodeDetail({ name }) {
     const [status, setStatus] = useState(null);
     const [err, setErr] = useState(null);
@@ -15,5 +16,5 @@ export function NodeDetail({ name }) {
         })
             .catch((e) => setErr(String(e)));
     }, [name]);
-    return (_jsxs("div", { className: "space-y-6", children: [_jsxs("div", { children: [_jsx(Link, { href: "/", children: _jsx("a", { className: "text-sm text-slate-500 hover:text-slate-300", children: "\u2190 fleet" }) }), _jsx("h1", { className: "text-2xl font-semibold text-slate-100 mt-2", children: name })] }), err && (_jsxs("div", { className: "rounded border border-amber-800 bg-amber-950/40 p-3 text-amber-300 text-sm", children: [err, _jsxs("div", { className: "mt-2 text-xs text-slate-400", children: ["Cross-node lookup lands in a follow-on PR. Until then this page shows detail only when you're already viewing the dashboard hosted by ", name, ". Try opening", ' ', _jsxs("span", { className: "font-mono", children: ["http://", name, ":7700/v2/#/nodes/", name] }), ' ', "directly."] })] })), status && (_jsxs(_Fragment, { children: [_jsxs("div", { className: "grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-6 gap-3", children: [_jsx(StatTile, { label: "blobs", value: status.blob_count.toLocaleString(), color: "ok" }), _jsx(StatTile, { label: "tags", value: status.tag_count, color: "ok" }), _jsx(StatTile, { label: "refs", value: status.ref_count, color: "ok" }), _jsx(StatTile, { label: "snapshots", value: status.snapshot_count, color: "ok" }), _jsx(StatTile, { label: "ref-tracking", value: status.ref_tracking_count, color: "ok" }), _jsx(StatTile, { label: "store size", value: fmtBytes(status.blob_store_bytes), color: "ok" })] }), _jsxs("div", { className: "rounded border border-slate-800 bg-slate-900/40 p-4 text-sm", children: [_jsx("div", { className: "text-slate-500 uppercase text-xs tracking-wider", children: "blob store root" }), _jsx("div", { className: "font-mono mt-1", children: status.blob_store_root ?? '—' })] })] }))] }));
+    return (_jsxs("div", { className: "space-y-6", children: [_jsxs("div", { children: [_jsx(Link, { href: "/", children: _jsx("a", { className: "text-sm text-slate-500 hover:text-slate-300", children: "\u2190 fleet" }) }), _jsx("h1", { className: "text-2xl font-semibold text-slate-100 mt-2", children: name })] }), err && (_jsxs("div", { className: "rounded border border-amber-800 bg-amber-950/40 p-3 text-amber-300 text-sm", children: [err, _jsxs("div", { className: "mt-2 text-xs text-slate-400", children: ["Cross-node lookup lands in a follow-on PR. Until then this page shows detail only when you're already viewing the dashboard hosted by ", name, ". Try opening", ' ', _jsxs("span", { className: "font-mono", children: ["http://", name, ":7700/v2/#/nodes/", name] }), ' ', "directly."] })] })), status && (_jsxs(_Fragment, { children: [_jsxs("div", { className: "grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-6 gap-3", children: [_jsx(StatTile, { label: "blobs", value: status.blob_count.toLocaleString(), color: "ok" }), _jsx(StatTile, { label: "tags", value: status.tag_count, color: "ok" }), _jsx(StatTile, { label: "refs", value: status.ref_count, color: "ok" }), _jsx(StatTile, { label: "snapshots", value: status.snapshot_count, color: "ok" }), _jsx(StatTile, { label: "ref-tracking", value: status.ref_tracking_count, color: "ok" }), _jsx(StatTile, { label: "store size", value: fmtBytes(status.blob_store_bytes), color: "ok" })] }), _jsxs("div", { className: "rounded border border-slate-800 bg-slate-900/40 p-4 text-sm", children: [_jsx("div", { className: "text-slate-500 uppercase text-xs tracking-wider", children: "blob store root" }), _jsx("div", { className: "font-mono mt-1", children: status.blob_store_root ?? '—' })] }), _jsx(ShutdownPrepPanel, { name: name })] }))] }));
 }

dashboard-v2/src/pages/NodeDetail.tsx

@@ -2,6 +2,7 @@ import { useEffect, useState } from 'react';
 import { Link } from 'wouter';
 import { api, NodeStatusV2, fmtBytes } from '../lib/api';
 import { StatTile } from '../components/StatTile';
+import { ShutdownPrepPanel } from '../components/ShutdownPrepPanel';
 
 interface Props {
   name: string;
@@ -67,6 +68,8 @@ export function NodeDetail({ name }: Props) {
             </div>
             <div className="font-mono mt-1">{status.blob_store_root ?? '—'}</div>
           </div>
+
+          <ShutdownPrepPanel name={name} />
         </>
       )}
     </div>

dashboard-v2/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/App.tsx","./src/main.tsx","./src/components/NodeCard.tsx","./src/components/ProjectsPanel.tsx","./src/components/StatTile.tsx","./src/components/StorageBar.tsx","./src/lib/api.ts","./src/pages/CommandCenter.tsx","./src/pages/NodeDetail.tsx","./src/pages/RefTrackingPage.tsx","./src/pages/StorageBrowser.tsx"],"version":"6.0.3"}
+{"root":["./src/App.tsx","./src/main.tsx","./src/components/NodeCard.tsx","./src/components/ProjectsPanel.tsx","./src/components/ShutdownPrepPanel.tsx","./src/components/StatTile.tsx","./src/components/StorageBar.tsx","./src/lib/api.ts","./src/pages/CommandCenter.tsx","./src/pages/NodeDetail.tsx","./src/pages/RefTrackingPage.tsx","./src/pages/StorageBrowser.tsx"],"version":"6.0.3"}

deploy/scripts/safe-shutdown-prep.sh

@@ -211,8 +211,8 @@ step "flushing filesystem buffers"
 sync
 ok "sync complete"
 
-POOL=$(mount | awk '/on \/slab / {print $1}')
-if [ -n "$POOL" ]; then
+POOL=$(df --output=source /slab 2>/dev/null | tail -1 | tr -d '[:space:]')
+if [ -n "$POOL" ] && [ "$POOL" != "none" ]; then
   step "zpool health check ($POOL)"
   zpool status -x "$POOL" 2>&1 | sed 's/^/  /'
   if [ "$EXPORT_ZPOOL" -eq 1 ]; then