@huynle/hub 0.8.3 → 0.8.5

package/packages/cli/src/bootstrap/discovery/executables.ts

@@ -1,9 +1,11 @@
 // Executables on PATH: where a command is, whether it is a native binary, a wrapper script or a shim into a
 // container (docker/podman exec), what it resolves to, and how (and at which version) a harness was installed,
-// read from the install layout. A harness is never run to find out.
-import { rootPathIn, SEMVER, type ExecutionContext, type HarnessID, type InstallMethod, type RootMapping, type Shim, type ShimKind } from "../contracts/index.ts"
+// read from the install layout. A harness is never run to find out. On Windows (the probe's platform "win32") PATH is
+// split on ";", commands are looked up with their PATHEXT extension (only .com/.exe/.bat/.cmd), "MZ" marks a native
+// binary, and a .cmd/.bat file is a wrapper: npm's shim (into its node_modules) or hubctl's own `@"<target>" %*`.
+import { isWindowsPath, rootPathIn, SEMVER, type ExecutionContext, type HarnessID, type InstallMethod, type RootMapping, type Shim, type ShimKind } from "../contracts/index.ts"
 import type { DiscoveryProbe } from "./probe.ts"
-import { decode, join, normalizeAbs } from "./util.ts"
+import { decode, hostAbs, join, normalizeAbs, underDir, WINDOWS_COMMAND_EXTENSIONS } from "./util.ts"
 
 /** How much of an executable discovery reads to tell a native binary from a script. */
 const HEAD_BYTES = 4096
@@ -16,19 +18,28 @@ export const HARNESS_BINARIES: Readonly<Record<HarnessID, string>> = Object.free
 
 export function pathDirs(probe: DiscoveryProbe): string[] {
   const dirs: string[] = []
-  for (const raw of (probe.env.PATH ?? "").split(":")) {
-    const d = normalizeAbs(raw)
+  for (const raw of (probe.env.PATH ?? "").split(probe.platform === "win32" ? ";" : ":")) {
+    const d = hostAbs(probe.platform, raw)
     if (d && !dirs.includes(d)) dirs.push(d)
     if (dirs.length >= MAX_PATH_DIRS) break
   }
   return dirs
 }
 
+/** The extensions a command is looked up with on Windows: PATHEXT's order (lower-cased), only command extensions. */
+export function commandExtensions(probe: DiscoveryProbe): readonly string[] {
+  const listed = (probe.env.PATHEXT ?? "").split(";").map((e) => e.trim().toLowerCase())
+  const known = listed.filter((e, i): e is (typeof WINDOWS_COMMAND_EXTENSIONS)[number] => (WINDOWS_COMMAND_EXTENSIONS as readonly string[]).includes(e) && listed.indexOf(e) === i)
+  return known.length > 0 ? known : WINDOWS_COMMAND_EXTENSIONS
+}
+
 export function which(probe: DiscoveryProbe, dirs: readonly string[], name: string): string | undefined {
-  for (const d of dirs) {
-    const candidate = join(d, name)
-    if (probe.executable(candidate)) return candidate
-  }
+  const names = probe.platform === "win32" ? commandExtensions(probe).map((e) => `${name}${e}`) : [name]
+  for (const d of dirs)
+    for (const n of names) {
+      const candidate = join(d, n)
+      if (probe.executable(candidate)) return candidate
+    }
   return undefined
 }
 
@@ -68,16 +79,35 @@ const MAGIC = [
   [0xfe, 0xed, 0xfa, 0xce],
   [0xca, 0xfe, 0xba, 0xbe], // Mach-O (thin and universal)
 ]
+/** A Windows PE image ("MZ"); native only for a file on a Windows path. */
+const PE_MAGIC = [0x4d, 0x5a]
+
+/**
+ * What a Windows cmd shim runs: hubctl's own (`@"C:\\…\\opencode.exe" %*`), else npm's last `"%dp0%\\…"` (the
+ * package's bin script, relative to the shim's directory; node.exe is the interpreter, not the target).
+ */
+function cmdShimTarget(script: string, shimPath: string): string | undefined {
+  const own = /^\s*@?"([A-Za-z]:\\[^"%]+)"\s+%\*/m.exec(script)
+  if (own) return normalizeAbs(own[1])
+  const relative = [...script.matchAll(/"%~?dp0%?\\([^"%]+)"/g)].map((m) => m[1]!).filter((rel) => !/^node(?:\.exe)?$/i.test(rel))
+  const rel = relative.at(-1)
+  if (!rel || rel.split(/[\\/]/).includes("..")) return undefined
+  return normalizeAbs(`${shimPath.slice(0, shimPath.lastIndexOf("/"))}/${rel}`)
+}
 
 /** What an executable on PATH is: a native binary, a script wrapper, or a shim into a container. */
 export function classifyExecutable(probe: DiscoveryProbe, name: string, path: string): Shim {
   const isLink = probe.lstat(path) === "symlink"
   const real = isLink ? normalizeAbs(probe.realpath(path)) : undefined
   const head = probe.readFile(path, HEAD_BYTES) ?? new Uint8Array()
-  const native = MAGIC.some((m) => m.every((b, i) => head[i] === b))
+  const windows = isWindowsPath(path)
+  const native = [...MAGIC, ...(windows ? [PE_MAGIC] : [])].some((m) => m.every((b, i) => head[i] === b))
   let kind: ShimKind = native || isLink ? "host" : "unknown"
   let resolvesTo = real && real !== path ? real : undefined
-  if (!native && head[0] === 0x23 && head[1] === 0x21) {
+  if (!native && windows && /\.(?:cmd|bat)$/i.test(path)) {
+    kind = "wrapper"
+    resolvesTo ??= cmdShimTarget(decode(head), path)
+  } else if (!native && head[0] === 0x23 && head[1] === 0x21) {
     const script = decode(head)
     if (CONTAINER_EXEC.test(script)) {
       kind = "container-shim"
@@ -113,21 +143,26 @@ export function installOf(probe: DiscoveryProbe, id: HarnessID, shim: Shim, root
   }
   const data = local("data")
   const home = local("home")
-  const hubLayout = data ? new RegExp(`^${escape(data)}/hub/harnesses/${escape(id)}/([^/]+)(?:/|$)`) : undefined
+  // NTFS names are case-insensitive: so are the Windows layouts.
+  const windows = isWindowsPath(real)
+  const hubLayout = data ? new RegExp(`^${escape(data)}/hub/harnesses/${escape(id)}/([^/]+)(?:/|$)`, windows ? "i" : "") : undefined
   let hub = hubLayout?.exec(real) ?? null
   // v1.1 layout: `current` is a link to the version directory in use; the version is where it leads.
   if (hub?.[1] === "current") hub = hubLayout!.exec(normalizeAbs(probe.realpath(real)) ?? "") ?? null
   if (hub && semver(hub[1])) return { installMethod: "hub", version: hub[1] }
   const brew = /\/(?:Cellar|Caskroom)\/[^/]+\/([^/]+)\//.exec(real)
   if (brew) return { installMethod: "brew", ...(semver(brew[1]) ? { version: brew[1] } : {}) }
-  if (real.includes("/node_modules/")) {
+  if (windows ? /\/node_modules\//i.test(real) : real.includes("/node_modules/")) {
     const version = packageVersion(probe, real)
     return { installMethod: "npm", ...(version ? { version } : {}) }
   }
   const claude = /\/claude\/versions\/([^/]+)$/.exec(real)
   if (id === "claude-code" && claude) return { installMethod: "native", ...(semver(claude[1]) ? { version: claude[1] } : {}) }
-  if (home && id === "opencode" && real.startsWith(`${home}/.opencode/bin/`)) return { installMethod: "native" }
+  if (home && id === "opencode" && underDir(real, `${home}/.opencode/bin`)) return { installMethod: "native" }
   if (/^\/(?:usr\/)?s?bin\//.test(real)) return { installMethod: "package-manager" }
+  // Windows: npm's global dir without a resolvable shim, and Scoop, WinGet and Chocolatey.
+  if (windows && /\/AppData\/Roaming\/npm\/[^/]+$/i.test(real)) return { installMethod: "npm" }
+  if (windows && /\/(?:scoop\/(?:shims|apps)|Microsoft\/WinGet\/(?:Links|Packages)|chocolatey\/(?:bin|lib))\//i.test(real)) return { installMethod: "package-manager" }
   return { installMethod: "unknown" }
 }
 

package/packages/cli/src/bootstrap/discovery/host.ts

@@ -1,17 +1,21 @@
 // Host facts: path roots (and their host location inside a container), C library, OS name and version, and
-// container kind. Everything is read through the probe; nothing is executed.
+// container kind. Everything is read through the probe; nothing is executed. On Windows (PHASE2-CONTRACT.md) the
+// roots are the same XDG-style layout under %USERPROFILE%; only drive-letter values count there (hostAbs), so a Git
+// Bash HOME ("/c/Users/x") is ignored.
 import { ROOT_IDS, type ContainerKind, type Libc, type RootID, type RootMapping } from "../contracts/index.ts"
 import type { DiscoveryProbe } from "./probe.ts"
 import path from "node:path"
 import { resolveHubStateDir } from "../../../../../src/migrate.ts"
-import { decode, join, normalizeAbs, oneLine } from "./util.ts"
+import { decode, hostAbs, join, normalizeAbs, oneLine } from "./util.ts"
 
 // ---------- roots ----------
 
 export function discoverRoots(probe: DiscoveryProbe): RootMapping[] | undefined {
-  const home = normalizeAbs(probe.env.HOME) ?? normalizeAbs(probe.home)
+  const abs = (v: string | undefined) => hostAbs(probe.platform, v)
+  const windows = probe.platform === "win32"
+  const home = abs(probe.env.HOME) ?? (windows ? abs(probe.env.USERPROFILE) : undefined) ?? abs(probe.home)
   if (!home) return undefined
-  const xdg = (key: string, fallback: string) => normalizeAbs(probe.env[key]) ?? join(home, fallback)
+  const xdg = (key: string, fallback: string) => abs(probe.env[key]) ?? join(home, fallback)
   const config = xdg("XDG_CONFIG_HOME", ".config")
   const paths: Partial<Record<RootID, string>> = {
     home,
@@ -19,7 +23,7 @@ export function discoverRoots(probe: DiscoveryProbe): RootMapping[] | undefined
     state: hubStateRoot(probe, home) ?? xdg("XDG_STATE_HOME", ".local/state"),
     data: xdg("XDG_DATA_HOME", ".local/share"),
     "user-bin": join(home, ".local/bin"),
-    "system-bin": "/usr/local/bin",
+    ...(windows ? {} : { "system-bin": "/usr/local/bin" }),
   }
   if (probe.platform === "darwin") paths["launch-agents"] = join(home, "Library/LaunchAgents")
   if (probe.platform === "linux") paths["systemd-user"] = join(config, "systemd/user")
@@ -32,9 +36,12 @@ export function discoverRoots(probe: DiscoveryProbe): RootMapping[] | undefined
  * "hub" (a custom HUB_STATE_DIR): the plan's paths are <state>/hub/….
  */
 function hubStateRoot(probe: DiscoveryProbe, home: string): string | undefined {
-  const env = { ...probe.env, ...(probe.env.XDG_STATE_HOME !== undefined ? { XDG_STATE_HOME: normalizeAbs(probe.env.XDG_STATE_HOME) } : {}) }
+  const env: Record<string, string | undefined> = { ...probe.env }
+  if (probe.env.XDG_STATE_HOME !== undefined) env.XDG_STATE_HOME = hostAbs(probe.platform, probe.env.XDG_STATE_HOME)
+  // A HUB_STATE_DIR this platform cannot use (a POSIX path on Windows) is as if unset.
+  if (probe.platform === "win32" && env.HUB_STATE_DIR !== undefined && !hostAbs(probe.platform, env.HUB_STATE_DIR)) delete env.HUB_STATE_DIR
   const { dir } = resolveHubStateDir(env, home, (p) => probe.lstat(p) !== "missing")
-  const abs = normalizeAbs(dir)
+  const abs = hostAbs(probe.platform, dir)
   return abs && path.posix.basename(abs) === "hub" ? path.posix.dirname(abs) : undefined
 }
 
@@ -72,7 +79,7 @@ export function mapContainerRoots(roots: RootMapping[], mounts: readonly Mount[]
 // ---------- host ----------
 
 export function discoverLibc(probe: DiscoveryProbe): Libc {
-  if (probe.platform === "darwin") return "none"
+  if (probe.platform === "darwin" || probe.platform === "win32") return "none"
   if (probe.platform !== "linux") return "unknown"
   const names = ["/lib", "/lib64", "/usr/lib"].flatMap((d) => probe.readdir(d) ?? [])
   if (names.some((n) => n.startsWith("ld-musl-"))) return "musl"
@@ -91,6 +98,7 @@ export function discoverOS(probe: DiscoveryProbe): { name: string; version: stri
     const value = (key: string) => oneLine(new RegExp(`^${key}=(.*)$`, "m").exec(text)?.[1]?.trim().replace(/^(["'])(.*)\1$/, "$2"))
     return { name: value("NAME") ?? "Linux", version: value("VERSION_ID") ?? "unknown" }
   }
+  if (probe.platform === "win32") return { name: oneLine(probe.osInfo?.name) ?? "Windows", version: oneLine(probe.osInfo?.version) ?? "unknown" }
   return { name: oneLine(probe.platform, 32) ?? "unknown", version: "unknown" }
 }
 

package/packages/cli/src/bootstrap/discovery/node-probe.ts

@@ -1,12 +1,15 @@
 // The real DiscoveryProbe, over node:fs. Every method is a read: lstat/stat, a bounded read of a file opened
 // read-only, readdir, readlink, realpath and an access(X_OK) check. Errors mean "missing" or "unknown", never a
-// throw. The only process it may start is the macOS machine-identity query (`ioreg`, a fixed read-only argv, no
-// shell), and only when no machine ID was injected; Linux reads /etc/machine-id.
+// throw. The only process it may start is the machine-identity query, and only when no machine ID was injected:
+// `ioreg` on macOS, `reg query` of HKLM\SOFTWARE\Microsoft\Cryptography MachineGuid on Windows (both a fixed
+// read-only argv, no shell); Linux reads /etc/machine-id. On Windows, where X_OK means nothing, an executable is a
+// regular file with a command extension, and the OS name and version come from os.version()/os.release().
 import childProcess from "node:child_process"
 import fs from "node:fs"
 import os from "node:os"
 import { programLayout, type EntryKind } from "../contracts/index.ts"
 import type { DiscoveryProbe, RuntimeFact } from "./probe.ts"
+import { isWindowsExecutable, probePath } from "./util.ts"
 
 export interface NodeProbeOptions {
   /** Defaults to process.env (read, never recorded). */
@@ -48,9 +51,37 @@ function osMachineID(): string | undefined {
     const out = attempt(() => childProcess.execFileSync("/usr/sbin/ioreg", ["-rd1", "-c", "IOPlatformExpertDevice"], { encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] }))
     return out ? /"IOPlatformUUID"\s*=\s*"([^"]+)"/.exec(out)?.[1] : undefined
   }
+  if (process.platform === "win32") {
+    const root = /^[A-Za-z]:\\[^"<>|?*]*$/.test(process.env.SystemRoot ?? "") ? process.env.SystemRoot! : "C:\\Windows"
+    const out = attempt(() =>
+      childProcess.execFileSync(`${root.replace(/\\+$/, "")}\\System32\\reg.exe`, ["query", "HKLM\\SOFTWARE\\Microsoft\\Cryptography", "/v", "MachineGuid"], {
+        encoding: "utf8",
+        timeout: 5000,
+        windowsHide: true,
+        stdio: ["ignore", "pipe", "ignore"],
+      }),
+    )
+    return out ? parseMachineGuid(out) : undefined
+  }
   return undefined
 }
 
+/** The MachineGuid value of `reg query HKLM\SOFTWARE\Microsoft\Cryptography /v MachineGuid` output. */
+export const parseMachineGuid = (text: string): string | undefined => /^\s*MachineGuid\s+REG_SZ\s+(\S+)\s*$/m.exec(text)?.[1]
+
+/**
+ * Windows' name and version from os.version() ("Windows 10 Pro") and os.release() ("10.0.26100"). Windows 11 still
+ * calls itself Windows 10 there; build 22000 and later is Windows 11.
+ */
+export function windowsOS(version: string, release: string): { name: string; version: string } {
+  const build = Number(/^10\.0\.(\d+)/.exec(release)?.[1] ?? 0)
+  let name = /^Windows\b[ -~]{0,56}$/.test(version.trim()) ? version.trim() : "Windows"
+  if (build >= 22000) name = name.replace(/^Windows 10\b/, "Windows 11")
+  return { name, version: /^[0-9.]{1,32}$/.test(release) ? release : "unknown" }
+}
+
+export { isWindowsExecutable }
+
 export function createNodeProbe(options: NodeProbeOptions = {}): DiscoveryProbe {
   let machineID: string | undefined | null = options.machineID ?? null
   const runtime = options.runtime === null ? undefined : (options.runtime ?? currentRuntime())
@@ -62,6 +93,7 @@ export function createNodeProbe(options: NodeProbeOptions = {}): DiscoveryProbe
     hostname: os.hostname(),
     env: options.env ?? process.env,
     ...(runtime ? { runtime } : {}),
+    ...(process.platform === "win32" ? { osInfo: windowsOS(attempt(() => os.version()) ?? "", os.release()) } : {}),
     lstat: (p) => attempt(() => kindOf(fs.lstatSync(p))) ?? "missing",
     stat: (p) => attempt(() => kindOf(fs.statSync(p))) ?? "missing",
     readFile(p, limit) {
@@ -86,12 +118,16 @@ export function createNodeProbe(options: NodeProbeOptions = {}): DiscoveryProbe
       }
     },
     readdir: (p) => attempt(() => fs.readdirSync(p).sort()),
-    readlink: (p) => attempt(() => fs.readlinkSync(p)),
-    realpath: (p) => attempt(() => fs.realpathSync(p)),
-    executable: (p) => attempt(() => fs.statSync(p).isFile() && (fs.accessSync(p, fs.constants.X_OK), true)) ?? false,
+    readlink: (p) => probePath(process.platform, attempt(() => fs.readlinkSync(p))),
+    realpath: (p) => probePath(process.platform, attempt(() => fs.realpathSync(p))),
+    executable: (p) =>
+      process.platform === "win32"
+        ? isWindowsExecutable(p) && (attempt(() => fs.statSync(p).isFile()) ?? false)
+        : (attempt(() => fs.statSync(p).isFile() && (fs.accessSync(p, fs.constants.X_OK), true)) ?? false),
     machineID() {
       if (machineID === null) machineID = osMachineID()
       return machineID
     },
   }
 }
+

package/packages/cli/src/bootstrap/discovery/probe.ts

@@ -15,14 +15,18 @@ export interface DiscoveryProbe {
   /** process.platform and process.arch as found (may be unsupported). */
   readonly platform: string
   readonly arch: string
+  /** The POSIX uid; 0 on Windows, which has none (the home directory tells its users apart in the fingerprint). */
   readonly uid: number
   /** The user's home directory (os.homedir()). */
   readonly home: string
   readonly hostname: string
-  /** Read, never recorded: discovery looks at PATH, HOME, XDG_*, HUB_STATE_DIR and `container` only. */
+  /** Read, never recorded: discovery looks at PATH, HOME, XDG_*, HUB_STATE_DIR and `container` only (on Windows also USERPROFILE and
+   * PATHEXT). */
   readonly env: Readonly<Record<string, string | undefined>>
   /** The runtime running this script, when hubctl runs as a script (absent for a standalone binary). */
   readonly runtime?: RuntimeFact
+  /** OS name and version when the OS states them only to the process (Windows: os.version(), os.release()). */
+  readonly osInfo?: { readonly name: string; readonly version: string }
   /** Does not follow a final symlink. */
   lstat(path: string): EntryKind
   /** Follows symlinks. */
@@ -34,8 +38,8 @@ export interface DiscoveryProbe {
   readlink(path: string): string | undefined
   /** The canonical path (every link resolved), or undefined when it does not exist. */
   realpath(path: string): string | undefined
-  /** A regular file (after links) this user may execute. */
+  /** A regular file (after links) this user may execute; on Windows, one with a command extension (.exe, .cmd, …). */
   executable(path: string): boolean
-  /** /etc/machine-id (Linux) or IOPlatformUUID (macOS); never recorded raw. */
+  /** /etc/machine-id (Linux), IOPlatformUUID (macOS) or MachineGuid (Windows); never recorded raw. */
   machineID(): string | undefined
 }

package/packages/cli/src/bootstrap/discovery/util.ts

@@ -1,13 +1,50 @@
 // Small path and text helpers shared by discovery and preview.
-import { isAbsolutePath } from "../contracts/index.ts"
+import { isAbsolutePath, isWindowsPath } from "../contracts/index.ts"
 
-/** A normalized absolute path (duplicate and trailing slashes removed), or undefined. */
+/**
+ * A canonical absolute path (validate.ts isAbsolutePath) from a host's own form, or undefined: duplicate and trailing
+ * separators removed; on Windows forms, backslashes become "/" and the drive letter is upper-cased. UNC (\\\\server)
+ * and device (\\\\?\\, \\\\.\\) paths are refused.
+ */
 export function normalizeAbs(value: string | undefined): string | undefined {
-  if (typeof value !== "string" || !value.startsWith("/")) return undefined
-  const p = value.replace(/\/{2,}/g, "/").replace(/(.)\/+$/, "$1")
+  if (typeof value !== "string") return undefined
+  let p = value
+  if (/^[A-Za-z]:[\\/]/.test(p)) p = p[0]!.toUpperCase() + p.slice(1).replace(/\\/g, "/")
+  else if (!p.startsWith("/") || p.startsWith("//")) return undefined
+  p = p.replace(/\/{2,}/g, "/")
+  if (p.endsWith("/") && p !== "/" && !/^[A-Z]:\/$/.test(p)) p = p.slice(0, -1)
   return isAbsolutePath(p) ? p : undefined
 }
 
-export const join = (dir: string, rel: string) => (dir === "/" ? `/${rel}` : `${dir}/${rel}`)
+/** A link or real path Windows reports (`\\\\?\\C:\\a\\`, `\\??\\c:\\a`, `C:\\a`) as a canonical path; anything else unchanged. */
+export function canonicalWinLink(text: string): string {
+  const stripped = text.replace(/^(\\\\\?\\|\\\?\?\\)/, "")
+  return normalizeAbs(stripped) ?? text
+}
+
+/** A path a probe read from the OS (realpath, readlink), in canonical form on win32; unchanged elsewhere. */
+export const probePath = (platform: string, text: string | undefined): string | undefined => (text !== undefined && platform === "win32" ? canonicalWinLink(text) : text)
+
+export const join = (dir: string, rel: string) => (dir.endsWith("/") ? `${dir}${rel}` : `${dir}/${rel}`)
 export const decode = (bytes: Uint8Array | undefined) => (bytes ? new TextDecoder("utf-8", { fatal: false }).decode(bytes) : "")
 export const oneLine = (v: string | undefined, max = 64) => (v && v.length <= max && !/[\u0000-\u001f\u007f]/.test(v) ? v : undefined)
+
+/**
+ * normalizeAbs for a value read from a host on `platform`: on win32 only a drive-letter path counts (a Git Bash
+ * HOME such as "/c/Users/x", or a POSIX PATH entry, is no path a native Windows program can use).
+ */
+export const hostAbs = (platform: string, value: string | undefined): string | undefined => {
+  const p = normalizeAbs(value)
+  return p && (platform !== "win32" || isWindowsPath(p)) ? p : undefined
+}
+
+/** Path prefix test; Windows paths compare case-insensitively (NTFS names are). */
+export const underDir = (p: string, dir: string): boolean => {
+  const prefix = dir.endsWith("/") ? dir : `${dir}/`
+  return isWindowsPath(p) ? p.toLowerCase().startsWith(prefix.toLowerCase()) : p.startsWith(prefix)
+}
+
+/** The extensions hubctl treats as commands on Windows (PATHEXT may list more, e.g. .JS; those are not run). */
+export const WINDOWS_COMMAND_EXTENSIONS = [".com", ".exe", ".bat", ".cmd"] as const
+
+export const isWindowsExecutable = (path: string): boolean => WINDOWS_COMMAND_EXTENSIONS.some((e) => path.toLowerCase().endsWith(e))

package/packages/cli/src/bootstrap/enrollment/store.ts

@@ -1,12 +1,14 @@
 // The machine credential store: the spoke's config.json (src/config.ts), the one file every spoke and `hub node` on
 // this machine read their identity from. Writes merge into the raw JSON (every key the file holds survives, I4),
 // atomically (private temp file + rename) with mode 0600 in a 0700 directory. A symlinked config.json or config
-// directory is refused: a machine token must never be written into a dotfiles repository (T23).
+// directory is refused: a machine token must never be written into a dotfiles repository (T23). On Windows the file
+// gets an owner-only ACL instead of a mode (src/win-acl.ts), set before the credential is written.
 import { randomBytes } from "node:crypto"
 import { closeSync, lstatSync, mkdirSync, openSync, rmSync } from "node:fs"
 import { hostname } from "node:os"
 import path from "node:path"
 import { configPath, normalize, prepareConfigPath, readRawConfig, updateRawConfig, type Mode } from "../../../../../src/config.ts"
+import { defaultWinAcl, isWin32, nativeWinPath, type SecretFileOptions } from "../../../../../src/win-acl.ts"
 import type { CredentialStore, MachineCredential } from "../contracts/index.ts"
 
 export type CredentialStoreFailure = "symlink" | "not_object" | "invalid" | "io"
@@ -54,9 +56,12 @@ const isLink = (p: string) => {
 
 export class ConfigCredentialStore implements CredentialStore {
   readonly location: string
+  private readonly secrets: SecretFileOptions | undefined
 
-  constructor(file: string) {
+  /** `secrets`: the platform and ACL helper for writes (default: this process's). */
+  constructor(file: string, secrets?: SecretFileOptions) {
     this.location = file
+    this.secrets = secrets
   }
 
   /** The raw config object ({} when there is none); throws a CredentialStoreError when it is not a JSON object. */
@@ -77,7 +82,8 @@ export class ConfigCredentialStore implements CredentialStore {
 
   /**
    * Checks, before a one-time enrollment code is redeemed, that write() can succeed: no symlink, a JSON object (or
-   * no file), and a writable private directory (created 0700 if missing). Leaves no file behind.
+   * no file), and a writable private directory (created 0700 if missing). On Windows, also that a file there can be
+   * restricted to the current user (icacls). Leaves no file behind.
    */
   async preflight(): Promise<void> {
     this.refuseLinks()
@@ -87,6 +93,7 @@ export class ConfigCredentialStore implements CredentialStore {
     try {
       mkdirSync(dir, { recursive: true, mode: 0o700 })
       closeSync(openSync(probe, "wx", 0o600))
+      if (isWin32(this.secrets)) (this.secrets?.acl ?? defaultWinAcl()).restrictToOwner(nativeWinPath(probe))
     } catch (cause) {
       throw ioError(dir, "write to", cause)
     } finally {
@@ -114,7 +121,7 @@ export class ConfigCredentialStore implements CredentialStore {
     this.refuseLinks()
     if ("mode" in this.raw()) return false
     try {
-      updateRawConfig(this.location, (raw) => ("mode" in raw ? raw : { ...raw, mode: DEFAULT_SHARING }))
+      updateRawConfig(this.location, (raw) => ("mode" in raw ? raw : { ...raw, mode: DEFAULT_SHARING }), this.secrets)
     } catch (cause) {
       throw ioError(this.location, "write", cause)
     }
@@ -145,7 +152,7 @@ export class ConfigCredentialStore implements CredentialStore {
         token: credential.token,
         // An enrolled machine shares by default (the /hub dialog asks; hubctl cannot): only when the user never chose.
         ...("mode" in raw ? {} : { mode: DEFAULT_SHARING }),
-      }))
+      }), this.secrets)
     } catch (cause) {
       throw ioError(this.location, "write", cause)
     }
@@ -156,7 +163,7 @@ export class ConfigCredentialStore implements CredentialStore {
     const raw = this.raw()
     if (!("token" in raw) && !("machineID" in raw)) return
     try {
-      updateRawConfig(this.location, ({ token: _token, machineID: _machineID, ...rest }) => rest)
+      updateRawConfig(this.location, ({ token: _token, machineID: _machineID, ...rest }) => rest, this.secrets)
     } catch (cause) {
       throw ioError(this.location, "write", cause)
     }

package/packages/cli/src/bootstrap/preview/plan.ts

@@ -42,6 +42,7 @@ import {
   type Result,
   type SetupPlan,
 } from "../contracts/index.ts"
+import { NO_SERVICES_ON_TARGET } from "../profiles/desired.ts"
 
 /** What a contributor plans from: the adapters' input, and the actions planned before it (adapters first). */
 export type ContributorInput = PlanInput & { readonly planned?: readonly Action[] }
@@ -146,6 +147,8 @@ export function planSetup(
   const profile = prof.value
   const target = checkTarget(snapshot.host.target)
   if (!target.ok || !snapshot.host.supported) return failed(issuesAt("/snapshot/host/target", target.ok ? fail("", "unsupported_platform", "unsupported host") : target))
+  if (profile.services.length > 0 && target.value.serviceManager === "none")
+    return fail("/profile/services", "unsupported_platform", `${profile.id} ${NO_SERVICES_ON_TARGET}`)
   if (profile.services.length > 0 && snapshot.managers.service === "none")
     return fail("/profile/services", "no_service_manager", `the ${profile.id} profile installs services, but this host has no user service manager (launchd or systemd --user)`)
 

package/packages/cli/src/bootstrap/profiles/desired.ts

@@ -1,10 +1,11 @@
 // Profile → desired state: what this host should end up with, as a pure function of (profile, discovery snapshot).
 // It is a description, never a write: the planner turns it into actions, the audit mode only verifies it. Hosts it
-// cannot serve fail explicitly (an unsupported target, services without a user service manager, OpenShell that is
-// absent or was not discovered) instead of being half-configured. OpenShell is verify-only: hubctl never installs
-// or configures it. A harness the user installed some other way stays theirs (owner "user"): hub verifies it and
+// cannot serve fail explicitly (an unsupported target, services on a target without them (windows-x64) or on a host
+// without a user service manager, OpenShell that is absent or was not discovered) instead of being half-configured.
+// OpenShell is verify-only: hubctl never installs or configures it. A harness the user installed some other way stays theirs (owner "user"): hub verifies it and
 // never replaces it.
 import {
+  checkTarget,
   Checker,
   fail,
   REQUIRED_PROBES,
@@ -21,6 +22,9 @@ import {
   type ServiceManagerID,
 } from "../contracts/index.ts"
 
+/** PHASE2-CONTRACT.md: a target without a service manager (windows-x64) runs session-only; preview refuses the rest. */
+export const NO_SERVICES_ON_TARGET = "needs user services, which hubctl does not install on Windows yet"
+
 export interface DesiredHarness {
   readonly id: HarnessID
   readonly presence: "installed" | "missing"
@@ -66,6 +70,9 @@ export function desiredState(profileDoc: unknown, snapshotDoc: unknown): Result<
 
   if (!snapshot.host.supported) return fail("/snapshot/host/target", "unsupported_platform", `cannot set up ${snapshot.host.target}`)
   const manager = snapshot.managers.service
+  const target = checkTarget(snapshot.host.target)
+  if (profile.services.length > 0 && target.ok && target.value.serviceManager === "none")
+    return fail("/profile/services", "unsupported_platform", `${profile.id} ${NO_SERVICES_ON_TARGET}`)
   if (profile.services.length > 0 && manager === "none")
     c.add("/profile/services", "no_service_manager", `${profile.id} runs services, but this host has no user service manager (launchd or systemd --user)`)
   const runtimes = profile.runtimes.map((id, i): DesiredRuntime => {

package/packages/cli/src/bootstrap/release/README.md

@@ -8,10 +8,10 @@ unchanged.
 |---|---|
 | `verify.ts` | The installer's checks on a downloaded hubctl: signature (trust root), exact target, size and digest, downgrade policy. |
 | `manifest.ts` | Builds the manifest body (every supported target, or an explicit `targets` subset; matrix order; harness pins) and signs it (ed25519, detached, over `manifestPayload`). |
-| `pins.ts` | The reviewed harness pin list (`harness-pins.json`): format, validation, re-download check. |
+| `pins.ts` | The reviewed harness pin list (`harness-pins.json`) and the pending, unreviewed one (`harness-pins.pending.json`): format, validation, re-download check. |
 | `trust-root.ts` | The trust root embedded at build time (`--define HUBCTL_TRUST_ROOT=…`), never read at run time. |
 | `assets.ts` | The six service templates of `EMBEDDED_ASSETS`, imported as text so the binary carries them. |
-| `cli.ts` | The release tool behind `bun scripts/hubctl-release.ts build\|manifest\|sign\|verify\|trust-root`. |
+| `cli.ts` | The release tool behind `bun scripts/hubctl-release.ts build\|manifest\|sign\|verify\|trust-root\|dev`. |
 
 Everything except `build` needs only bun and node's built-ins, so the signing job installs no npm packages.
 
@@ -24,11 +24,14 @@ scripts/build-hubctl.sh --require-trust-root   # release build: refuses without
 scripts/build-hubctl.sh linux-x64 --outdir /tmp/out   # binaries and checksums in /tmp/out
 ```
 
-Outputs: `dist/hubctl-<target>` and `dist/HUBCTL_SHA256SUMS` (in `--outdir` instead, when given). x64 targets are
-compiled against Bun's `-baseline` runtime, which needs no AVX2 (older CPUs, QEMU's default `kvm64` model). The supported targets are `darwin-arm64`,
-`darwin-x64`, `linux-x64` and `linux-arm64` (glibc). Windows and musl are refused with their reasons. The
-binary is the whole program: it runs without bun, node or the repository, and a `hub` link to it is the same
-command surface. A build without a trust root cannot verify any release (`shippedTrustRoot` fails closed).
+Outputs: `dist/hubctl-<target>` (`dist/hubctl-windows-x64.exe` for Windows) and `dist/HUBCTL_SHA256SUMS` (in
+`--outdir` instead, when given). x64 targets are compiled against Bun's `-baseline` runtime, which needs no AVX2
+(older CPUs, QEMU's default `kvm64` model). The supported targets are `darwin-arm64`, `darwin-x64`, `linux-x64`,
+`linux-arm64` (glibc) and `windows-x64` (`bun-windows-x64-baseline`, Phase 2: session-only). `windows-arm64` and musl
+are refused with their reasons. The binary is the whole program: it runs without bun, node or the repository, and a
+`hub` link to it is the same command surface (on Windows a `hub.cmd` shim hubctl writes at install). A build without
+a trust root cannot verify any release (`shippedTrustRoot` fails closed). No Authenticode signature yet: SmartScreen
+may warn once; the signed manifest and the checksum protect the download.
 
 ## The harness pin list (`harness-pins.json`)
 
@@ -60,6 +63,13 @@ The list is empty until the harness adapter tasks confirm the upstream sources (
      - `evidence-listed`: `evidence` lists exactly the upstream evidence published for that file (§5 of the
        contracts doc).
 3. CI validates the file (`bootstrap-release-pins.test.ts`).
+   - A pin an author prepared but nobody has reviewed yet lives in `harness-pins.pending.json` (schema
+     `hub.harness-pin-pending`): the same pin, with a `prepared` record (`by`, `on`, `note`) instead of `review`. The
+     release job reads only `harness-pins.json` and `validatePinList` refuses the pending schema, so a pending pin is
+     never signed into a release. Only the dev release (below) includes it. To promote one, the reviewer redoes the
+     checks, moves the entry into `harness-pins.json` with their own `review`, and removes it from the pending file.
+   - Pending today: OpenCode 2.2.0 `windows-x64` (`opencode-windows-x64-baseline.zip`, member `opencode.exe`),
+     prepared 2026-11-05 by an agent. It needs the owner's review.
 4. At release time, the `hubctl-sign` job downloads every pinned file again and refuses to sign on any size or
    digest mismatch. The signature never vouches for a file that nobody fetched during that release.
 
@@ -87,14 +97,16 @@ To rotate the key, publish a version-2 trust root signed by the current key (`ro
 
 The hubctl jobs are added alongside the existing jobs. They run only when `HUBCTL_RELEASE` is `true`.
 
-1. `hubctl` (needs `test`): `scripts/build-hubctl.sh --require-trust-root` cross-compiles all four targets.
+1. `hubctl` (needs `test`): `scripts/build-hubctl.sh --require-trust-root` cross-compiles all five targets.
    Then it smoke-tests `linux-x64` with an empty `PATH` (no bun or node): `--version` must equal the CLI
    version, and `hub --help` must equal `hubctl --help`.
+   `hubctl-windows` (needs `hubctl`, `windows-latest`) runs `hubctl-windows-x64.exe --version` (must equal the CLI
+   version) and `--help` with only `System32` on `PATH`.
 2. `hubctl-sign` (needs `hubctl`, environment `hubctl-release`, no npm install):
    - `manifest` re-downloads the pins and writes the body. `issuedAt` is the tagged commit's time.
    - `sign` signs the body and verifies it against `trust-root.json`. A wrong secret writes nothing.
    - `verify --dist dist` runs the installer's checks on every artifact.
-3. `hubctl-publish` (needs the existing `release` job and `hubctl-sign`): it verifies again, then attaches
+3. `hubctl-publish` (needs the existing `release` job, `hubctl-sign` and `hubctl-windows`): it verifies again, then attaches
    `hubctl-*`, `hubctl-manifest.json` and `HUBCTL_SHA256SUMS` to the GitHub release.
 
 ## Verifying by hand
@@ -113,3 +125,45 @@ The exit code is 0 when the artifact is accepted and 11 when it is rejected: `si
 targets a test or partial release ships. Each listed target must be built and is checked in full; an artifact for
 any other target is refused. `sign` refuses a partial body unless `--targets` names the same list, so a partial
 release is never signed by accident. Without `--targets`, every supported target is required.
+
+## Testing on real machines (a dev release)
+
+`dev` makes a throwaway release that test machines install exactly like a real one, through a hub's
+`HUB_RELEASE_BASE`, without the release key:
+
+```sh
+bun scripts/hubctl-release.ts dev --targets linux-x64,windows-x64 --out /tmp/hubctl-dev
+cd /tmp/hubctl-dev && python3 -m http.server 8000 --bind 0.0.0.0      # or: bunx serve -l 8000 .
+```
+
+Then start the hub with `HUB_RELEASE_BASE=http://<LAN IP of the serving machine>:8000` in its environment. Plain http
+is allowed only on loopback or a private-network address. Its `/install.sh` and `/install.ps1` now download from
+there.
+
+It writes into `--out`:
+
+| File | What |
+|---|---|
+| `hubctl-<target>`, `hubctl-windows-x64.exe` | hubctl for each listed target, built with the dev trust root embedded. |
+| `hubctl-manifest.json` | The manifest (exactly the listed targets), signed with the throwaway key. |
+| `HUBCTL_SHA256SUMS` | As `sha256sum` prints it, for install.sh and install.ps1. |
+| `dev-trust-root.json` | The dev trust root (public key only), for `verify --trust-root`. |
+
+- **The key.** A fresh ed25519 key with key ID `dev-<8 hex>` is generated for each run and held only in memory. The
+  private half is never written, so nothing in the served directory can sign anything. Only the binaries of that run
+  trust it. A release-built hubctl rejects the dev manifest (`signature_invalid`), and a dev hubctl rejects the real
+  one. Rebuild to get a new release.
+- **The pins.** `harness-pins.json` plus `harness-pins.pending.json` (`--pending FILE`, or `--no-pending`). Each
+  pending pin is announced on stderr. Every pinned file is downloaded again and checked, unless you pass
+  `--skip-pin-download`.
+- **Options.** `--release V` (default: the CLI version) and `--minimum-version V` (default `0.0.0`). The release
+  must be newer than what a test machine has installed, or you need `--allow-downgrade` there.
+- **Never shipped.** `dev` refuses to run when `HUB_RELEASE_SIGNING_KEY` is set (the signing job), on GitHub Actions
+  (`GITHUB_ACTIONS=true`), or with `--out` inside the repository's `dist/`, where release builds go.
+
+Check a dev release by hand:
+
+```sh
+bun scripts/hubctl-release.ts verify --manifest /tmp/hubctl-dev/hubctl-manifest.json \
+  --trust-root /tmp/hubctl-dev/dev-trust-root.json --dist /tmp/hubctl-dev --targets linux-x64,windows-x64
+```