@huynle/hub 0.9.0 → 0.9.2

package/packages/cli/src/node.ts

@@ -5,12 +5,17 @@
 // entry), writes the file, and prints the launchctl / systemctl commands that load it. Nothing here starts a process:
 // loading, unloading and inspecting the service are always left to the user (printed, never run). --dry-run
 // prints the file instead of writing it. The same machinery (ServiceSpec) installs the harness spokes' services
-// (spoke-services.ts: `hub claude-code install`, `hub codex-spoke install`).
-import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs"
+// (spoke-services.ts: `hub claude-code install`, `hub codex-spoke install`). On Windows (PHASE3-CONTRACT.md) the node
+// is a per-user logon task: install writes its Task XML (UTF-16LE) under the hub state dir's tasks/ and prints the
+// schtasks commands that register and start it; the spokes have no task yet.
+import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs"
 import path from "node:path"
 import { nodeConfigPath, readNodeConfig, readSpokeCredentials, runNode } from "../../node/src/index.ts"
-import { renderServiceUnit } from "./bootstrap/adapters/node-services/render.ts"
-import { isAbsolutePath, programLayout, type ServiceID, type ServiceManagerID } from "./bootstrap/contracts/index.ts"
+import { renderServiceUnit, taskNameFor } from "./bootstrap/adapters/node-services/render.ts"
+import { isAbsolutePath, programLayout, toNativePath, type ProgramLayout, type ServiceID, type ServiceManagerID } from "./bootstrap/contracts/index.ts"
+import { normalizeAbs } from "./bootstrap/discovery/util.ts"
+import { resolveHubStateDir } from "../../../src/migrate.ts"
+import { defaultWinAcl } from "../../../src/win-acl.ts"
 import type { Env } from "./credentials"
 import { CliError, EXIT } from "./http"
 
@@ -57,16 +62,20 @@ export interface NodeIo {
   readonly platform: NodeJS.Platform
   readonly uid: number
   readonly program: Program
+  /** Windows: the current user's SID (the logon task's principal); default `whoami /user` (win-acl.ts). */
+  readonly userSid?: () => string
 }
 
-export type ServiceKind = "launchd" | "systemd"
+export type ServiceKind = "launchd" | "systemd" | "task-scheduler"
 
 export interface NodeService {
   readonly kind: ServiceKind
   /** Where the unit file goes. */
   readonly file: string
-  /** Its content, as install writes it. */
+  /** Its content, as install writes it (as text). */
   readonly content: string
+  /** Its bytes when they are not the UTF-8 of `content` (a Task XML is UTF-16LE). */
+  readonly bytes?: Uint8Array
   /** Directories the service needs (its log). */
   readonly dirs: readonly string[]
   /** Commands that load (or reload) it, for the user to run. */
@@ -150,16 +159,61 @@ function systemd(spec: ServiceSpec, io: NodeIo, extra?: ExtraEnvironment): NodeS
   }
 }
 
+/** The node as a Windows logon task: the Task XML in <hub state>/tasks and the schtasks commands (printed, not run). */
+function taskScheduler(spec: ServiceSpec, io: NodeIo, extra?: ExtraEnvironment): NodeService {
+  if (spec.service !== "node")
+    throw new CliError(EXIT.unavailable, `${spec.command} install does not support Windows yet: hubctl installs no user service for it there`, spec.elsewhere)
+  const home = normalizeAbs(io.home)
+  if (!home) throw new CliError(EXIT.usage, `cannot write the ${spec.command} task: the home directory ${io.home} is not a drive path`)
+  const state = normalizeAbs(resolveHubStateDir(io.env, io.home).dir)
+  if (!state) throw new CliError(EXIT.usage, `cannot write the ${spec.command} task: the hub state directory is not a drive path`)
+  const executable = normalizeAbs(io.program.execPath)
+  const found = programLayout(io.program)
+  const layout: ProgramLayout = found.kind === "standalone" && executable ? { kind: "standalone", executable } : found
+  const { environment, skipped } = carried(spec, io, extra)
+  let name: string
+  try {
+    name = taskNameFor(spec.service, io.env.USERNAME ?? "", io.env)
+  } catch (error) {
+    throw new CliError(EXIT.usage, `cannot write the ${spec.command} task: ${(error as Error).message}`)
+  }
+  const r = renderServiceUnit({ service: spec.service, manager: "task-scheduler", layout, home, writtenBy: spec.command, task: { name, userSid: (io.userSid ?? (() => defaultWinAcl().sid()))() } })
+  if (!r.ok) throw new CliError(EXIT.usage, `cannot write the ${spec.command} task: ${r.issues.map((i) => `${i.path ? `${i.path}: ` : ""}${i.message}`).join("; ")}`)
+  const file = toNativePath(`${state}/tasks/${r.value.path.rel}`, "win32")
+  const stopNode = `Get-CimInstance Win32_Process -Filter "Name='hubctl.exe'" | Where-Object CommandLine -like '* node run' | Invoke-CimMethod -MethodName Terminate   # PowerShell: /End stops only the hidden console host`
+  return {
+    kind: "task-scheduler",
+    file,
+    content: r.value.text,
+    bytes: r.value.bytes,
+    // The task carries no environment: these settings of this shell are not seen by it.
+    skipped: [...Object.keys(environment), ...skipped].sort(),
+    dirs: [],
+    load: [`schtasks /Create /TN ${name} /XML "${file}" /F`, `schtasks /Run /TN ${name}`],
+    unload: [`schtasks /End /TN ${name}`, stopNode, `schtasks /Delete /TN ${name} /F`],
+    check: [`schtasks /Query /TN ${name} /V /FO LIST`],
+  }
+}
+
 /** `spec`'s service for this platform; unsupported (exit 7) elsewhere. */
 export function serviceFor(spec: ServiceSpec, io: NodeIo, extra?: ExtraEnvironment): NodeService {
   if (io.platform === "darwin") return launchd(spec, io, extra)
   if (io.platform === "linux") return systemd(spec, io, extra)
+  if (io.platform === "win32") return taskScheduler(spec, io, extra)
   throw new CliError(EXIT.unavailable, `${spec.command} install supports macOS (launchd) and Linux (systemd), not ${io.platform}`, spec.elsewhere)
 }
 
 /** The node's service for this platform; unsupported (exit 7) elsewhere. */
 export const nodeService = (io: NodeIo): NodeService => serviceFor(NODE_SERVICE, io)
 
+const readBytes = (file: string): Buffer | undefined => {
+  try {
+    return readFileSync(file)
+  } catch {
+    return undefined
+  }
+}
+
 const readText = (file: string): string | undefined => {
   try {
     return readFileSync(file, "utf8")
@@ -194,14 +248,15 @@ export function installNode(io: NodeIo, options: { readonly dryRun: boolean }):
 /** Writes `spec`'s service file (or prints it, dry run) and prints the commands that load it; `warnings` go to stderr. */
 export function installService(spec: ServiceSpec, io: NodeIo, options: { readonly dryRun: boolean }, given: readonly string[], extra?: ExtraEnvironment): NodeCommandOutput {
   const service = serviceFor(spec, io, extra)
-  const warnings = [...given, ...service.skipped.map((key) => `${key} is not an absolute path, so the service does not carry it`)]
+  const why = service.kind === "task-scheduler" ? "is set in this shell, but a logon task has no environment of its own, so the node does not see it" : "is not an absolute path, so the service does not carry it"
+  const warnings = [...given, ...service.skipped.map((key) => `${key} ${why}`)]
   const load = commands(`Load it ${NOT_RUN}:`, service.load)
   if (options.dryRun) return { stdout: `would write ${service.file}:\n\n${service.content}\n${load}`, warnings }
-  const current = readText(service.file)
+  const current = service.bytes ? readBytes(service.file) : readText(service.file)
   for (const dir of service.dirs) mkdirSync(dir, { recursive: true })
-  if (current === service.content) return { stdout: `${service.file} is up to date\n${load}`, warnings }
+  if (service.bytes ? current !== undefined && Buffer.from(service.bytes).equals(current as Buffer) : current === service.content) return { stdout: `${service.file} is up to date\n${load}`, warnings }
   mkdirSync(path.dirname(service.file), { recursive: true })
-  writeFileSync(service.file, service.content, { mode: 0o644 })
+  writeFileSync(service.file, service.bytes ?? service.content, { mode: 0o644 })
   return { stdout: `${current === undefined ? "wrote" : "updated"} ${service.file}\n${load}`, warnings }
 }
 
@@ -225,6 +280,10 @@ export type ServiceState = { readonly kind: ServiceKind; readonly file: string;
 export function serviceState(spec: ServiceSpec, io: NodeIo, extra?: ExtraEnvironment): ServiceState {
   try {
     const s = serviceFor(spec, io, extra)
+    if (s.bytes) {
+      const bytes = readBytes(s.file)
+      return { kind: s.kind, file: s.file, installed: bytes !== undefined, current: bytes !== undefined && Buffer.from(s.bytes).equals(bytes), check: s.check }
+    }
     const text = readText(s.file)
     return { kind: s.kind, file: s.file, installed: text !== undefined, current: text === s.content, check: s.check }
   } catch {
@@ -273,7 +332,30 @@ export function nodeStatusText(status: NodeStatus): string {
   return lines.join("\n")
 }
 
+/** node.log is rotated to node.log.1 once it grows past this. */
+export const NODE_LOG_MAX_BYTES = 1024 * 1024
+
+/**
+ * The node's log: stderr everywhere; on win32 also <hub state dir>/node.log, because the logon task runs hubctl
+ * headless (conhost --headless) and its stderr goes nowhere. Writing the file never throws.
+ */
+export function nodeLogger(o: { readonly platform: string; readonly stateDir: string; stderr(s: string): void; readonly now?: () => Date }): (line: string) => void {
+  const file = path.join(o.stateDir, "node.log")
+  return (line) => {
+    o.stderr(`[hub node] ${line}\n`)
+    if (o.platform !== "win32") return
+    try {
+      mkdirSync(o.stateDir, { recursive: true })
+      try {
+        if (statSync(file).size > NODE_LOG_MAX_BYTES) renameSync(file, `${file}.1`)
+      } catch {}
+      appendFileSync(file, `${(o.now ?? (() => new Date()))().toISOString()} ${line}\n`)
+    } catch {}
+  }
+}
+
 /** `hub node run`: the daemon until `signal` aborts; runNode's exit code. */
-export function runNodeCommand(io: { readonly env: Env; readonly home: string; readonly signal?: AbortSignal; stderr(s: string): void }): Promise<number> {
-  return runNode({ env: io.env, home: io.home, signal: io.signal ?? new AbortController().signal, log: (line) => io.stderr(`[hub node] ${line}\n`) })
+export function runNodeCommand(io: { readonly env: Env; readonly home: string; readonly signal?: AbortSignal; readonly platform?: string; stderr(s: string): void }): Promise<number> {
+  const log = nodeLogger({ platform: io.platform ?? process.platform, stateDir: resolveHubStateDir(io.env, io.home).dir, stderr: (s) => io.stderr(s) })
+  return runNode({ env: io.env, home: io.home, signal: io.signal ?? new AbortController().signal, log })
 }

package/packages/cli/src/setup/commands.ts

@@ -42,7 +42,7 @@ import { OpencodePlanError } from "../bootstrap/adapters/opencode/plan.ts"
 import { parseJsonc } from "../bootstrap/transaction/json-merge.ts"
 import { renderRoleVars } from "../bootstrap/ansible/render.ts"
 import { createNodeProbe } from "../bootstrap/discovery/node-probe.ts"
-import { normalizeAbs } from "../bootstrap/discovery/util.ts"
+import { normalizeAbs, underDir } from "../bootstrap/discovery/util.ts"
 import { credentialStoreFor, defaultMachineName, machineEnroll, machineStatus, renderMachineResult, sharingOffWarning } from "../bootstrap/enrollment/index.ts"
 import { previewSetup, renderPreview, revalidateApply } from "../bootstrap/preview/index.ts"
 import { defaultProfile } from "../bootstrap/profiles/catalog.ts"
@@ -284,25 +284,45 @@ function discovered(io: SetupIo): DiscoverySnapshot {
   return r.value
 }
 
-/** A PathRef for an absolute path under a mapped root (the verification launch's workspace). */
-function refFor(abs: string, snapshot: DiscoverySnapshot): PathRef | undefined {
+/** A PathRef for an absolute path under a mapped root (the verification launch's workspace; Windows paths in any case). */
+export function refFor(abs: string, snapshot: DiscoverySnapshot): PathRef | undefined {
   const ctx = executionContextOf(snapshot)
   for (const id of ["home"] as const) {
     const root = snapshot.roots.find((r) => r.id === id)
     const base = root ? rootPathIn(root, ctx) : undefined
-    if (base && abs.startsWith(`${base}/`)) return { root: id, rel: abs.slice(base.length + 1) }
+    if (base && underDir(abs, base)) return { root: id, rel: abs.slice(base.length + (base.endsWith("/") ? 0 : 1)) }
   }
   return undefined
 }
 
+/**
+ * A --workspace-root as a canonical absolute path. POSIX: resolved against the working directory, as before. Windows
+ * (PHASE3-CONTRACT.md): a native ("C:\\x"), canonical ("C:/x") or lower-case drive path, "~/…" or "~\\…" under
+ * the home, or a path relative to the working directory; UNC and device paths are refused (undefined).
+ */
+export function workspaceRootOf(raw: string, where: { readonly platform: string; readonly cwd: string; readonly home: string }): string | undefined {
+  if (where.platform !== "win32") return path.resolve(where.cwd, raw)
+  if (/^[\\/]{2}/.test(raw)) return undefined
+  const home = normalizeAbs(where.home)
+  const tilde = /^~(?:[\\/](.*))?$/.exec(raw)
+  if (tilde) return home ? normalizeAbs(path.win32.join(home, tilde[1] ?? "")) : undefined
+  const resolved = path.win32.resolve(path.win32.normalize(where.cwd), raw)
+  return /^[\\/]{2}/.test(resolved) ? undefined : normalizeAbs(resolved)
+}
+
 function choicesOf(io: SetupIo, flags: Parsed["flags"], profile: Profile, snapshot: DiscoverySnapshot): SetupChoices {
   const enrollment = str(flags, "enrollment")
   if (enrollment !== undefined && !(ENROLLMENT_MODES as readonly string[]).includes(enrollment)) throw new Refusal("usage", `--enrollment is ${ENROLLMENT_MODES.join(" or ")}`)
-  let roots = (flags["workspace-root"] as string[] | undefined)?.map((r) => path.resolve(io.cwd ?? process.cwd(), r))
+  const where = { platform: snapshot.host.platform, cwd: io.cwd ?? process.cwd(), home: io.home }
+  let roots = (flags["workspace-root"] as string[] | undefined)?.map((r) => {
+    const root = workspaceRootOf(r, where)
+    if (root === undefined) throw new Refusal("usage", `--workspace-root ${r} is not a local absolute path (a drive path such as C:\\Users\\you\\projects, or ~/projects)`)
+    return root
+  })
   if (!roots?.length && profile.services.includes("node")) {
-    // Without --workspace-root, the workspace roots node.json already lists.
+    // Without --workspace-root, the workspace roots node.json already lists (canonical on Windows, as the plan holds them).
     const existing = readNodeConfig(nodeConfigPath(io.env as Record<string, string | undefined>, io.home)).config.workspaceRoots
-    if (existing.length > 0) roots = [...existing]
+    if (existing.length > 0) roots = where.platform === "win32" ? existing.map((r) => workspaceRootOf(r, where) ?? r) : [...existing]
   }
   const launchHarness = str(flags, "verify-launch")
   let launch: SetupChoices["launch"]

package/packages/cli/src/setup/runtime.ts

@@ -32,6 +32,7 @@ import {
   type ProgramLayout,
   type Result,
   type RootMapping,
+  type ServiceID,
   type ServiceManagerID,
   type VerifiedManifest,
 } from "../bootstrap/contracts/index.ts"
@@ -49,10 +50,13 @@ import {
   type ManagerRunner,
   type NodeServiceControl,
   type NodeServicesPlan,
+  taskNameFor,
+  type TaskIdentity,
 } from "../bootstrap/adapters/node-services/index.ts"
 import { createOpencodeHarness, type Download, type ProcessRunner } from "../bootstrap/adapters/opencode/index.ts"
 import type { ReadinessGate } from "../bootstrap/adapters/readiness.ts"
-import { discover } from "../bootstrap/discovery/discover.ts"
+import { discover, systemRootOf } from "../bootstrap/discovery/discover.ts"
+import { defaultWinAcl } from "../../../../src/win-acl.ts"
 import { pathDirs, which } from "../bootstrap/discovery/executables.ts"
 import type { DiscoveryProbe } from "../bootstrap/discovery/probe.ts"
 import { machineEnroll, type EnrollPrompt } from "../bootstrap/enrollment/enroll.ts"
@@ -89,6 +93,14 @@ export interface RuntimePorts {
   readonly hubctlBytes?: () => Uint8Array | undefined
   readonly fs?: TxFs
   readonly uid?: number
+  /** Windows: the current user's SID (the logon task's principal); default `whoami /user` (win-acl.ts). */
+  readonly userSid?: () => string
+}
+
+/** The Windows programs the task-scheduler control runs: absolute, under %SystemRoot%\System32 (canonical form). */
+export function windowsServicePrograms(systemRoot: string): { readonly schtasks: string; readonly powershell: string; readonly taskkill: string } {
+  const dir = `${systemRoot.replace(/\/+$/, "")}/System32`
+  return { schtasks: `${dir}/schtasks.exe`, powershell: `${dir}/WindowsPowerShell/v1.0/powershell.exe`, taskkill: `${dir}/taskkill.exe` }
 }
 
 export interface RuntimeDeps {
@@ -324,6 +336,7 @@ export function createSetupRuntime(deps: RuntimeDeps): SetupRuntime {
           ...(choices.activate ? { activate: true } : {}),
           environment: deps.env,
           ...(choices.launch ? { launch: choices.launch } : {}),
+          ...(input.snapshot.managers.service === "task-scheduler" && input.profile.services.length > 0 ? { task: taskIdentity() } : {}),
         })
         if (!planned.ok) return planned
         nodePlan = planned.value
@@ -343,14 +356,28 @@ export function createSetupRuntime(deps: RuntimeDeps): SetupRuntime {
     return { sources: { adapters: registry, contributors, ...(choices.enrollment ? { enrollment: choices.enrollment } : {}) }, node: () => nodePlan, history: records }
   }
 
+  /** The node's logon task for this Windows user: hub-node-<USERNAME> (a hub-test-… name only under test) and the SID. */
+  function taskIdentity(): TaskIdentity {
+    return { name: taskNameFor("node", deps.env.USERNAME ?? "", deps.env), userSid: (ports.userSid ?? (() => defaultWinAcl().sid()))() }
+  }
+
   function control(snap: DiscoverySnapshot): NodeServiceControl | undefined {
     if (snap.managers.service === "none") return undefined
+    const tasks = snap.managers.service === "task-scheduler"
     let run = ports.serviceRunner
     if (!run) {
-      const systemctl = which(deps.probe, [...pathDirs(deps.probe), "/usr/bin", "/bin"], "systemctl") ?? "/usr/bin/systemctl"
-      run = spawnManagerRunner({ programs: { launchctl: "/bin/launchctl", systemctl }, env: deps.env })
+      if (tasks) run = spawnManagerRunner({ programs: windowsServicePrograms(systemRootOf(deps.probe)), env: deps.env })
+      else {
+        const systemctl = which(deps.probe, [...pathDirs(deps.probe), "/usr/bin", "/bin"], "systemctl") ?? "/usr/bin/systemctl"
+        run = spawnManagerRunner({ programs: { launchctl: "/bin/launchctl", systemctl }, env: deps.env })
+      }
     }
-    return createServiceControl({ run, uid: ports.uid ?? deps.probe.uid, unitPath: unitPathResolver(snap.roots, executionContextOf(snap)) })
+    return createServiceControl({
+      run,
+      uid: ports.uid ?? deps.probe.uid,
+      unitPath: unitPathResolver(snap.roots, executionContextOf(snap)),
+      ...(tasks ? { taskName: (service: ServiceID) => taskNameFor(service, deps.env.USERNAME ?? "", deps.env) } : {}),
+    })
   }
 
   function hubctlSource(): HubctlSource | undefined {

package/packages/codex/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-codex",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "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.9.0",
+  "version": "0.9.2",
   "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 {