@huynle/hub 0.8.7 → 0.9.1

package/packages/codex/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-codex",
-  "version": "0.8.7",
+  "version": "0.9.1",
   "private": true,
   "description": "The Codex app-server spoke: attaches to Codex's app-server (its own over stdio, and the shared daemon's socket when present), and the `hub codex` wrapper (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/codex/src/wrapper.ts

@@ -39,7 +39,7 @@ function spawnService(io: CodexIo): void {
   ensurePrivateDir(dir)
   const log = openSync(path.join(dir, "spoke.log"), "a", 0o600)
   try {
-    const child = spawn(io.program.execPath, [io.program.entry, "codex-spoke", "serve"], { detached: true, stdio: ["ignore", log, log], env: { ...io.env, BUN_BE_BUN: "1" } })
+    const child = spawn(io.program.execPath, [io.program.entry, "codex-spoke", "serve"], { detached: true, windowsHide: true, stdio: ["ignore", log, log], env: { ...io.env, BUN_BE_BUN: "1" } })
     child.on("error", () => {})
     child.unref()
   } finally {
@@ -69,7 +69,7 @@ const SIGNALS: Record<string, number> = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGK
 /** Runs `bin` with the terminal; resolves with its exit code (128 + signal number when a signal ended it). */
 function spawnCodex(bin: string, args: readonly string[], env: Env, stderr: (s: string) => void): Promise<number> {
   return new Promise((resolve) => {
-    const child = spawn(bin, args, { stdio: "inherit", env: env as NodeJS.ProcessEnv })
+    const child = spawn(bin, args, { stdio: "inherit", windowsHide: true, env: env as NodeJS.ProcessEnv })
     // The terminal sends Ctrl-C to Codex too: it decides what that means; this process keeps waiting.
     const ignore = () => {}
     const forward = () => child.kill("SIGTERM")

package/packages/node/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-node",
-  "version": "0.8.7",
+  "version": "0.9.1",
   "private": true,
   "description": "`hub node`: the per-machine daemon that prepares, collects and cleans up launch workspaces (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/node/src/config.ts

@@ -14,10 +14,12 @@
 // service (loopback URLs only, the password from a private file), and the project directories to keep loaded on the
 // service (`directories`) or on a server (its own `directories`); absent: the projects of recent sessions under
 // workspaceRoots. `opencode.timeoutSeconds` (1–300, default 30) bounds each warm request.
+// On Windows (Phase 3) paths may be written `C:\\Users\\x\\projects`, `C:/Users/x/projects` or `~/projects`; the node
+// keeps them in canonical form (`C:/…`, protocol canonicalNativePath), so its hello carries canonical paths only.
 import { readFileSync } from "node:fs"
 import { homedir, hostname } from "node:os"
 import path from "node:path"
-import { isAbsolutePath, labelsProblem, NODE_ROOTS_MAX, NODE_SLOTS_MAX } from "../../protocol/src/index.ts"
+import { canonicalNativePath, isAbsolutePath, isWindowsAbsolutePath, labelsProblem, NODE_ROOTS_MAX, NODE_SLOTS_MAX } from "../../protocol/src/index.ts"
 import { normalizeOpenShellProfiles, type OpenShellProfiles } from "../../runtime-openshell/src/profiles.ts"
 import { configPath, readConfig } from "../../../src/config.ts"
 import { WARM_DIRECTORIES_MAX } from "./opencode-warm.ts"
@@ -94,8 +96,35 @@ const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "obj
 const whole = (v: unknown, min: number, max: number): v is number => typeof v === "number" && Number.isInteger(v) && v >= min && v <= max
 const show = (v: unknown) => JSON.stringify(v)?.slice(0, 80) ?? String(v)
 
+/** Where node.json is read: the platform (default this one) and, for `~/…` on Windows, the user's home. */
+export interface NodeConfigOptions {
+  readonly platform?: string
+  readonly home?: string
+}
+
+/**
+ * A node.json path as the node uses it, or undefined when it is not acceptable: on POSIX the path as it is (an
+ * absolute path); on Windows (Phase 3) `C:\…`, `C:/…` or `~/…` (`~\…`) in canonical form (`C:/…`), never UNC, device or
+ * POSIX paths. Drive and file-system roots are refused by the callers.
+ */
+function configPathOf(raw: unknown, options: NodeConfigOptions): string | undefined {
+  if ((options.platform ?? process.platform) !== "win32") return isAbsolutePath(raw) ? raw : undefined
+  if (typeof raw !== "string") return undefined
+  let native = raw
+  if (/^~[\\/]/.test(raw)) {
+    const home = canonicalNativePath(options.home ?? homedir())
+    if (!home || !isWindowsAbsolutePath(home)) return undefined
+    native = `${home}/${raw.slice(2)}`
+  }
+  const canonical = canonicalNativePath(native)
+  return canonical && isWindowsAbsolutePath(canonical) ? canonical : undefined
+}
+
+/** A file-system root ("/", "C:/"): never a workspace root or warm directory. */
+const isRoot = (p: string) => p === "/" || /^[A-Z]:\/$/.test(p)
+
 /** Normalizes untrusted node.json content, field by field. */
-export function normalizeNodeConfig(raw: unknown): NodeConfigResult {
+export function normalizeNodeConfig(raw: unknown, options: NodeConfigOptions = {}): NodeConfigResult {
   const problems: string[] = []
   let r: Record<string, unknown> = {}
   if (isObject(raw)) r = raw
@@ -103,9 +132,10 @@ export function normalizeNodeConfig(raw: unknown): NodeConfigResult {
 
   const workspaceRoots: string[] = []
   if (r.workspaceRoots !== undefined && !Array.isArray(r.workspaceRoots)) problems.push("workspaceRoots must be a list of absolute paths")
-  for (const root of Array.isArray(r.workspaceRoots) ? r.workspaceRoots : []) {
-    if (!isAbsolutePath(root) || root === "/") {
-      problems.push(`workspaceRoots: ${show(root)} is not an absolute path (without . or .. segments, and not /)`)
+  for (const entry of Array.isArray(r.workspaceRoots) ? r.workspaceRoots : []) {
+    const root = configPathOf(entry, options)
+    if (root === undefined || isRoot(root)) {
+      problems.push(`workspaceRoots: ${show(entry)} is not an absolute path (without . or .. segments, and not /)`)
       continue
     }
     const clean = root.replace(/\/+$/, "")
@@ -137,7 +167,7 @@ export function normalizeNodeConfig(raw: unknown): NodeConfigResult {
 
   const openshell = r.openshell === undefined ? undefined : normalizeOpenShell(r.openshell, problems)
   const harnesses = r.harnesses === undefined ? undefined : normalizeHarnesses(r.harnesses, problems)
-  const opencode = r.opencode === undefined ? undefined : normalizeOpenCode(r.opencode, problems)
+  const opencode = r.opencode === undefined ? undefined : normalizeOpenCode(r.opencode, problems, options)
 
   return {
     config: { workspaceRoots, labels, slots, ...(memoryMB !== undefined ? { memoryMB } : {}), ...(openshell ? { openshell } : {}), ...(harnesses ? { harnesses } : {}), ...(opencode ? { opencode } : {}) },
@@ -146,15 +176,16 @@ export function normalizeNodeConfig(raw: unknown): NodeConfigResult {
 }
 
 /** Absolute directories (not /), trailing slashes dropped, at most WARM_DIRECTORIES_MAX; undefined for a non-list. */
-function normalizeDirectories(raw: unknown, field: string, problems: string[]): string[] | undefined {
+function normalizeDirectories(raw: unknown, field: string, problems: string[], options: NodeConfigOptions): string[] | undefined {
   if (!Array.isArray(raw)) {
     problems.push(`${field} must be a list of absolute paths`)
     return undefined
   }
   const out: string[] = []
-  for (const dir of raw) {
-    if (!isAbsolutePath(dir) || dir === "/") {
-      problems.push(`${field}: ${show(dir)} is not an absolute path (without . or .. segments, and not /)`)
+  for (const entry of raw) {
+    const dir = configPathOf(entry, options)
+    if (dir === undefined || isRoot(dir)) {
+      problems.push(`${field}: ${show(entry)} is not an absolute path (without . or .. segments, and not /)`)
       continue
     }
     const clean = dir.replace(/\/+$/, "")
@@ -184,12 +215,12 @@ function loopbackOrigin(raw: unknown): string | undefined {
   return url.origin
 }
 
-function normalizeOpenCode(raw: unknown, problems: string[]): OpenCodeNodeConfig | undefined {
+function normalizeOpenCode(raw: unknown, problems: string[], options: NodeConfigOptions): OpenCodeNodeConfig | undefined {
   if (!isObject(raw)) {
     problems.push("opencode must be an object")
     return undefined
   }
-  const directories = raw.directories === undefined ? undefined : normalizeDirectories(raw.directories, "opencode.directories", problems)
+  const directories = raw.directories === undefined ? undefined : normalizeDirectories(raw.directories, "opencode.directories", problems, options)
   const servers: OpenCodeServerConfig[] = []
   if (raw.servers !== undefined && !Array.isArray(raw.servers)) problems.push("opencode.servers must be a list of {url, passwordFile, directories?}")
   const list = Array.isArray(raw.servers) ? raw.servers : []
@@ -198,10 +229,11 @@ function normalizeOpenCode(raw: unknown, problems: string[]): OpenCodeNodeConfig
     if (!isObject(entry)) return void problems.push(`${field} must be an object {url, passwordFile, directories?}`)
     const url = loopbackOrigin(entry.url)
     if (!url) return void problems.push(`${field}.url must be an http(s) URL on 127.0.0.1, [::1] or localhost, without user info, path or query`)
-    if (!isAbsolutePath(entry.passwordFile) || entry.passwordFile === "/") return void problems.push(`${field}.passwordFile must be the absolute path of a private (chmod 600) file holding the server's password`)
+    const passwordFile = configPathOf(entry.passwordFile, options)
+    if (passwordFile === undefined || isRoot(passwordFile)) return void problems.push(`${field}.passwordFile must be the absolute path of a private (chmod 600) file holding the server's password`)
     if (servers.some((s) => s.url === url)) return void problems.push(`${field}: ${url} is listed twice; the first one is used`)
-    const dirs = entry.directories === undefined ? undefined : normalizeDirectories(entry.directories, `${field}.directories`, problems)
-    servers.push({ url, passwordFile: entry.passwordFile, ...(dirs ? { directories: dirs } : {}) })
+    const dirs = entry.directories === undefined ? undefined : normalizeDirectories(entry.directories, `${field}.directories`, problems, options)
+    servers.push({ url, passwordFile, ...(dirs ? { directories: dirs } : {}) })
   })
   if (servers.length > OPENCODE_SERVERS_MAX) {
     problems.push(`opencode.servers: at most ${OPENCODE_SERVERS_MAX} servers; the rest are ignored`)
@@ -256,7 +288,7 @@ function normalizeOpenShell(raw: unknown, problems: string[]): OpenShellNodeConf
 }
 
 /** Reads node.json; a missing file is the defaults, unreadable or bad JSON the defaults with a problem. */
-export function readNodeConfig(file: string): NodeConfigResult {
+export function readNodeConfig(file: string, options: NodeConfigOptions = {}): NodeConfigResult {
   let text: string
   try {
     text = readFileSync(file, "utf8")
@@ -265,7 +297,7 @@ export function readNodeConfig(file: string): NodeConfigResult {
     return { config: normalizeNodeConfig(undefined).config, problems: [`${file}: cannot read (${(cause as Error).message})`] }
   }
   try {
-    return normalizeNodeConfig(JSON.parse(text))
+    return normalizeNodeConfig(JSON.parse(text), options)
   } catch {
     return { config: normalizeNodeConfig(undefined).config, problems: [`${file}: not valid JSON`] }
   }

package/packages/node/src/git.ts

@@ -3,7 +3,11 @@
 // ask), only the https and ssh transports (never ext::, file:: or a local path as a remote), and none of the
 // inherited GIT_* variables that redirect a repository, its config or git's own programs. Every run has a time limit
 // and can be cancelled. node:child_process (not Bun.spawn) so the node also runs bundled for node.
+//
+// Process trees: on POSIX git leads its own process group and a timeout or cancel signals the group; win32 has no
+// groups, so there the shared process-tree helper ends git's tree (taskkill /T /F, Phase 3).
 import { spawn } from "node:child_process"
+import { processTree, type ProcessTree } from "../../cli/src/bootstrap/adapters/process-tree.ts"
 
 type Env = Readonly<Record<string, string | undefined>>
 
@@ -48,12 +52,17 @@ export interface GitOptions {
   readonly env?: Env
   /** The git executable (default "git" on PATH). */
   readonly binary?: string
+  /** The platform (default this one); win32 ends git's tree with `tree`. */
+  readonly platform?: string
+  /** win32's tree kill (default the shared process-tree helper). */
+  readonly tree?: ProcessTree
 }
 
 /** Runs `git -c protocol.ext.allow=never <args>` and resolves with stdout; rejects with a GitError. */
 export function runGit(args: readonly string[], options: GitOptions): Promise<string> {
   const argv = ["-c", "protocol.ext.allow=never", ...args]
   const what = `git ${args.find((a) => !a.startsWith("-")) ?? ""}`.trim()
+  const win32 = (options.platform ?? process.platform) === "win32"
   return new Promise((resolve, reject) => {
     if (options.signal?.aborted) return reject(new GitError(`${what} cancelled`))
     let settled = false
@@ -65,12 +74,12 @@ export function runGit(args: readonly string[], options: GitOptions): Promise<st
       if (error) reject(error)
       else resolve(stdout ?? "")
     }
-    // Its own process group, so a timeout or cancel also kills what git started (ssh, git-remote-https).
+    // Its own process group (POSIX), so a timeout or cancel also kills what git started (ssh, git-remote-https).
     const child = spawn(options.binary ?? "git", argv, {
       cwd: options.cwd,
       env: gitEnv(options.baseEnv ?? process.env, options.env),
       stdio: ["ignore", "pipe", "pipe"],
-      detached: true,
+      detached: !win32,
       windowsHide: true,
     })
     const out: Buffer[] = []
@@ -92,6 +101,11 @@ export function runGit(args: readonly string[], options: GitOptions): Promise<st
     // Settles at once: a killed git's children may hold its output pipes open for a while.
     function stop(why: string): void {
       if (settled) return
+      if (win32) {
+        if (child.pid) void (options.tree ?? processTree({ platform: "win32" })).killTree(child.pid)
+        else child.kill("SIGKILL")
+        return finish(new GitError(`${what} ${why}`))
+      }
       try {
         if (child.pid) process.kill(-child.pid, "SIGKILL")
       } catch {

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).