@huynle/hub 0.8.4 → 0.8.6

package/src/central/install/install.sh

@@ -0,0 +1,266 @@
+#!/bin/sh
+# Hub machine setup for macOS and Linux, served by the hub as GET /install.sh (see CONTRACT.md):
+#
+#   curl -fsSL '<hub>/install.sh?<choices>' | sh
+#
+# Downloads the hubctl release this hub pins, checks its sha256, enrolls this machine with the hub (device code,
+# approved in the console), then runs `hubctl setup preview`, `setup apply` and `setup verify` for the chosen
+# profile. Nothing runs until the last line: a truncated download only defines functions. Every child process reads
+# /dev/null, never the script on stdin. Re-running it is safe: an enrolled machine is not enrolled again, and apply
+# converges.
+
+hub_say() {
+  printf 'hub setup: %s\n' "$*" >&2
+}
+
+# hub_die <exit code> <message...>
+hub_die() {
+  hub_code=$1
+  shift
+  hub_say "$*"
+  exit "$hub_code"
+}
+
+hub_has() {
+  command -v "$1" >/dev/null 2>&1
+}
+
+hub_is_musl() {
+  if ldd --version 2>&1 </dev/null | grep -qi musl; then
+    return 0
+  fi
+  for hub_f in /lib/ld-musl-* /usr/lib/ld-musl-*; do
+    if [ -e "$hub_f" ]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+# Sets HUB_TARGET (darwin-arm64, darwin-x64, linux-x64, linux-arm64) or stops with the reason.
+hub_target() {
+  hub_os=$(uname -s 2>/dev/null || echo unknown)
+  hub_arch=$(uname -m 2>/dev/null || echo unknown)
+  case "$hub_os" in
+    Darwin) hub_os=darwin ;;
+    Linux) hub_os=linux ;;
+    *) hub_die 7 "this system ($hub_os) is not supported: use macOS or Linux (on Windows, use the PowerShell command)" ;;
+  esac
+  case "$hub_arch" in
+    x86_64 | amd64) hub_arch=x64 ;;
+    arm64 | aarch64) hub_arch=arm64 ;;
+    *) hub_die 7 "this processor ($hub_arch) is not supported: hubctl is built for x86_64 and arm64" ;;
+  esac
+  if [ "$hub_os" = linux ]; then
+    if hub_is_musl; then
+      hub_die 7 "this Linux uses musl libc (Alpine?), which hubctl does not support yet: use a glibc distribution"
+    fi
+    if [ -r /proc/version ] && grep -qi microsoft /proc/version && ! grep -qi wsl2 /proc/version; then
+      hub_die 7 "this is WSL 1, which hubctl does not support: convert the distribution to WSL 2 (wsl --set-version <distro> 2)"
+    fi
+  fi
+  HUB_TARGET="$hub_os-$hub_arch"
+}
+
+# hub_fetch <url> <file>: https stays https across redirects.
+hub_fetch() {
+  case "$1" in
+    https://*) hub_tls=1 ;;
+    *) hub_tls=0 ;;
+  esac
+  if hub_has curl; then
+    if [ "$hub_tls" = 1 ]; then
+      curl -fsSL --proto '=https' --proto-redir '=https' -o "$2" "$1" </dev/null
+    else
+      curl -fsSL -o "$2" "$1" </dev/null
+    fi
+  elif hub_has wget; then
+    if [ "$hub_tls" = 1 ]; then
+      wget -q --https-only -O "$2" "$1" </dev/null
+    else
+      wget -q -O "$2" "$1" </dev/null
+    fi
+  else
+    hub_die 1 "needs curl or wget to download hubctl"
+  fi
+}
+
+# hub_sha256 <file>: the lower-case hex digest on stdout.
+hub_sha256() {
+  if hub_has sha256sum; then
+    sha256sum "$1" </dev/null | awk '{print tolower($1)}'
+  elif hub_has shasum; then
+    shasum -a 256 "$1" </dev/null | awk '{print tolower($1)}'
+  else
+    hub_die 1 "needs sha256sum or shasum to check the hubctl download; nothing was run"
+  fi
+}
+
+# hub_json_field <name> <file>: the first string value of "name" (hubctl's --json output is one field per line).
+hub_json_field() {
+  sed -n "s/^[[:space:]]*\"$1\":[[:space:]]*\"\\([^\"]*\\)\".*/\\1/p" "$2" | head -n 1
+}
+
+hub_on_path() {
+  case ":$PATH:" in
+    *":$1:"* | *":$1/:"*) return 0 ;;
+  esac
+  return 1
+}
+
+# hub_run <command...>: runs hubctl with stdin from /dev/null; its exit code in hub_rc (set -e never trips).
+hub_run() {
+  if "$hub_bin" "$@" </dev/null; then
+    hub_rc=0
+  else
+    hub_rc=$?
+  fi
+}
+
+main() {
+  set -eu
+  umask 077
+
+  HUB_URL='{{HUB_URL}}'
+  HUB_VERSION='{{HUB_VERSION}}'
+  RELEASE_BASE='{{RELEASE_BASE}}'
+  PROFILE='{{PROFILE}}'
+  # A leading ~/ is kept literal here and expanded to $HOME before preview.
+  # shellcheck disable=SC2088
+  WORKSPACE_ROOT='{{WORKSPACE_ROOT}}'
+  ACTIVATE='{{ACTIVATE}}'
+  INSECURE_HTTP='{{INSECURE_HTTP}}'
+
+  hub_release=${HUB_INSTALL_RELEASE_BASE:-$RELEASE_BASE}
+  hub_release=${hub_release%/}
+
+  hub_say "setting up this machine for $HUB_URL (hub $HUB_VERSION, profile $PROFILE)"
+  if [ "$INSECURE_HTTP" = 1 ]; then
+    hub_say "warning: $HUB_URL is plain http: this machine's token travels unencrypted on your network"
+  fi
+
+  hub_target
+
+  HUB_TMP=$(mktemp -d 2>/dev/null || mktemp -d -t hub-setup)
+  if [ -z "$HUB_TMP" ] || [ ! -d "$HUB_TMP" ]; then
+    hub_die 1 "cannot create a private temporary directory"
+  fi
+  trap 'rm -rf "$HUB_TMP"' EXIT
+  trap 'exit 130' INT
+  trap 'exit 143' TERM HUP
+
+  # ---------- download and check hubctl ----------
+  hub_asset="hubctl-$HUB_TARGET"
+  hub_bin="$HUB_TMP/hubctl"
+  hub_manifest="$HUB_TMP/hubctl-manifest.json"
+  hub_say "downloading $hub_asset from $hub_release"
+  hub_fetch "$hub_release/HUBCTL_SHA256SUMS" "$HUB_TMP/HUBCTL_SHA256SUMS" || hub_die 1 "could not download $hub_release/HUBCTL_SHA256SUMS"
+  hub_fetch "$hub_release/$hub_asset" "$hub_bin" || hub_die 1 "could not download $hub_release/$hub_asset"
+  hub_fetch "$hub_release/hubctl-manifest.json" "$hub_manifest" || hub_die 1 "could not download $hub_release/hubctl-manifest.json"
+
+  # "<sha256>  <file>" lines (sha256sum or shasum; a leading * marks binary mode); exactly this file's name.
+  hub_expected=$(awk -v f="$hub_asset" '{ n = $2; sub(/^\*/, "", n) } NF == 2 && n == f { print tolower($1); exit }' "$HUB_TMP/HUBCTL_SHA256SUMS")
+  case "$hub_expected" in
+    "") hub_die 11 "HUBCTL_SHA256SUMS has no checksum for $hub_asset; nothing was run" ;;
+    *[!0-9a-f]*) hub_die 11 "HUBCTL_SHA256SUMS has a malformed checksum for $hub_asset; nothing was run" ;;
+  esac
+  if [ "${#hub_expected}" -ne 64 ]; then
+    hub_die 11 "HUBCTL_SHA256SUMS has a malformed checksum for $hub_asset; nothing was run"
+  fi
+  hub_actual=$(hub_sha256 "$hub_bin")
+  if [ "$hub_actual" != "$hub_expected" ]; then
+    hub_die 11 "the sha256 of $hub_asset does not match HUBCTL_SHA256SUMS (got $hub_actual); nothing was run"
+  fi
+  chmod 700 "$hub_bin"
+  hub_say "checksum ok (hubctl checks the release manifest signature itself)"
+
+  # ---------- enrollment ----------
+  # Skipped only when hubctl reports this exact hub; otherwise `machine enroll` decides (it is a no-op for the
+  # same hub and refuses another hub without --reenroll). A credential this hub revoked is replaced.
+  hub_enroll=1
+  hub_reenroll=0
+  hub_run machine status --json >"$HUB_TMP/status.json" 2>"$HUB_TMP/status.err"
+  hub_state=$(hub_json_field state "$HUB_TMP/status.json")
+  hub_server=$(hub_json_field server "$HUB_TMP/status.json")
+  if [ "$hub_server" = "$HUB_URL" ]; then
+    case "$hub_rc:$hub_state" in
+      0:verified | 0:configured | 0:insecure)
+        hub_enroll=0
+        hub_say "this machine is already enrolled with $HUB_URL ($hub_state); not enrolling again"
+        ;;
+      9:revoked)
+        hub_reenroll=1
+        hub_say "$HUB_URL revoked this machine's credential; enrolling it again"
+        ;;
+    esac
+  fi
+  if [ "$hub_enroll" = 1 ]; then
+    set -- machine enroll --server "$HUB_URL"
+    if [ "$INSECURE_HTTP" = 1 ]; then
+      set -- "$@" --allow-insecure-http
+    fi
+    if [ "$hub_reenroll" = 1 ]; then
+      set -- "$@" --reenroll
+    fi
+    hub_say "enrolling: approve the code below in the hub console"
+    hub_run "$@"
+    case "$hub_rc" in
+      0) ;;
+      5) hub_die 5 "the enrollment was denied on the hub; nothing was set up. Run the command again to start over" ;;
+      4) hub_die 4 "the enrollment did not complete (expired, cancelled, or this machine is enrolled with another hub: see above); nothing was set up" ;;
+      *) hub_die "$hub_rc" "enrollment failed (hubctl exit $hub_rc); nothing was set up" ;;
+    esac
+  fi
+
+  # ---------- preview and apply ----------
+  case "$WORKSPACE_ROOT" in
+    \~) WORKSPACE_ROOT=$HOME ;;
+    \~/*) WORKSPACE_ROOT="$HOME/${WORKSPACE_ROOT#\~/}" ;;
+  esac
+  hub_preview="$HUB_TMP/preview.json"
+  set -- setup preview --profile "$PROFILE" --enrollment separate --manifest "$hub_manifest" --out "$hub_preview"
+  if [ -n "$WORKSPACE_ROOT" ]; then
+    set -- "$@" --workspace-root "$WORKSPACE_ROOT"
+  fi
+  if [ "$ACTIVATE" = 1 ]; then
+    set -- "$@" --confirm-activation
+  fi
+  hub_run "$@"
+  if [ "$hub_rc" != 0 ]; then
+    hub_die "$hub_rc" "setup preview failed (hubctl exit $hub_rc); nothing was changed"
+  fi
+  if [ ! -s "$hub_preview" ]; then
+    hub_die 1 "setup preview wrote no preview; nothing was changed"
+  fi
+
+  # Manual edits (a config behind a symlink, a format hubctl cannot edit losslessly) are blockers, and apply
+  # refuses the whole plan while any remains (contracts §3.12, exit 10). The preview above printed them.
+  if grep -Eq '"blockers":[[:space:]]*\[[[:space:]]*$' "$hub_preview"; then
+    hub_die 10 "nothing was applied: make the edits listed above by hand (hubctl does not write those files), then run this command again"
+  fi
+
+  set -- setup apply --preview "$hub_preview" --manifest "$hub_manifest"
+  if [ "$ACTIVATE" = 1 ]; then
+    set -- "$@" --confirm-activation
+  fi
+  hub_run "$@"
+  case "$hub_rc" in
+    0) ;;
+    10) hub_die 10 "setup apply needs edits by hand or found a conflict (see above); resolve them, then run this command again" ;;
+    *) hub_die "$hub_rc" "setup apply failed (hubctl exit $hub_rc); see above" ;;
+  esac
+
+  # ---------- verify ----------
+  hub_run setup verify --profile "$PROFILE"
+  if ! hub_on_path "$HOME/.local/bin"; then
+    hub_say "note: $HOME/.local/bin is not on your PATH; add it (for example in ~/.profile) to run hub and hubctl by name"
+  fi
+  case "$hub_rc" in
+    0) hub_say "done: this machine is set up for $HUB_URL" ;;
+    15) hub_say "set up for $HUB_URL; to finish, do the next steps above (usually: start OpenCode with \`opencode\` and keep it open, so this machine shows online), then check with: hubctl setup verify" ;;
+    *) hub_die "$hub_rc" "setup verify failed (hubctl exit $hub_rc)" ;;
+  esac
+  return 0
+}
+
+main "$@"

package/src/central/install/render.ts

@@ -0,0 +1,146 @@
+// GET /install.sh and /install.ps1 (CONTRACT.md): the query allowlist, the values put into a template, and the
+// rendering. Pure: the route in http.ts passes the hub's public URL, version and HUB_RELEASE_BASE.
+//
+// Every value is checked against UNSAFE before it reaches a template: the templates put them inside single quotes,
+// so none may contain ' " ` $ \ or a line break. A value that does is a server bug and throws (the route answers 500),
+// never a script.
+import { checkServerURL, isLoopbackServer, isPrivateNetworkHost } from "../../../packages/cli/src/bootstrap/enrollment/policy.ts"
+import { INSTALL_TEMPLATES } from "./templates"
+
+export type InstallScript = "sh" | "ps1"
+export type InstallProfile = "session-only" | "launch-node" | "full-harness"
+
+export interface InstallChoices {
+  readonly profile: InstallProfile
+  /** The workspace root for launch-node, else "". */
+  readonly root: string
+  readonly activate: "0" | "1"
+}
+
+export const PLACEHOLDERS = ["HUB_URL", "HUB_VERSION", "RELEASE_BASE", "PROFILE", "WORKSPACE_ROOT", "ACTIVATE", "INSECURE_HTTP"] as const
+export type Placeholder = (typeof PLACEHOLDERS)[number]
+
+const PROFILES: readonly InstallProfile[] = ["session-only", "launch-node", "full-harness"]
+const KEYS = new Set(["profile", "root", "activate"])
+const DEFAULT_ROOT = "~/projects"
+const ROOT = /^(?:\/|~\/)[A-Za-z0-9._/~-]*$/
+const ROOT_MAX = 200
+const SEMVER = /^\d+\.\d+\.\d+$/
+const UNSAFE = /['"`$\\\r\n]/
+const RELEASES = "https://github.com/huynle/hub-releases/releases/download"
+
+type Parsed = { readonly ok: true; readonly choices: InstallChoices } | { readonly ok: false; readonly reason: string }
+
+const refuse = (reason: string): Parsed => ({ ok: false, reason })
+
+function rootProblem(root: string): string | undefined {
+  if (root.length < 1 || root.length > ROOT_MAX) return `root must be 1-${ROOT_MAX} characters`
+  if (!ROOT.test(root)) return "root must start with / or ~/ and use only letters, digits and . _ / ~ -"
+  if (root.includes("//")) return "root must not contain //"
+  if (root.split("/").includes("..")) return "root must not contain a .. segment"
+  return undefined
+}
+
+/** The choices of an install query, or why it is refused (a one-line reason for the 400). */
+export function parseInstallQuery(script: InstallScript, search: URLSearchParams): Parsed {
+  const seen = new Map<string, string>()
+  for (const [key, value] of search) {
+    if (!KEYS.has(key)) return refuse(`unknown query parameter ${JSON.stringify(key.slice(0, 40))} (allowed: profile, root, activate)`)
+    if (seen.has(key)) return refuse(`query parameter ${key} given more than once`)
+    seen.set(key, value)
+  }
+  const profile = seen.get("profile") ?? "session-only"
+  if (!PROFILES.includes(profile as InstallProfile)) return refuse(`profile must be one of ${PROFILES.join(", ")}`)
+  const activate = seen.get("activate") ?? "0"
+  if (activate !== "0" && activate !== "1") return refuse("activate must be 0 or 1")
+  const root = seen.get("root")
+  if (script === "ps1") {
+    if (profile !== "session-only") return refuse("install.ps1 supports only profile=session-only for now")
+    if (root !== undefined) return refuse("install.ps1 takes no root (no launch-node on Windows yet)")
+    if (activate !== "0") return refuse("install.ps1 supports only activate=0 for now")
+  }
+  if (root !== undefined && profile !== "launch-node") return refuse("root is only for profile=launch-node")
+  if (root !== undefined) {
+    const problem = rootProblem(root)
+    if (problem) return refuse(problem)
+  }
+  return { ok: true, choices: { profile: profile as InstallProfile, root: profile === "launch-node" ? (root ?? DEFAULT_ROOT) : "", activate } }
+}
+
+/**
+ * HUB_RELEASE_BASE, normalized (no trailing slash), or undefined when not allowed: https, or plain http on loopback
+ * or a private-network IP address (the enrollment policy's rule, policy.ts); no user info, query, fragment or
+ * whitespace, and none of the characters a template cannot quote.
+ */
+export function checkReleaseBase(value: string): string | undefined {
+  if (UNSAFE.test(value)) return undefined
+  const base = checkServerURL(value, { allowInsecureHTTP: true })
+  return base && !UNSAFE.test(base) ? base : undefined
+}
+
+export interface InstallContext {
+  /** The hub's public URL (config.publicURL). */
+  readonly publicURL: string
+  /** The hub version (as /api/me reports it). */
+  readonly version: string
+  /** HUB_RELEASE_BASE, already checked (checkReleaseBase). */
+  readonly releaseBase?: string
+}
+
+type Values = { readonly ok: true; readonly values: Record<Placeholder, string> } | { readonly ok: false; readonly status: 400 | 503; readonly reason: string }
+
+/** The placeholder values for these choices, or why there is no script (400 plain-http hub, 503 no release). */
+export function installValues(input: InstallContext & { readonly choices: InstallChoices }): Values {
+  const hub = checkServerURL(input.publicURL, { allowInsecureHTTP: true })
+  if (!hub) {
+    return { ok: false, status: 400, reason: "this hub's public URL must be https to install from it (plain http only on loopback or a private-network IP address)" }
+  }
+  const insecure = hub.startsWith("http:") && (isLoopbackServer(hub) || isPrivateNetworkHost(new URL(hub).hostname))
+  const release = input.releaseBase ?? (SEMVER.test(input.version) && input.version !== "0.0.0" ? `${RELEASES}/v${input.version}` : undefined)
+  if (!release) {
+    return { ok: false, status: 503, reason: `this hub (version ${input.version.slice(0, 40)}) has no published release to install; set HUB_RELEASE_BASE on the hub` }
+  }
+  const values: Record<Placeholder, string> = {
+    HUB_URL: hub,
+    HUB_VERSION: input.version,
+    RELEASE_BASE: release,
+    PROFILE: input.choices.profile,
+    WORKSPACE_ROOT: input.choices.root,
+    ACTIVATE: input.choices.activate,
+    INSECURE_HTTP: insecure ? "1" : "0",
+  }
+  assertSafe(values)
+  return { ok: true, values }
+}
+
+function assertSafe(values: Readonly<Record<string, string>>): void {
+  for (const [name, value] of Object.entries(values)) {
+    if (UNSAFE.test(value)) throw new Error(`install script value ${name} contains a character the template cannot quote`)
+  }
+}
+
+/** The template with every {{NAME}} replaced. Throws on an unsafe value, or a placeholder without a value or left over. */
+export function renderTemplate(template: string, values: Readonly<Record<string, string>>): string {
+  assertSafe(values)
+  const out = template.replace(/\{\{([A-Z_]+)\}\}/g, (match, name: string) => {
+    const value = values[name]
+    if (value === undefined) throw new Error(`install template placeholder {{${name}}} has no value`)
+    return value
+  })
+  const left = /\{\{[^}\n]*\}\}/.exec(out)
+  if (left) throw new Error(`install template has a leftover placeholder ${left[0].slice(0, 60)}`)
+  return out
+}
+
+const TEXT_HEADERS = { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store", "x-content-type-options": "nosniff" }
+
+const text = (status: number, body: string): Response => new Response(body, { status, headers: TEXT_HEADERS })
+
+/** The answer to GET /install.sh or /install.ps1: the rendered script, or a 400/503 one-line reason. */
+export function installResponse(script: InstallScript, url: URL, ctx: InstallContext & { readonly template?: string }): Response {
+  const parsed = parseInstallQuery(script, url.searchParams)
+  if (!parsed.ok) return text(400, `${parsed.reason}\n`)
+  const values = installValues({ ...ctx, choices: parsed.choices })
+  if (!values.ok) return text(values.status, `${values.reason}\n`)
+  return text(200, renderTemplate(ctx.template ?? INSTALL_TEMPLATES[script], values.values))
+}

package/src/central/install/templates.ts

@@ -0,0 +1,6 @@
+// The install script templates (CONTRACT.md), imported as text so `bun build --compile` and the npm package carry
+// them. The bodies belong to the scripts workstream; the server only fills their {{…}} placeholders (render.ts).
+import sh from "./install.sh" with { type: "text" }
+import ps1 from "./install.ps1" with { type: "text" }
+
+export const INSTALL_TEMPLATES: { readonly sh: string; readonly ps1: string } = { sh, ps1 }

package/src/central/install/text-assets.d.ts

@@ -0,0 +1,9 @@
+// Install script templates imported `with { type: "text" }` (templates.ts): Bun gives their contents as a string.
+declare module "*.sh" {
+  const text: string
+  export default text
+}
+declare module "*.ps1" {
+  const text: string
+  export default text
+}

package/src/config.ts

@@ -1,5 +1,5 @@
 // Per-machine spoke configuration, shared by every OpenCode process on the machine and edited
-// from the /hub dialog. Holds the machine token, so it is written with mode 0600.
+// from the /hub dialog. Holds the machine token, so it is written with mode 0600 (on Windows: an owner-only ACL).
 import { randomBytes } from "node:crypto"
 import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeSync } from "node:fs"
 import { homedir } from "node:os"
@@ -7,6 +7,7 @@ import path from "node:path"
 import { hubEnv, type Env } from "./env"
 import { APP_DIR, configBase, legacyPaths, migrateFirst } from "./migrate"
 import { isHubURL } from "./protocol"
+import { defaultWinAcl, isWin32, writeOwnerOnlyFile, type SecretFileOptions } from "./win-acl"
 
 export type Mode = "off" | "always" | "session"
 
@@ -169,8 +170,12 @@ export function readRawConfig(file: string): RawConfig | undefined {
   return parsed
 }
 
-/** Writes `content` to `file` atomically (a private temp file in the same directory, fsync, rename), mode 0600. */
-function writePrivate(file: string, content: string): void {
+/**
+ * Writes `content` to `file` atomically (a private temp file in the same directory, fsync, rename), mode 0600. On
+ * Windows the temporary file is restricted to the current user (an ACL) before the content is written (win-acl.ts).
+ */
+function writePrivate(file: string, content: string, options?: SecretFileOptions): void {
+  if (isWin32(options)) return writeOwnerOnlyFile(file, content, options?.acl ?? defaultWinAcl())
   mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 })
   const tmp = `${file}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`
   let fd: number | undefined
@@ -196,22 +201,22 @@ const serialize = (raw: RawConfig) => `${JSON.stringify(raw, null, 2)}\n`
  * returns the next one, written atomically with 0600. Refuses (throws, file untouched) when the file is not a JSON
  * object, so a hand-edited config is never replaced.
  */
-export function updateRawConfig(file: string, update: (raw: RawConfig) => RawConfig): void {
-  writePrivate(file, serialize(update(readRawConfig(file) ?? {})))
+export function updateRawConfig(file: string, update: (raw: RawConfig) => RawConfig, options?: SecretFileOptions): void {
+  writePrivate(file, serialize(update(readRawConfig(file) ?? {})), options)
 }
 
 /**
  * Atomic write with 0600 permissions. Lossless: keys config.json holds that VoiceConfig does not know are kept; the
  * known keys come from `config` (a known key it lacks is removed). A file that is not a JSON object is replaced.
  */
-export function writeConfig(file: string, config: VoiceConfig): void {
+export function writeConfig(file: string, config: VoiceConfig, options?: SecretFileOptions): void {
   let previous: RawConfig = {}
   try {
     previous = readRawConfig(file) ?? {}
   } catch {}
   const next: RawConfig = { ...previous }
   for (const key of CONFIG_KEYS) delete next[key]
-  writePrivate(file, serialize({ ...next, ...config }))
+  writePrivate(file, serialize({ ...next, ...config }), options)
 }
 
 /** Changing the server URL drops the machine credentials, which belong to the old server. */

package/src/spoke/env-inject.ts

@@ -114,13 +114,28 @@ export function stripInheritedHubEnv(env: Env): void {
   for (const name of HUB_VARS) delete env[name]
 }
 
-/** Strips inherited HUB_*, sets the session's identity when it has one, and puts `binDir` first on PATH once. */
-export function applyHubEnv(env: Env, identity: Identity | undefined, binDir: string): void {
+/**
+ * Strips inherited HUB_*, sets the session's identity when it has one, and puts `binDir` first on PATH once. On
+ * win32 the variable is case-insensitive (usually `Path`) and ';'-separated: the one key keeps its name, entries
+ * compare without case, and no second `PATH` key is added (which one a child sees would be undefined).
+ */
+export function applyHubEnv(env: Env, identity: Identity | undefined, binDir: string, platform: string = process.platform): void {
   stripInheritedHubEnv(env)
   if (identity) {
     if (identity.url) env.HUB_URL = identity.url
     env.HUB_SESSION_TOKEN = identity.token
   }
+  if (platform === "win32") {
+    const keys = Object.keys(env).filter((k) => k.toLowerCase() === "path")
+    const key = keys.find((k) => env[k] !== undefined) ?? keys[0] ?? "Path"
+    const value = env[key]
+    for (const k of keys) delete env[k]
+    const same = (dir: string) => dir.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase() === binDir.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase()
+    const root = env.SystemRoot ?? env.SYSTEMROOT ?? "C:\\Windows"
+    const rest = value === undefined ? [`${root}\\System32`, root] : value.split(";").filter((dir) => dir && !same(dir))
+    env[key] = [binDir, ...rest].join(";")
+    return
+  }
   const rest = env.PATH === undefined ? DEFAULT_PATH : env.PATH.split(path.delimiter).filter((dir) => dir !== binDir)
   env.PATH = [binDir, ...rest].join(path.delimiter)
 }

package/src/spoke/herdr.ts

@@ -17,9 +17,10 @@ export const AGENT_START_TIMEOUT_MS = 20_000
 
 const STDERR_MAX = 300
 
-export function herdrRunner(bin = "herdr"): HerdrRunner {
+export function herdrRunner(bin = "herdr", spawn: typeof Bun.spawn = Bun.spawn): HerdrRunner {
   return async (args, timeoutMs) => {
-    const proc = Bun.spawn([bin, ...args], { stdin: "ignore", stdout: "pipe", stderr: "pipe" })
+    // windowsHide: on Windows each poll would otherwise flash a console window (no-op elsewhere).
+    const proc = spawn([bin, ...args], { stdin: "ignore", stdout: "pipe", stderr: "pipe", windowsHide: true })
     const what = `herdr ${args.slice(0, 2).join(" ")}`
     const stdout = collect(proc.stdout)
     const stderr = collect(proc.stderr)