@huynle/hub 0.8.7 → 0.9.1

package/packages/cli/src/cli.ts

@@ -14,7 +14,7 @@ import { readSpokeCredentials } from "../../node/src/config.ts"
 import { hostname } from "node:os"
 import { serveMcp } from "./mcp"
 import { intentLine, writeIntent } from "./intents"
-import { ASK_EXPIRES_DEFAULT_S, askOutcome, declinedText, durationArg, inboxText, mutedText, repliedText, sentText, textArg } from "./messaging"
+import { ASK_EXPIRES_DEFAULT_S, askOutcome, declinedText, durationArg, inboxText, mutedText, notAfterArg, repliedText, sentText, textArg } from "./messaging"
 import { watch } from "./watch"
 import { DECISION_FLAGS, decisionOptions, decisionsText, openedText, stateArg } from "./decisions"
 import { GRANT_FLAGS, GRANT_REQUEST_FLAGS, grantError, grantRequestArg, grantSpecArg, grantsText, grantText, requestedText, userOnly } from "./grants"
@@ -81,10 +81,13 @@ Identity
   hub role release <role[.project]> [--session <addr>]
 
 Messaging (text "-" reads it from stdin)
-  hub msg <addr> "text" [--all] [--no-wake] [--urgent]   tell: fire and forget
-  hub ask <addr> "text" [--wait [secs]] [--expires 2h] [--all] [--no-wake] [--urgent]
+  hub msg <addr> "text" [--all] [--no-wake] [--urgent] [--not-after <ms|ISO time>] [--key K]
+                                      tell: fire and forget; --not-after: never delivered after that time
+  hub ask <addr> "text" [--wait [secs]] [--expires 2h] [--not-after <ms|ISO time>] [--all] [--no-wake] [--urgent] [--key K]
                                       tracked until answered, declined or expired; --wait alone waits until
-                                      it expires; exit 0 answered, 1 declined or no answer yet, 8 expired
+                                      it expires; exit 0 answered, 1 declined or no answer yet, 8 expired;
+                                      --key (Idempotency-Key): a retry with the same key and text answers
+                                      the first send again and sends nothing (24 h, per credential)
   hub reply <msgID> "text" [--no-wake]   goes to the real sender
   hub decline <msgID> --why "reason"
   hub ask @me "question" [--option id=label[:safe]]... [--recommend id [--why "…"]] [--urgency low|normal|high]
@@ -119,9 +122,10 @@ Launching (users; agents and app tokens with sessions:launch under a grant with
          [--name <@name>] [--role R]... [--harness H] [--agent A] [--model provider/model]
          [--runtime host|openshell [--profile P]] [--machine M] [--node-label k=v]... [--prefer]
          [--label k=v]... [--prompt "text" | --prompt -] [--end idle|asked|never] [--timeout 4h]
-         [--cleanup keep|remove] [--key K]
+         [--cleanup keep|remove] [--key K] [--not-after <ms|ISO time>]
                                       start a session; the same --key again answers the same launch;
-                                      --label tags it for apps, --node-label picks nodes (--prefer: not required)
+                                      --label tags it for apps, --node-label picks nodes (--prefer: not required);
+                                      --not-after: still waiting for a machine then, it never starts (expired)
   hub launches list [--state S[,S]] [--label k=v]...   your launches (agents: the ones they started)
   hub launches show <launchID> · hub launches stop <launchID>   (stop: exit 8 when it already ended)
 
@@ -278,8 +282,17 @@ const whyOf = (flags: Parsed["flags"]) => {
   return why !== undefined ? { why } : {}
 }
 
-/** --no-wake and --urgent as SDK send options. */
-const sendFlags = (flags: Parsed["flags"]) => ({ ...(flags["no-wake"] === true ? { wake: false } : {}), ...(flags.urgent === true ? { urgent: true } : {}) })
+/** --no-wake, --urgent, --not-after and --key as SDK send options. */
+const sendFlags = (flags: Parsed["flags"]) => {
+  const notAfter = str(flags, "not-after")
+  const key = str(flags, "key")
+  return {
+    ...(flags["no-wake"] === true ? { wake: false } : {}),
+    ...(flags.urgent === true ? { urgent: true } : {}),
+    ...(notAfter === undefined ? {} : { notAfter: notAfterArg(notAfter, "--not-after") }),
+    ...(key !== undefined ? { idempotencyKey: key } : {}),
+  }
+}
 
 const nodeIo = (io: Io): NodeIo => ({
   env: io.env,
@@ -399,7 +412,7 @@ const COMMANDS: Record<string, Command> = {
   },
   msg: {
     args: ["<addr>", "<text>"],
-    flags: { all: "bool", "no-wake": "bool", urgent: "bool" },
+    flags: { all: "bool", "no-wake": "bool", urgent: "bool", "not-after": "string", key: "string" },
     async handle(context) {
       const { flags, args } = context.parsed
       const text = await textArg(args[1]!, context.io.stdin)
@@ -410,7 +423,7 @@ const COMMANDS: Record<string, Command> = {
   },
   ask: {
     args: ["<addr>", "<text>"],
-    flags: { all: "bool", "no-wake": "bool", urgent: "bool", expires: "string", wait: "optional", ...DECISION_FLAGS },
+    flags: { all: "bool", "no-wake": "bool", urgent: "bool", "not-after": "string", key: "string", expires: "string", wait: "optional", ...DECISION_FLAGS },
     async handle(context) {
       const { flags, args } = context.parsed
       const decision = decisionOptions(flags, args[0]!)

package/packages/cli/src/http.ts

@@ -33,6 +33,7 @@ const EXIT_OF: Record<string, number> = {
   offline: EXIT.unavailable,
   busy: EXIT.unavailable,
   gone: EXIT.gone,
+  expired: EXIT.gone,
   unauthorized: EXIT.unauthorized,
   token_expired: EXIT.unauthorized,
 }

package/packages/cli/src/launches.ts

@@ -5,6 +5,7 @@ import path from "node:path"
 import type { LaunchSpec, LaunchStep, LaunchView } from "../../sdk/src/index.ts"
 import { CLEANUP_POLICIES, LAUNCH_END_WHEN, RUNTIME_KINDS, WORKSPACE_MODES } from "../../protocol/src/launch.ts"
 import { str, UsageError, type FlagKind, type Parsed } from "./args"
+import { notAfterArg } from "./messaging"
 
 export const LAUNCH_FLAGS: Readonly<Record<string, FlagKind>> = {
   key: "string",
@@ -28,6 +29,7 @@ export const LAUNCH_FLAGS: Readonly<Record<string, FlagKind>> = {
   end: "string",
   timeout: "string",
   cleanup: "string",
+  "not-after": "string",
 }
 
 /** `a, b or c` */
@@ -93,10 +95,12 @@ export async function launchSpecArg(flags: Parsed["flags"], context: LaunchArgCo
   const runtime = kind === undefined ? undefined : { kind, ...(profile !== undefined ? { profile } : {}) }
   const placement = defined({ labels: nodeLabels, machine, mode: flags.prefer === true ? ("prefer" as const) : undefined })
   const end = defined({ when, timeout: str(flags, "timeout"), cleanup })
+  const notAfterText = str(flags, "not-after")
+  const notAfter = notAfterText === undefined ? undefined : notAfterArg(notAfterText, "--not-after")
   return {
     ...defined({ key: str(flags, "key"), name, roles, harness: str(flags, "harness"), agent: str(flags, "agent"), model: str(flags, "model") }),
     workspace,
-    ...defined({ runtime, placement, prompt, labels, end }),
+    ...defined({ runtime, placement, prompt, labels, end, notAfter }),
   }
 }
 

package/packages/cli/src/mcp.ts

@@ -18,7 +18,7 @@ import { intentLine, writeIntent } from "./intents"
 import type { Credentials } from "./credentials"
 import { logText, oneLine, sessionsText, showText, statusText, whoamiText, whoText } from "./format"
 import { CliError, withHub } from "./http"
-import { askOutcome, declinedText, deliveryText, durationArg, mutedText, repliedText, sentText } from "./messaging"
+import { askOutcome, declinedText, deliveryText, durationArg, mutedText, notAfterArg, repliedText, sentText } from "./messaging"
 import { DECISION_STATES, decisionsText, decisionText, openedText } from "./decisions"
 import { CLEANUP_POLICIES, LAUNCH_END_WHEN, RUNTIME_KINDS, WORKSPACE_MODES } from "../../protocol/src/launch.ts"
 import { launchedText, launchesText, launchText, stoppedLaunchText } from "./launches"
@@ -103,11 +103,27 @@ const optionalExpires = (args: Args): number | undefined => {
   }
   throw new ArgError(`"expires" must be seconds or a duration like 30s, 5m, 2h, 1d`)
 }
-/** The wake and urgent arguments as SDK send options. */
+/** notAfter (H2): epoch milliseconds, or an ISO 8601 date-time converted to them. */
+const optionalNotAfter = (args: Args): number | undefined => {
+  const value = args.notAfter
+  if (value === undefined || value === null) return undefined
+  if (typeof value === "number" && Number.isSafeInteger(value)) return value
+  if (typeof value === "string") {
+    try {
+      return notAfterArg(value, "\"notAfter\"")
+    } catch (cause) {
+      if (cause instanceof UsageError) throw new ArgError(cause.message)
+      throw cause
+    }
+  }
+  throw new ArgError(`"notAfter" must be epoch milliseconds or an ISO 8601 date-time like 2027-01-15T12:00:00Z`)
+}
+/** The wake, urgent and notAfter arguments as SDK send options. */
 const sendOptions = (args: Args) => {
   const wake = optionalBool(args, "wake")
   const urgent = optionalBool(args, "urgent")
-  return { ...(wake !== undefined ? { wake } : {}), ...(urgent !== undefined ? { urgent } : {}) }
+  const notAfter = optionalNotAfter(args)
+  return { ...(wake !== undefined ? { wake } : {}), ...(urgent !== undefined ? { urgent } : {}), ...(notAfter !== undefined ? { notAfter } : {}) }
 }
 
 /** The why argument as SDK act options. */
@@ -178,6 +194,7 @@ function launchSpec(args: Args): LaunchSpec {
       prompt: optional(args, "prompt"),
       labels: optionalLabels(args, "labels"),
       end: definedFields({ when: optionalEnum(args, "end", LAUNCH_END_WHEN), timeout: optional(args, "timeout"), cleanup: optionalEnum(args, "cleanup", CLEANUP_POLICIES) }),
+      notAfter: optionalNotAfter(args),
     }),
   }
 }
@@ -220,6 +237,7 @@ const STRING = { type: "string" } as const
 const SEND = {
   wake: { type: "boolean", description: "false: admit the message without starting a turn." },
   urgent: { type: "boolean", description: "Steer into the recipient's running turn." },
+  notAfter: { type: ["number", "string"], description: "Never deliver after this time: epoch milliseconds or an ISO 8601 date-time (at most 30 days ahead). Already passed: nothing is sent (expired)." },
   all: { type: "boolean", description: "Send to every session the address names (each holder of a role)." },
 } as const
 const TO = { type: "string", description: "The recipient: @name, @@role, @@role#team (a role of one of your teams), @name.project, ses_…, or @me (the user)." } as const
@@ -388,7 +406,7 @@ const webhookText = (w: { id: string; url: string; events: readonly string[]; la
 const webhookTools: readonly Tool[] = [
   {
     name: "webhook_create",
-    description: "Create a durable signed webhook for canonical compact events. The signing secret is returned only here. Needs events:subscribe plus every selected family's scope.",
+    description: "Create a durable signed webhook for canonical compact events (e.g. launch.*, session.*, message.changed, team.intake). The signing secret is returned only here. Needs events:subscribe plus every selected family's scope; events [\"team.intake\"] alone needs only teams:submit (an app gets only its own submissions).",
     properties: { url: STRING, events: { type: "array", items: STRING }, label: STRING }, required: ["url"], readOnly: false,
     run: async (hub, args, signal) => {
       const events = optionalStrings(args, "events")
@@ -809,13 +827,13 @@ const TOOLS: readonly Tool[] = [
   {
     name: "msg",
     description: "Tell a session something (fire and forget). Sent as this server's credential, not as an OpenCode session.",
-    properties: { to: TO, text: { ...STRING, description: "The message." }, ...SEND },
+    properties: { to: TO, text: { ...STRING, description: "The message." }, ...SEND, idempotencyKey: IDEMPOTENCY },
     required: ["to", "text"],
     readOnly: false,
     run: async (hub, args, signal) => {
       const to = need(args, "to")
       const text = need(args, "text")
-      const options = { ...sendOptions(args), signal }
+      const options = { ...sendOptions(args), ...idemOption(args), signal }
       if (optionalBool(args, "all")) return sentAllText(await hub.msg(to, text, { ...options, all: true }))
       return sentText(await hub.msg(to, text, options))
     },
@@ -829,6 +847,7 @@ const TOOLS: readonly Tool[] = [
       wait: { type: "number", minimum: 0, maximum: WAIT_POLL_MAX_S, description: `Seconds to wait for the answer (0–${WAIT_POLL_MAX_S}).` },
       expires: { type: ["number", "string"], description: "When the ask expires: seconds, or 30s, 5m, 2h, 1d (1 minute to 7 days; default 24 h)." },
       ...SEND,
+      idempotencyKey: IDEMPOTENCY,
     },
     required: ["to", "text"],
     readOnly: false,
@@ -837,7 +856,7 @@ const TOOLS: readonly Tool[] = [
       const text = need(args, "text")
       const wait = optionalWait(args)
       const expires = optionalExpires(args)
-      const options = { ...sendOptions(args), ...(expires !== undefined ? { expires } : {}), signal }
+      const options = { ...sendOptions(args), ...(expires !== undefined ? { expires } : {}), ...idemOption(args), signal }
       if (optionalBool(args, "all")) {
         if (wait !== undefined) throw new ArgError(`"wait" cannot be combined with "all"`)
         return sentAllText(await hub.ask(to, text, { ...options, all: true }))
@@ -999,7 +1018,7 @@ const TOOLS: readonly Tool[] = [
   {
     name: "launch",
     description:
-      "Start a new session on a node (a hub node with the repo under its workspace roots). The same key again answers the same launch. Needs an app token with scope sessions:launch and a grant with verb launch covering the repo.",
+      "Start a new session on a node (a hub node with the repo under its workspace roots). The same key again answers the same launch. With notAfter, a launch still waiting for a machine at that time is never started (it ends expired). Needs an app token with scope sessions:launch and a grant with verb launch covering the repo.",
     properties: {
       repo: { ...STRING, description: "Absolute path of the repository on the node (or where a clone goes)." },
       mode: { type: "string", enum: [...WORKSPACE_MODES], description: "worktree (default: <repo>/.worktrees/<branch>, needs branch), checkout, or clone (needs remote)." },
@@ -1022,6 +1041,7 @@ const TOOLS: readonly Tool[] = [
       end: { type: "string", enum: [...LAUNCH_END_WHEN], description: "When it ends: idle (default; idle with nothing open for 30 s), asked (with a question open: needs_user), never." },
       timeout: { ...STRING, description: "Longest run, e.g. 4h or 90m." },
       cleanup: { type: "string", enum: [...CLEANUP_POLICIES], description: "keep (default) or remove the workspace when it ends." },
+      notAfter: { type: ["number", "string"], description: "Do not start after this time: epoch milliseconds or an ISO 8601 date-time (at most 30 days ahead). Still waiting for a machine then, the launch ends expired; once placed it runs (timeout bounds it). Already passed: nothing is launched (expired)." },
     },
     required: ["repo"],
     readOnly: false,

package/packages/cli/src/messaging.ts

@@ -57,6 +57,20 @@ export function durationArg(value: string, flag: string): number {
   return Number(match[1]) * UNIT_S[match[2]!]!
 }
 
+/** An ISO 8601 date-time with at least hours and minutes; no zone means local time. */
+const ISO_DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:?\d{2})?$/i
+
+/**
+ * A notAfter (H2) as epoch milliseconds, from epoch milliseconds (digits) or an ISO 8601 date-time like
+ * 2027-01-15T12:00:00Z; the hub checks the range (future, at most 30 days ahead). Throws UsageError(`what` …).
+ */
+export function notAfterArg(value: string, what: string): number {
+  const text = value.trim()
+  const ms = /^\d+$/.test(text) ? Number(text) : ISO_DATE_TIME.test(text) ? Date.parse(text) : Number.NaN
+  if (!Number.isSafeInteger(ms)) throw new UsageError(`${what} takes epoch milliseconds or an ISO 8601 date-time like 2027-01-15T12:00:00Z (got "${value}")`)
+  return ms
+}
+
 const iso = (ms: number) => new Date(ms).toISOString().replace(/\.\d{3}Z$/, "Z")
 
 /** What an ask came to, its text, and the exit code: answered 0, declined 1, open after a wait 1, expired 8. */

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/cli/src/team-intake-mcp.ts

@@ -5,6 +5,8 @@
 // sessions submit under team policy and, in the team's entry role, report status.
 import { sanitizeText } from "../../sdk/src/envelope.ts"
 import { reportIntakeStatus, TEAM_INTAKE_STATUS_INPUTS, type TeamIntake, type TeamIntakeApi, type TeamIntakePriority, type TeamIntakeStatus, type TeamIntakeStatusInput } from "../../sdk/src/team-intake.ts"
+import { UsageError } from "./args"
+import { notAfterArg } from "./messaging"
 import { ToolArgError } from "./tool-args"
 
 type Args = Record<string, unknown>
@@ -60,6 +62,22 @@ function dueOf(args: Args): number | undefined {
   return ms
 }
 
+/** `notAfter` (H4) as epoch milliseconds or an ISO 8601 date-time; the hub checks the range. */
+function notAfterOf(args: Args): number | undefined {
+  const value = args.notAfter
+  if (value === undefined || value === null || value === "") return undefined
+  if (typeof value === "number" && Number.isSafeInteger(value)) return value
+  if (typeof value === "string") {
+    try {
+      return notAfterArg(value, `"notAfter"`)
+    } catch (cause) {
+      if (cause instanceof UsageError) throw new ToolArgError(cause.message)
+      throw cause
+    }
+  }
+  throw new ToolArgError(`"notAfter" must be epoch milliseconds or an ISO 8601 date-time like 2027-01-15T12:00:00Z`)
+}
+
 const line = (i: TeamIntake) =>
   `${i.id}  ${i.status}${i.progress ? `/${i.progress}` : ""}  ${i.priority}  r${i.revision}  ${sanitizeText(i.title).replace(/\s+/g, " ")}`
 
@@ -71,6 +89,7 @@ function intakeText(i: TeamIntake): string {
     `status: ${i.status}${i.progress ? ` (${i.progress})` : ""}  priority: ${i.priority}  from: ${from}`,
     ...(i.assignmentID ? [`assignment: ${i.assignmentID} in workspace ${i.workspaceID ?? "?"}${i.sessionID ? `, delivered to ${i.sessionID}` : ""}`] : []),
     ...(i.due !== undefined ? [`due: ${new Date(i.due).toISOString()}`] : []),
+    ...(i.notAfter !== undefined ? [`not after: ${new Date(i.notAfter).toISOString()}`] : []),
     ...(i.labels?.length ? [`labels: ${i.labels.join(", ")}`] : []),
     ...(i.criteria?.length ? ["done means:", ...i.criteria.map((c) => `- ${sanitizeText(c)}`)] : []),
     ...(i.ref ? [`ref: ${sanitizeText(i.ref)}`] : []),
@@ -83,7 +102,7 @@ export const teamIntakeTools: readonly TeamIntakeTool[] = [
   {
     name: "team_submit",
     description:
-      "Give work to a team: its entry role (e.g. the project manager) receives the task with the team's context and owns it as an assignment in the team's workspace; while the role is vacant it waits queued. Pass `key` to make retries idempotent. App tokens need scope teams:submit; sessions submit under the team's communication policy.",
+      "Give work to a team: its entry role (e.g. the project manager) receives the task with the team's context and owns it as an assignment in the team's workspace; while the role is vacant it waits queued (with `notAfter`, only until then: still queued at that time, it is cancelled with reason not_after instead of delivered late). Pass `key` to make retries idempotent. App tokens need scope teams:submit; sessions submit under the team's communication policy.",
     properties: {
       team: TEAM,
       title: { ...STRING, description: "One line, at most 120 characters." },
@@ -91,6 +110,10 @@ export const teamIntakeTools: readonly TeamIntakeTool[] = [
       priority: { type: "string", enum: PRIORITIES, description: "Default normal." },
       labels: { type: "array", items: STRING, description: "Slugs (lowercase letters, digits, dashes)." },
       due: { ...STRING, description: "When it is due: an ISO date/time." },
+      notAfter: {
+        type: ["number", "string"],
+        description: "Never deliver after this time: epoch milliseconds or an ISO 8601 date-time (at most 30 days ahead). Already passed: nothing is submitted (expired). Still queued then: cancelled (reason not_after).",
+      },
       criteria: { type: "array", items: STRING, description: "What done means (at most 8 lines)." },
       ref: { ...STRING, description: "An external reference, e.g. a Brain task ID." },
       key: { ...STRING, description: "Idempotency-Key: the same key and body return the original submission." },
@@ -103,12 +126,13 @@ export const teamIntakeTools: readonly TeamIntakeTool[] = [
       const labels = strings(args, "labels")
       const criteria = strings(args, "criteria")
       const due = dueOf(args)
+      const notAfter = notAfterOf(args)
       const brief = optional(args, "brief")
       const ref = optional(args, "ref")
       const key = optional(args, "key")
       const { intake, created } = await hub.teams.submit(
         need(args, "team"),
-        { title: need(args, "title"), ...(brief ? { brief } : {}), ...(priority ? { priority } : {}), ...(labels ? { labels } : {}), ...(due !== undefined ? { due } : {}), ...(criteria ? { criteria } : {}), ...(ref ? { ref } : {}) },
+        { title: need(args, "title"), ...(brief ? { brief } : {}), ...(priority ? { priority } : {}), ...(labels ? { labels } : {}), ...(due !== undefined ? { due } : {}), ...(notAfter !== undefined ? { notAfter } : {}), ...(criteria ? { criteria } : {}), ...(ref ? { ref } : {}) },
         { signal, ...(key ? { idempotencyKey: key } : {}) },
       )
       return `${created ? "Submitted" : "Already submitted (same key)"}: ${intake.id} is ${intake.status}${intake.status === "queued" ? " (waiting for the entry role)" : ""}\n${intakeText(intake)}`