@huynle/hub 0.9.0 → 0.9.2

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-cli",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "private": true,
   "description": "The hub CLI (`hub` / `hubctl`) for agents and scripts (internal; bundled into @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/cli/src/bootstrap/PHASE3-CONTRACT.md

@@ -0,0 +1,112 @@
+# Phase 3: user services on Windows (launch-node), shared contract
+
+Design: `docs/plans/2026-11-05-machine-setup-installer-design.md` §3 (Phase 3); Phase 2 contract
+`PHASE2-CONTRACT.md` and `docs/bootstrap-contracts.md` §11 (v1.3) still hold. Branch `feat/ms3` from v0.8.7
+(`ebe8f6a1`). Three workstreams build against this file in parallel; change it only through the integrator.
+
+Goal: `launch-node` works on `windows-x64`. `hub node` runs as a per-user logon task (no admin, no password, no
+visible window), the node keeps OpenCode's background service running so the machine stays online without OpenCode
+open, and launches prepare worktrees under `C:/…` workspace roots. `full-harness` (Claude Code / Codex spokes) stays
+refused on Windows (Phase 4).
+
+## Paths in the protocol and the node (workstream A)
+
+- The launch/node protocol (`packages/protocol/src/launch.ts` `isAbsolutePath`, `node.ts`) accepts canonical absolute
+  paths exactly as the bootstrap contracts do: POSIX `/a/b` or Windows `C:/a/b` (upper-case drive, `/`, no UNC or
+  device paths). Reuse or mirror `packages/cli/src/bootstrap/contracts/validate.ts` `isAbsolutePath` (one rule).
+- Everything the node sends (hello `workspaceRoots`, prepared `directory`) is canonical; the node canonicalizes
+  native paths it reads (node.json, `realpathSync`, git output) at the edge (`normalizeAbs`-style). The hub compares
+  canonical strings; drive letters are upper-case, so case-insensitive Windows paths compare equal.
+- node.json `workspaceRoots` on Windows may be written as `C:\Users\x\projects`, `C:/Users/x/projects` or
+  `~/projects`; the node canonicalizes them.
+
+## The `task-scheduler` service manager (workstream B)
+
+- `ServiceManager` gains `"task-scheduler"`; `windows-x64` has `serviceManager: "task-scheduler"` (was `"none"`).
+  Discovery reports `task-scheduler` on Windows when `%SystemRoot%\System32\schtasks.exe` exists, else `none`.
+- New root `task-defs` = `state/hub/tasks` (canonical `C:/Users/x/.local/state/hub/tasks`): where hubctl writes the
+  rendered Task XML it registers. The XML is journaled like a unit file; Task Scheduler keeps its own copy.
+- Embedded asset `service/task-scheduler/node` = `scripts/hub-node.task.xml`, kind `task-xml`. The rendered file is
+  written as **UTF-16LE with BOM** if `schtasks /XML` needs it (verify on Windows; UTF-8 if it accepts that).
+- Task: name `hub-node-<user>` (user = `%USERNAME%`, `[A-Za-z0-9._-]` only, others `_`) in the root folder;
+  `LogonTrigger` for this user; principal = the user's SID, `InteractiveToken`, `LeastPrivilege` (no admin, no stored
+  password); `MultipleInstancesPolicy` `IgnoreNew`; no battery limits; `ExecutionTimeLimit` `PT0S`;
+  `RestartOnFailure` interval `PT1M`, count `999`. No visible window: the action must not open a console window at
+  logon (try `conhost.exe --headless <hubctl.exe> node run`; if that is not reliable, find another way, verify it on
+  Windows, and say what you chose). The command is `user-bin:hubctl.exe node run` (native path in the XML), never a
+  `.cmd`.
+- No per-task environment exists: settings a systemd unit carries in `Environment=` are passed another way (flags, or
+  nothing when they are defaults). The script layout (`__RUNTIME__ __ENTRY__`) is refused on Windows: only the
+  standalone `hubctl.exe` layout.
+- Control: absolute `%SystemRoot%\System32\schtasks.exe`, `shell:false`, `windowsHide:true`, a fixed allowlist:
+  `/Create /TN <name> /XML <abs task-defs file> /F`, `/Run /TN <name>`, `/End /TN <name>`, `/Delete /TN <name> /F`,
+  `/Query /TN <name> /XML` (state: registered / enabled) and a locale-independent running check (e.g. the task's
+  process: `hubctl.exe` with `node run` whose parent is the Task Scheduler engine, or `schtasks /Query /XML` plus a
+  CIM process query) with the same `state` / `activate` / `deactivate` / `restore` / `health` semantics and the
+  existing health window. `/End` is TerminateProcess: no graceful stop on Windows (accepted; the node is crash-safe).
+- Exit 78 ("nothing to do") cannot be excluded from restarts in Task XML: on win32 the node exits **0** in that case
+  (no restart) and logs why; the task is started again at the next logon or by `hubctl setup apply`.
+- The hand path `hub node install/uninstall` on Windows writes the XML and prints the `schtasks` commands (never runs
+  them), like launchd/systemd today.
+- Profiles: `launch-node` plans on `windows-x64`; `full-harness` stays refused there with
+  "<service> needs a user service hubctl does not install on Windows yet" for the claude-code / codex spokes.
+  `--workspace-root` takes native or canonical Windows paths and `~/…`.
+
+## The node on Windows (workstream A)
+
+- **OpenCode background service.** On win32, when no background service is registered or its process is gone, the node
+  starts it (`<opencode> service start`, found like the warmer finds OpenCode, `windowsHide`, no shell), at most once
+  per tick with back-off, and logs it. Then the warmer warms it as on other OSes. Verify on Windows where OpenCode
+  2.x writes `service.json` and how `opencode service start` behaves; fix `run.ts`'s path if it differs.
+- `opencode-warm.ts` `readServiceRegistration`: the POSIX mode check (`mode & 0o022`) does not apply on win32; use the
+  ACL check from `src/win-acl.ts` (owner, SYSTEM, Administrators only) or none for a non-secret file — say which.
+- Process trees: `git.ts` (and `runtime-openshell/src/cli.ts` if it can run on Windows) stop with the shared
+  `packages/cli/src/bootstrap/adapters/process-tree.ts` tree kill on win32 instead of `process.kill(-pid)`.
+- Harness lookup (`harnesses.ts`): PATHEXT and `.exe` on win32 (`opencode.exe`, `claude.exe`, `bin/codex.exe`).
+- Every spawn that can run on Windows sets `windowsHide: true` (also `control.ts` `defaultSpawn`,
+  `claude-code/src/wrapper.ts`, `codex/src/wrapper.ts`).
+
+## Installer and console (workstream C)
+
+- `/install.ps1` accepts `profile=launch-node`, `root` and `activate=1` (still refuses `full-harness`). `root` on
+  Windows: `~/…` or a drive path `C:/…` (forward slashes in the URL; same character allowlist plus `:` after a single
+  drive letter); the server validates and the script passes it to `--workspace-root`; `activate=1` adds
+  `--confirm-activation`.
+- The console dialog offers **+ launch node** on Windows (workspace folder default `~/projects`, Start services now);
+  **All harnesses** stays "Coming soon on Windows".
+
+## Verification on winpixel (all workstreams)
+
+`ssh winpixel` (user `dacra`, PowerShell 5.1 remote shell; send scripts as `powershell -NoProfile -EncodedCommand
+<base64 UTF-16LE>`). Work only under `C:\Users\dacra\AppData\Local\Temp\<your-workstream>\`, with `USERPROFILE`,
+`HOME`, `TEMP`, `TMP`, `XDG_*` pointed inside it. Scheduled tasks you create must be named `hub-test-<something>` and
+be deleted before you finish (`schtasks /Delete /F`). Never touch the real profile, the real `hub-node-*` task,
+the registry or PATH. Processes started over ssh die when the session ends; a logon task needs a logon to fire, so test
+it with `/Run`. If winpixel is unreachable (it may be off), finish everything else with tests and list exactly what
+still needs a Windows run.
+
+## As built (integrator, 2026-11-06)
+
+Verified on winpixel during the workstreams; these replace the contract text where they differ.
+
+- **Encoding:** `schtasks /XML` refuses UTF-8 ("unable to switch the encoding"); the Task XML is written UTF-16LE
+  with a BOM.
+- **No window:** the action is `conhost.exe --headless <hubctl.exe> node run` (checked with Comet KVM screenshots
+  and a window-process query; without `--headless` Windows Terminal opens).
+- **Restart:** `conhost --headless` always exits 0, so `RestartOnFailure` never fires. The logon trigger repeats every
+  minute with `IgnoreNew`: an exited node is started again within a minute whatever its exit code.
+- **Idle node:** because of that, a node with no workspace roots on win32 does not exit: it logs why and re-reads
+  node.json every 60 s (`IDLE_RECHECK_MS`) until it lists roots (replaces "exit 0").
+- **Logs:** stderr is lost under the headless console, so on win32 `hub node run` also appends to
+  `<hub state dir>/node.log` (rotated to `node.log.1` past 1 MiB).
+- **Stop:** `schtasks /End` ends only the console host; deactivate first runs `taskkill /T /F /PID <pid>` on the
+  task's process (allowlisted as exactly that), then `/End` and `/Delete`.
+- **Running check:** a fixed PowerShell script reads the task through Task Scheduler's COM API (numeric state, so no
+  localized text, and the action's process ID).
+- **Carried settings:** variables a systemd unit would carry (`XDG_CONFIG_HOME` …) are dropped on Windows and named in
+  a warning at preview and `hub node install`.
+- **Spokes:** `full-harness` is refused per spoke ("claude-code needs a user service hubctl does not install on Windows
+  yet", likewise codex-spoke).
+- **Node paths:** service.json is `%USERPROFILE%\.local\state\opencode\service.json` (as on POSIX); it is checked by ACL.
+  Launch placement compares canonical paths exactly (drive upper-case); a repo path differing only in case from a
+  node's root is not placed there.

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

@@ -7,6 +7,10 @@
 //                   systemctl --user show --property=ActiveState,SubState,NRestarts <hub unit>
 //   launchd         launchctl bootstrap gui/<uid> <the hub agent's plist> | bootout gui/<uid>/<hub label>
 //                   launchctl print gui/<uid>/<hub label>
+//   Task Scheduler  schtasks /Create /TN <hub task> /XML <its task-defs file> /F | /Run | /End /TN <hub task>
+//   (Windows)       schtasks /Delete /TN <hub task> /F | /Query /TN <hub task> /XML
+//                   powershell -NoProfile -NonInteractive -Command <one fixed Schedule.Service query of the task>
+//                   taskkill /T /F /PID <the task's running process>
 // Every call is checked against that set (checkManagerCall) before it reaches the injected runner, so a bug cannot
 // turn it into anything else; the real runner (spawnManagerRunner) checks again, spawns the absolute program
 // without a shell and with an empty environment (only the user bus address is passed), and reports an exit code;
@@ -23,15 +27,23 @@
 // Activation rolls back to the state the service had before: a service that was not loaded is unloaded (and
 // disabled) again; one that was already loaded stays loaded (the engine then restores its previous unit file).
 // After a crash the prior state is unknown, so recovery unloads it: no persistence remains without consent.
+//
+// Task Scheduler (PHASE3-CONTRACT.md): activation registers the task from the Task XML hubctl wrote (/Create /XML /F,
+// replacing an older definition) and starts it (/Run); "loaded" means registered. The running check reads the task
+// through the Schedule.Service COM object (a fixed PowerShell script: its State and LastTaskResult are numbers, so the
+// answer does not depend on the display language, and each running instance's EnginePID is the process of its
+// action). `schtasks /End` ends only that process, the hidden console host, and would leave `hubctl node run`
+// running without it, so deactivation (and a re-activation) first ends the action's whole process tree with
+// taskkill /T /F. There is no graceful stop on Windows; the node is crash-safe.
 import { spawn as nodeSpawn } from "node:child_process"
 import path from "node:path"
-import { EMBEDDED_ASSETS, isAbsolutePath, isRecord, resolvePathRef, SERVICE_IDS, type ExecutionContext, type RootMapping, type ServiceID, type ServiceManagerID } from "../../contracts/index.ts"
+import { EMBEDDED_ASSETS, isAbsolutePath, isRecord, resolvePathRef, SERVICE_IDS, toNativePath, type ExecutionContext, type RootMapping, type ServiceID, type ServiceManagerID } from "../../contracts/index.ts"
 import type { ServiceControl } from "../../transaction/builtin.ts"
 import type { ActionExecutor } from "../../transaction/executor.ts"
 import { txFail, txOk, type TxResult } from "../../transaction/result.ts"
-import { assetIDFor, serviceName, UNIT_ROOT } from "./render.ts"
+import { assetIDFor, serviceName, TASK_NAME, UNIT_ROOT } from "./render.ts"
 
-export type ManagerProgram = "systemctl" | "launchctl"
+export type ManagerProgram = "systemctl" | "launchctl" | "schtasks" | "powershell" | "taskkill"
 
 /** One call to the user's service manager: the program and its words (never a shell string). */
 export interface ManagerCall {
@@ -48,7 +60,7 @@ export const HEALTH_WINDOW = Object.freeze({ timeoutMs: 10_000, stableMs: 3_000,
 /** What a state query says about a service. `detail` is the manager's own state words (never other output). */
 export interface ServiceHealth {
   readonly state: "running" | "starting" | "crash-looping" | "failed" | "stopped"
-  /** Restarts the manager counted (systemd NRestarts; launchd runs - 1). */
+  /** Restarts the manager counted (systemd NRestarts; launchd runs - 1; Task Scheduler counts none). */
   readonly restarts: number
   readonly detail: string
 }
@@ -61,9 +73,9 @@ export interface Clock {
 const realClock: Clock = { now: () => Date.now(), sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)) }
 
 export interface ServiceRunState {
-  /** systemd: active; launchd: loaded in the user's GUI domain. */
+  /** systemd: active; launchd: loaded in the user's GUI domain; Task Scheduler: the task is registered. */
   readonly loaded: boolean
-  /** systemd only: enabled (started at login). */
+  /** systemd: enabled (started at login); Task Scheduler: the registered task is enabled. */
   readonly enabled?: boolean
 }
 
@@ -89,12 +101,50 @@ const labelOfTarget = (word: string | undefined) => {
   return at > 0 && DOMAIN.test(word!.slice(0, at)) ? word!.slice(at + 1) : undefined
 }
 
+/** The Task XML files hubctl registers (task-defs file names). */
+const TASK_FILES = new Set(Object.values(EMBEDDED_ASSETS).flatMap((a) => (a.manager === "task-scheduler" ? [a.installAs] : [])))
+/** A native, drive-rooted Windows path to one of them. */
+const TASK_FILE = /^[A-Z]:\\(?:[^\\/:*?"<>|]+\\)*([^\\/:*?"<>|]+)$/
+
+/** The fixed PowerShell words of the state query of `name` (Schedule.Service: numeric state, the action's pids). */
+export function taskQueryWords(name: string): readonly string[] {
+  if (!TASK_NAME.test(name)) throw new Error(`not a hub task name: ${JSON.stringify(name)}`)
+  const script =
+    "$ErrorActionPreference='Stop';$s=New-Object -ComObject Schedule.Service;$s.Connect();" +
+    `$t=$s.GetFolder('\\').GetTask('${name}');` +
+    "'state='+[int]$t.State;'enabled='+$t.Enabled;'result='+$t.LastTaskResult;" +
+    "foreach($r in $t.GetInstances(0)){'pid='+$r.EnginePID}"
+  return ["-NoProfile", "-NonInteractive", "-Command", script]
+}
+
+function checkWindowsCall(program: ManagerProgram, words: readonly string[]): boolean {
+  if (program === "taskkill") return words.length === 4 && words[0] === "/T" && words[1] === "/F" && words[2] === "/PID" && /^[1-9][0-9]{0,9}$/.test(words[3]!)
+  if (program === "powershell") {
+    const name = /GetTask\('([^']*)'\)/.exec(words[words.length - 1] ?? "")?.[1]
+    if (!name || !TASK_NAME.test(name)) return false
+    const expected = taskQueryWords(name)
+    return words.length === expected.length && words.every((w, i) => w === expected[i])
+  }
+  const [verb, tn, name] = words
+  if (tn !== "/TN" || !TASK_NAME.test(name ?? "")) return false
+  if (verb === "/Run" || verb === "/End") return words.length === 3
+  if (verb === "/Delete") return words.length === 4 && words[3] === "/F"
+  if (verb === "/Query") return words.length === 4 && words[3] === "/XML"
+  if (verb === "/Create") return words.length === 6 && words[3] === "/XML" && words[5] === "/F" && TASK_FILES.has(TASK_FILE.exec(words[4]!)?.[1] ?? "")
+  return false
+}
+
+const WINDOWS_PROGRAMS = new Set<string>(["schtasks", "powershell", "taskkill"])
+
 /** Whether `call` is one of the fixed calls this client makes. */
 export function checkManagerCall(call: unknown): call is ManagerCall {
-  if (!isRecord(call) || !Array.isArray(call.words) || call.words.length > 4) return false
+  if (!isRecord(call) || !Array.isArray(call.words)) return false
+  const windows = typeof call.program === "string" && WINDOWS_PROGRAMS.has(call.program)
+  if (call.words.length > (windows ? 6 : 4)) return false
   const w = call.words as unknown[]
   if (!w.every((x) => typeof x === "string" && x.length > 0 && x.length <= 4096 && !CONTROL.test(x))) return false
   const words = w as string[]
+  if (windows) return checkWindowsCall(call.program as ManagerProgram, words)
   if (call.program === "systemctl") {
     if (words[0] !== "--user") return false
     const verb = words[1]!
@@ -124,11 +174,36 @@ export function unitPathResolver(roots: readonly RootMapping[], context: Executi
   }
 }
 
+/** The fields of the task state query (key=value lines). */
+const taskFields = (output: string) => showFields(output.replaceAll("\r", ""))
+
+/** The process ids of a task's running instances (the state query's pid= lines). */
+const taskPids = (output: string): number[] =>
+  output
+    .replaceAll("\r", "")
+    .split("\n")
+    .flatMap((line) => (/^pid=([1-9][0-9]{0,9})$/.exec(line.trim()) ? [Number(line.trim().slice(4))] : []))
+
+/** What the task state query says: TASK_STATE numbers (0 unknown, 1 disabled, 2 queued, 3 ready, 4 running). */
+export function taskSchedulerHealth(output: string): ServiceHealth {
+  const fields = taskFields(output)
+  const state = /^[0-4]$/.test(fields.state ?? "") ? Number(fields.state) : undefined
+  const result = /^-?[0-9]{1,10}$/.test(fields.result ?? "") ? Number(fields.result) >>> 0 : undefined
+  const pid = taskPids(output)[0]
+  if (state === 4) return { state: "running", restarts: 0, detail: pid ? `running, pid ${pid}` : "running" }
+  if (state === 2) return { state: "starting", restarts: 0, detail: "queued" }
+  if (state === 1) return { state: "stopped", restarts: 0, detail: "disabled" }
+  if (state === 3) return { state: result === 0x41303 ? "starting" : "stopped", restarts: 0, detail: `ready, last result 0x${(result ?? 0).toString(16)}` }
+  return { state: "stopped", restarts: 0, detail: "unknown" }
+}
+
 export interface ServiceControlOptions {
   readonly run: ManagerRunner
   /** The user whose launchd GUI domain the agents load in (process.getuid()). */
   readonly uid: number
   readonly unitPath: (service: ServiceID, manager: ServiceManagerID) => string | undefined
+  /** Task Scheduler: the task name of each service for this user (taskNameFor); without it, tasks are refused. */
+  readonly taskName?: (service: ServiceID) => string | undefined
   /** Time for the health window (injected in tests). */
   readonly clock?: Clock
 }
@@ -286,15 +361,73 @@ export function createServiceControl(options: ServiceControlOptions): NodeServic
     },
   }
 
+  const taskOf = (service: ServiceID): string | undefined => {
+    const name = options.taskName?.(service)
+    return name && TASK_NAME.test(name) ? name : undefined
+  }
+  const noTask = (service: ServiceID) => txFail("invalid", `this hubctl has no Task Scheduler task name for the ${service} service`)
+  const tasks = {
+    /** The state query: undefined when the task is not registered. */
+    async query(name: string): Promise<string | undefined> {
+      const r = await options.run(checked("powershell", ...taskQueryWords(name)))
+      return r.exitCode === 0 ? (r.output ?? "") : undefined
+    },
+    /** Ends each running instance's whole process tree (schtasks /End would end only the console host). */
+    async endTrees(name: string): Promise<void> {
+      for (const pid of taskPids((await tasks.query(name)) ?? "")) await call("taskkill", "/T", "/F", "/PID", String(pid))
+    },
+    async state(service: ServiceID): Promise<TxResult<ServiceRunState>> {
+      const name = taskOf(service)
+      if (!name) return noTask(service)
+      const r = await options.run(checked("schtasks", "/Query", "/TN", name, "/XML"))
+      if (r.exitCode !== 0) return txOk({ loaded: false, enabled: false })
+      const enabled = /<Settings>[\s\S]*?<Enabled>(true|false)<\/Enabled>/.exec(r.output ?? "")?.[1] !== "false"
+      return txOk({ loaded: true, enabled })
+    },
+    async activate(service: ServiceID): Promise<TxResult<void>> {
+      const name = taskOf(service)
+      if (!name) return noTask(service)
+      const file = options.unitPath(service, "task-scheduler")
+      if (!file) return txFail("invalid", `this host has no task-defs directory for ${name}`)
+      await tasks.endTrees(name) // a running node keeps the old definition and binary otherwise
+      const created = await call("schtasks", "/Create", "/TN", name, "/XML", toNativePath(file, "win32"), "/F")
+      if (created !== 0) return txFail("internal", `schtasks /Create of ${name} failed (exit ${created})`)
+      const run = await call("schtasks", "/Run", "/TN", name)
+      if (run !== 0) return txFail("internal", `schtasks /Run of ${name} failed (exit ${run})`)
+      return settle(() => tasks.health(service), name, `schtasks /Query /TN ${name} /V /FO LIST and the Task Scheduler history`)
+    },
+    async health(service: ServiceID): Promise<TxResult<ServiceHealth>> {
+      const name = taskOf(service)
+      if (!name) return noTask(service)
+      const output = await tasks.query(name)
+      return txOk(output === undefined ? { state: "stopped", restarts: 0, detail: "not registered" } : taskSchedulerHealth(output))
+    },
+    async deactivate(service: ServiceID): Promise<TxResult<void>> {
+      const name = taskOf(service)
+      if (!name) return noTask(service)
+      await tasks.endTrees(name)
+      await call("schtasks", "/End", "/TN", name) // not running is fine
+      await call("schtasks", "/Delete", "/TN", name, "/F") // not registered is fine
+      return (await call("schtasks", "/Query", "/TN", name, "/XML")) === 0 ? txFail("internal", `${name} is still registered after schtasks /Delete`) : ok
+    },
+  }
+
+  /** Explicit dispatch: an unknown manager is an error, never another manager's calls. */
+  const by = <T>(manager: ServiceManagerID, calls: Readonly<Record<ServiceManagerID, () => Promise<TxResult<T>>>>): Promise<TxResult<T>> =>
+    guarded(() => {
+      const f = Object.hasOwn(calls, manager) ? calls[manager] : undefined
+      if (!f) throw new Error(`unknown service manager ${String(manager)}`)
+      return f()
+    })
   const deactivate = (service: ServiceID, manager: ServiceManagerID) =>
-    guarded(() => (manager === "launchd" ? launchd.deactivate(service) : systemd.restore(service, { loaded: false, enabled: false })))
+    by(manager, { launchd: () => launchd.deactivate(service), "systemd-user": () => systemd.restore(service, { loaded: false, enabled: false }), "task-scheduler": () => tasks.deactivate(service) })
   return {
-    state: (service, manager) => guarded(() => (manager === "launchd" ? launchd.state(service) : systemd.state(service))),
-    activate: (service, manager) => guarded(() => (manager === "launchd" ? launchd.activate(service) : systemd.activate(service))),
+    state: (service, manager) => by(manager, { launchd: () => launchd.state(service), "systemd-user": () => systemd.state(service), "task-scheduler": () => tasks.state(service) }),
+    activate: (service, manager) => by(manager, { launchd: () => launchd.activate(service), "systemd-user": () => systemd.activate(service), "task-scheduler": () => tasks.activate(service) }),
     deactivate,
     restore: (service, manager, prior) =>
-      prior.loaded ? guarded(async () => (manager === "launchd" ? ok : systemd.restore(service, prior))) : deactivate(service, manager),
-    health: (service, manager) => guarded(() => (manager === "launchd" ? launchd.health(service) : systemd.health(service))),
+      prior.loaded ? by(manager, { launchd: async () => ok, "systemd-user": () => systemd.restore(service, prior), "task-scheduler": async () => ok }) : deactivate(service, manager),
+    health: (service, manager) => by(manager, { launchd: () => launchd.health(service), "systemd-user": () => systemd.health(service), "task-scheduler": () => tasks.health(service) }),
   }
 }
 
@@ -308,12 +441,15 @@ export type Spawner = (
 /** At most this much of a state query's output is kept. */
 const MAX_OUTPUT = 64 * 1024
 /** The calls whose output is read: the state queries. */
-const capturesOutput = (call: ManagerCall) => (call.program === "systemctl" ? call.words[1] === "show" : call.words[0] === "print")
+const capturesOutput = (call: ManagerCall) =>
+  call.program === "systemctl" ? call.words[1] === "show" : call.program === "launchctl" ? call.words[0] === "print" : call.program === "powershell" || (call.program === "schtasks" && call.words[0] === "/Query")
 
 export interface SpawnRunnerOptions {
-  /** Absolute paths of the two programs (discovery's view of this context). */
-  readonly programs: Readonly<Record<ManagerProgram, string>>
-  /** The caller's environment; only the user bus address is passed on (systemctl --user needs it). */
+  /** Absolute paths of this host's programs (discovery's view of this context): systemctl and launchctl, or the
+   * Windows ones (schtasks.exe, powershell.exe, taskkill.exe under %SystemRoot%\System32). */
+  readonly programs: Readonly<Partial<Record<ManagerProgram, string>>>
+  /** The caller's environment; only the user bus address (systemctl --user) and, on Windows, the few variables the
+   * system programs need are passed on. */
   readonly env?: Readonly<Record<string, string | undefined>>
   readonly timeoutMs?: number
   /** Injected in tests; the default spawns with node:child_process (never with a shell). */
@@ -321,10 +457,12 @@ export interface SpawnRunnerOptions {
 }
 
 const BUS_ENV = ["XDG_RUNTIME_DIR", "DBUS_SESSION_BUS_ADDRESS"] as const
+/** What schtasks and PowerShell need to start (no PATH: every program is absolute). */
+const WINDOWS_ENV = ["SystemRoot", "windir", "SystemDrive", "TEMP", "TMP", "USERPROFILE", "LOCALAPPDATA", "APPDATA", "USERNAME", "USERDOMAIN"] as const
 
 const defaultSpawn: Spawner = (file, words, options) =>
   new Promise((resolve) => {
-    const child = nodeSpawn(file, [...words], { shell: false, env: { ...options.env }, stdio: ["ignore", options.capture ? "pipe" : "ignore", "ignore"], timeout: options.timeoutMs, killSignal: "SIGKILL" })
+    const child = nodeSpawn(file, [...words], { shell: false, windowsHide: true, env: { ...options.env }, stdio: ["ignore", options.capture ? "pipe" : "ignore", "ignore"], timeout: options.timeoutMs, killSignal: "SIGKILL" })
     let output = ""
     child.stdout?.setEncoding("utf8")
     child.stdout?.on("data", (chunk: string) => {
@@ -337,18 +475,23 @@ const defaultSpawn: Spawner = (file, words, options) =>
 
 /** The real runner: checked calls only, absolute programs, no shell, no inherited environment. */
 export function spawnManagerRunner(options: SpawnRunnerOptions): ManagerRunner {
-  for (const program of ["systemctl", "launchctl"] as const) {
+  const given = Object.keys(options.programs) as ManagerProgram[]
+  const windows = given.some((p) => WINDOWS_PROGRAMS.has(p))
+  for (const program of windows ? given : (["systemctl", "launchctl"] as const)) {
     const file = options.programs[program]
-    if (!isAbsolutePath(file) || path.basename(file) !== program) throw new Error(`${program} must be given as an absolute path to ${program}`)
+    const base = file === undefined ? "" : path.basename(file)
+    if (!isAbsolutePath(file) || (base !== program && base.toLowerCase() !== `${program}.exe`)) throw new Error(`${program} must be given as an absolute path to ${program}`)
   }
   const env: Record<string, string> = {}
-  for (const key of BUS_ENV) if (options.env?.[key]) env[key] = options.env[key]!
+  for (const key of windows ? WINDOWS_ENV : BUS_ENV) if (options.env?.[key]) env[key] = options.env[key]!
   const spawn = options.spawn ?? defaultSpawn
   const timeoutMs = options.timeoutMs ?? 30_000
   return async (call: ManagerCall) => {
     if (!checkManagerCall(call)) throw new Error(`refused a service manager call outside the fixed set (${String((call as { program?: unknown }).program)})`)
     const capture = capturesOutput(call)
-    const r = await spawn(options.programs[call.program], [...call.words], { shell: false, env, timeoutMs, ...(capture ? { capture: true as const } : {}) })
+    const file = options.programs[call.program]
+    if (!file) throw new Error(`this host's service manager does not use ${call.program}`)
+    const r = await spawn(file, [...call.words], { shell: false, env, timeoutMs, ...(capture ? { capture: true as const } : {}) })
     if (typeof r === "number") return { exitCode: r }
     return capture ? { exitCode: r.exitCode, output: r.output.slice(0, MAX_OUTPUT) } : { exitCode: r.exitCode }
   }

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

@@ -21,9 +21,10 @@ import {
   type ProgramLayout,
   type Result,
   type ServiceID,
+  type ServiceManagerID,
 } from "../../contracts/index.ts"
 import type { PlanContributor } from "../../preview/plan.ts"
-import { renderServiceUnit, SERVICE_ENVIRONMENT, type RenderedUnit } from "./render.ts"
+import { renderServiceUnit, SERVICE_ENVIRONMENT, type RenderedUnit, type TaskIdentity } from "./render.ts"
 import { checkNodeSettings, inside, serviceContextOf, type NodeSettings, type ServiceContext } from "./validate.ts"
 
 export interface NodeServicesOptions {
@@ -39,6 +40,8 @@ export interface NodeServicesOptions {
   readonly environment?: Readonly<Record<string, string | undefined>>
   /** One bounded verification launch, inside a workspace root (needs `activate` and a launch-enabled profile). */
   readonly launch?: { readonly harness: HarnessID; readonly workspace: PathRef }
+  /** Task Scheduler (Windows): the node's task name and the user's SID (the runtime finds them; never a default). */
+  readonly task?: TaskIdentity
 }
 
 export interface NodeServicesPlan {
@@ -54,6 +57,7 @@ export interface NodeServicesPlan {
 export const NODE_CONFIG_REF: PathRef = { root: "config", rel: "hub/node.json" }
 const CONFIG_DIR: PathRef = { root: "config", rel: "hub" }
 
+const UNIT_KIND: Readonly<Record<ServiceManagerID, string>> = { launchd: "launchd agent", "systemd-user": "systemd --user unit", "task-scheduler": "logon task" }
 const LABEL: Readonly<Record<ServiceID, string>> = { node: "hub node", "claude-code": "Claude Code spoke", "codex-spoke": "Codex spoke" }
 const SERVICE_HARNESS: Readonly<Partial<Record<ServiceID, HarnessID>>> = Object.fromEntries(Object.entries(HARNESS_SERVICE).map(([h, s]) => [s, h]))
 const BIN_SETTING: Readonly<Partial<Record<HarnessID, string>>> = { "claude-code": "HUB_CLAUDE_BIN", codex: "HUB_CODEX_BIN" }
@@ -132,9 +136,19 @@ export function planNodeServices(input: PlanInput, options: NodeServicesOptions)
   }
 
   const units: RenderedUnit[] = []
+  const uncarried = new Set<string>()
   for (const service of profile.services) {
-    const environment = environmentFor(service, servedBy(service, profile.harnesses), ctx, options.environment)
-    const unit = renderServiceUnit({ service, manager: ctx.manager, layout: options.layout, home: ctx.home, environment })
+    let environment = environmentFor(service, servedBy(service, profile.harnesses), ctx, options.environment)
+    if (ctx.manager === "task-scheduler") {
+      // A task has no environment of its own: say what this shell sets that the node will not see.
+      for (const key of Object.keys(environment)) uncarried.add(key)
+      environment = {}
+      if (!options.task) {
+        issues.push({ path: `/services/${service}/task`, code: "missing_field", message: "a Windows logon task needs its name and your SID; hubctl could not find them (USERNAME, whoami)" })
+        continue
+      }
+    }
+    const unit = renderServiceUnit({ service, manager: ctx.manager, layout: options.layout, home: ctx.home, environment, ...(ctx.manager === "task-scheduler" ? { task: options.task! } : {}) })
     if (!unit.ok) {
       issues.push(...prefixed(`/services/${service}`, unit))
       continue
@@ -144,7 +158,7 @@ export function planNodeServices(input: PlanInput, options: NodeServicesOptions)
       id: `install-${service}-service`,
       kind: "install-service",
       escalation: "user",
-      summary: `Write the ${LABEL[service]} ${ctx.manager === "launchd" ? "launchd agent" : "systemd --user unit"} (${unit.value.name})`,
+      summary: `Write the ${LABEL[service]} ${UNIT_KIND[ctx.manager]} (${unit.value.name})`,
       service,
       manager: ctx.manager,
       path: unit.value.path,
@@ -175,7 +189,7 @@ export function planNodeServices(input: PlanInput, options: NodeServicesOptions)
     if (!valid.ok) issues.push(...prefixed(`/actions/${action.id}`, valid))
   }
   if (issues.length > 0) return failed(issues)
-  return { ok: true, value: { actions, units, ...(settings ? { settings } : {}), context: ctx, notes: notesFor(options, ctx) } }
+  return { ok: true, value: { actions, units, ...(settings ? { settings } : {}), context: ctx, notes: notesFor(options, ctx, [...uncarried].sort()) } }
 }
 
 function checkLaunch(input: PlanInput, options: NodeServicesOptions, ctx: ServiceContext, settings: NodeSettings | undefined): Issue[] {
@@ -191,10 +205,13 @@ function checkLaunch(input: PlanInput, options: NodeServicesOptions, ctx: Servic
   return []
 }
 
-function notesFor(options: NodeServicesOptions, ctx: ServiceContext): string[] {
+function notesFor(options: NodeServicesOptions, ctx: ServiceContext, uncarried: readonly string[]): string[] {
   const notes: string[] = []
   if (!options.activate) notes.push("The services are installed but not loaded: pass --confirm-activation to load them (hubctl never loads a service without it).")
-  if (ctx.manager === "systemd-user")
+  if (ctx.manager === "task-scheduler") {
+    notes.push("The hub node runs as a logon task for you (no window, no administrator rights, no stored password): Windows starts it at each logon and again within a minute after it exits; it runs while you are logged in.")
+    if (uncarried.length > 0) notes.push(`The logon task does not see ${uncarried.join(", ")} from this shell (a task has no environment of its own); set them as user environment variables if the node needs them.`)
+  } else if (ctx.manager === "systemd-user")
     notes.push(
       options.linger
         ? "To keep the services running while you are logged out, run `loginctl enable-linger` yourself; hubctl does not change login settings."