@huynle/hub 0.9.0 → 0.9.2

package/packages/cli/src/bootstrap/adapters/node-services/render.ts

@@ -9,6 +9,16 @@
 // binary run hub-cli.js, so only the script layout keeps it. A standalone hubctl with it would run `bun node run`
 // (a missing module) and crash-loop, so its units never mention it.
 //
+// Task Scheduler (windows-x64, PHASE3-CONTRACT.md) gets a Task XML instead: a logon task for one user (their SID,
+// InteractiveToken, LeastPrivilege: no admin, no stored password) whose action is the hidden console host
+// (`conhost.exe --headless`, verified on Windows 11 to open no window, where starting hubctl.exe directly opens a
+// console or Windows Terminal) running `hubctl.exe node run`: native paths, quoted by the MSVCRT argv rules. A task has
+// no environment of its own, so it carries none (the planner names what it leaves out), and only the standalone
+// hubctl.exe can be its program. schtasks /XML refuses UTF-8 ("unable to switch the encoding"), so the file is
+// UTF-16LE with a BOM. The hidden console host does not pass its child's exit code on (always 0), so RestartOnFailure
+// never sees a crash: the logon trigger repeats every minute instead, and IgnoreNew makes that a no-op while the
+// node runs, so a node that exited for any reason is started again within a minute.
+//
 // Rendering is pure: the same input always gives the same bytes, so a plan can pin the unit's digest
 // (install-service.sha256) and apply can render it again and compare.
 import {
@@ -19,7 +29,10 @@ import {
   pointer,
   serviceArgv,
   SERVICE_COMMANDS,
+  SERVICE_ROOT,
   sha256Hex,
+  toNativePath,
+  isWindowsPath,
   type PathRef,
   type ProgramLayout,
   type Result,
@@ -36,7 +49,47 @@ export const SERVICE_ENVIRONMENT: Readonly<Record<ServiceID, readonly string[]>>
 })
 
 /** The named root each manager's units live in. */
-export const UNIT_ROOT: Readonly<Record<ServiceManagerID, "launch-agents" | "systemd-user">> = Object.freeze({ launchd: "launch-agents", "systemd-user": "systemd-user" })
+export const UNIT_ROOT = SERVICE_ROOT
+
+/** A Task Scheduler task hubctl registers: `hub-<service>-<user>`, or a test task `hub-test-<x>-<user>`. */
+export const TASK_NAME = /^hub-(?:node|claude-code|codex-spoke|test-[a-z0-9-]{1,32})-[A-Za-z0-9._-]{1,64}$/
+const TEST_PREFIX = /^hub-test-[a-z0-9-]{1,32}$/
+const SID = /^S-1-[0-9]{1,12}(?:-[0-9]{1,10}){1,15}$/
+
+/**
+ * The task name of `service` for the Windows user `user` (%USERNAME%; characters other than [A-Za-z0-9._-] become
+ * "_"). HUBCTL_TEST_TASK_PREFIX (tests on a real machine only) replaces "hub-<service>", and must start with hub-test-.
+ */
+export function taskNameFor(service: ServiceID, user: string, env: Readonly<Record<string, string | undefined>>): string {
+  const safe = user.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 64)
+  if (!safe) throw new Error("the Windows user name is empty; set USERNAME")
+  const prefix = env.HUBCTL_TEST_TASK_PREFIX
+  if (prefix !== undefined && !TEST_PREFIX.test(prefix)) throw new Error("HUBCTL_TEST_TASK_PREFIX must start with hub-test- (lower-case letters, digits and -)")
+  return `${prefix ?? `hub-${service}`}-${safe}`
+}
+
+/** One word of a Windows command line, quoted as the MSVCRT (CommandLineToArgvW) rules read it back. */
+export function quoteWindowsArg(word: string): string {
+  if (word !== "" && !/[\s"]/.test(word)) return word
+  let out = '"'
+  let slashes = 0
+  for (const ch of word) {
+    if (ch === "\\") slashes++
+    else {
+      out += "\\".repeat(ch === '"' ? slashes * 2 + 1 : slashes) + ch
+      slashes = 0
+    }
+  }
+  return `${out}${"\\".repeat(slashes * 2)}"`
+}
+
+/** The logon task a Task XML registers (task-scheduler only). */
+export interface TaskIdentity {
+  /** The task's name (taskNameFor). */
+  readonly name: string
+  /** The user's SID: the trigger's and the principal's UserId. */
+  readonly userSid: string
+}
 
 export interface RenderInput {
   readonly service: ServiceID
@@ -49,6 +102,8 @@ export interface RenderInput {
   readonly environment?: Readonly<Record<string, string>>
   /** The command that writes the unit by hand ("hub node"): its header then names its install/uninstall (default: hubctl setup). */
   readonly writtenBy?: string
+  /** task-scheduler: the task and its user. */
+  readonly task?: TaskIdentity
 }
 
 export interface RenderedUnit {
@@ -58,7 +113,7 @@ export interface RenderedUnit {
   readonly manager: ServiceManagerID
   /** Where it is installed: the manager's root and the asset's file name. */
   readonly path: PathRef
-  /** The launchd label or the systemd unit name (what the service manager calls it). */
+  /** The launchd label, the systemd unit name or the task name (what the service manager calls it). */
   readonly name: string
   readonly argv: readonly string[]
   readonly text: string
@@ -68,8 +123,8 @@ export interface RenderedUnit {
 
 export const assetIDFor = (service: ServiceID, manager: ServiceManagerID): string => `service/${manager}/${service}`
 
-/** The launchd label or systemd unit name of a service under a manager. */
-export function serviceName(service: ServiceID, manager: ServiceManagerID): string {
+/** The launchd label or systemd unit name of a service under a manager (a task's name depends on its user: taskNameFor). */
+export function serviceName(service: ServiceID, manager: "launchd" | "systemd-user"): string {
   const file = EMBEDDED_ASSETS[assetIDFor(service, manager)]!.installAs
   return manager === "launchd" ? file.replace(/\.plist$/, "") : file
 }
@@ -87,7 +142,7 @@ const SYSTEMD_HOME = /^\/[A-Za-z0-9_./@+,:-]*$/
 const PLACEHOLDER = /__[A-Z]+__/
 
 /** The template's BUN_BE_BUN=1 setting, per manager (removed for the standalone layout). */
-const BUN_BE_BUN: Readonly<Record<ServiceManagerID, RegExp>> = Object.freeze({
+const BUN_BE_BUN: Readonly<Record<"launchd" | "systemd-user", RegExp>> = Object.freeze({
   "systemd-user": /^Environment=BUN_BE_BUN=1\n/m,
   launchd: /\n[ \t]*<key>BUN_BE_BUN<\/key>\s*<string>1<\/string>/,
 })
@@ -136,6 +191,39 @@ function renderLaunchd(c: Checker, asset: string, template: string, argv: readon
     .replace(/(<key>PATH<\/key>\s*<string>[^<]*<\/string>)/, (line) => `${line}${extra}`)
 }
 
+/** XML character data (quotes stay as they are: an <Arguments> value is a command line). */
+const xmlText = (text: string) => text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")
+
+function renderTask(c: Checker, input: RenderInput, asset: string, template: string): string | undefined {
+  if (input.layout.kind !== "standalone") c.add("/layout", "unsupported_platform", "a Windows logon task starts the standalone hubctl.exe only, not a script under a runtime")
+  if (Object.keys(input.environment ?? {}).length > 0) c.add("/environment", "invalid_value", "a Task Scheduler task carries no environment of its own")
+  const task = input.task
+  if (!task) c.add("/task", "missing_field", "a Task Scheduler task needs its name and the user's SID")
+  else {
+    if (!TASK_NAME.test(task.name)) c.add("/task/name", "invalid_value", "expected a hub task name (hub-<service>-<user>)")
+    if (!SID.test(task.userSid)) c.add("/task/userSid", "invalid_value", "expected the user's SID (S-1-…)")
+  }
+  if (!isAbsolutePath(input.home) || !isWindowsPath(input.home)) c.add("/home", "invalid_path", "a Windows logon task needs a Windows home directory (C:/…)")
+  if (!/<Arguments>--headless __ARGV__<\/Arguments>/.test(template)) c.add("/asset", "inconsistent", `${asset} does not start hubctl under the hidden console host`)
+  if (c.issues.length > 0) return undefined
+  const argv = serviceArgv(input.layout, input.service)
+  const words = argv.map((w, i) => (i === 0 ? toNativePath(w, "win32") : w))
+  if (words.some((w) => w.includes('"'))) c.add("/layout", "invalid_path", "the program path may not contain a double quote")
+  return template
+    .replace(/<!--[\s\S]*?-->/, () => `<!-- ${header(asset, input.writtenBy)} -->`)
+    .replaceAll("__USER__", () => task!.userSid)
+    .replace("__ARGV__", () => xmlText(words.map(quoteWindowsArg).join(" ")))
+}
+
+/** UTF-16LE with a byte order mark: what schtasks /XML reads. */
+const utf16le = (text: string) => {
+  const body = Buffer.from(text, "utf16le")
+  const bytes = new Uint8Array(body.length + 2)
+  bytes.set([0xff, 0xfe])
+  bytes.set(body, 2)
+  return bytes
+}
+
 /** The unit for `service` under `manager`, rendered from its embedded template. */
 export function renderServiceUnit(input: RenderInput): Result<RenderedUnit> {
   const c = new Checker()
@@ -146,24 +234,43 @@ export function renderServiceUnit(input: RenderInput): Result<RenderedUnit> {
     c.add("/service", "invalid_value", `no embedded template for ${input.service} under ${input.manager}`)
     return c.result(undefined)
   }
+  if (input.manager === "task-scheduler") {
+    const text = renderTask(c, input, asset, template)
+    if (text === undefined || c.issues.length > 0) return c.result(undefined)
+    if (PLACEHOLDER.test(text)) c.add("/asset", "inconsistent", `${asset} has a placeholder this hubctl does not fill`)
+    if (c.issues.length > 0) return c.result(undefined)
+    const bytes = utf16le(text)
+    return c.result<RenderedUnit>({
+      asset,
+      service: input.service,
+      manager: input.manager,
+      path: { root: UNIT_ROOT[input.manager], rel: entry.installAs },
+      name: input.task!.name,
+      argv: serviceArgv(input.layout, input.service),
+      text,
+      bytes,
+      sha256: `sha256:${sha256Hex(bytes)}`,
+    })
+  }
+  const manager = input.manager
   let argv: string[] = []
   try {
     argv = serviceArgv(input.layout, input.service)
   } catch (error) {
     c.add("/layout", "invalid_path", (error as Error).message)
   }
-  const homeOK = isAbsolutePath(input.home) && input.home !== "/" && (input.manager !== "systemd-user" || SYSTEMD_HOME.test(input.home))
+  const homeOK = isAbsolutePath(input.home) && input.home !== "/" && (manager !== "systemd-user" || SYSTEMD_HOME.test(input.home))
   if (!homeOK) c.add("/home", "invalid_path", "the service's home must be an absolute, normalized directory other than /")
   const env = checkEnvironment(c, input.service, input.environment ?? {})
   if (c.issues.length > 0) return c.result(undefined)
 
   const command = SERVICE_COMMANDS[input.service]
   const raw =
-    input.manager === "systemd-user"
+    manager === "systemd-user"
       ? renderSystemd(c, asset, template, argv, command, input.home, env, input.writtenBy)
       : renderLaunchd(c, asset, template, argv, command, input.home, env, input.writtenBy)
   const asBun = input.layout.kind === "script"
-  const text = asBun ? raw : raw.replace(BUN_BE_BUN[input.manager], "")
+  const text = asBun ? raw : raw.replace(BUN_BE_BUN[manager], "")
   if (!asBun && text.includes("BUN_BE_BUN")) c.add("/asset", "inconsistent", `${asset} sets BUN_BE_BUN, which a standalone hubctl must not get`)
   if (PLACEHOLDER.test(text)) c.add("/asset", "inconsistent", `${asset} has a placeholder this hubctl does not fill`)
   if (isSecretValue(text)) c.add("/environment", "secret", "service units never carry credentials")
@@ -174,7 +281,7 @@ export function renderServiceUnit(input: RenderInput): Result<RenderedUnit> {
     service: input.service,
     manager: input.manager,
     path: { root: UNIT_ROOT[input.manager], rel: entry.installAs },
-    name: serviceName(input.service, input.manager),
+    name: serviceName(input.service, manager),
     argv,
     text,
     bytes,

package/packages/cli/src/bootstrap/adapters/node-services/validate.ts

@@ -19,6 +19,7 @@ import {
   fail,
   findSecrets,
   isAbsolutePath,
+  isWindowsPath,
   isRecord,
   pointer,
   rootPathIn,
@@ -52,9 +53,14 @@ export interface NodePlaces {
   readonly snapshot: Pick<DiscoverySnapshot, "roots" | "topology">
 }
 
+/** Windows paths compare case-insensitively (NTFS names are); POSIX paths exactly. */
+const folded = (p: string) => (isWindowsPath(p) ? p.toLowerCase() : p)
 /** Whether `path` is `dir` or inside it. */
-export const inside = (path: string, dir: string) => path === dir || path.startsWith(dir === "/" ? "/" : `${dir}/`)
-const parentOf = (path: string) => path.slice(0, path.lastIndexOf("/")) || "/"
+export const inside = (path: string, dir: string) => {
+  const [p, d] = [folded(path), folded(dir)]
+  return p === d || p.startsWith(d.endsWith("/") ? d : `${d}/`)
+}
+const parentOf = (path: string) => folded(path.slice(0, path.lastIndexOf("/")) || "/")
 
 /** Mount prefixes as the *other* context sees them (a path under one is not valid where the service runs). */
 function otherViews(roots: readonly RootMapping[], context: ExecutionContext): string[] {

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

@@ -16,7 +16,8 @@ export type Escalation = "user" | "elevated"
 export type ConfigOwner = "user" | "hub" | `harness:${HarnessID}`
 export const CONFIG_OWNERS: readonly ConfigOwner[] = ["user", "hub", ...HARNESS_ORDER.map((h) => `harness:${h}` as const)]
 export type ConfigFormat = "json" | "jsonc" | "toml"
-export type ServiceManagerID = "launchd" | "systemd-user"
+export const SERVICE_MANAGERS = ["launchd", "systemd-user", "task-scheduler"] as const
+export type ServiceManagerID = (typeof SERVICE_MANAGERS)[number]
 
 /** What the target file must look like for an edit to apply; anything else is a conflicting user edit. */
 export interface Precondition {
@@ -246,7 +247,8 @@ const ASSET_ID = /^[a-z0-9][a-z0-9._-]*(?:\/[a-z0-9][a-z0-9._-]*)*$/
 const MACHINE_NAME = /^[A-Za-z0-9._-]{1,64}$/
 const MCP_NAME = /^[a-z0-9][a-z0-9-]{0,31}$/
 const JSON_POINTER = /^(?:\/(?:[^~/]|~[01])*)+$/
-const SERVICE_ROOT: Record<ServiceManagerID, string> = { launchd: "launch-agents", "systemd-user": "systemd-user" }
+/** The named root each manager's unit files live in (the Task XML hubctl registers, on Windows). */
+export const SERVICE_ROOT: Readonly<Record<ServiceManagerID, "launch-agents" | "systemd-user" | "task-defs">> = Object.freeze({ launchd: "launch-agents", "systemd-user": "systemd-user", "task-scheduler": "task-defs" })
 const EXEC = new Set<string>(EXEC_KEYS)
 
 /** JSON pointers of every key named like EXEC_KEYS inside `value`. */
@@ -413,7 +415,7 @@ export function checkAction(c: Checker, path: string, value: unknown): void {
       break
     case "install-service": {
       oneOf(c, at("service"), r.service, SERVICE_IDS)
-      oneOf(c, at("manager"), r.manager, ["launchd", "systemd-user"] as const)
+      oneOf(c, at("manager"), r.manager, SERVICE_MANAGERS)
       ref("path")
       digest(c, at("sha256"), r.sha256)
       const asset = typeof r.asset === "string" ? EMBEDDED_ASSETS[r.asset] : undefined
@@ -424,18 +426,18 @@ export function checkAction(c: Checker, path: string, value: unknown): void {
     }
     case "deactivate-service":
       oneOf(c, at("service"), r.service, SERVICE_IDS)
-      oneOf(c, at("manager"), r.manager, ["launchd", "systemd-user"] as const)
+      oneOf(c, at("manager"), r.manager, SERVICE_MANAGERS)
       break
     case "remove-service":
       oneOf(c, at("service"), r.service, SERVICE_IDS)
-      oneOf(c, at("manager"), r.manager, ["launchd", "systemd-user"] as const)
+      oneOf(c, at("manager"), r.manager, SERVICE_MANAGERS)
       ref("path")
       digest(c, at("sha256"), r.sha256)
       checkServiceUnitPath(c, at, r)
       break
     case "activate-service":
       oneOf(c, at("service"), r.service, SERVICE_IDS)
-      oneOf(c, at("manager"), r.manager, ["launchd", "systemd-user"] as const)
+      oneOf(c, at("manager"), r.manager, SERVICE_MANAGERS)
       if (r.confirm !== "explicit") c.add(at("confirm"), "invalid_value", "services are only activated on explicit confirmation")
       break
     case "enroll-machine":

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

@@ -71,7 +71,7 @@ export interface RuntimePresence {
 export interface ConfigFile {
   readonly path: string
   readonly owner: ConfigOwner | "package-manager"
-  readonly format: "json" | "jsonc" | "toml" | "plist" | "unit"
+  readonly format: "json" | "jsonc" | "toml" | "plist" | "unit" | "xml"
   /** Digest of its bytes now; null when it does not exist. Contents are never recorded. */
   readonly sha256: string | null
 }
@@ -180,10 +180,11 @@ export function validateDiscoverySnapshot(value: unknown): Result<DiscoverySnaps
       semver(c, pointer(p, "version"), rt.version)
       absPath(c, pointer(p, "path"), rt.path)
     })
-    oneOf(c, "/managers/service", managers.service, ["launchd", "systemd-user", "none"] as const)
+    oneOf(c, "/managers/service", managers.service, ["launchd", "systemd-user", "task-scheduler", "none"] as const)
     const platform = host?.platform
     if (managers.service === "launchd" && platform !== "darwin") c.add("/managers/service", "inconsistent", "launchd is macOS only")
     if (managers.service === "systemd-user" && platform !== "linux") c.add("/managers/service", "inconsistent", "systemd is Linux only")
+    if (managers.service === "task-scheduler" && platform !== "win32") c.add("/managers/service", "inconsistent", "Task Scheduler is Windows only")
   }
 
   list(c, "/harnesses", r.harnesses, HARNESS_ORDER.length, (p, v) => checkHarness(c, p, v), (v) => (v as { id?: string })?.id)
@@ -199,7 +200,7 @@ export function validateDiscoverySnapshot(value: unknown): Result<DiscoverySnaps
     if (!cf) return
     absPath(c, pointer(p, "path"), cf.path)
     oneOf(c, pointer(p, "owner"), cf.owner, [...CONFIG_OWNERS, "package-manager"])
-    oneOf(c, pointer(p, "format"), cf.format, ["json", "jsonc", "toml", "plist", "unit"] as const)
+    oneOf(c, pointer(p, "format"), cf.format, ["json", "jsonc", "toml", "plist", "unit", "xml"] as const)
     if (cf.sha256 !== null) digest(c, pointer(p, "sha256"), cf.sha256)
   }, (v) => (v as { path?: string })?.path)
   list(c, "/roots", r.roots, ROOT_IDS.length, (p, v) => {

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

@@ -51,12 +51,12 @@ export function serviceArgv(layout: ProgramLayout, service: ServiceID): string[]
   return [...program, ...command]
 }
 
-export type AssetKind = "launchd-plist" | "systemd-unit"
+export type AssetKind = "launchd-plist" | "systemd-unit" | "task-xml"
 
 export interface EmbeddedAsset {
   readonly kind: AssetKind
   readonly service: ServiceID
-  readonly manager: "launchd" | "systemd-user"
+  readonly manager: "launchd" | "systemd-user" | "task-scheduler"
   /** The repository file it is embedded from (the template the source install reads today). */
   readonly source: string
   /** The file name it is installed as. */
@@ -71,4 +71,6 @@ export const EMBEDDED_ASSETS: Readonly<Record<string, EmbeddedAsset>> = Object.f
   "service/systemd-user/claude-code": { kind: "systemd-unit", service: "claude-code", manager: "systemd-user", source: "scripts/hub-claude-code.service", installAs: "hub-claude-code.service" },
   "service/launchd/codex-spoke": { kind: "launchd-plist", service: "codex-spoke", manager: "launchd", source: "scripts/io.github.huynle.hub-codex-spoke.plist", installAs: "io.github.huynle.hub-codex-spoke.plist" },
   "service/systemd-user/codex-spoke": { kind: "systemd-unit", service: "codex-spoke", manager: "systemd-user", source: "scripts/hub-codex-spoke.service", installAs: "hub-codex-spoke.service" },
+  // Phase 3: the node as a per-user logon task on Windows. The spokes have no task yet (Phase 4).
+  "service/task-scheduler/node": { kind: "task-xml", service: "node", manager: "task-scheduler", source: "scripts/hub-node.task.xml", installAs: "hub-node.xml" },
 })

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

@@ -4,7 +4,8 @@
 // symlink between the root and the target (checkNoSymlinkEscape), so a planted link cannot redirect a write.
 import { Checker, fail, isAbsolutePath, ok, oneOf, pointer, shape, type Result } from "./validate.ts"
 
-export const ROOT_IDS = ["home", "config", "state", "data", "user-bin", "launch-agents", "systemd-user", "system-bin"] as const
+/** `task-defs` (Phase 3, Windows): `state/hub/tasks`, where hubctl writes the Task XML it registers with Task Scheduler. */
+export const ROOT_IDS = ["home", "config", "state", "data", "user-bin", "launch-agents", "systemd-user", "system-bin", "task-defs"] as const
 export type RootID = (typeof ROOT_IDS)[number]
 
 /**

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

@@ -7,8 +7,8 @@ export type Platform = "darwin" | "linux" | "windows"
 export type Arch = "arm64" | "x64"
 /** "none" on macOS; "unknown" when a Linux host's C library could not be identified. */
 export type Libc = "none" | "glibc" | "musl" | "unknown"
-export type ServiceManager = "launchd" | "systemd-user"
-/** A target's service manager: "none" where hubctl installs no user services yet (Windows until Phase 3). */
+export type ServiceManager = "launchd" | "systemd-user" | "task-scheduler"
+/** A target's service manager: "none" where hubctl installs no user services (no target today; Windows until Phase 3). */
 export type TargetServiceManager = ServiceManager | "none"
 
 export interface SupportedTarget {
@@ -31,9 +31,9 @@ export const SUPPORTED_TARGETS: readonly SupportedTarget[] = Object.freeze([
   { target: "darwin-x64", platform: "darwin", arch: "x64", libc: "none", serviceManager: "launchd", bunTarget: "bun-darwin-x64-baseline" },
   { target: "linux-x64", platform: "linux", arch: "x64", libc: "glibc", serviceManager: "systemd-user", bunTarget: "bun-linux-x64-baseline" },
   { target: "linux-arm64", platform: "linux", arch: "arm64", libc: "glibc", serviceManager: "systemd-user", bunTarget: "bun-linux-arm64" },
-  // Phase 2 (docs/plans/2026-11-05-machine-setup-installer-design.md §3): the session-only profile; user services
-  // (Task Scheduler) arrive in Phase 3.
-  { target: "windows-x64", platform: "windows", arch: "x64", libc: "none", serviceManager: "none", bunTarget: "bun-windows-x64-baseline" },
+  // Phase 2 (docs/plans/2026-11-05-machine-setup-installer-design.md §3) brought session-only; Phase 3 the node as a
+  // per-user logon task (PHASE3-CONTRACT.md). The harness spokes have no task yet (Phase 4).
+  { target: "windows-x64", platform: "windows", arch: "x64", libc: "none", serviceManager: "task-scheduler", bunTarget: "bun-windows-x64-baseline" },
 ] as const)
 
 export interface UnsupportedTarget {

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

@@ -29,7 +29,7 @@ import {
 import { classifyExecutable, HARNESS_BINARIES, installOf, pathDirs, which } from "./executables.ts"
 import { discoverContainer, discoverLibc, discoverOS, discoverRoots, mapContainerRoots, parseMountinfo } from "./host.ts"
 import type { DiscoveryProbe } from "./probe.ts"
-import { decode, join, normalizeAbs } from "./util.ts"
+import { decode, hostAbs, join, normalizeAbs } from "./util.ts"
 
 export interface DiscoverOptions {
   readonly now: number
@@ -65,6 +65,7 @@ export function configCandidates(platform: string, roots: readonly RootMapping[]
   for (const asset of Object.values(EMBEDDED_ASSETS)) {
     if (platform === "darwin" && asset.manager === "launchd") add("launch-agents", asset.installAs, "hub", "plist")
     if (platform === "linux" && asset.manager === "systemd-user") add("systemd-user", asset.installAs, "hub", "unit")
+    if (platform === "win32" && asset.manager === "task-scheduler") add("task-defs", asset.installAs, "hub", "xml")
   }
   return list.filter((c): c is ConfigCandidate => c !== undefined)
 }
@@ -74,6 +75,9 @@ export function configCandidates(platform: string, roots: readonly RootMapping[]
 /** Where each harness's binary is inside a hub install root (the adapters' unpackers). */
 const HARNESS_BIN_DIR: Readonly<Record<(typeof HARNESS_ORDER)[number], string>> = { opencode: "/bin", "claude-code": "", codex: "/bin" }
 
+/** %SystemRoot% in canonical form (C:/Windows when unset or not a drive path). */
+export const systemRootOf = (probe: Pick<DiscoveryProbe, "platform" | "env">): string => hostAbs("win32", probe.env.SystemRoot ?? probe.env.SYSTEMROOT) ?? "C:/Windows"
+
 /** Discovers this host through `probe`. Fails (instead of recording) if anything found looks like a credential. */
 export function discover(probe: DiscoveryProbe, options: DiscoverOptions): Result<DiscoverySnapshot> {
   let roots = discoverRoots(probe)
@@ -92,10 +96,11 @@ export function discover(probe: DiscoveryProbe, options: DiscoverOptions): Resul
   const managerDirs = [...dirs, ...extra.filter((d) => !dirs.includes(d))]
   const packages: PackageManager[] = PACKAGE_MANAGERS.filter((m) => which(probe, managerDirs, m) !== undefined)
   const runtime: RuntimeInfo[] = probe.runtime && SEMVER.test(probe.runtime.version) && normalizeAbs(probe.runtime.path) ? [{ ...probe.runtime }] : []
-  // Windows has no user service manager hubctl drives yet (PHASE2-CONTRACT.md): "none".
+  // Windows (PHASE3-CONTRACT.md): Task Scheduler, when %SystemRoot%\System32\schtasks.exe is there.
   let service: DiscoverySnapshot["managers"]["service"] = "none"
   if (probe.platform === "darwin" && probe.executable("/bin/launchctl")) service = "launchd"
   if (probe.platform === "linux" && probe.lstat("/run/systemd/system") === "directory" && which(probe, [...dirs, "/usr/bin", "/bin"], "systemctl")) service = "systemd-user"
+  if (probe.platform === "win32" && probe.executable(join(systemRootOf(probe), "System32/schtasks.exe"))) service = "task-scheduler"
 
   const shims: Shim[] = []
   const harnesses: HarnessPresence[] = HARNESS_ORDER.map((id) => {

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

@@ -27,6 +27,8 @@ export function discoverRoots(probe: DiscoveryProbe): RootMapping[] | undefined
   }
   if (probe.platform === "darwin") paths["launch-agents"] = join(home, "Library/LaunchAgents")
   if (probe.platform === "linux") paths["systemd-user"] = join(config, "systemd/user")
+  // Phase 3: where hubctl writes the Task XML it registers with Task Scheduler.
+  if (windows) paths["task-defs"] = join(paths.state!, "hub/tasks")
   return ROOT_IDS.flatMap((id) => (paths[id] ? [{ id, path: paths[id]! }] : []))
 }
 

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

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

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

@@ -7,11 +7,13 @@
 import {
   checkTarget,
   Checker,
+  EMBEDDED_ASSETS,
   fail,
   REQUIRED_PROBES,
   validateDiscoverySnapshot,
   validateProfile,
   type DiscoverySnapshot,
+  type Issue,
   type HarnessID,
   type Profile,
   type ProbeKind,
@@ -22,8 +24,17 @@ import {
   type ServiceManagerID,
 } from "../contracts/index.ts"
 
-/** PHASE2-CONTRACT.md: a target without a service manager (windows-x64) runs session-only; preview refuses the rest. */
+/** PHASE2-CONTRACT.md: a target without a service manager runs session-only; preview refuses the rest. */
 export const NO_SERVICES_ON_TARGET = "needs user services, which hubctl does not install on Windows yet"
+/** PHASE3-CONTRACT.md: a service with no template for the target's manager (the Claude Code / Codex spokes on Windows). */
+export const NO_SERVICE_ON_TARGET = "needs a user service hubctl does not install on Windows yet"
+
+/** One unsupported_platform issue per profile service the target's manager has no template for. */
+export function servicesWithoutTemplate(profile: Pick<Profile, "services">, manager: ServiceManagerID, at = "/profile/services"): Issue[] {
+  return profile.services.flatMap((service, i) =>
+    EMBEDDED_ASSETS[`service/${manager}/${service}`] ? [] : [{ path: `${at}/${i}`, code: "unsupported_platform" as const, message: `${service} ${NO_SERVICE_ON_TARGET}` }],
+  )
+}
 
 export interface DesiredHarness {
   readonly id: HarnessID
@@ -73,6 +84,10 @@ export function desiredState(profileDoc: unknown, snapshotDoc: unknown): Result<
   const target = checkTarget(snapshot.host.target)
   if (profile.services.length > 0 && target.ok && target.value.serviceManager === "none")
     return fail("/profile/services", "unsupported_platform", `${profile.id} ${NO_SERVICES_ON_TARGET}`)
+  if (target.ok && target.value.serviceManager !== "none") {
+    const missing = servicesWithoutTemplate(profile, target.value.serviceManager)
+    if (missing.length > 0) return { ok: false, issues: missing }
+  }
   if (profile.services.length > 0 && manager === "none")
     c.add("/profile/services", "no_service_manager", `${profile.id} runs services, but this host has no user service manager (launchd or systemd --user)`)
   const runtimes = profile.runtimes.map((id, i): DesiredRuntime => {

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

@@ -28,6 +28,7 @@ import {
   type JournalEntry,
   type SelectHarnessVersion,
   type ServiceID,
+  SERVICE_ROOT,
   type ServiceManagerID,
   type PathRef,
   type RecoveryDecision,
@@ -176,7 +177,7 @@ export function installedHarnesses(history: readonly TransactionRecord[]): Parti
  */
 export function installedServiceUnits(history: readonly TransactionRecord[], manager: ServiceManagerID): Partial<Record<ServiceID, string>> {
   const byFile = new Map(Object.values(EMBEDDED_ASSETS).filter((a) => a.manager === manager).map((a) => [a.installAs, a.service]))
-  const root = manager === "launchd" ? "launch-agents" : "systemd-user"
+  const root = SERVICE_ROOT[manager]
   const units: Partial<Record<ServiceID, string>> = {}
   for (const tx of history) {
     if (tx.outcome !== "committed") continue

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

@@ -26,6 +26,7 @@ import {
   canonicalJSON,
   decideHarnessInstall,
   EMBEDDED_ASSETS,
+  SERVICE_ROOT,
   fail,
   HARNESS_ORDER,
   ok,
@@ -67,7 +68,6 @@ export interface ServiceFacts {
   readonly installed: Partial<Record<ServiceID, string>>
 }
 
-const UNIT_ROOT: Readonly<Record<ServiceManagerID, "launch-agents" | "systemd-user">> = { launchd: "launch-agents", "systemd-user": "systemd-user" }
 
 /** Deactivates, then removes (when hub knows the unit it installed), one service of a removed component. */
 function removeServiceActions(service: ServiceID, facts: ServiceFacts): Action[] {
@@ -84,7 +84,7 @@ function removeServiceActions(service: ServiceID, facts: ServiceFacts): Action[]
       summary: `Remove the hub ${service} ${facts.manager} unit (profile downgrade)`,
       service,
       manager: facts.manager,
-      path: { root: UNIT_ROOT[facts.manager], rel: asset.installAs },
+      path: { root: SERVICE_ROOT[facts.manager], rel: asset.installAs },
       sha256,
     })
   return actions

package/packages/cli/src/bootstrap/release/assets.ts

@@ -1,4 +1,4 @@
-// The embedded-asset bundle: the six service templates of EMBEDDED_ASSETS (contracts §3.7, I2), imported as text so
+// The embedded-asset bundle: the seven service templates of EMBEDDED_ASSETS (contracts §3.7, I2), imported as text so
 // `bun build --compile` (and the npm bundle) carry them inside the program. A standalone hubctl never reads
 // scripts/ at run time; node.ts / spoke-services.ts render from embeddedAsset(id).text (wired by HBS-13).
 //
@@ -11,6 +11,7 @@ import launchdClaude from "../../../../../scripts/io.github.huynle.hub-claude-co
 import systemdClaude from "../../../../../scripts/hub-claude-code.service" with { type: "text" }
 import launchdCodex from "../../../../../scripts/io.github.huynle.hub-codex-spoke.plist" with { type: "text" }
 import systemdCodex from "../../../../../scripts/hub-codex-spoke.service" with { type: "text" }
+import taskNode from "../../../../../scripts/hub-node.task.xml" with { type: "text" }
 
 export type AssetID = keyof typeof EMBEDDED_ASSETS
 
@@ -22,6 +23,8 @@ export const EMBEDDED_TEXT: Readonly<Record<string, string>> = Object.freeze({
   "service/systemd-user/claude-code": systemdClaude,
   "service/launchd/codex-spoke": launchdCodex,
   "service/systemd-user/codex-spoke": systemdCodex,
+  // `*.xml` is declared as a DOM Document elsewhere; imported `with { type: "text" }` it is the file's text.
+  "service/task-scheduler/node": taskNode as unknown as string,
 })
 
 export interface EmbeddedText {