@huynle/hub 0.8.4 → 0.8.6

package/packages/cli/src/bootstrap/adapters/opencode/plan.ts

@@ -34,19 +34,46 @@ import {
   type PlanInput,
   type Precondition,
   type VerifiedManifest,
+  toNativePath,
 } from "../../contracts/index.ts"
 import { txFail, txOk, type TxResult } from "../../transaction/result.ts"
 import { sha256Of } from "../../transaction/state.ts"
+import { isWindowsTarget } from "./archive.ts"
 import { inspectOpencodeConfig, pluginSets, pluginSpec, type ConfigInspection, type Finding } from "./config.ts"
 
 /** The Hub plugin is an OpenCode 2 plugin (the @opencode/plugin 2 API): no older OpenCode is ever installed for it. */
 export const MIN_OPENCODE_VERSION = "2.0.0"
 
-/** The stable hubctl authority: the standalone hubctl hub installs (contract install-artifact, user-bin:hubctl). */
+/**
+ * The stable hubctl authority: the standalone hubctl hub installs (contract install-artifact, user-bin:hubctl;
+ * user-bin:hubctl.exe on Windows, authorityFor).
+ */
 export const DEFAULT_AUTHORITY: PathRef = { root: "user-bin", rel: "hubctl" }
 /** Authorities the MCP server may run: hubctl or its hub alias (one command surface), in a bin root. */
 const AUTHORITY_ROOTS = new Set<PathRef["root"]>(["user-bin", "system-bin"])
-const AUTHORITY_NAMES = new Set(["hubctl", "hub"])
+const AUTHORITY_NAMES = new Set(["hubctl", "hub", "hubctl.exe"])
+
+/**
+ * The authority the MCP server runs on `target`. POSIX: as given (hubctl or hub; a Windows name is refused).
+ * Windows (PHASE2-CONTRACT.md): hubctl.exe itself, for `hubctl` or `hubctl.exe`. The hub alias is a cmd shim there
+ * (`user-bin:hub.cmd`), and a .cmd file is no program OpenCode can start without a shell, so it is refused.
+ */
+export function authorityFor(ref: PathRef, target: string): TxResult<PathRef> {
+  if (isWindowsTarget(target)) {
+    if (ref.rel === "hubctl" || ref.rel === "hubctl.exe") return txOk({ root: ref.root, rel: "hubctl.exe" })
+    return txFail("invalid", `on Windows the MCP server runs hubctl.exe itself, not ${ref.root}:${ref.rel} (the hub alias is a cmd shim, which OpenCode cannot start without a shell)`)
+  }
+  if (ref.rel.endsWith(".exe")) return txFail("invalid", `${ref.root}:${ref.rel} is a Windows name; on ${target} the MCP server runs ${ref.rel.slice(0, -4)}`)
+  return txOk(ref)
+}
+
+/**
+ * The MCP command as OpenCode's config holds it: on Windows the native path (C:\Users\…\hubctl.exe, toNativePath).
+ * Windows' CreateProcess accepts C:/… as well, but the native form is what OpenCode's own Windows docs and users write,
+ * what cmd.exe accepts should anything ever pass it through a shell (`/` starts a switch there), and what a user
+ * reading the config recognises. Comparisons accept either form (config.ts samePath). Elsewhere: as is.
+ */
+export const mcpCommandPath = (canonical: string, target: string): string => toNativePath(canonical, isWindowsTarget(target) ? "win32" : "posix")
 
 /** The config files OpenCode reads from its global config dir, in the order hubctl prefers to edit them. */
 export const CONFIG_REFS: readonly { readonly ref: PathRef; readonly format: ConfigFormat }[] = [
@@ -172,8 +199,9 @@ function readConfigs(snapshot: DiscoverySnapshot, options: OpencodePlanOptions,
 }
 
 function planConfig(snapshot: DiscoverySnapshot, options: OpencodePlanOptions, authorityRef: PathRef, findings: Finding[]): TxResult<Action[]> {
-  const authority = resolvePathRef(authorityRef, snapshot.roots, executionContextOf(snapshot))
-  if (!authority.ok) return txFail("invalid", `this host has no ${authorityRef.root} root for hubctl`)
+  const resolved = resolvePathRef(authorityRef, snapshot.roots, executionContextOf(snapshot))
+  if (!resolved.ok) return txFail("invalid", `this host has no ${authorityRef.root} root for hubctl`)
+  const authority = { value: mcpCommandPath(resolved.value, snapshot.host.target) }
   const views = readConfigs(snapshot, options, authority.value)
   if (!views.ok) return views
   const fresh: ConfigView = { ...NEW_CONFIG, precondition: { exists: false }, inspection: { plugin: { state: "absent" }, mcp: { state: "absent" }, findings: [] } }
@@ -227,12 +255,15 @@ const verifyAction = (): Action => ({
 /** The OpenCode actions for this snapshot and profile, with the findings worth showing; or the refusal. */
 export function planOpencode(input: PlanInput, options: OpencodePlanOptions): TxResult<OpencodePlan> {
   if (!input.profile.harnesses.includes("opencode")) return txOk({ actions: [], findings: [] })
-  const authority = options.authority ?? DEFAULT_AUTHORITY
+  const given = options.authority ?? DEFAULT_AUTHORITY
   try {
-    checkAuthority(authority)
+    checkAuthority(given)
   } catch (error) {
     return txFail("invalid", (error as Error).message)
   }
+  const forTarget = authorityFor(given, input.snapshot.host.target)
+  if (!forTarget.ok) return forTarget
+  const authority = forTarget.value
   const findings: Finding[] = []
   const install = planInstall(input.snapshot, options, findings)
   if (!install.ok) return install

package/packages/cli/src/bootstrap/adapters/opencode/verify.ts

@@ -3,25 +3,29 @@
 //   version-exec     the binary itself (hub's `current` version, else what the PATH entry resolves to; never a
 //                    container shim, which would test another environment) runs `opencode --version` and reports
 //                    OpenCode 2 (and the pinned version, when hub installed it).
-//   provider-auth    `opencode models` answers with at least one provider/model: the user's providers load and
-//                    list models with the user's own, user-local configuration and credentials. It sends no prompt
-//                    (it costs nothing). A stronger probe (a real completion) can be injected.
+//   provider-auth    `opencode models --standalone` answers with at least one provider/model: the user's providers
+//                    load and list models with the user's own, user-local configuration and credentials. It sends no
+//                    prompt (it costs nothing). --standalone runs a private server inside the probe, so it tests
+//                    exactly this binary and starts no background service (`opencode serve --service`) that would
+//                    outlive the probe: on Windows that service kept the hub-installed version directory busy, so a
+//                    rollback could not remove it. A stronger probe (a real completion) can be injected.
 //   spoke-connected  the hub sees this machine's OpenCode spoke (an injected client: the integrator asks the hub with
 //                    the machine credential; without one this probe fails, so the harness is never ready by default).
 //
 // Every process is a fixed argv of the harness binary (OPENCODE_PROBE_ARGV) run through an injected ProcessRunner:
-// no shell, no command from a plan, an absolute file, bounded time and output. Probe details are built here (a
-// version, counts, an exit status), never the harness's raw output, and anything credential-shaped is withheld.
-import { execFile } from "node:child_process"
-import { compareVersions, executionContextOf, isSecretValue, REQUIRED_PROBES, rootPathIn, SEMVER, type AdapterContext, type HarnessVerification, type Probe } from "../../contracts/index.ts"
+// no shell, no command from a plan, an absolute file, bounded time and output, and no process outliving the probe.
+// Probe details are built here (a version, counts, an exit status), never the harness's raw output, and anything
+// credential-shaped is withheld.
+import { compareVersions, executionContextOf, isAbsolutePath, isSecretValue, REQUIRED_PROBES, rootPathIn, SEMVER, toNativePath, type AdapterContext, type HarnessVerification, type Probe } from "../../contracts/index.ts"
 import { discover } from "../../discovery/discover.ts"
 import type { DiscoveryProbe } from "../../discovery/probe.ts"
 import { txFail, txOk, type TxResult } from "../../transaction/result.ts"
-import { OPENCODE_BINARY_REL } from "./archive.ts"
+import { runBounded, type BoundedOptions } from "../process-tree.ts"
+import { opencodeBinaryRel } from "./archive.ts"
 import { MIN_OPENCODE_VERSION } from "./plan.ts"
 
 /** The only argv the adapter ever runs (after the absolute binary path). */
-export const OPENCODE_PROBE_ARGV = Object.freeze({ version: Object.freeze(["--version"]), models: Object.freeze(["models"]) }) as {
+export const OPENCODE_PROBE_ARGV = Object.freeze({ version: Object.freeze(["--version"]), models: Object.freeze(["models", "--standalone"]) }) as {
   readonly version: readonly string[]
   readonly models: readonly string[]
 }
@@ -51,26 +55,39 @@ export interface ProcessRunner {
   run(request: ProcessRequest): Promise<ProcessOutcome>
 }
 
-/** child_process.execFile with shell: false, bounded output and time; stdin closed. */
-export const nodeProcessRunner: ProcessRunner = {
-  run: (request) =>
-    new Promise((resolve, reject) => {
-      if (!request.file.startsWith("/")) return reject(new Error("the harness binary must be an absolute path"))
-      const env = Object.fromEntries(Object.entries(request.env).filter((e): e is [string, string] => typeof e[1] === "string"))
-      const child = execFile(
-        request.file,
-        [...request.argv],
-        { shell: false, env, timeout: request.timeoutMs, maxBuffer: request.maxOutputBytes, encoding: "utf8", windowsHide: true, ...(request.signal ? { signal: request.signal } : {}) },
-        (error, stdout, stderr) => {
-          const e = error as (NodeJS.ErrnoException & { killed?: boolean; code?: number | string }) | null
-          if (e && typeof e.code === "string" && e.code !== "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") return reject(e)
-          resolve({ exitCode: e ? (typeof e.code === "number" ? e.code : null) : 0, stdout: String(stdout ?? ""), stderr: String(stderr ?? ""), timedOut: Boolean(e?.killed) })
+/**
+ * The bounded runner (process-tree.ts) with shell: false, bounded output and time, stdin closed. Nothing the probe
+ * starts outlives it: a timeout, an abort or an overflow ends its whole tree, and what it left running when it exited
+ * is ended too (POSIX process group; win32 taskkill /T). `tree` and `spawn` are injectable for tests.
+ */
+export function processRunner(options: BoundedOptions = {}): ProcessRunner {
+  return {
+    run: async (request) => {
+      // A canonical absolute path (POSIX, or C:/… on Windows), handed to the OS in its native form.
+      if (!isAbsolutePath(request.file)) throw new Error("the harness binary must be an absolute path")
+      const r = await runBounded(
+        {
+          file: toNativePath(request.file, process.platform),
+          args: request.argv,
+          env: request.env,
+          timeoutMs: request.timeoutMs,
+          maxOutputBytes: request.maxOutputBytes,
+          stderr: true,
+          overflow: "kill",
+          ...(request.signal ? { signal: request.signal } : {}),
         },
+        options,
       )
-      child.stdin?.end()
-    }),
+      if (r.spawnError) throw r.spawnError
+      if (r.aborted) throw Object.assign(new Error("the probe was cancelled"), { name: "AbortError", code: "ABORT_ERR" })
+      return { exitCode: r.exitCode, stdout: r.stdout, stderr: r.stderr, timedOut: r.timedOut }
+    },
+  }
 }
 
+/** The CLI's runner: processRunner with the platform's process tree. */
+export const nodeProcessRunner: ProcessRunner = processRunner()
+
 /** A provider probe beyond the default model listing (e.g. a real, tiny completion), injected by the integrator. */
 export type ProviderProbe = (input: { readonly binary: string; readonly context: AdapterContext; readonly runner: ProcessRunner }) => Promise<{ readonly ok: boolean; readonly detail?: string }>
 
@@ -196,7 +213,7 @@ export function locateOpencodeBinary(probe: DiscoveryProbe): TxResult<string> {
   const data = snap.value.roots.find((r) => r.id === "data")
   const base = data ? rootPathIn(data, executionContextOf(snap.value)) : undefined
   if (base) {
-    const current = probe.realpath(`${base}/hub/harnesses/opencode/current/${OPENCODE_BINARY_REL}`)
+    const current = probe.realpath(`${base}/hub/harnesses/opencode/current/${opencodeBinaryRel(snap.value.host.target)}`)
     if (current && probe.executable(current)) return txOk(current)
   }
   const presence = snap.value.harnesses.find((h) => h.id === "opencode")
@@ -206,3 +223,9 @@ export function locateOpencodeBinary(probe: DiscoveryProbe): TxResult<string> {
   const target = shim?.resolvesTo ?? presence.path
   return probe.executable(target) ? txOk(target) : txFail("not_found", `${target} is not an executable on this host`)
 }
+
+/** The version directory of a hub-managed binary (data:hub/harnesses/opencode/<version>/bin/opencode[.exe]). */
+const HUB_VERSION = /\/hub\/harnesses\/opencode\/([^/]+)\/bin\/opencode(?:\.exe)?$/
+
+/** The version hub installed `binary` as, when it is a hub-managed OpenCode; else undefined. */
+export const hubManagedVersion = (binary: string): string | undefined => HUB_VERSION.exec(binary)?.[1]

package/packages/cli/src/bootstrap/adapters/process-tree.ts

@@ -0,0 +1,263 @@
+// Probe processes never outlive their probe (Phase 2 Windows end-to-end run). A harness CLI may start helpers or a
+// background service: OpenCode 2's `opencode models` starts `opencode serve --service`, which then keeps the
+// hub-installed version directory busy (Windows refuses to delete a running exe) and its database open. So:
+//
+//   - on a timeout, an abort or (overflow: "kill") too much output, the probe's whole tree is ended;
+//   - after the probe exits by itself, what it left behind is ended too.
+//
+// POSIX: the probe leads its own process group (spawn detached), so kill(-pid, SIGKILL) reaches every process that
+// stayed in the group (a daemon that called setsid escapes it; probes are run so that none is started). win32 has no
+// process groups: `taskkill.exe /T /F /PID <pid>` from System32 ends a live tree, and after an exit the processes
+// whose parent was the probe and that started since it began (a fixed PowerShell CIM query; a reused PID's older
+// process is spared) have their trees ended. Every helper runs with a fixed argv, no shell, and never throws.
+import { execFile, spawn as nodeSpawn } from "node:child_process"
+
+export interface ProcessTree {
+  /** Spawn option: POSIX probes lead their own process group so the whole group can be signalled. */
+  readonly detached: boolean
+  /** Ends `pid` and everything it started (a timeout, an abort). Never throws. */
+  killTree(pid: number): Promise<void>
+  /** After `pid` exited by itself (it started at `startedAt`, ms): ends what it left running. Never throws. */
+  reap(pid: number, startedAt: number): Promise<void>
+}
+
+export interface ProcessTreeDeps {
+  readonly platform?: NodeJS.Platform
+  /** process.kill */
+  readonly kill?: (pid: number, signal: NodeJS.Signals) => void
+  /** Runs a fixed argv without a shell (win32 tools). */
+  readonly exec?: (file: string, args: readonly string[]) => Promise<{ readonly code: number | null; readonly stdout: string }>
+  /** %SystemRoot% (default from the environment, else C:\Windows). */
+  readonly systemRoot?: string
+}
+
+const TOOL_TIMEOUT_MS = 15_000
+/** Clock slack for the "started since the probe began" cut-off. */
+const START_SLACK_MS = 2000
+/** Milliseconds between 1601-01-01 (FILETIME) and 1970-01-01. */
+const FILETIME_EPOCH_MS = 11_644_473_600_000n
+
+const defaultExec = (file: string, args: readonly string[]) =>
+  new Promise<{ code: number | null; stdout: string }>((resolve) => {
+    execFile(file, [...args], { shell: false, windowsHide: true, timeout: TOOL_TIMEOUT_MS, encoding: "utf8", maxBuffer: 1 << 20 }, (error, stdout) => {
+      const code = (error as { code?: unknown } | null)?.code
+      resolve({ code: error ? (typeof code === "number" ? code : null) : 0, stdout: String(stdout ?? "") })
+    })
+  })
+
+/** A drive-rooted SystemRoot without characters that could matter to anything; else C:\Windows. */
+function systemRootOf(value: string | undefined): string {
+  const v = value?.replace(/\\+$/, "")
+  return v && /^[A-Za-z]:\\[A-Za-z0-9 ._\\()-]*$/.test(v) ? v : "C:\\Windows"
+}
+
+export function processTree(deps: ProcessTreeDeps = {}): ProcessTree {
+  const platform = deps.platform ?? process.platform
+  if (platform === "win32") {
+    const exec = deps.exec ?? defaultExec
+    const root = systemRootOf(deps.systemRoot ?? process.env.SystemRoot ?? process.env.SYSTEMROOT)
+    const taskkill = `${root}\\System32\\taskkill.exe`
+    const powershell = `${root}\\System32\\WindowsPowerShell\\v1.0\\powershell.exe`
+    const killTree = async (pid: number) => {
+      if (!Number.isInteger(pid) || pid <= 0) return
+      try {
+        await exec(taskkill, ["/T", "/F", "/PID", String(pid)])
+      } catch {}
+    }
+    return {
+      detached: false,
+      killTree,
+      async reap(pid, startedAt) {
+        if (!Number.isInteger(pid) || pid <= 0) return
+        const since = (BigInt(Math.max(0, Math.floor(startedAt) - START_SLACK_MS)) + FILETIME_EPOCH_MS) * 10_000n
+        const script =
+          `$t=[DateTime]::FromFileTimeUtc(${since}); ` +
+          `Get-CimInstance -ClassName Win32_Process -Filter 'ParentProcessId=${pid}' | ` +
+          `Where-Object { $_.CreationDate.ToUniversalTime() -ge $t } | ForEach-Object { $_.ProcessId }`
+        let stdout = ""
+        try {
+          stdout = (await exec(powershell, ["-NoProfile", "-NonInteractive", "-Command", script])).stdout
+        } catch {
+          return
+        }
+        for (const line of stdout.split(/\r?\n/)) {
+          const child = line.trim()
+          if (/^[1-9]\d*$/.test(child)) await killTree(Number(child))
+        }
+      },
+    }
+  }
+  const kill = deps.kill ?? ((pid: number, signal: NodeJS.Signals) => void process.kill(pid, signal))
+  const group = (pid: number): boolean => {
+    try {
+      kill(-pid, "SIGKILL")
+      return true
+    } catch {
+      return false
+    }
+  }
+  return {
+    detached: true,
+    async killTree(pid) {
+      if (!Number.isInteger(pid) || pid <= 0) return
+      if (group(pid)) return
+      try {
+        kill(pid, "SIGKILL")
+      } catch {}
+    },
+    async reap(pid) {
+      if (Number.isInteger(pid) && pid > 0) group(pid)
+    },
+  }
+}
+
+export interface BoundedRequest {
+  /** The native path of the program (no shell; the argv as is). */
+  readonly file: string
+  readonly args: readonly string[]
+  readonly env: Readonly<Record<string, string | undefined>>
+  readonly timeoutMs: number
+  readonly maxOutputBytes: number
+  readonly signal?: AbortSignal
+  /** Read stderr too (bounded the same way); default: dropped. */
+  readonly stderr?: boolean
+  /** Output past maxOutputBytes: end the tree (default), or keep the first bytes and let it run. */
+  readonly overflow?: "kill" | "truncate"
+}
+
+export interface BoundedResult {
+  /** null when it was ended (timeout, abort, overflow, signal) or never started. */
+  readonly exitCode: number | null
+  readonly stdout: string
+  readonly stderr: string
+  readonly timedOut: boolean
+  readonly aborted: boolean
+  readonly overflowed: boolean
+  /** The program could not be started (ENOENT, EACCES, …). */
+  readonly spawnError?: NodeJS.ErrnoException
+}
+
+export interface BoundedOptions {
+  readonly spawn?: typeof nodeSpawn
+  readonly tree?: ProcessTree
+  readonly now?: () => number
+}
+
+/** How long, after the exit and the reap, the output may take to end before it is cut. */
+const DRAIN_GRACE_MS = 1000
+
+/** Runs one argv (no shell, stdin closed) with bounded time and output; its tree never outlives it. */
+export function runBounded(request: BoundedRequest, options: BoundedOptions = {}): Promise<BoundedResult> {
+  const tree = options.tree ?? processTree()
+  const spawn = options.spawn ?? nodeSpawn
+  const now = options.now ?? Date.now
+  const env = Object.fromEntries(Object.entries(request.env).filter((e): e is [string, string] => typeof e[1] === "string"))
+  return new Promise<BoundedResult>((resolve) => {
+    let timedOut = false
+    let aborted = false
+    let overflowed = false
+    let ended = false
+    const out: Buffer[] = []
+    const err: Buffer[] = []
+    const size = { out: 0, err: 0 }
+    const result = (exitCode: number | null, spawnError?: NodeJS.ErrnoException): BoundedResult => ({
+      exitCode,
+      stdout: Buffer.concat(out).toString("utf8"),
+      stderr: Buffer.concat(err).toString("utf8"),
+      timedOut,
+      aborted,
+      overflowed,
+      ...(spawnError ? { spawnError } : {}),
+    })
+    if (request.signal?.aborted) {
+      aborted = true
+      return resolve(result(null))
+    }
+    const startedAt = now()
+    let child: ReturnType<typeof nodeSpawn>
+    try {
+      child = spawn(request.file, [...request.args], {
+        shell: false,
+        env,
+        stdio: ["ignore", "pipe", request.stderr ? "pipe" : "ignore"],
+        windowsHide: true,
+        detached: tree.detached,
+      })
+    } catch (error) {
+      return resolve(result(null, error as NodeJS.ErrnoException))
+    }
+    let settled = false
+    let exited = false
+    const pid = child.pid
+    const end = () => {
+      if (ended || pid === undefined) return
+      ended = true
+      void tree.killTree(pid)
+    }
+    const timer = setTimeout(() => {
+      timedOut = true
+      end()
+    }, request.timeoutMs)
+    const onAbort = () => {
+      aborted = true
+      end()
+    }
+    request.signal?.addEventListener("abort", onAbort, { once: true })
+    const finish = (r: BoundedResult) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      request.signal?.removeEventListener("abort", onAbort)
+      resolve(r)
+    }
+    const collect = (into: Buffer[], key: "out" | "err") => (chunk: Buffer) => {
+      const room = request.maxOutputBytes - size[key]
+      if (chunk.length > room) {
+        overflowed = true
+        if (room > 0) into.push(chunk.subarray(0, room))
+        size[key] = request.maxOutputBytes
+        if ((request.overflow ?? "kill") === "kill") end()
+        return
+      }
+      into.push(chunk)
+      size[key] += chunk.length
+    }
+    child.stdout?.on("data", collect(out, "out"))
+    child.stderr?.on("data", collect(err, "err"))
+    const streams = [child.stdout, child.stderr].filter((s): s is NonNullable<typeof s> => Boolean(s))
+    const drained = () =>
+      new Promise<void>((done) => {
+        let open = streams.filter((s) => !s.readableEnded && !s.destroyed).length
+        if (open === 0) return done()
+        const grace = setTimeout(() => {
+          for (const s of streams) s.destroy()
+          done()
+        }, DRAIN_GRACE_MS)
+        for (const s of streams) {
+          if (s.readableEnded || s.destroyed) continue
+          const one = () => {
+            if (--open === 0) {
+              clearTimeout(grace)
+              done()
+            }
+          }
+          s.once("end", one)
+          s.once("close", () => (s.readableEnded ? undefined : one()))
+        }
+      })
+    child.on("error", (error: NodeJS.ErrnoException) => {
+      if (!exited) finish(result(null, error))
+    })
+    child.on("exit", (code) => {
+      if (exited) return
+      exited = true
+      clearTimeout(timer)
+      const exitCode = typeof code === "number" && !ended ? code : null
+      void (async () => {
+        if (pid !== undefined) await tree.reap(pid, startedAt)
+        await drained()
+        finish(result(exitCode))
+      })()
+    })
+  })
+}

package/packages/cli/src/bootstrap/contracts/paths.ts

@@ -67,7 +67,7 @@ export function resolvePathRef(ref: PathRef, roots: readonly RootMapping[], cont
   const root = roots.find((r) => r.id === ref.root)
   const base = root ? rootPathIn(root, context) : undefined
   if (!base || !isAbsolutePath(base)) return fail("/root", "unmapped_root", `this host has no ${ref.root} root`)
-  return ok(base === "/" ? `/${ref.rel}` : `${base}/${ref.rel}`)
+  return ok(joinAbs(base, ref.rel))
 }
 
 export type EntryKind = "file" | "directory" | "symlink" | "missing" | "other"
@@ -80,12 +80,15 @@ export function checkNoSymlinkEscape(rootAbs: string, rel: string, lstat: (path:
   if (!isAbsolutePath(rootAbs)) return fail("", "invalid_path", "the root must be an absolute, normalized path")
   if (!isSafeRel(rel)) return fail("", "invalid_path", "expected a relative path inside the root")
   const parts = rel.split("/")
-  let current = rootAbs === "/" ? "" : rootAbs
+  let current = rootAbs
   for (const part of parts) {
-    current = `${current}/${part}`
+    current = joinAbs(current, part)
     const kind = lstat(current)
     if (kind === "symlink") return fail("", "symlink", `${current} is a symbolic link; refusing to write through it`)
     if (kind === "missing") break
   }
-  return ok(rootAbs === "/" ? `/${rel}` : `${rootAbs}/${rel}`)
+  return ok(joinAbs(rootAbs, rel))
 }
+
+/** `rel` under the canonical absolute `base` ("/" and "C:/" end with a separator already). */
+const joinAbs = (base: string, rel: string) => (base.endsWith("/") ? `${base}${rel}` : `${base}/${rel}`)

package/packages/cli/src/bootstrap/contracts/platform.ts

@@ -3,19 +3,21 @@
 // guess at a nearby target.
 import { fail, ok, type Result } from "./validate.ts"
 
-export type Platform = "darwin" | "linux"
+export type Platform = "darwin" | "linux" | "windows"
 export type Arch = "arm64" | "x64"
 /** "none" on macOS; "unknown" when a Linux host's C library could not be identified. */
 export type Libc = "none" | "glibc" | "musl" | "unknown"
 export type ServiceManager = "launchd" | "systemd-user"
+/** A target's service manager: "none" where hubctl installs no user services yet (Windows until Phase 3). */
+export type TargetServiceManager = ServiceManager | "none"
 
 export interface SupportedTarget {
   readonly target: string
   readonly platform: Platform
   readonly arch: Arch
   readonly libc: Libc
-  /** The per-user service manager services are installed for on this target. */
-  readonly serviceManager: ServiceManager
+  /** The per-user service manager services are installed for on this target; "none": profiles with services are refused. */
+  readonly serviceManager: TargetServiceManager
   /**
    * The `bun build --compile --target` the release builds this target's hubctl with. x64 targets use Bun's
    * `-baseline` runtime: the default x64 runtime needs AVX2 and dies with SIGILL (exit 132) on CPUs without it,
@@ -29,6 +31,9 @@ export const SUPPORTED_TARGETS: readonly SupportedTarget[] = Object.freeze([
   { target: "darwin-x64", platform: "darwin", arch: "x64", libc: "none", serviceManager: "launchd", bunTarget: "bun-darwin-x64-baseline" },
   { target: "linux-x64", platform: "linux", arch: "x64", libc: "glibc", serviceManager: "systemd-user", bunTarget: "bun-linux-x64-baseline" },
   { target: "linux-arm64", platform: "linux", arch: "arm64", libc: "glibc", serviceManager: "systemd-user", bunTarget: "bun-linux-arm64" },
+  // Phase 2 (docs/plans/2026-11-05-machine-setup-installer-design.md §3): the session-only profile; user services
+  // (Task Scheduler) arrive in Phase 3.
+  { target: "windows-x64", platform: "windows", arch: "x64", libc: "none", serviceManager: "none", bunTarget: "bun-windows-x64-baseline" },
 ] as const)
 
 export interface UnsupportedTarget {
@@ -37,8 +42,7 @@ export interface UnsupportedTarget {
 }
 
 export const UNSUPPORTED_TARGETS: readonly UnsupportedTarget[] = Object.freeze([
-  { target: "windows-x64", reason: "Windows bootstrap is out of scope (no launchd/systemd user services, different credential store)" },
-  { target: "windows-arm64", reason: "Windows bootstrap is out of scope (no launchd/systemd user services, different credential store)" },
+  { target: "windows-arm64", reason: "Windows on arm64 has no hubctl build yet (only windows-x64 is built)" },
   { target: "linux-x64-musl", reason: "musl Linux (e.g. Alpine) has no hubctl build yet; the glibc build does not run there" },
   { target: "linux-arm64-musl", reason: "musl Linux (e.g. Alpine) has no hubctl build yet; the glibc build does not run there" },
 ] as const)

package/packages/cli/src/bootstrap/contracts/validate.ts

@@ -132,16 +132,32 @@ export const digest = (c: Checker, path: string, value: unknown): value is strin
 export const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/
 export const semver = (c: Checker, path: string, value: unknown): value is string => text(c, path, value, 64, SEMVER)
 
-/** An absolute, normalized POSIX path: no empty, "." or ".." segments, no trailing slash, no control characters. */
+/**
+ * An absolute, normalized path in canonical form: POSIX ("/a/b") or Windows ("C:/a/b": an upper-case drive letter
+ * and "/" separators). No empty, "." or ".." segments, no trailing slash (except the roots "/" and "C:/"), no
+ * backslashes or control characters. UNC and device paths are not canonical. Native Windows forms ("c:\\x") are
+ * accepted only at the edges (discovery's normalizeAbs) and converted back with toNativePath.
+ */
 export function isAbsolutePath(value: unknown): value is string {
-  if (typeof value !== "string" || !value.startsWith("/") || value.length > 4096 || CONTROL.test(value) || value.includes("\\")) return false
-  if (value === "/") return true
-  return value
+  if (typeof value !== "string" || value.length > 4096 || CONTROL.test(value) || value.includes("\\")) return false
+  const drive = WINDOWS_ROOT.exec(value)
+  const rest = drive ? value.slice(2) : value
+  if (!rest.startsWith("/") || rest.startsWith("//")) return false
+  if (rest === "/") return true
+  return rest
     .slice(1)
     .split("/")
     .every((s) => s !== "" && s !== "." && s !== "..")
 }
 
+const WINDOWS_ROOT = /^[A-Z]:(?=\/)/
+
+/** Whether a canonical absolute path is a Windows one ("C:/…"). */
+export const isWindowsPath = (value: string): boolean => WINDOWS_ROOT.test(value)
+
+/** A canonical path in the form a program on `platform` expects: backslashes for Windows paths on win32. */
+export const toNativePath = (value: string, platform: string): string => (platform === "win32" && isWindowsPath(value) ? value.replace(/\//g, "\\") : value)
+
 export function absPath(c: Checker, path: string, value: unknown): value is string {
   if (isAbsolutePath(value)) return true
   if (value !== undefined) c.add(path, "invalid_path", "expected an absolute, normalized path")

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

@@ -87,10 +87,12 @@ export function discover(probe: DiscoveryProbe, options: DiscoverOptions): Resul
   if (container !== "none") roots = mapContainerRoots(roots, parseMountinfo(decode(probe.readFile("/proc/self/mountinfo", 1024 * 1024))))
 
   const dirs = pathDirs(probe)
-  const extra = probe.platform === "darwin" ? ["/opt/homebrew/bin", "/usr/local/bin"] : ["/usr/local/sbin", "/usr/sbin", "/sbin", "/nix/var/nix/profiles/default/bin"]
+  // Package managers off PATH in their usual places; none on Windows (npm and bun are found on PATH there).
+  const extra = probe.platform === "darwin" ? ["/opt/homebrew/bin", "/usr/local/bin"] : probe.platform === "win32" ? [] : ["/usr/local/sbin", "/usr/sbin", "/sbin", "/nix/var/nix/profiles/default/bin"]
   const managerDirs = [...dirs, ...extra.filter((d) => !dirs.includes(d))]
   const packages: PackageManager[] = PACKAGE_MANAGERS.filter((m) => which(probe, managerDirs, m) !== undefined)
   const runtime: RuntimeInfo[] = probe.runtime && SEMVER.test(probe.runtime.version) && normalizeAbs(probe.runtime.path) ? [{ ...probe.runtime }] : []
+  // Windows has no user service manager hubctl drives yet (PHASE2-CONTRACT.md): "none".
   let service: DiscoverySnapshot["managers"]["service"] = "none"
   if (probe.platform === "darwin" && probe.executable("/bin/launchctl")) service = "launchd"
   if (probe.platform === "linux" && probe.lstat("/run/systemd/system") === "directory" && which(probe, [...dirs, "/usr/bin", "/bin"], "systemctl")) service = "systemd-user"