@huynle/hub 0.8.4 → 0.8.5

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

@@ -22,6 +22,7 @@ import {
   resolvePathRef,
   rootPathIn,
   executionContextOf,
+  toNativePath,
   validateEnvelope,
   type DiscoverySnapshot,
   type EnrollmentMode,
@@ -36,11 +37,12 @@ import {
   type SetupPlan,
   type VerifiedManifest,
 } from "../bootstrap/contracts/index.ts"
-import { verifyManifest } from "../bootstrap/contracts/index.ts"
+import { verifyManifest, type TransactionJournal } from "../bootstrap/contracts/index.ts"
 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 { 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"
@@ -63,6 +65,8 @@ import { hubLaunchDriver } from "./launch-driver.ts"
 import { errorCodeOf, issuesText, PlanRefusal } from "./contributors.ts"
 import { createSetupRuntime, enrollPromptText, type RuntimePorts, type SetupRuntime } from "./runtime.ts"
 import { BootstrapStateStore, raiseFloors, validateSetupRequest, type BootstrapState, type SetupChoices, type SetupRequest } from "./state.ts"
+import { defaultWinAcl, writeOwnerOnlyFile } from "../../../../src/win-acl.ts"
+import { nodeSelfAsideIo, removeSelfAside, selfIdentity, type SelfAsideIo, type SelfAsideOutcome, type SelfIdentity } from "./self-aside.ts"
 
 /** Test seams (never set by main.ts): fakes for everything that reaches outside the process. */
 export interface BootstrapSeams {
@@ -75,6 +79,8 @@ export interface BootstrapSeams {
   readonly trustRoot?: string
   /** Floor of the enrollment poll interval. */
   readonly minIntervalMs?: number
+  /** Windows: the platform calls that delete this hubctl.exe's aside after exit (self-aside.ts). */
+  readonly selfAside?: SelfAsideIo
 }
 
 export interface SetupIo {
@@ -380,6 +386,12 @@ export function pathHint(snapshot: DiscoverySnapshot, plan: SetupPlan, env: Read
   const bin = snapshot.roots.find((r) => r.id === "user-bin")
   if (!bin) return undefined
   const dir = rootPathIn(bin, executionContextOf(snapshot))
+  if (snapshot.host.platform === "win32") {
+    // Windows: PATH is ";"-separated, case-insensitive; install.ps1 adds user-bin to the user PATH, which only new
+    // terminals see.
+    const onPath = (env.PATH ?? "").split(";").some((d) => normalizeAbs(d.trim())?.toLowerCase() === dir.toLowerCase())
+    return onPath ? undefined : `${toNativePath(dir, "win32")} is not on your PATH, so ${linked.join(", ")} will not be found by name; install.ps1 adds it to your user PATH: open a new terminal (or add it to PATH yourself)`
+  }
   const onPath = (env.PATH ?? "").split(":").some((d) => d.replace(/\/+$/, "") === dir)
   return onPath ? undefined : `${dir} is not on your PATH, so ${linked.join(", ")} will not be found by name; add it to PATH (for example in ~/.profile)`
 }
@@ -411,9 +423,13 @@ async function preview(io: SetupIo, flags: Parsed["flags"], json: boolean): Prom
   if (out) {
     const request: SetupRequest = { schema: "hub.setup-request", version: 1, preview: r.value, profile, choices }
     const file = path.resolve(io.cwd ?? process.cwd(), out)
-    const tmp = `${file}.${process.pid}.tmp`
-    writeFileSync(tmp, `${JSON.stringify(request, null, 2)}\n`, { mode: 0o600 })
-    renameSync(tmp, file)
+    const text = `${JSON.stringify(request, null, 2)}\n`
+    if (snapshot.host.platform === "win32") writeOwnerOnlyFile(file, text, defaultWinAcl())
+    else {
+      const tmp = `${file}.${process.pid}.tmp`
+      writeFileSync(tmp, text, { mode: 0o600 })
+      renameSync(tmp, file)
+    }
   }
   const warnings = previewWarnings(snapshot, r.value.plan, bundle.node()?.notes ?? [], io.env)
   return emit(io, json, envelope("setup preview", true, { data: r.value, warnings }), () =>
@@ -686,7 +702,50 @@ async function drift(io: SetupIo, flags: Parsed["flags"], json: boolean): Promis
   )
 }
 
+/** Where user-bin is on this host (the only place a hubctl.exe's aside is deleted after exit). */
+function userBinOf(snapshot: DiscoverySnapshot): string | undefined {
+  const root = snapshot.roots.find((r) => r.id === "user-bin")
+  return root ? rootPathIn(root, executionContextOf(snapshot)) : undefined
+}
+
+const selfAsideIo = (io: SetupIo) => io.bootstrap?.selfAside ?? nodeSelfAsideIo(io.env)
+
+/**
+ * Windows, after a rollback or recovery: when it removed the hubctl.exe running it, the aside it left is deleted now
+ * or once this process exits (self-aside.ts). The text says what happened, so the user knows hubctl is gone.
+ */
+function selfRemoval(io: SetupIo, self: SelfIdentity | undefined, snapshot: DiscoverySnapshot): { outcome: SelfAsideOutcome; text?: string; warning?: string } {
+  let outcome: SelfAsideOutcome
+  try {
+    outcome = removeSelfAside(self, userBinOf(snapshot), selfAsideIo(io))
+  } catch (error) {
+    return { outcome: { state: "none" }, warning: `could not check for this hubctl's leftover file: ${(error as Error).message}` }
+  }
+  if (outcome.state === "none") return { outcome }
+  const exe = toNativePath(self!.path, "win32")
+  const aside = toNativePath(outcome.aside, "win32")
+  const gone = `this rolled back hubctl's own install: ${exe} is removed (install hubctl again to run hubctl setup)`
+  if (outcome.state === "left") return { outcome, text: gone, warning: `${aside} could not be deleted (${outcome.reason}); delete it once this command has exited` }
+  return { outcome, text: outcome.state === "scheduled" ? `${gone}; ${aside} is deleted once this command exits` : gone }
+}
+
+/** What to do after a recovery_required outcome of rollback or recover. */
+const recoveryHint = (code: string): { hint?: string } => (code === "recovery_required" ? { hint: "Run hubctl setup recover (once nothing runs from the paths named) to finish it" } : {})
+
+/** After a rollback: the state describes `target` (a committed transaction this host keeps), or nothing. */
+function writeRolledBackState(snapshot: DiscoverySnapshot, state: BootstrapState, target: TransactionJournal | undefined): void {
+  const request = target ? stateStore(snapshot).readRequest(target.planDigest) : undefined
+  stateStore(snapshot).write({
+    schema: "hub.bootstrap-state",
+    version: 1,
+    ...(request ? { profile: request.profile, choices: request.choices, ...(request.profile.revision ? { catalogRevision: request.profile.revision } : {}), txID: target!.txID, planDigest: target!.planDigest } : {}),
+    floors: state.floors,
+  })
+}
+
 async function rollback(io: SetupIo, flags: Parsed["flags"], json: boolean): Promise<number> {
+  // Before anything moves: the executable running this (a rollback may remove it, see selfRemoval).
+  const self = flags["dry-run"] === true ? undefined : selfIdentity(io.program.execPath, selfAsideIo(io))
   const snapshot = discovered(io)
   const to = str(flags, "to")
   const store = new TxStore(nodeFs, snapshot.roots, executionContextOf(snapshot))
@@ -703,25 +762,33 @@ async function rollback(io: SetupIo, flags: Parsed["flags"], json: boolean): Pro
   const runtime = runtimeFor(io, undefined, snapshot)
   const profile = state.profile ?? unwrapProfile(defaultProfile("session-only"))
   const bundle = await runtime.plan(profile, state.choices ?? {})
+  const committed = new Set(store.journals().filter((j) => j.state === "committed" && j.hostFingerprint === snapshot.host.fingerprint).map((j) => j.txID))
   const outcome = await runtime.applier(snapshot, runtime.executors(bundle, snapshot, {})).rollback(to ? { to } : {})
-  if (!outcome.ok) return emit(io, json, envelope("setup rollback", false, { error: { code: outcome.code, message: outcome.message } }))
+  if (!outcome.ok) {
+    noteKept(io, json, outcome)
+    const report = reportData(outcome)
+    return emit(io, json, envelope("setup rollback", false, { ...(report ? { data: report } : {}), error: { code: outcome.code, message: outcome.message, ...recoveryHint(outcome.code) } }))
+  }
   if (!outcome.report) return emit(io, json, envelope("setup rollback", true, { data: { rolledBack: false } }), () => "nothing to roll back")
+  // Newest first, as they were undone.
+  const undone = store
+    .journals()
+    .filter((j) => committed.has(j.txID) && j.state === "rolled-back")
+    .sort((a, b) => b.startedAt - a.startedAt)
+    .map((j) => j.txID)
   // The state now describes the target transaction (or nothing, after a full rollback).
-  const target = to ? store.journals().find((j) => j.txID === to) : undefined
-  const request = target ? stateStore(snapshot).readRequest(target.planDigest) : undefined
-  stateStore(snapshot).write({
-    schema: "hub.bootstrap-state",
-    version: 1,
-    ...(request ? { profile: request.profile, choices: request.choices, ...(request.profile.revision ? { catalogRevision: request.profile.revision } : {}), txID: target!.txID, planDigest: target!.planDigest } : {}),
-    floors: state.floors,
-  })
+  writeRolledBackState(snapshot, state, to ? store.journals().find((j) => j.txID === to) : undefined)
   noteKept(io, json, outcome)
-  const data = { rolledBack: true, ...reportData(outcome) }
-  const warnings = outcome.report.conflicts.map((c) => `${c.actionID}: ${c.reason}`)
-  return emit(io, json, envelope("setup rollback", true, { data, warnings }), () => `rolled back${to ? ` to ${to}` : ""}${warnings.length ? ` (${warnings.length} file(s) kept because they changed since)` : ""}`)
+  const removal = selfRemoval(io, self, snapshot)
+  const data = { rolledBack: true, ...reportData(outcome), transactions: undone, ...(removal.outcome.state !== "none" ? { selfRemoved: removal.outcome } : {}) }
+  const conflicts = outcome.report.conflicts.map((c) => `${c.actionID}: ${c.reason}`)
+  const warnings = [...conflicts, ...(removal.warning ? [removal.warning] : [])]
+  const summary = `rolled back ${undone.length} transaction(s)${to ? ` to ${to}` : ""}${undone.length ? `: ${undone.join(", ")}` : ""}${conflicts.length ? ` (${conflicts.length} file(s) kept because they changed since)` : ""}`
+  return emit(io, json, envelope("setup rollback", true, { data, warnings }), () => [summary, ...(removal.text ? [removal.text] : [])].join("\n"))
 }
 
 async function recover(io: SetupIo, flags: Parsed["flags"], json: boolean): Promise<number> {
+  const self = selfIdentity(io.program.execPath, selfAsideIo(io))
   const snapshot = discovered(io)
   const store = new TxStore(nodeFs, snapshot.roots, executionContextOf(snapshot))
   let pending
@@ -747,9 +814,20 @@ async function recover(io: SetupIo, flags: Parsed["flags"], json: boolean): Prom
     consent: { escalate: flags.escalate === true, confirmActivation: flags["confirm-activation"] === true },
   })
   noteKept(io, json, outcome)
-  if (!outcome.ok) return emit(io, json, envelope("setup recover", false, { ...(outcome.report ? { data: reportData(outcome) } : {}), error: { code: outcome.code, message: outcome.message } }))
+  if (!outcome.ok) return emit(io, json, envelope("setup recover", false, { ...(outcome.report ? { data: reportData(outcome) } : {}), error: { code: outcome.code, message: outcome.message, ...recoveryHint(outcome.code) } }))
   if (!outcome.report) return emit(io, json, envelope("setup recover", true, { data: { recovered: false } }), () => "nothing to recover")
-  return emit(io, json, envelope("setup recover", true, { data: { recovered: true, mode, ...reportData(outcome) } }), () => `recovered ${outcome.report!.txID} (${mode}): ${outcome.report!.state}`)
+  // A recovered rollback of the transaction the state describes (a `setup rollback` a busy path interrupted): the
+  // state now describes the newest transaction this host still has committed, or nothing.
+  const journals = store.journals()
+  if (state.txID && journals.find((j) => j.txID === state.txID)?.state === "rolled-back") {
+    const kept = journals.filter((j) => j.state === "committed" && j.hostFingerprint === snapshot.host.fingerprint).sort((a, b) => b.startedAt - a.startedAt)[0]
+    writeRolledBackState(snapshot, state, kept)
+  }
+  const removal = selfRemoval(io, self, snapshot)
+  const data = { recovered: true, mode, ...reportData(outcome), ...(removal.outcome.state !== "none" ? { selfRemoved: removal.outcome } : {}) }
+  return emit(io, json, envelope("setup recover", true, { data, ...(removal.warning ? { warnings: [removal.warning] } : {}) }), () =>
+    [`recovered ${outcome.report!.txID} (${mode}): ${outcome.report!.state}`, ...(removal.text ? [removal.text] : [])].join("\n"),
+  )
 }
 
 async function ansible(io: SetupIo, flags: Parsed["flags"], json: boolean): Promise<number> {

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

@@ -4,7 +4,8 @@
 //
 //   hubctlContributor      the standalone hubctl this verified manifest pins for the host's exact target, into
 //                          user-bin:hubctl (the stable authority services and MCP clients run), and the `hub` alias
-//                          next to it (one command surface; the name grants nothing).
+//                          next to it (one command surface; the name grants nothing). On Windows (PHASE2-CONTRACT.md)
+//                          user-bin:hubctl.exe and user-bin:hub.cmd (the applier writes the link as a cmd shim).
 //   enrollmentContributor  inline enrollment: one enroll-machine for the hub the user named, only while this machine
 //                          is not enrolled with it (the device code is approved by a person on the hub).
 //   refusing               a contributor that can refuse: planSetup has no refusal channel for contributors, so a
@@ -16,6 +17,17 @@ import { userBinLinkDecision } from "./user-bin.ts"
 export const HUBCTL_REF = { root: "user-bin", rel: "hubctl" } as const
 export const HUB_ALIAS_REF = { root: "user-bin", rel: "hub" } as const
 
+const isWindowsTarget = (target: string) => target.startsWith("windows-")
+
+/**
+ * hubctl and its `hub` alias on `target`: user-bin:hubctl and user-bin:hub; on Windows user-bin:hubctl.exe and
+ * user-bin:hub.cmd (link-executable there is a cmd shim, PHASE2-CONTRACT.md "Install primitives on win32").
+ */
+export function hubctlRefs(target: string): { readonly hubctl: PathRef; readonly alias: PathRef } {
+  if (isWindowsTarget(target)) return { hubctl: { root: "user-bin", rel: "hubctl.exe" }, alias: { root: "user-bin", rel: "hub.cmd" } }
+  return { hubctl: { ...HUBCTL_REF }, alias: { ...HUB_ALIAS_REF } }
+}
+
 /** A plan that cannot be made, with the envelope error code it maps to. */
 export class PlanRefusal extends Error {
   override readonly name = "PlanRefusal"
@@ -62,21 +74,22 @@ export function hubctlContributor(options: { readonly manifest?: VerifiedManifes
     const artifact = selectArtifact(manifest, snapshot.host.target)
     if (!artifact.ok) return []
     const installed = options.installed
+    const refs = hubctlRefs(snapshot.host.target)
     const actions: Action[] = []
-    if (installed?.sha256(HUBCTL_REF) !== artifact.value.sha256)
+    if (installed?.sha256(refs.hubctl) !== artifact.value.sha256)
       actions.push({
         id: "install-hubctl",
         kind: "install-artifact",
         escalation: "user",
-        summary: `Install hubctl ${manifest.release} for ${snapshot.host.target} as ~/.local/bin/hubctl (pinned by the signed release manifest)`,
+        summary: `Install hubctl ${manifest.release} for ${snapshot.host.target} as ~/.local/bin/${refs.hubctl.rel} (pinned by the signed release manifest)`,
         artifact: "hubctl",
         version: manifest.release,
         target: snapshot.host.target,
         sha256: artifact.value.sha256,
-        path: { ...HUBCTL_REF },
+        path: { ...refs.hubctl },
       })
-    if (!installed?.linksTo(HUB_ALIAS_REF, HUBCTL_REF))
-      actions.push({ id: "link-hub", kind: "link-executable", escalation: "user", summary: "Link hub to hubctl (the same command surface)", path: { ...HUB_ALIAS_REF }, target: { ...HUBCTL_REF } })
+    if (!installed?.linksTo(refs.alias, refs.hubctl))
+      actions.push({ id: "link-hub", kind: "link-executable", escalation: "user", summary: "Link hub to hubctl (the same command surface)", path: { ...refs.alias }, target: { ...refs.hubctl } })
     return actions
   }
 }
@@ -100,6 +113,27 @@ export const HARNESS_EXECUTABLES: Readonly<Record<HarnessID, { readonly name: st
   codex: { name: "codex", rel: "bin/codex", label: "Codex" },
 })
 
+export interface HarnessExecutable {
+  /** The command name (what PATH is searched for). */
+  readonly name: string
+  /** The link's name in user-bin: the command name; on Windows `<name>.cmd` (a cmd shim). */
+  readonly link: string
+  /** The binary inside the install root. */
+  readonly rel: string
+  readonly label: string
+}
+
+/**
+ * A harness's executable on `target`. On Windows only OpenCode has a known layout (bin/opencode.exe, Phase 2); the
+ * others are undefined there, so no link is planned for them.
+ */
+export function harnessExecutable(harness: HarnessID, target: string): HarnessExecutable | undefined {
+  const exe = HARNESS_EXECUTABLES[harness]
+  if (!isWindowsTarget(target)) return { name: exe.name, link: exe.name, rel: exe.rel, label: exe.label }
+  if (harness !== "opencode") return undefined
+  return { name: exe.name, link: `${exe.name}.cmd`, rel: `${exe.rel}.exe`, label: exe.label }
+}
+
 /**
  * Contract amendment A6 (HBS-12 E4): a hub-installed harness goes on PATH through a typed link in user-bin
  * (`~/.local/bin/opencode` → `data:hub/harnesses/opencode/current/bin/opencode`), journaled and rolled back like any
@@ -108,16 +142,17 @@ export const HARNESS_EXECUTABLES: Readonly<Record<HarnessID, { readonly name: st
  * hub's harness directory): a user's binary is never shadowed or replaced.
  */
 export function harnessLinkContributor(inspector: PathInspector): PlanContributor {
-  return ({ profile, planned = [] }) => {
+  return ({ snapshot, profile, planned = [] }) => {
     const actions: Action[] = []
     for (const harness of HARNESS_ORDER) {
       if (!profile.harnesses.includes(harness)) continue
-      const exe = HARNESS_EXECUTABLES[harness]
+      const exe = harnessExecutable(harness, snapshot.host.target)
+      if (!exe) continue
       const current = harnessCurrentRef(harness)
       const target: PathRef = { root: current.root, rel: `${current.rel}/${exe.rel}` }
       const selected = planned.some((a) => a.kind === "select-harness-version" && a.harness === harness)
       if (!selected && inspector.entry(target) !== "file") continue
-      const link: PathRef = { root: "user-bin", rel: exe.name }
+      const link: PathRef = { root: "user-bin", rel: exe.link }
       const linkPath = inspector.where(link)
       const targetPath = inspector.where(target)
       const ownDir = inspector.where({ root: current.root, rel: `hub/harnesses/${harness}` })
@@ -137,7 +172,7 @@ export function harnessLinkContributor(inspector: PathInspector): PlanContributo
         id: `link-${harness}`,
         kind: "link-executable",
         escalation: "user",
-        summary: `Put the hub-installed ${exe.label} on PATH: link ~/.local/bin/${exe.name} to its current version`,
+        summary: `Put the hub-installed ${exe.label} on PATH: link ~/.local/bin/${exe.link} to its current version`,
         path: link,
         target,
       })

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

@@ -64,11 +64,12 @@ import { builtinExecutors, type HarnessSource, type HubctlSource } from "../boot
 import { createApplier, type Applier } from "../bootstrap/transaction/engine.ts"
 import type { ActionExecutor, ExecutorMap } from "../bootstrap/transaction/executor.ts"
 import { nodeFs, type TxFs } from "../bootstrap/transaction/fs.ts"
+import { parseCmdShim } from "../bootstrap/transaction/shim.ts"
 import { fileDigest } from "../bootstrap/transaction/stream.ts"
 import { txFail, txOk } from "../bootstrap/transaction/result.ts"
 import { TxStore } from "../bootstrap/transaction/store.ts"
 import { checkOpenShell } from "../openshell.ts"
-import { enrollmentContributor, harnessLinkContributor, HUBCTL_REF, hubctlContributor, refusing, type InstalledInspector, type PathInspector } from "./contributors.ts"
+import { enrollmentContributor, harnessLinkContributor, hubctlContributor, hubctlRefs, refusing, type InstalledInspector, type PathInspector } from "./contributors.ts"
 import { dispatchByHarness, dispatchHarnessSource } from "./dispatch.ts"
 import { claudeSpokeProbes, codexSpokeStatus, opencodeSpokeProbe, type PresenceOptions } from "./spoke-probe.ts"
 import type { BootstrapState, SetupChoices } from "./state.ts"
@@ -151,6 +152,7 @@ export interface SetupRuntime {
 /**
  * What the files a plan would write hold now, read-only through the applier's filesystem: a regular file's digest
  * (in chunks; hubctl is ~105 MB) and whether a path is a symlink to a target, in the snapshot's execution context.
+ * On a win32 host a hub cmd shim (link-executable's stand-in for a symlink there, shim.ts) is the link it names.
  */
 export function installedInspector(snapshot: DiscoverySnapshot, fs: TxFs): InstalledInspector {
   const where = (ref: PathRef) => {
@@ -170,7 +172,9 @@ export function installedInspector(snapshot: DiscoverySnapshot, fs: TxFs): Insta
       const link = where(ref)
       const to = where(target)
       try {
-        return link !== undefined && to !== undefined && fs.lstat(link)?.kind === "symlink" && nodePath.resolve(nodePath.dirname(link), fs.readlink(link)) === to
+        if (link === undefined || to === undefined) return false
+        if (snapshot.host.platform === "win32" && fs.lstat(link)?.kind === "file") return parseCmdShim(fs.readRange(link, 0, SHIM_MAX)) === to
+        return fs.lstat(link)?.kind === "symlink" && nodePath.resolve(nodePath.dirname(link), fs.readlink(link)) === to
       } catch {
         return false
       }
@@ -178,21 +182,36 @@ export function installedInspector(snapshot: DiscoverySnapshot, fs: TxFs): Insta
   }
 }
 
-/** Paths and PATH as the probe sees them (read-only), in the snapshot's execution context. */
+/** More than any cmd shim hub writes (`@"<path>" %*`). */
+const SHIM_MAX = 4097
+
+/**
+ * Paths and PATH as the probe sees them (read-only), in the snapshot's execution context. On a win32 host a hub cmd
+ * shim is reported as a symlink to its target, so the user-bin link rule treats it as hub's own link.
+ */
 export function pathInspector(snapshot: DiscoverySnapshot, probe: DiscoveryProbe): PathInspector {
   const where = (ref: PathRef) => {
     const r = resolvePathRef(ref, snapshot.roots, executionContextOf(snapshot))
     return r.ok ? r.value : undefined
   }
+  const shimTarget = (p: string) => {
+    if (snapshot.host.platform !== "win32" || probe.lstat(p) !== "file") return undefined
+    const bytes = probe.readFile(p, SHIM_MAX)
+    return bytes ? parseCmdShim(bytes) : undefined
+  }
   return {
     where,
     entry: (ref) => {
       const p = where(ref)
-      return p ? probe.lstat(p) : "missing"
+      if (!p) return "missing"
+      return shimTarget(p) !== undefined ? "symlink" : probe.lstat(p)
     },
     linkTarget: (ref) => {
       const p = where(ref)
-      if (!p || probe.lstat(p) !== "symlink") return undefined
+      if (!p) return undefined
+      const shim = shimTarget(p)
+      if (shim !== undefined) return shim
+      if (probe.lstat(p) !== "symlink") return undefined
       const text = probe.readlink(p)
       return text === undefined ? undefined : nodePath.resolve(nodePath.dirname(p), text)
     },
@@ -281,7 +300,7 @@ export function createSetupRuntime(deps: RuntimeDeps): SetupRuntime {
   function serviceLayout(snap: DiscoverySnapshot): ProgramLayout {
     const root = snap.roots.find((r) => r.id === "user-bin")
     const installs = deps.manifest?.artifacts.some((a) => a.target === snap.host.target)
-    if (root && installs) return { kind: "standalone", executable: `${rootPathIn(root, executionContextOf(snap))}/${HUBCTL_REF.rel}` }
+    if (root && installs) return { kind: "standalone", executable: `${rootPathIn(root, executionContextOf(snap))}/${hubctlRefs(snap.host.target).hubctl.rel}` }
     return deps.layout
   }
 

package/packages/cli/src/setup/self-aside.ts

@@ -0,0 +1,130 @@
+// Windows: the setup commands delete, once this process has exited, the aside of the hubctl.exe that is running them.
+//
+// A rollback that undoes hubctl's own install (`~\.local\bin\hubctl.exe setup rollback`) removes the very executable
+// that runs it. The engine moves it aside (`<name>.old-<txid>-<seq>-undo`, Phase 2 contract "rename-aside"), but a
+// running image cannot be deleted on Windows, and a later apply or recover would sweep it only if some hubctl were
+// left to run one. So the command hands the delete to a detached, hidden `cmd.exe` that retries it once a second
+// (bounded) until the file is gone, which is right after this process exits. Only for:
+//   - the aside that is this executable: the same file ID as the hubctl.exe this process started from;
+//   - inside user-bin, with the aside name pattern;
+//   - a path cmd takes literally (printable ASCII without " % ^ & | < > ! ( )); the command line is fixed otherwise,
+//     so nothing from outside reaches cmd's parser.
+// Anything else is left as it was, and the command says so. POSIX unlinks a running executable directly: nothing here.
+// MoveFileEx(MOVEFILE_DELAY_UNTIL_REBOOT) would need FFI (and admin for the PendingFileRenameOperations key).
+import { spawn } from "node:child_process"
+import { readdirSync, statSync, unlinkSync } from "node:fs"
+import { toNativePath } from "../bootstrap/contracts/index.ts"
+import { normalizeAbs } from "../bootstrap/discovery/util.ts"
+
+/** The platform calls, injectable (tests). */
+export interface SelfAsideIo {
+  readonly platform: string
+  /** %SystemRoot% (C:\Windows): where cmd.exe and PING.EXE are run from, never through PATH. */
+  readonly systemRoot: string
+  /** The file ID of `path`, undefined when it is not there. */
+  stat(path: string): { readonly ino: bigint } | undefined
+  readdir(path: string): string[]
+  unlink(path: string): void
+  /** Starts `file` with exactly `line` as its arguments (no quoting added), detached and hidden, not waited for. */
+  spawnDetached(file: string, line: string, cwd: string): void
+}
+
+/** The executable this process runs from, as it was when the command started. */
+export interface SelfIdentity {
+  /** Canonical (C:/… on Windows). */
+  readonly path: string
+  readonly ino: bigint
+}
+
+export type SelfAsideOutcome =
+  | { readonly state: "none" }
+  | { readonly state: "deleted" | "scheduled"; readonly aside: string }
+  | { readonly state: "left"; readonly aside: string; readonly reason: string }
+
+export const nodeSelfAsideIo = (env: Readonly<Record<string, string | undefined>> = process.env): SelfAsideIo => ({
+  platform: process.platform,
+  systemRoot: env.SystemRoot ?? env.SYSTEMROOT ?? "C:\\Windows",
+  stat: (path) => {
+    try {
+      return { ino: statSync(path, { bigint: true }).ino }
+    } catch {
+      return undefined
+    }
+  },
+  readdir: (path) => readdirSync(path),
+  unlink: (path) => unlinkSync(path),
+  spawnDetached: (file, line, cwd) => {
+    const child = spawn(file, [line], { cwd, detached: true, stdio: "ignore", windowsHide: true, windowsVerbatimArguments: true })
+    child.on("error", () => {})
+    child.unref()
+  },
+})
+
+/** The aside names rename-aside gives `base` (engine.ts asidePath). */
+const ASIDE = /\.old-tx_[A-Za-z0-9]{1,64}-\d{1,9}(-undo)?$/
+/** What cmd takes literally inside double quotes, outside any variable expansion or grouping. */
+const CMD_SAFE = /^[\x20-\x7e]+$/
+const CMD_SPECIAL = /["%^&|<>!()]/
+
+const key = (p: string) => p.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase()
+const parent = (p: string) => p.slice(0, p.lastIndexOf("/")) || "/"
+const nameOf = (p: string) => p.slice(p.lastIndexOf("/") + 1)
+
+function cmdLiteral(path: string, what: string): string {
+  if (!CMD_SAFE.test(path) || CMD_SPECIAL.test(path)) throw new Error(`${what} ${JSON.stringify(path)} is not a path cmd takes literally (printable ASCII without " % ^ & | < > ! ( ))`)
+  return path
+}
+
+/** The fixed cmd.exe call that deletes `aside` once it is no longer running: about two minutes of retries at most. */
+export function deleteAfterExitCommand(aside: string, systemRoot: string): { file: string; line: string } {
+  if (!ASIDE.test(aside)) throw new Error(`${JSON.stringify(aside)} is not a rename-aside name`)
+  const p = cmdLiteral(toNativePath(aside, "win32"), "the aside")
+  const root = cmdLiteral(systemRoot.replace(/\//g, "\\").replace(/\\+$/, ""), "SystemRoot")
+  return {
+    file: `${root}\\System32\\cmd.exe`,
+    line: `/d /s /c "for /l %i in (1,1,120) do @if exist "${p}" ("${root}\\System32\\PING.EXE" -n 2 127.0.0.1 >nul & del /f /q "${p}" >nul 2>&1)"`,
+  }
+}
+
+/** Records the executable this process runs from (before a command may move it aside). */
+export function selfIdentity(execPath: string, io: SelfAsideIo = nodeSelfAsideIo()): SelfIdentity | undefined {
+  const path = normalizeAbs(execPath)
+  if (!path) return undefined
+  const st = io.stat(path)
+  return st ? { path, ino: st.ino } : undefined
+}
+
+/**
+ * After a command: when `self` (this process's executable, inside `userBin`) was moved aside, deletes the aside, or
+ * when it is still running (it is: this process), schedules its deletion for after this process exits.
+ */
+export function removeSelfAside(self: SelfIdentity | undefined, userBin: string | undefined, io: SelfAsideIo = nodeSelfAsideIo()): SelfAsideOutcome {
+  if (io.platform !== "win32" || !self || !userBin) return { state: "none" }
+  const dir = parent(self.path)
+  if (key(dir) !== key(userBin)) return { state: "none" }
+  if (io.stat(self.path)?.ino === self.ino) return { state: "none" }
+  let names: string[]
+  try {
+    names = io.readdir(dir)
+  } catch {
+    return { state: "none" }
+  }
+  const base = nameOf(self.path).toLowerCase()
+  for (const name of names) {
+    if (!name.toLowerCase().startsWith(`${base}.old-`) || !ASIDE.test(name) || name.length - base.length !== name.match(ASIDE)![0].length) continue
+    const aside = `${dir}/${name}`
+    if (io.stat(aside)?.ino !== self.ino) continue
+    try {
+      io.unlink(aside)
+      return { state: "deleted", aside }
+    } catch {}
+    try {
+      const { file, line } = deleteAfterExitCommand(aside, io.systemRoot)
+      io.spawnDetached(file, line, file.slice(0, file.lastIndexOf("\\")))
+      return { state: "scheduled", aside }
+    } catch (error) {
+      return { state: "left", aside, reason: error instanceof Error ? `${(error as NodeJS.ErrnoException).code ?? ""} ${error.message}`.trim() : String(error) }
+    }
+  }
+  return { state: "none" }
+}

package/packages/codex/package.json

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

package/packages/node/package.json

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

package/packages/node/src/opencode-warm.ts

@@ -17,6 +17,7 @@
 import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync, statSync, type Stats } from "node:fs"
 import path from "node:path"
 import { listServiceSessions, type ListingClient, type RawProject, type RawSession } from "../../../src/spoke/listing.ts"
+import { defaultWinAcl, isWin32, nativeWinPath, type SecretFileOptions } from "../../../src/win-acl.ts"
 
 /** How often the daemon asks (a restarted server is warmed within this). */
 export const WARM_INTERVAL_MS = 30_000
@@ -290,9 +291,11 @@ const PSEUDO_ROOTS = ["/proc", "/sys", "/dev"]
  * A server password from a file (its first line): only a private regular file (not a link, FIFO, device or socket,
  * nothing under /proc, /sys or /dev, no symbolic link in its directory path, no group or other access, owned by this
  * user) of 1 byte to 4 KiB. Never blocks: the file is checked with lstat before it is opened, and opened with
- * O_NONBLOCK and O_NOFOLLOW (then checked again on the descriptor). Problems never include the content.
+ * O_NONBLOCK and O_NOFOLLOW (then checked again on the descriptor). Problems never include the content. On Windows
+ * (no modes, no uid) "private" is an access list that allows no one but this user, SYSTEM and Administrators
+ * (src/win-acl.ts); `options` injects the platform and the ACL helper.
  */
-export function readPasswordFile(file: string): { password: string } | { problem: string } {
+export function readPasswordFile(file: string, options?: SecretFileOptions): { password: string } | { problem: string } {
   if (!path.isAbsolute(file)) return { problem: `password file ${file} is not an absolute path` }
   const resolved = path.resolve(file)
   if (PSEUDO_ROOTS.some((root) => resolved === root || resolved.startsWith(`${root}/`))) return { problem: `password file ${file} is not a regular file` }
@@ -320,8 +323,13 @@ export function readPasswordFile(file: string): { password: string } | { problem
   try {
     const stat = fstatSync(fd)
     if (!stat.isFile() || stat.dev !== before.dev || stat.ino !== before.ino) return { problem: `password file ${file} is not a regular file` }
-    if ((stat.mode & 0o077) !== 0) return { problem: `password file ${file} is readable by others (chmod 600 it)` }
-    if (typeof process.getuid === "function" && stat.uid !== process.getuid()) return { problem: `password file ${file} is not owned by this user` }
+    if (isWin32(options)) {
+      const acl = (options?.acl ?? defaultWinAcl()).check(nativeWinPath(resolved))
+      if (!acl.ok) return { problem: `password file ${file} is readable by others (${acl.problem})` }
+    } else {
+      if ((stat.mode & 0o077) !== 0) return { problem: `password file ${file} is readable by others (chmod 600 it)` }
+      if (typeof process.getuid === "function" && stat.uid !== process.getuid()) return { problem: `password file ${file} is not owned by this user` }
+    }
     if (stat.size === 0) return { problem: `password file ${file} is empty` }
     if (stat.size > PASSWORD_FILE_MAX) return { problem: `password file ${file} is too large` }
     const buffer = Buffer.alloc(PASSWORD_FILE_MAX + 1)

package/packages/preset/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-preset",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "private": true,
   "description": "The preset spoke: drives a harness without a spoke of its own through a terminal pane (tmux), described by a data-only preset; official presets in presets/ (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-protocol",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "private": true,
   "description": "Hub ↔ spoke wire protocol (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/runtime-openshell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-runtime-openshell",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "private": true,
   "description": "The `openshell` runtime of `hub node`: launches in NVIDIA OpenShell sandboxes, driven through the openshell CLI (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/runtime-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-runtime-sdk",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "private": true,
   "description": "The Runtime interface `hub node` runtimes implement (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-sdk",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "private": true,
   "description": "Typed client for the hub's /api/agent (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/spoke-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-spoke-sdk",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "private": true,
   "description": "Harness-neutral spoke building blocks: hub connection, enrollment, tokens, idempotent deliver, prompt references, HarnessSpoke (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",