Require an explicit scimesh source in the worker wizard (PyPI name is another project)

coordinator/internal/agent/check.go

@@ -84,7 +84,11 @@ func CheckEnvironment(ctx context.Context) CheckReport {
 	cmd := exec.CommandContext(ctx, python, "-c", "import scimesh; print(scimesh.__version__ if hasattr(scimesh, '__version__') else 'installed')")
 	out, err := cmd.Output()
 	if err != nil {
-		report.Scimesh = CheckItem{Name: "scimesh", OK: false, Detail: "install with: pip install scimesh"}
+		// The worker executes workloads by spawning scimesh's task runner, so
+		// the package is a hard requirement, not an optimisation. The PyPI
+		// name belongs to a different project, so the wizard installs from
+		// SCIMESH_PIP_PACKAGE instead of suggesting a bare pip install.
+		report.Scimesh = CheckItem{Name: "scimesh", OK: false, Detail: "the worker runs workloads through scimesh — install it from your wheel or index (SCIMESH_PIP_PACKAGE)"}
 		return report
 	}
 	report.Scimesh = CheckItem{Name: "scimesh", OK: true, Detail: strings.TrimSpace(string(out))}

coordinator/internal/agent/setupui/server.go

@@ -183,6 +183,7 @@ type Server struct {
 	sup         Supervisor
 	openBrowser func(string)
 	port        int
+	install     func(ctx context.Context, venvPython, pkg string) error
 }
 
 // Options customises the wizard for tests and embedding.
@@ -192,6 +193,9 @@ type Options struct {
 	OpenBrowser func(url string)
 	Supervisor  Supervisor
 	Dir         string // directory for pid/log files; defaults to the config dir
+	// InstallScimesh overrides the pip step of the runtime installer (tests
+	// substitute a fake); nil uses the real pip inside the managed venv.
+	InstallScimesh func(ctx context.Context, venvPython, pkg string) error
 }
 
 func New(log *slog.Logger, opts Options) *Server {
@@ -215,7 +219,11 @@ func New(log *slog.Logger, opts Options) *Server {
 	if port == 0 {
 		port = defaultPort
 	}
-	return &Server{log: log, cfgPath: cfgPath, logPath: filepath.Join(dir, logFileName), dir: dir, sup: sup, openBrowser: open, port: port}
+	install := opts.InstallScimesh
+	if install == nil {
+		install = installScimeshWithPip
+	}
+	return &Server{log: log, cfgPath: cfgPath, logPath: filepath.Join(dir, logFileName), dir: dir, sup: sup, openBrowser: open, port: port, install: install}
 }
 
 // Listen binds the loopback listener and returns it; Serve runs the server on
@@ -234,6 +242,7 @@ func (s *Server) Serve(ctx context.Context, listener net.Listener) error {
 	mux.HandleFunc("GET /api/status", s.handleStatus)
 	mux.HandleFunc("POST /api/config", s.handleSaveConfig)
 	mux.HandleFunc("POST /api/test", s.handleTest)
+	mux.HandleFunc("POST /api/runtime/install", s.handleInstallRuntime)
 	mux.HandleFunc("POST /api/start", s.handleStart)
 	mux.HandleFunc("POST /api/stop", s.handleStop)
 	mux.HandleFunc("GET /api/logs", s.handleLogs)
@@ -412,3 +421,100 @@ func (s *Server) handleLogs(w http.ResponseWriter, r *http.Request) {
 // ErrCanceled mirrors context.Canceled for callers that treat a cancelled
 // wizard as a clean exit.
 var ErrCanceled = errors.New("setup wizard cancelled")
+
+type installRuntimeRequest struct {
+	// ScimeshPackage overrides where the scimesh wheel comes from: a local
+	// wheel/index path or the PyPI name. Defaults to SCIMESH_PIP_PACKAGE, then
+	// to the PyPI name.
+	ScimeshPackage string `json:"scimesh_package"`
+}
+
+type installRuntimeResponse struct {
+	OK        bool   `json:"ok"`
+	Python    string `json:"python,omitempty"` // venv python to use as TASK_RUNNER[0]
+	Installed bool   `json:"installed"`
+}
+
+// handleInstallRuntime creates a managed venv next to the worker config and
+// installs the scimesh package into it, so the machine needs no manual pip
+// step. The venv python path is returned for the wizard to bake into the
+// task runner.
+func (s *Server) handleInstallRuntime(w http.ResponseWriter, r *http.Request) {
+	var req installRuntimeRequest
+	if err := json.NewDecoder(io.LimitReader(r.Body, 1<<20)).Decode(&req); err != nil {
+		writeJSON(w, http.StatusBadRequest, map[string]string{"error": "invalid JSON body"})
+		return
+	}
+	pkg := strings.TrimSpace(req.ScimeshPackage)
+	if pkg == "" {
+		pkg = os.Getenv("SCIMESH_PIP_PACKAGE")
+	}
+	if pkg == "" {
+		// No PyPI default on purpose: the PyPI name "scimesh" belongs to an
+		// unrelated project, so a silent `pip install scimesh` would install
+		// the wrong software.
+		writeJSON(w, http.StatusConflict, map[string]string{
+			"error": "no scimesh source configured: set SCIMESH_PIP_PACKAGE to your wheel, checkout or index, then retry",
+		})
+		return
+	}
+
+	python3, err := exec.LookPath("python3")
+	if err != nil {
+		writeJSON(w, http.StatusConflict, map[string]string{"error": "python3 is not installed on this machine"})
+		return
+	}
+	venvDir := filepath.Join(s.dir, "venv")
+	venvPython := filepath.Join(venvDir, "bin", "python")
+	if _, err := os.Stat(venvPython); err != nil {
+		// Windows layout: Scripts/python.exe.
+		if win := filepath.Join(venvDir, "Scripts", "python.exe"); stat(win) {
+			venvPython = win
+		}
+	}
+	if _, err := os.Stat(venvPython); err != nil {
+		ctx, cancel := context.WithTimeout(r.Context(), 3*time.Minute)
+		defer cancel()
+		cmd := exec.CommandContext(ctx, python3, "-m", "venv", venvDir) //nolint:gosec // G204: python3 from LookPath, venvDir is our own dir
+		if out, err := cmd.CombinedOutput(); err != nil {
+			s.log.Error("create runtime venv", "err", err, "out", truncate(string(out), 500))
+			writeJSON(w, http.StatusConflict, map[string]string{"error": "could not create the python venv"})
+			return
+		}
+	}
+
+	if err := s.install(r.Context(), venvPython, pkg); err != nil {
+		s.log.Error("install scimesh runtime", "err", err)
+		writeJSON(w, http.StatusConflict, map[string]string{
+			"error": "pip install " + pkg + " failed: " + err.Error() +
+				". Set SCIMESH_PIP_PACKAGE to your scimesh wheel or index and retry.",
+		})
+		return
+	}
+	writeJSON(w, http.StatusOK, installRuntimeResponse{OK: true, Python: venvPython, Installed: true})
+}
+
+// installScimeshWithPip installs the package with the venv's own pip,
+// streaming into the agent log so a long build is not silent.
+func installScimeshWithPip(ctx context.Context, venvPython, pkg string) error {
+	pip := filepath.Join(filepath.Dir(venvPython), "pip")
+	if _, err := os.Stat(pip); err != nil {
+		pip += ".exe"
+	}
+	ctx, cancel := context.WithTimeout(ctx, 10*time.Minute)
+	defer cancel()
+	cmd := exec.CommandContext(ctx, pip, "install", pkg) //nolint:gosec // G204: pip from our venv, pkg is operator-set or a fixed default
+	return cmd.Run()
+}
+
+func stat(path string) bool {
+	_, err := os.Stat(path)
+	return err == nil
+}
+
+func truncate(s string, n int) string {
+	if len(s) <= n {
+		return s
+	}
+	return s[:n] + "…"
+}

coordinator/internal/agent/setupui/server_test.go

@@ -3,6 +3,7 @@ package setupui
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"io"
 	"log/slog"
 	"net"
@@ -23,17 +24,23 @@ func testLogger() *slog.Logger {
 }
 
 func newTestServer(t *testing.T, sup Supervisor) (*Server, string) {
+	t.Helper()
+	return newTestServerWithInstall(t, sup, nil)
+}
+
+func newTestServerWithInstall(t *testing.T, sup Supervisor, install func(ctx context.Context, venvPython, pkg string) error) (*Server, string) {
 	t.Helper()
 	dir := t.TempDir()
 	server := New(testLogger(), Options{
 		// A distinct random port per test: Port 0 means "the default 12700" in
 		// the server, which would let the shared http.Client pool reuse a stale
 		// keep-alive connection across tests (EOF after a Shutdown).
-		Port:        freePort(t),
-		ConfigPath:  filepath.Join(dir, "config.json"),
-		Dir:         dir,
-		Supervisor:  sup,
-		OpenBrowser: func(string) {},
+		Port:           freePort(t),
+		ConfigPath:     filepath.Join(dir, "config.json"),
+		Dir:            dir,
+		Supervisor:     sup,
+		OpenBrowser:    func(string) {},
+		InstallScimesh: install,
 	})
 	listener, err := server.Listen()
 	if err != nil {
@@ -291,3 +298,58 @@ func TestConfigFileDefaultsAndEnvOverride(t *testing.T) {
 		t.Errorf("cpu = %d", config.CPUCount)
 	}
 }
+
+func TestInstallRuntimeCreatesVenvAndReportsPython(t *testing.T) {
+	var installedPkg string
+	sup := &fakeSup{}
+	_, base := newTestServerWithInstall(t, sup, func(ctx context.Context, venvPython, pkg string) error {
+		installedPkg = pkg
+		// Prove the venv python path really exists by creating a marker file
+		// where the real venv python would be.
+		_ = os.MkdirAll(filepath.Dir(venvPython), 0o755)
+		_ = os.WriteFile(venvPython, []byte("#!/bin/sh\nexit 0\n"), 0o755)
+		return nil
+	})
+
+	rec, data := postJSON(t, base, "/api/runtime/install", map[string]any{"scimesh_package": "/wheels/scimesh.whl"})
+	if rec.Code != http.StatusOK || data["ok"] != true {
+		t.Fatalf("install: got %d %v, want 200 ok", rec.Code, data)
+	}
+	if installedPkg != "/wheels/scimesh.whl" {
+		t.Errorf("package = %q, want the requested wheel", installedPkg)
+	}
+	if !strings.HasSuffix(data["python"].(string), "venv/bin/python") {
+		t.Errorf("python = %v, want the venv python", data["python"])
+	}
+}
+
+func TestInstallRuntimeRequiresASource(t *testing.T) {
+	sup := &fakeSup{}
+	_, base := newTestServerWithInstall(t, sup, func(ctx context.Context, venvPython, pkg string) error {
+		t.Fatal("install must not run without a package source")
+		return nil
+	})
+	// No source anywhere (SCIMESH_PIP_PACKAGE unset, request empty): 409 with
+	// guidance. The PyPI name is another project, so no silent fallback.
+	rec, data := postJSON(t, base, "/api/runtime/install", map[string]any{})
+	if rec.Code != http.StatusConflict {
+		t.Fatalf("install without source: got %d, want 409", rec.Code)
+	}
+	if !strings.Contains(data["error"].(string), "SCIMESH_PIP_PACKAGE") {
+		t.Errorf("error = %v, want a hint about SCIMESH_PIP_PACKAGE", data["error"])
+	}
+}
+
+func TestInstallRuntimeFailureIsExplained(t *testing.T) {
+	sup := &fakeSup{}
+	_, base := newTestServerWithInstall(t, sup, func(ctx context.Context, venvPython, pkg string) error {
+		return errors.New("no matching distribution found")
+	})
+	rec, data := postJSON(t, base, "/api/runtime/install", map[string]any{"scimesh_package": "/wheels/scimesh.whl"})
+	if rec.Code != http.StatusConflict {
+		t.Fatalf("install failure: got %d, want 409", rec.Code)
+	}
+	if !strings.Contains(data["error"].(string), "SCIMESH_PIP_PACKAGE") {
+		t.Errorf("error = %v, want a hint about SCIMESH_PIP_PACKAGE", data["error"])
+	}
+}

coordinator/internal/agent/setupui/template.html

@@ -183,7 +183,7 @@ code{font-family:var(--mono);font-size:.86em}
 
 <script>
 const $=id=>document.getElementById(id);
-let state={mode:'token',cpu:'auto'};
+let state={mode:'token',cpu:'auto',venvPython:null};
 let checksOk=false;
 
 function err(msg){$('error-box').innerHTML=msg?'<div class="error-strip">'+msg+'</div>':''}
@@ -215,7 +215,7 @@ async function postJSON(path,body){
   return {status:r.status,data};
 }
 function draftConfig(){
-  return {
+  const cfg={
     coordinator_url:$('in-url').value.trim(),
     token:state.mode==='token'?$('in-token').value.trim():'',
     worker_key:state.mode==='key'?$('in-key').value.trim():'',
@@ -224,6 +224,8 @@ function draftConfig(){
     worker_name:$('in-name').value.trim(),
     cpu_count:state.cpu==='custom'?parseInt($('in-cpu').value||'1',10):0
   };
+  if(state.venvPython)cfg.task_runner=[state.venvPython,'-m','scimesh.worker.task'];
+  return cfg;
 }
 
 $('b1').onclick=()=>{

coordinator/internal/transport/http/server.go

@@ -158,6 +158,7 @@ func (s *Server) Handler(token string, uiToken ...string) http.Handler {
 			// Public auth pages — reachable without a session so a user can log in.
 			ui.HandleFunc("GET /ui/login", s.handleUILoginForm)
 			ui.HandleFunc("POST /ui/login", s.handleUILogin)
+			ui.HandleFunc("GET /ui/logout-form", s.handleUILogoutForm)
 			ui.HandleFunc("GET /ui/register", s.handleUIRegisterForm)
 			ui.HandleFunc("POST /ui/register", s.handleUIRegister)
 			ui.HandleFunc("POST /ui/logout", s.handleUILogout)

coordinator/internal/transport/http/templates/login.html

@@ -20,7 +20,10 @@
       <input id="password" name="password" type="password" autocomplete="current-password" required>
       <button class="button" type="submit">Sign in</button>
     </form>
-    {{if .Error}}<p class="error">{{.Error}}</p>{{end}}
+    {{if eq .Error "admin role required"}}
+    <p class="error">The admin console is reserved for the cluster administrator.</p>
+    <p class="alt">You are signed in as a non-admin. <a href="/ui/logout-form">Log out</a>, then sign in with the admin account — its login is printed by <code>coordinator serve</code> on first start and stored in <code>~/.scimesh/admin.password</code>.</p>
+    {{else if .Error}}<p class="error">{{.Error}}</p>{{end}}
     <p class="alt">No account? <a href="/ui/register">Register</a></p>
   </main>
 </body>

coordinator/internal/transport/http/templates/logout-form.html

@@ -0,0 +1,24 @@
+{{define "logout-form.html"}}
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Sign out · SciMesh</title>
+  <style>
+    :root{color:#e5efff;background:#08111f;font:16px/1.5 Inter,ui-sans-serif,system-ui,sans-serif;color-scheme:dark}*{box-sizing:border-box}body{margin:0;min-height:100vh;display:grid;place-items:center;background:radial-gradient(circle at 10% -8%,#183f77 0,transparent 32rem),#08111f}a{color:#94bdff}.card{width:min(92vw,380px);border:1px solid #294662;border-radius:15px;background:#0d1a2cdd;box-shadow:0 20px 45px #00000021;padding:28px}.eyebrow{margin:0 0 4px;color:#7baaff;font-size:.78rem;font-weight:800;letter-spacing:.14em;text-transform:uppercase}h1{margin:0 0 12px;color:#f4f8ff;font-size:1.5rem;letter-spacing:-.03em}p{margin:0 0 18px;color:#9fb3cf;font-size:.92rem}code{color:#cfe0ff}.button{display:block;width:100%;margin-top:4px;border:0;border-radius:10px;padding:12px 16px;background:#ff7d92;color:#230810;font:inherit;font-weight:850;cursor:pointer}.alt{margin:18px 0 0;color:#9fb3cf;font-size:.92rem}
+  </style>
+</head>
+<body>
+  <main class="card">
+    <p class="eyebrow">SciMesh</p>
+    <h1>Sign out</h1>
+    <p>End the current session so you can sign in with a different account (for example the cluster administrator).</p>
+    <form method="post" action="/ui/logout">
+      <button class="button" type="submit">Log out</button>
+    </form>
+    <p class="alt">Changed your mind? <a href="/ui/login">Back to sign in</a></p>
+  </main>
+</body>
+</html>
+{{end}}

coordinator/internal/transport/http/ui_admin.go

@@ -33,7 +33,12 @@ var adminUserActions = map[string]bool{
 func requireAdmin(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if req, ok := authctx.From(r.Context()); !ok || !req.IsAdmin() {
-			http.Redirect(w, r, "/ui/login?error=admin+role+required", http.StatusSeeOther)
+			target := "/ui/login?error=admin+role+required"
+			// Keep the destination so a successful login lands straight back.
+			if strings.HasPrefix(r.URL.Path, "/ui/") {
+				target += "&next=" + url.QueryEscape(r.URL.Path)
+			}
+			http.Redirect(w, r, target, http.StatusSeeOther)
 			return
 		}
 		next.ServeHTTP(w, r)

coordinator/internal/transport/http/ui_admin_internal_test.go

@@ -29,15 +29,15 @@ func TestRequireAdminAllowsAdminOnly(t *testing.T) {
 		t.Error("admin must reach the handler")
 	}
 
-	// Plain user is redirected to the login with the reason.
+	// Plain user is redirected to the login with the reason and the destination.
 	reached = false
 	rec := httptest.NewRecorder()
 	h.ServeHTTP(rec, adminReq(t, "user"))
 	if reached {
 		t.Error("non-admin must not reach the handler")
 	}
-	if rec.Code != http.StatusSeeOther || rec.Header().Get("Location") != "/ui/login?error=admin+role+required" {
-		t.Errorf("non-admin got %d -> %q, want 303 -> login with the admin-required error", rec.Code, rec.Header().Get("Location"))
+	if rec.Code != http.StatusSeeOther || rec.Header().Get("Location") != "/ui/login?error=admin+role+required&next=%2Fui%2Fadmin" {
+		t.Errorf("non-admin got %d -> %q, want 303 -> login with the admin-required error and next", rec.Code, rec.Header().Get("Location"))
 	}
 }
 
@@ -99,3 +99,25 @@ func TestAdminUserActionRejectsBadID(t *testing.T) {
 		t.Errorf("bad id redirect = %q, want an error", rec.Header().Get("Location"))
 	}
 }
+
+func TestLoginPageExplainsAdminRequiredError(t *testing.T) {
+	html := render(t, "login.html", map[string]any{"Error": "admin role required"})
+	if !strings.Contains(html, "/ui/logout-form") {
+		t.Error("the admin-required error must offer a logout path to switch accounts")
+	}
+	if !strings.Contains(html, "cluster administrator") {
+		t.Error("the admin-required error must name the admin account")
+	}
+	// Other errors keep the plain message, no logout teaser.
+	plain := render(t, "login.html", map[string]any{"Error": "invalid email or password"})
+	if strings.Contains(plain, "/ui/logout-form") {
+		t.Error("plain login errors must not advertise logout")
+	}
+}
+
+func TestLogoutFormRendersPostButton(t *testing.T) {
+	html := render(t, "logout-form.html", map[string]any{})
+	if !strings.Contains(html, `action="/ui/logout"`) || !strings.Contains(html, "Log out") {
+		t.Error("logout form must POST /ui/logout")
+	}
+}

coordinator/internal/transport/http/ui_auth.go

@@ -58,6 +58,13 @@ func (s *Server) handleUILoginForm(w http.ResponseWriter, r *http.Request) {
 	s.renderUI(w, "login.html", map[string]any{"Error": r.URL.Query().Get("error"), "Next": r.URL.Query().Get("next")})
 }
 
+// handleUILogoutForm renders a small confirm page for ending the current
+// session. The actual logout stays a POST (/ui/logout); this page exists so a
+// signed-in non-admin who hit an admin-only page can switch accounts.
+func (s *Server) handleUILogoutForm(w http.ResponseWriter, r *http.Request) {
+	s.renderUI(w, "logout-form.html", map[string]any{})
+}
+
 func (s *Server) handleUIRegisterForm(w http.ResponseWriter, r *http.Request) {
 	s.renderUI(w, "register.html", map[string]any{"Error": r.URL.Query().Get("error")})
 }

install.ps1

@@ -97,6 +97,7 @@ if ($Component -eq "coordinator") {
         Write-Host "For a coordinator started with 'coordinator serve', the worker token is"
         Write-Host "in ~\.scimesh\worker.token on that machine. Set SCIMESH_PIP_PACKAGE to"
         Write-Host "install scimesh into a managed venv, or install it yourself:"
-        Write-Host "  pip install scimesh"
+        Write-Host "  set SCIMESH_PIP_PACKAGE=<your wheel or index>"
+        Write-Host "  $Target setup"
     }
 }

install.sh

@@ -112,5 +112,5 @@ else
   echo "For a coordinator started with 'coordinator serve', the worker token is"
   echo "in ~/.scimesh/worker.token on that machine. Set SCIMESH_PIP_PACKAGE to"
   echo "install scimesh into a managed venv, or install it yourself:"
-  echo "  pip install scimesh"
+  echo "  SCIMESH_PIP_PACKAGE=<your wheel or index> worker-agent setup"
 fi

mkdocs/index.md

@@ -113,10 +113,12 @@ chmod +x coordinator
   ```
 
   It spawns `python -m scimesh.worker.task`, so the machine needs Python 3
-  with the `scimesh` package (`pip install scimesh`, or let the managed venv
-  do it via `SCIMESH_PIP_PACKAGE`). For a `coordinator serve` instance, the
-  worker token is in `~/.scimesh/worker.token`. On Windows set
-  `SCIMESH_COMPONENT=worker` for `install.ps1`.
+  with the `scimesh` package. The wizard installs it into its own venv; the
+  package must come from your wheel, checkout or index — point
+  `SCIMESH_PIP_PACKAGE` at it (the PyPI name `scimesh` belongs to an unrelated
+  project). For a `coordinator serve` instance, the worker token is in
+  `~/.scimesh/worker.token`. On Windows set `SCIMESH_COMPONENT=worker` for
+  `install.ps1`.
 - **coordinator** needs no external services at all in its default mode:
   `coordinator serve` embeds SQLite (both databases), the userservice, and
   local workers. The `SCIMESH_DB=postgres` engine remains for cluster