@huynle/hub 0.9.0 → 0.9.1

package/packages/node/src/harnesses.ts

@@ -8,6 +8,9 @@
 // - node.json `harnesses` overrides detection either way (true offers a harness, false withholds it).
 //
 // Which binary (claudeBinary, codexBinary): the explicit setting, then the one `hubctl setup` installed, then PATH.
+// On Windows (Phase 3) executables carry an extension: a bare name is tried with PATHEXT's .exe/.com (the ones a
+// program starts without a shell; .cmd/.bat shims are never chosen), PATH splits on `;`, and a regular file counts
+// (no execute bit); hub's Codex is bin/codex.exe.
 import { accessSync, constants, readFileSync, statSync } from "node:fs"
 import { homedir } from "node:os"
 import path from "node:path"
@@ -25,21 +28,35 @@ export interface DetectHarnessesOptions {
   readonly overrides?: Readonly<Record<string, boolean>>
   /** Where hub's config and data are (default os.homedir()). */
   readonly home?: string
+  /** The platform (default this one). */
+  readonly platform?: string
 }
 
-function executable(file: string): boolean {
+function executable(file: string, win32 = false): boolean {
   try {
     if (!statSync(file).isFile()) return false
-    accessSync(file, constants.X_OK)
+    if (!win32) accessSync(file, constants.X_OK)
     return true
   } catch {
     return false
   }
 }
 
+/** Extensions a Windows program can be started with without a shell. */
+const WIN_RUNNABLE = [".exe", ".com"]
+
+/** The names `name` may be on Windows: as it is when it has a runnable extension, else with each, in PATHEXT order. */
+function windowsNames(name: string, env: Env): string[] {
+  if (WIN_RUNNABLE.includes(path.win32.extname(name).toLowerCase())) return [name]
+  const listed = (env.PATHEXT ?? "").split(";").map((e) => e.trim().toLowerCase()).filter((e) => WIN_RUNNABLE.includes(e))
+  const order = listed.length ? [...new Set(listed)] : WIN_RUNNABLE
+  return order.map((ext) => `${name}${ext}`)
+}
+
 /** The executable `name` runs as: an absolute path checked as it is, else the first match on PATH. */
-export function findExecutable(name: string, env: Env): string | undefined {
+export function findExecutable(name: string, env: Env, platform: string = process.platform): string | undefined {
   if (!name) return undefined
+  if (platform === "win32") return findWindowsExecutable(name, env)
   if (path.isAbsolute(name)) return executable(name) ? name : undefined
   if (name.includes("/")) return undefined
   for (const dir of (env.PATH ?? "").split(path.delimiter)) {
@@ -50,13 +67,27 @@ export function findExecutable(name: string, env: Env): string | undefined {
   return undefined
 }
 
+function findWindowsExecutable(name: string, env: Env): string | undefined {
+  if (path.isAbsolute(name) || path.win32.isAbsolute(name)) return windowsNames(name, env).find((file) => executable(file, true))
+  if (/[\\/]/.test(name)) return undefined
+  for (const dir of (env.PATH ?? env.Path ?? "").split(";")) {
+    if (!dir || !(path.isAbsolute(dir) || path.win32.isAbsolute(dir))) continue
+    for (const file of windowsNames(name, env)) {
+      const full = path.join(dir, file)
+      if (executable(full, true)) return full
+    }
+  }
+  return undefined
+}
+
 /** The harnesses this machine's host runtime offers. */
 export function detectHarnesses(options: DetectHarnessesOptions = {}): string[] {
   const env = options.env ?? process.env
   const found = new Set<string>(["opencode"])
   const home = options.home ?? homedir()
-  if (findExecutable(claudeBinary(env, home), env)) found.add("claude-code")
-  if (findExecutable(codexBinary(env, home), env)) found.add("codex")
+  const platform = options.platform ?? process.platform
+  if (findExecutable(claudeBinary(env, home), env, platform)) found.add("claude-code")
+  if (findExecutable(codexBinary(env, home, platform), env, platform)) found.add("codex")
   for (const [name, on] of Object.entries(options.overrides ?? {})) {
     if (on) found.add(name)
     else found.delete(name)
@@ -85,11 +116,25 @@ export function claudeBinary(env: Env, home: string = homedir()): string {
 
 /**
  * The Codex CLI to run: HUB_CODEX_BIN, else the Codex `hubctl setup` installed (data/hub/harnesses/codex/current/
- * bin/codex, under XDG_DATA_HOME or ~/.local/share) when it is there, else `codex` on PATH.
+ * bin/codex, bin/codex.exe on Windows, under XDG_DATA_HOME or ~/.local/share) when it is there, else `codex` on PATH.
  */
-export function codexBinary(env: Env, home: string = homedir()): string {
+export function codexBinary(env: Env, home: string = homedir(), platform: string = process.platform): string {
   if (env.HUB_CODEX_BIN) return env.HUB_CODEX_BIN
   const data = env.XDG_DATA_HOME && path.isAbsolute(env.XDG_DATA_HOME) ? env.XDG_DATA_HOME : path.join(home, ".local", "share")
-  const current = path.join(data, "hub", "harnesses", "codex", "current", "bin", "codex")
-  return executable(current) ? current : "codex"
+  const win32 = platform === "win32"
+  const current = path.join(data, "hub", "harnesses", "codex", "current", "bin", win32 ? "codex.exe" : "codex")
+  return executable(current, win32) ? current : "codex"
+}
+
+/**
+ * The OpenCode CLI (the node starts its background service with it on Windows): HUB_OPENCODE_BIN, else the OpenCode
+ * `hubctl setup` installed (data/hub/harnesses/opencode/current/bin/opencode, opencode.exe on Windows) when it is
+ * there, else `opencode` on PATH.
+ */
+export function opencodeBinary(env: Env, home: string = homedir(), platform: string = process.platform): string {
+  if (env.HUB_OPENCODE_BIN) return env.HUB_OPENCODE_BIN
+  const data = env.XDG_DATA_HOME && path.isAbsolute(env.XDG_DATA_HOME) ? env.XDG_DATA_HOME : path.join(home, ".local", "share")
+  const win32 = platform === "win32"
+  const current = path.join(data, "hub", "harnesses", "opencode", "current", "bin", win32 ? "opencode.exe" : "opencode")
+  return executable(current, win32) ? current : "opencode"
 }

package/packages/node/src/host.ts

@@ -14,8 +14,10 @@
 import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs"
 import path from "node:path"
 import {
+  canonicalNativePath,
   isAbsolutePath,
   isRefName,
+  isWindowsAbsolutePath,
   launchWorkspaceProblem,
   preparedWorkspaceProblem,
   type CleanupPolicy,
@@ -38,41 +40,84 @@ export interface HostRuntimeOptions {
   readonly git?: Omit<GitOptions, "cwd" | "signal">
 }
 
+/**
+ * The file-system calls path resolution needs (tests inject a Windows one). On win32 (Phase 3) realpath reports native
+ * paths (`C:\\…`, `\\\\?\\C:\\…`); they are turned canonical (`C:/…`, protocol canonicalNativePath) and compared without
+ * case, as Windows compares them; a real path off a local drive (a mapped share's UNC path) is refused.
+ */
+export interface PathOps {
+  readonly win32: boolean
+  /** dirname and basename for the platform's paths (path.win32 also reads `/`). */
+  readonly path: Pick<typeof path, "dirname" | "basename">
+  readonly realpath: (p: string) => string
+  readonly isSymlink: (p: string) => boolean
+}
+
+const nativeOps: PathOps = {
+  win32: process.platform === "win32",
+  path,
+  realpath: (p) => realpathSync(p),
+  isSymlink: (p) => {
+    try {
+      return lstatSync(p).isSymbolicLink()
+    } catch {
+      return false
+    }
+  },
+}
+
+/** realpath in the form the runtime keeps: as it is on POSIX, canonical (or refused) on Windows. */
+function realOf(p: string, ops: PathOps): string {
+  const real = ops.realpath(p)
+  if (!ops.win32) return real
+  const canonical = canonicalNativePath(real)
+  if (canonical === undefined || !isWindowsAbsolutePath(canonical)) throw new RuntimeError(`${p} resolves to ${real}, which is not on a local drive`)
+  return canonical
+}
+
 /** `p` with every existing part resolved through symlinks; refuses a dangling symlink on the way. */
-function resolvePath(p: string): string {
+function resolvePath(p: string, ops: PathOps = nativeOps): string {
   const rest: string[] = []
   let current = p
   for (;;) {
+    let real: string
     try {
-      return path.join(realpathSync(current), ...rest.reverse())
+      real = realOf(current, ops)
     } catch (cause) {
+      if (cause instanceof RuntimeError) throw cause
       if ((cause as NodeJS.ErrnoException).code !== "ENOENT") throw new RuntimeError(`cannot resolve ${p}: ${(cause as Error).message}`)
-      let link = false
-      try {
-        link = lstatSync(current).isSymbolicLink()
-      } catch {}
-      if (link) throw new RuntimeError(`${p} goes through a dangling symlink`)
-      const parent = path.dirname(current)
+      if (ops.isSymlink(current)) throw new RuntimeError(`${p} goes through a dangling symlink`)
+      const parent = ops.path.dirname(current)
       if (parent === current) throw new RuntimeError(`cannot resolve ${p}`)
-      rest.push(path.basename(current))
+      rest.push(ops.path.basename(current))
       current = parent
+      continue
     }
+    return ops.win32 ? path.posix.join(real, ...rest.reverse()) : path.join(real, ...rest.reverse())
   }
 }
 
+/** Whether real path `real` is real root `root` or inside it (without case on Windows). */
+function within(real: string, root: string, ops: PathOps): boolean {
+  if (!ops.win32) return real === root || real.startsWith(root.endsWith(path.sep) ? root : root + path.sep)
+  const r = real.toLowerCase()
+  const base = root.toLowerCase()
+  return r === base || r.startsWith(base.endsWith("/") ? base : `${base}/`)
+}
+
 /** The real path of `p` when it is (or would be) under one of `roots`; throws a RuntimeError otherwise. */
-export function resolveUnderRoots(p: string, roots: readonly string[]): string {
+export function resolveUnderRoots(p: string, roots: readonly string[], ops: PathOps = nativeOps): string {
   if (roots.length === 0) throw new RuntimeError("this node has no workspaceRoots in node.json, so it prepares no workspaces")
   if (!isAbsolutePath(p)) throw new RuntimeError(`${p} is not an absolute path`)
-  const real = resolvePath(p)
+  const real = resolvePath(p, ops)
   for (const root of roots) {
     let realRoot: string
     try {
-      realRoot = realpathSync(root)
+      realRoot = realOf(root, ops)
     } catch {
       continue
     }
-    if (real === realRoot || real.startsWith(realRoot.endsWith(path.sep) ? realRoot : realRoot + path.sep)) return real
+    if (within(real, realRoot, ops)) return real
   }
   throw new RuntimeError(`${p} is not under this node's workspace roots`)
 }
@@ -128,7 +173,7 @@ export class HostRuntime implements Runtime {
       const directory = resolveUnderRoots(existing, this.roots)
       return this.prepared(repo, directory, "worktree", branch, base, true, ctx)
     }
-    const directory = resolveUnderRoots(path.join(repo, ".worktrees", ...branch.split("/")), this.roots)
+    const directory = resolveUnderRoots(path.posix.join(repo, ".worktrees", ...branch.split("/")), this.roots)
     if (existsSync(directory)) throw new RuntimeError(`${directory} exists and is not the worktree of ${branch}`)
     if (base) await this.git(repo, ["rev-parse", "--verify", "--quiet", `${base}^{commit}`], ctx, `base ${base} is not a commit in ${repo}`)
     ctx.progress?.(`creating worktree ${branch}`)
@@ -154,7 +199,8 @@ export class HostRuntime implements Runtime {
     const { branch, base, remote } = input.workspace
     const target = resolveUnderRoots(input.workspace.repo, this.roots)
     if (existsSync(target) || isLink(target)) throw new RuntimeError(`${target} exists; a clone needs a new directory`)
-    const parent = path.dirname(target)
+    // Canonical paths join and split with "/" on every platform (path.posix is path on POSIX).
+    const parent = path.posix.dirname(target)
     mkdirSync(parent, { recursive: true })
     // The parent was created through resolved paths, but check again before git writes there.
     if (resolveUnderRoots(parent, this.roots) !== parent) throw new RuntimeError(`${parent} moved while preparing`)

package/packages/node/src/opencode-service.ts

@@ -0,0 +1,111 @@
+// OpenCode's background service on Windows (Phase 3, PHASE3-CONTRACT.md "The node on Windows"). On macOS and Linux a
+// login item or the user keeps OpenCode's background service running; on Windows nothing does, so the node starts
+// it: when no service is registered (service.json missing, or its process gone), `<opencode> service start` (no shell,
+// hidden window) at most once per warm tick, backing off after a failure (START_BACKOFF_MS doubling up to
+// START_BACKOFF_MAX_MS), and logged. `service start` asks OpenCode's client to ensure the service (it spawns
+// `opencode serve --service` detached, waits until it is ready, prints its URL and exits), so the service outlives
+// the command: only the command itself is ended on a timeout, never its tree. The warmer then warms it as elsewhere.
+import { spawn } from "node:child_process"
+import type { WarmEndpoint } from "./opencode-warm.ts"
+
+/** First back-off after a failed start (the warm interval); it doubles up to START_BACKOFF_MAX_MS. */
+export const START_BACKOFF_MS = 30_000
+export const START_BACKOFF_MAX_MS = 10 * 60_000
+/** How long `service start` may take (it waits for the service to be ready). */
+export const START_TIMEOUT_MS = 90_000
+const STDERR_MAX = 2000
+
+/** Runs `file args` without a shell; resolves when it exits (or failed to start). */
+export type StartRun = (file: string, args: readonly string[]) => Promise<{ code: number | null; stderr: string; spawnError?: string }>
+
+export interface OpenCodeServiceStarterOptions {
+  /** The OpenCode executable (an absolute path), or undefined when it is not installed. */
+  readonly binary: () => string | undefined
+  readonly log: (line: string) => void
+  readonly run?: StartRun
+  readonly now?: () => number
+  /** The environment `service start` runs with (default process.env). */
+  readonly env?: Readonly<Record<string, string | undefined>>
+}
+
+/** The default run: hidden, no shell, stdin and stdout closed, stderr bounded; the command alone ends on a timeout. */
+export function startRun(env: Readonly<Record<string, string | undefined>> = process.env, timeoutMs = START_TIMEOUT_MS): StartRun {
+  return (file, args) =>
+    new Promise((resolve) => {
+      const clean = Object.fromEntries(Object.entries(env).filter((e): e is [string, string] => typeof e[1] === "string"))
+      let child: ReturnType<typeof spawn>
+      try {
+        child = spawn(file, [...args], { shell: false, windowsHide: true, env: clean, stdio: ["ignore", "ignore", "pipe"] })
+      } catch (cause) {
+        return resolve({ code: null, stderr: "", spawnError: (cause as Error).message })
+      }
+      let stderr = ""
+      let done = false
+      const finish = (r: { code: number | null; stderr: string; spawnError?: string }) => {
+        if (done) return
+        done = true
+        clearTimeout(timer)
+        // The service it started may hold an inherited handle; never wait for the pipe to close.
+        child.stderr?.destroy()
+        resolve(r)
+      }
+      child.stderr?.on("data", (chunk: Buffer) => {
+        if (stderr.length < STDERR_MAX) stderr += chunk.toString("utf8").slice(0, STDERR_MAX - stderr.length)
+      })
+      child.on("error", (cause) => finish({ code: null, stderr, spawnError: cause.message }))
+      child.on("exit", (code) => finish({ code, stderr }))
+      const timer = setTimeout(() => {
+        child.kill()
+        finish({ code: null, stderr, spawnError: `timed out after ${Math.round(timeoutMs / 1000)} s` })
+      }, timeoutMs)
+    })
+}
+
+const oneLine = (text: string) => text.replace(/[\p{Cc}\p{Cf}\u2028\u2029]+/gu, " ").replace(/\s+/g, " ").trim().slice(0, 300)
+
+export class OpenCodeServiceStarter {
+  private nextAttempt = 0
+  private delay = START_BACKOFF_MS
+  private missingLogged = false
+
+  constructor(private readonly options: OpenCodeServiceStarterOptions) {}
+
+  /** Starts the service unless backing off; true when `service start` succeeded. */
+  async start(): Promise<boolean> {
+    const now = (this.options.now ?? Date.now)()
+    if (now < this.nextAttempt) return false
+    const binary = this.options.binary()
+    if (!binary) {
+      if (!this.missingLogged) this.options.log("OpenCode is not installed (no opencode.exe found), so its background service cannot be started")
+      this.missingLogged = true
+      return false
+    }
+    this.missingLogged = false
+    this.options.log("OpenCode's background service is not running; starting it (opencode service start)")
+    const r = await (this.options.run ?? startRun(this.options.env))(binary, ["service", "start"])
+    if (r.code === 0) {
+      this.delay = START_BACKOFF_MS
+      this.nextAttempt = 0
+      this.options.log("started OpenCode's background service")
+      return true
+    }
+    const why = r.spawnError ?? (oneLine(r.stderr) || `exit ${r.code}`)
+    this.options.log(`could not start OpenCode's background service (${why}); retrying in ${Math.round(this.delay / 1000)} s`)
+    this.nextAttempt = (this.options.now ?? Date.now)() + this.delay
+    this.delay = Math.min(this.delay * 2, START_BACKOFF_MAX_MS)
+    return false
+  }
+}
+
+/**
+ * The warmer's discovery of the background service: on win32 a missing registration starts the service (at most one
+ * attempt per call, i.e. per tick) and reads the registration again; elsewhere `read` as it is.
+ */
+export function serviceDiscovery(read: () => Promise<WarmEndpoint | undefined>, starter: OpenCodeServiceStarter, platform: string = process.platform): () => Promise<WarmEndpoint | undefined> {
+  if (platform !== "win32") return read
+  return async () => {
+    const endpoint = await read()
+    if (endpoint) return endpoint
+    return (await starter.start()) ? read() : undefined
+  }
+}

package/packages/node/src/opencode-warm.ts

@@ -248,19 +248,25 @@ export class OpenCodeWarmer {
  * OpenCode's background service from its registration file (service.json: {url, pid, password?, id?, version?}),
  * without any request: undefined when the file is missing or malformed, is not this user's own (a symbolic link, not
  * owned by this uid, or writable by group or others), or its process is gone or another user's (EPERM). The URL is
- * passed on as it is; OpenCodeWarmer.tick decides whether it may be asked.
+ * passed on as it is; OpenCodeWarmer.tick decides whether it may be asked. On Windows (no modes, no uid; Phase 3) the
+ * file is this user's when its access list allows no one but this user, SYSTEM and Administrators (src/win-acl.ts, as
+ * for password files: it holds the service's password); Bun ignores numeric open flags there, so it is opened "r"
+ * after the lstat check.
  */
-export async function readServiceRegistration(file: string, options: { readonly uid?: number } = {}): Promise<WarmEndpoint | undefined> {
-  const uid = options.uid ?? (typeof process.getuid === "function" ? process.getuid() : undefined)
+export async function readServiceRegistration(file: string, options: { readonly uid?: number } & SecretFileOptions = {}): Promise<WarmEndpoint | undefined> {
+  const win32 = isWin32(options)
+  const uid = win32 ? undefined : (options.uid ?? (typeof process.getuid === "function" ? process.getuid() : undefined))
   let info: unknown
   let fd: number | undefined
   try {
     const before = lstatSync(file)
     if (!before.isFile()) return undefined
-    fd = openSync(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0))
+    fd = win32 ? openSync(file, "r") : openSync(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0))
     const stat = fstatSync(fd)
     if (!stat.isFile() || stat.dev !== before.dev || stat.ino !== before.ino) return undefined
-    if ((stat.mode & 0o022) !== 0) return undefined
+    if (win32) {
+      if (!(options.acl ?? defaultWinAcl()).check(nativeWinPath(file)).ok) return undefined
+    } else if ((stat.mode & 0o022) !== 0) return undefined
     if (uid !== undefined && stat.uid !== uid) return undefined
     if (stat.size > REGISTRATION_MAX) return undefined
     // Read through the descriptor that was checked (no second open by path).

package/packages/node/src/run.ts

@@ -7,7 +7,9 @@
 // node keeps OpenCode's background service and node.json's foreground servers warm (opencode-warm.ts) so their hub
 // plugin loads without a client opening a project. Exit codes: 0 after a clean stop, 1 when
 // the machine is not enrolled, EXIT_CONFIG (78, EX_CONFIG) when node.json gives the node nothing to do; the
-// service units do not restart on 78.
+// service units do not restart on 78. On Windows (Phase 3) the logon task restarts the node whatever its exit code,
+// so a node with nothing to do waits there, re-reading node.json, instead of exiting; and while it offers opencode the node starts OpenCode's
+// background service when none is registered (opencode-service.ts), since nothing else keeps it running there.
 import { homedir } from "node:os"
 import path from "node:path"
 import type { NodeLaunchReport } from "../../protocol/src/index.ts"
@@ -15,8 +17,9 @@ import { OpenShellCli } from "../../runtime-openshell/src/cli.ts"
 import type { Runtime } from "../../runtime-sdk/src/index.ts"
 import { nodeConfigPath, readNodeConfig, readSpokeCredentials, type NodeConfig, type SpokeCredentials } from "./config.ts"
 import { NodeDaemon, NODE_VERSION } from "./daemon.ts"
-import { detectHarnesses } from "./harnesses.ts"
+import { detectHarnesses, findExecutable, opencodeBinary } from "./harnesses.ts"
 import { HostRuntime } from "./host.ts"
+import { OpenCodeServiceStarter, serviceDiscovery, type StartRun } from "./opencode-service.ts"
 import { OpenCodeWarmer, readServiceRegistration, serverEndpoint, type WarmEndpoint } from "./opencode-warm.ts"
 import { createOpenShellRuntime, openshellBackends, PROBE_TIMEOUT_MS, sweepSandboxes } from "./openshell.ts"
 
@@ -35,8 +38,30 @@ export interface RunNodeOptions {
   readonly openshellBinary?: string
   /** Finds OpenCode's background service (default: readServiceRegistration on this env's registration file). */
   readonly openCodeService?: () => Promise<WarmEndpoint | undefined>
+  /** The platform (default this one): win32 exits 0 for "nothing to do" and starts OpenCode's service. */
+  readonly platform?: string
+  /** win32: the OpenCode executable (default opencodeBinary found like a harness), undefined when not installed. */
+  readonly openCodeBinary?: () => string | undefined
+  /** win32: how `opencode service start` runs (default opencode-service.ts startRun). */
+  readonly startOpenCode?: StartRun
+  /** win32: how often a node with nothing to do re-reads node.json (default IDLE_RECHECK_MS). */
+  readonly idleRecheckMs?: number
 }
 
+/** win32: how often a node with no workspace roots re-reads node.json while it waits. */
+export const IDLE_RECHECK_MS = 60_000
+
+const sleep = (ms: number, signal: AbortSignal) =>
+  new Promise<void>((resolve) => {
+    const timer = setTimeout(done, ms)
+    function done() {
+      clearTimeout(timer)
+      signal.removeEventListener("abort", done)
+      resolve()
+    }
+    signal.addEventListener("abort", done, { once: true })
+  })
+
 /** OpenCode's service registration file for `env` and `home` (@opencode/client's default location). */
 export const openCodeServiceFile = (env: Env, home: string): string =>
   path.join(env.XDG_STATE_HOME || path.join(home, ".local", "state"), "opencode", "service.json")
@@ -88,6 +113,7 @@ async function setupOpenShell(config: NodeConfig, credentials: SpokeCredentials,
 export async function runNode(options: RunNodeOptions): Promise<number> {
   const env = options.env ?? process.env
   const home = options.home ?? homedir()
+  const platform = options.platform ?? process.platform
   const log = options.log ?? ((line: string) => process.stderr.write(`[hub node] ${line}\n`))
 
   const credentials = readSpokeCredentials(env, home)
@@ -96,11 +122,21 @@ export async function runNode(options: RunNodeOptions): Promise<number> {
     return 1
   }
   const file = nodeConfigPath(env, home)
-  const { config, problems } = readNodeConfig(file)
+  let { config, problems } = readNodeConfig(file, { platform, home })
   for (const problem of problems) log(`${file}: ${problem}`)
   if (config.workspaceRoots.length === 0) {
     log(`${file} lists no workspaceRoots, so this node can prepare no workspaces; add e.g. {"workspaceRoots": ["${home}/projects"]}`)
-    return EXIT_CONFIG
+    if (platform !== "win32") return EXIT_CONFIG
+    // Task Scheduler restarts the logon task whatever the exit code (its repetition trigger), so a node with nothing to
+    // do waits here, re-reading node.json, instead of exiting and being started again every minute.
+    log(`waiting: re-reading ${file} every ${Math.round((options.idleRecheckMs ?? IDLE_RECHECK_MS) / 1000)} s until it lists workspaceRoots`)
+    while (config.workspaceRoots.length === 0) {
+      await sleep(options.idleRecheckMs ?? IDLE_RECHECK_MS, options.signal)
+      if (options.signal.aborted) return 0
+      ;({ config, problems } = readNodeConfig(file, { platform, home }))
+    }
+    for (const problem of problems) log(`${file}: ${problem}`)
+    log(`workspace roots now set in ${file}; starting`)
   }
 
   if (options.signal.aborted) return 0
@@ -122,7 +158,16 @@ export async function runNode(options: RunNodeOptions): Promise<number> {
   })
   log(`hub node ${NODE_VERSION}: ${config.slots} slots, roots ${config.workspaceRoots.join(", ")}; host harnesses ${harnesses.join(", ") || "none"}`)
   daemon.start()
-  if (harnesses.includes("opencode")) startOpenCodeWarmers(config, options.openCodeService ?? (() => readServiceRegistration(openCodeServiceFile(env, home))), log, options.signal)
+  if (harnesses.includes("opencode")) {
+    const read = options.openCodeService ?? (() => readServiceRegistration(openCodeServiceFile(env, home)))
+    const starter = new OpenCodeServiceStarter({
+      binary: options.openCodeBinary ?? (() => findExecutable(opencodeBinary(env, home, platform), env, platform)),
+      log,
+      env,
+      ...(options.startOpenCode ? { run: options.startOpenCode } : {}),
+    })
+    startOpenCodeWarmers(config, serviceDiscovery(read, starter, platform), log, options.signal)
+  }
   await new Promise<void>((resolve) => {
     if (options.signal.aborted) return resolve()
     options.signal.addEventListener("abort", () => resolve(), { once: true })

package/packages/preset/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-preset",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "private": true,
   "description": "The preset spoke: drives a harness without a spoke of its own through a terminal pane (tmux), described by a data-only preset; official presets in presets/ (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-protocol",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "private": true,
   "description": "Hub ↔ spoke wire protocol (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/protocol/src/index.ts

@@ -18,6 +18,7 @@
 
 import { featureList, HUB_URL_MAX_CHARS, ID, isByeFrame as isBye, isHubURL, isObj, isResFrame as isRes, isWelcomeFrame, MAX_FRAME, MAX_RETRY_AFTER_MS, nonEmpty, num, parseFrame as parse, str, token, UNSAFE_CHARS } from "./wire.ts"
 import type { NodeMessage, NodeServerMessage } from "./node.ts"
+import { isWindowsAbsolutePath } from "./launch.ts"
 import { PROFILE_APPLY_FEATURE, profileApplyRequestProblem, type ProfileApplyRequest, type ProfileApplyResult } from "./profiles.ts"
 import { SESSION_CONTEXT_FEATURE, sessionContextProblem, type SessionContextRequest, type SessionContextResult } from "./concierge.ts"
 import { isMediaOffset, parseMediaRef, type TimelineMediaResult } from "./media.ts"
@@ -1242,7 +1243,8 @@ function isServerRequest(v: unknown): v is ServerRequest {
     case "create":
       return (
         nonEmpty(v.directory) &&
-        v.directory.startsWith("/") &&
+        // POSIX as before; a Windows machine's directory in canonical form (C:/…, Phase 3).
+        (v.directory.startsWith("/") || isWindowsAbsolutePath(v.directory)) &&
         v.directory.length <= 4096 &&
         (v.title === undefined || (str(v.title) && v.title.length <= 200)) &&
         (v.herdrWorkspace === undefined || (nonEmpty(v.herdrWorkspace) && v.herdrWorkspace.length <= 100)) &&

package/packages/protocol/src/launch.ts

@@ -149,17 +149,52 @@ export const LABELS_MAX = 32
 export const LABEL_VALUE_MAX = 256
 const LABEL_KEY = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,62}$/
 
-/** An absolute path of at most PATH_MAX characters without `.`/`..` segments, empty segments or unsafe characters. */
+/**
+ * An absolute path of at most PATH_MAX characters without `.`/`..` segments, empty segments or unsafe characters:
+ * POSIX `/a/b` (a trailing slash allowed, as before), or a canonical Windows path `C:/a/b` (upper-case drive, `/`
+ * separators, the root `C:/`; no backslash). UNC (`//server`, `\\server`) and device paths (`//?/`, `\\?\`) are never
+ * absolute here. The Windows form is the bootstrap contracts' rule (packages/cli/src/bootstrap/contracts/validate.ts
+ * isAbsolutePath); native forms are canonicalized at the node's edge (canonicalNativePath).
+ */
 export function isAbsolutePath(v: unknown): v is string {
-  if (typeof v !== "string" || !v.startsWith("/") || v.length > PATH_MAX || UNSAFE_CHARS.test(v)) return false
-  if (v === "/") return true
-  return v
+  if (typeof v !== "string" || v.length > PATH_MAX || UNSAFE_CHARS.test(v)) return false
+  if (WINDOWS_ROOT.test(v)) return !v.includes("\\") && normalSegments(v.slice(2))
+  if (!v.startsWith("/")) return false
+  return normalSegments(v)
+}
+
+/** `rest` (starting with "/") is "/" or "/"-separated segments, none empty, "." or ".." (one trailing "/" allowed). */
+function normalSegments(rest: string): boolean {
+  if (!rest.startsWith("/")) return false
+  if (rest === "/") return true
+  return rest
     .slice(1)
     .replace(/\/$/, "")
     .split("/")
     .every((part) => part !== "" && part !== "." && part !== "..")
 }
 
+const WINDOWS_ROOT = /^[A-Z]:(?=\/)/
+
+/** Whether `v` is a canonical Windows absolute path (`C:/…`). */
+export const isWindowsAbsolutePath = (v: unknown): v is string => typeof v === "string" && WINDOWS_ROOT.test(v) && isAbsolutePath(v)
+
+/**
+ * The canonical form of a path a host reported in its own form (node.json, realpath, git output), or undefined when
+ * it has none: Windows drive paths get an upper-case drive and `/` separators (a `\\?\` or `\??\` final-path
+ * prefix is dropped); repeated and trailing slashes are dropped. UNC, device and relative paths have no canonical
+ * form. Mirrors packages/cli/src/bootstrap/discovery/util.ts normalizeAbs.
+ */
+export function canonicalNativePath(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined
+  let p = value.replace(/^(\\\\\?\\|\\\?\?\\)(?=[A-Za-z]:\\)/, "")
+  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
+}
+
 /** A branch name `git check-ref-format --branch` accepts, from a conservative character set, never starting with `-`. */
 export function isRefName(v: unknown): v is string {
   if (typeof v !== "string" || v.length === 0 || v.length > REF_MAX) return false

package/packages/runtime-openshell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-runtime-openshell",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "private": true,
   "description": "The `openshell` runtime of `hub node`: launches in NVIDIA OpenShell sandboxes, driven through the openshell CLI (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/runtime-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-runtime-sdk",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "private": true,
   "description": "The Runtime interface `hub node` runtimes implement (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-sdk",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "private": true,
   "description": "Typed client for the hub's /api/agent (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/spoke-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-spoke-sdk",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "private": true,
   "description": "Harness-neutral spoke building blocks: hub connection, enrollment, tokens, idempotent deliver, prompt references, HarnessSpoke (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/src/central/agent/launch-spec.ts

@@ -231,8 +231,10 @@ function validRoles(value: unknown): string[] {
 function validWorkspace(value: unknown, wording: Wording): LaunchWorkspace {
   if (!isObject(value)) throw invalid("workspace is {repo, mode?, branch?, base?, remote?}")
   onlyFields(value, WORKSPACE_FIELDS, "workspace", wording)
-  // canonicalProject rejects relative, `~` and root paths.
-  const repo = typeof value.repo === "string" ? canonicalProject(value.repo) : undefined
+  // canonicalProject rejects relative, `~` and root paths; a Windows repo is kept canonical (upper-case drive, `/`),
+  // and a native UNC or device path (`\\server\…`, `\\?\…`) is never one (Phase 3).
+  const raw = typeof value.repo === "string" && !value.repo.startsWith("\\") ? canonicalProject(value.repo) : undefined
+  const repo = raw && /^[a-z]:\//.test(raw) ? raw[0]!.toUpperCase() + raw.slice(1) : raw
   if (repo === undefined) throw invalid("workspace.repo is an absolute repository path")
   const mode = oneOf<WorkspaceMode>(value.mode, ["worktree", "checkout", "clone"], "worktree", "workspace.mode")
   for (const field of ["branch", "base"] as const) {