@huynle/hub 0.8.4 → 0.8.5

package/packages/cli/src/bootstrap/transaction/engine.ts

@@ -20,6 +20,18 @@
 //     credential, refuse a backup that does not match what it backed up;
 //   - resume after a crash: continue the stored plan from the interrupted step, when the host still agrees.
 //
+// On win32 (Phase 2 contract "Install primitives on win32"): a file or link that may be in use (hubctl.exe while
+// OpenCode runs `hubctl mcp`) cannot be renamed over, so it is replaced by rename-aside: the old entry is moved to
+// `<name>.old-<txID>-<seq>` in the same directory, the staged one moved in, and the aside deleted when possible (else
+// a later apply or recover sweeps it). A crash between the two renames is healed by renaming the aside back before
+// recovery or resume looks at the target, and a rollback renames the aside back rather than copying the backup.
+// Journal entries record no mode there (not applicable; comparisons skip it).
+// A path a rollback cannot move or delete because a program has it open (EBUSY; on win32 also EPERM/EACCES: a
+// running exe, or the directory holding one) never stops the rollback: every other entry is undone, the transaction
+// stays unfinished (`failed`, recovery required) with a message naming each busy path and what to do, and
+// `hubctl setup recover` finishes it (including the version directory moved aside, `.<name>.hub-<txID>-<seq>.tmp`)
+// once the program has exited.
+//
 // The engine performs only the TxFs operations; it never spawns processes or runs commands.
 import { randomBytes } from "node:crypto"
 import {
@@ -32,6 +44,7 @@ import {
   revalidatePreview,
   SETUP_PREVIEW_SCHEMA,
   snapshotDigest,
+  toNativePath,
   validateSetupPlan,
   type Action,
   type ApplyLock,
@@ -52,7 +65,7 @@ import {
   type TransactionJournal,
 } from "../contracts/index.ts"
 import type { ActionExecutor, Change, ExecutorMap, HostInfo, StepContext, StepPlan, TreeFile } from "./executor.ts"
-import { nodeFs, type TxFs } from "./fs.ts"
+import { createNodeFs, nodeFs, type TxFs } from "./fs.ts"
 import { breakStaleLock, releaseLock, renewLock, tryAcquireLock, type LockIO } from "./lock.ts"
 import { resolveTarget, rootDir, type ResolveOptions } from "./resolve.ts"
 import { errnoOf, fromResult, TxError, txFail, txOk, type TxFailure, type TxResult } from "./result.ts"
@@ -72,6 +85,8 @@ export interface ApplierConfig {
   readonly host: HostInfo
   readonly executors: ExecutorMap
   readonly fs?: TxFs
+  /** The platform (default process.platform): "win32" switches links, replacement and modes (see above). */
+  readonly platform?: string
   readonly now?: () => number
   readonly pid?: number
   /** Whether a process on this host is alive (default: signal 0). */
@@ -209,8 +224,44 @@ function failureOf(error: unknown): TxFailure {
   return txFail("internal", code ? `filesystem error ${code}: ${(error as Error).message}` : `unexpected error: ${error instanceof Error ? error.message : String(error)}`)
 }
 
+/** A path a rollback could not move or delete because a program has it open (Windows: a running exe). */
+interface Busy {
+  readonly path: string
+  readonly code: string
+  readonly directory: boolean
+}
+
+/**
+ * Whether `error` is a path in use: EBUSY anywhere; on win32 also EPERM/EACCES, which is what deleting or renaming a
+ * running exe (or a directory holding one) fails with. The path is the error's own, else `fallback`.
+ */
+function busyOf(error: unknown, fallback: string | undefined, win: boolean): Omit<Busy, "directory"> | undefined {
+  const code = errnoOf(error)
+  if (!(code === "EBUSY" || (win && (code === "EPERM" || code === "EACCES")))) return undefined
+  const own = (error as { path?: unknown }).path
+  const path = typeof own === "string" && own ? own.replace(/\\/g, "/") : fallback
+  return path ? { path, code } : undefined
+}
+
+/** Names every busy path and what to do; the native form on Windows. */
+function busyMessage(txID: string, busy: readonly Busy[], platform: string): string {
+  const native = (p: string) => toNativePath(p, platform)
+  // Where the program runs from, as the user knows it: a tree a rollback moved aside (`.<name>.hub-<txID>-<seq>.tmp`)
+  // under its own name.
+  const known = (p: string) => p.replace(/\/\.([^/]+)\.hub-tx_[A-Za-z0-9_]+-\d+\.tmp(?=\/|$)/g, "/$1")
+  const dirs = [...new Set(busy.map((b) => native(known(b.directory ? b.path : dirname(b.path)))))]
+  return `rollback of ${txID} is not finished: ${busy.map((b) => `${native(b.path)} is in use (${b.code})`).join("; ")}; close OpenCode or any program running from ${dirs.join(", ")}, then run \`hubctl setup recover\``
+}
+
+/** Where rename-aside moves the old entry of `target` (forward), or the entry hub wrote (a rollback's undo). */
+const asidePath = (target: string, txID: string, seq: number, undo = false) => `${target}.old-${txID}-${seq}${undo ? "-undo" : ""}`
+
 export function createApplier(config: ApplierConfig): Applier {
-  const fs = config.fs ?? nodeFs
+  const platform = config.platform ?? process.platform
+  const win = platform === "win32"
+  const fs = config.fs ?? (config.platform === undefined ? nodeFs : createNodeFs(platform))
+  /** A mode for the journal: none on win32. */
+  const modeIn = (mode: number): { mode?: number } => (win ? {} : { mode })
   const now = config.now ?? Date.now
   const pid = config.pid ?? process.pid
   const isAlive = config.isAlive ?? defaultIsAlive
@@ -218,6 +269,28 @@ export function createApplier(config: ApplierConfig): Applier {
   const hooks = config.hooks ?? {}
   const context: ExecutionContext = config.context ?? "host"
 
+  /** Removes `path` if it is there; false when it is still in use (a running executable on Windows). */
+  const discard = (path: string): boolean => {
+    try {
+      if (fs.lstat(path)) fs.unlink(path)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /** win32: deletes what rename-aside left of `journal`'s steps (asides that were still in use then). */
+  const sweepAsides = (journal: TransactionJournal): void => {
+    if (!win) return
+    for (const e of journal.entries) {
+      if (!e.path) continue
+      const r = resolveTarget(e.path, config.roots, fs, { context, ...(e.class === "link" ? { finalMayBeSymlink: true } : {}) })
+      if (!r.ok) continue
+      discard(asidePath(r.value, journal.txID, e.seq))
+      discard(asidePath(r.value, journal.txID, e.seq, true))
+    }
+  }
+
   const lockIO = (store: TxStore): LockIO => ({ fs, path: store.lockPath, hostFingerprint: config.host.fingerprint, pid, now, isAlive })
 
   /** Interrupted transactions of this host. Another host's (a shared home) are reported, never touched here. */
@@ -262,6 +335,7 @@ export function createApplier(config: ApplierConfig): Applier {
     const lock = { current: attempt.lock }
     try {
       store.sweep()
+      if (win) for (const j of store.journals()) if (FINISHED.includes(j.state) && j.hostFingerprint === config.host.fingerprint) sweepAsides(j)
       return await body(store, lock)
     } catch (error) {
       return failureOf(error)
@@ -489,6 +563,7 @@ export function createApplier(config: ApplierConfig): Applier {
         context,
         host: config.host,
         now,
+        platform,
         target,
         current,
         original: this.original(step.path, current),
@@ -524,7 +599,10 @@ export function createApplier(config: ApplierConfig): Applier {
             break
           }
         }
-        if (!failure) this.persist({ state: "committed" })
+        if (!failure) {
+          this.persist({ state: "committed" })
+          sweepAsides(this.journal)
+        }
       } catch (error) {
         failure = failureOf(error)
       }
@@ -622,7 +700,7 @@ export function createApplier(config: ApplierConfig): Applier {
       const info = fs.lstat(abs)
       if (info?.kind === "directory") return
       if (info) throw new TxError("conflict", `${abs} is not a directory`)
-      const entry = await this.append({ actionID: action.id, kind: action.kind, class: "directory", path: ref, before: { exists: false }, after: { exists: true, mode: PARENT_MODE }, status: "pending" })
+      const entry = await this.append({ actionID: action.id, kind: action.kind, class: "directory", path: ref, before: { exists: false }, after: { exists: true, ...modeIn(PARENT_MODE) }, status: "pending" })
       const again = this.resolve(ref)
       if (!again.ok) throw new TxError(again.code, `${action.id}: ${again.message}`)
       fs.mkdir(abs, PARENT_MODE)
@@ -710,7 +788,7 @@ export function createApplier(config: ApplierConfig): Applier {
         case "directory": {
           if (current.exists) return kind === "directory" ? this.skip() : conflict("exists and is not a directory")
           await this.parents(action, path!)
-          const entry = await this.append({ actionID: action.id, kind: action.kind, class: step.class, path: path!, before: current, after: { exists: true, mode: change.mode }, status: "pending" })
+          const entry = await this.append({ actionID: action.id, kind: action.kind, class: step.class, path: path!, before: current, after: { exists: true, ...modeIn(change.mode) }, status: "pending" })
           this.recheck(action, step)
           fs.mkdir(target!, change.mode)
           fs.chmod(target!, change.mode)
@@ -721,7 +799,7 @@ export function createApplier(config: ApplierConfig): Applier {
         case "symlink": {
           const desired: FileState =
             change.type === "file"
-              ? { exists: true, sha256: "bytes" in change ? sha256Of(change.bytes) : change.staged.sha256, mode: change.mode }
+              ? { exists: true, sha256: "bytes" in change ? sha256Of(change.bytes) : change.staged.sha256, ...modeIn(change.mode) }
               : { exists: true, symlink: true, sha256: sha256Of(change.target) }
           if (current.exists) {
             if (sameState(current, desired) && (change.type === "symlink" || kind === "file")) return this.skip()
@@ -737,7 +815,7 @@ export function createApplier(config: ApplierConfig): Applier {
           if (change.type === "symlink") fs.symlink(change.target, staged)
           else if ("bytes" in change) fs.writeExclusive(staged, change.bytes, change.mode)
           else this.place(change.staged, staged, change.mode, ctx.staging)
-          fs.rename(staged, target!)
+          this.replace(staged, target!, asidePath(target!, this.txID, entry.seq))
           fs.fsyncDir(dirname(target!))
           const after = fileState(fs, target!)
           if (!sameState(after, desired)) throw new TxError("conflict", `${action.id}: ${target} changed while it was being written`)
@@ -745,7 +823,7 @@ export function createApplier(config: ApplierConfig): Applier {
           return txOk("applied")
         }
         case "tree": {
-          const desired: FileState = { exists: true, sha256: treeDigestOfFiles(change.files, change.mode), mode: change.mode }
+          const desired: FileState = { exists: true, sha256: treeDigestOfFiles(change.files, change.mode, { modes: !win }), ...modeIn(change.mode) }
           if (current.exists) return sameState(current, desired) ? this.skip() : conflict("already exists with other content (install roots are never overwritten)")
           await this.parents(action, path!)
           const entry = await this.append({ actionID: action.id, kind: action.kind, class: step.class, path: path!, before: current, after: desired, status: "pending" })
@@ -762,6 +840,43 @@ export function createApplier(config: ApplierConfig): Applier {
       }
     }
 
+    /**
+     * Moves `staged` over `target`. POSIX: one atomic rename. win32: rename-aside when something is there (a rename
+     * cannot replace a directory link or a file in use): the old entry to `aside`, the staged one in (on failure the
+     * old one is moved back), then the aside deleted if it is no longer in use (else swept later).
+     */
+    private replace(staged: string, target: string, aside: string): void {
+      if (!win || !fs.lstat(target)) {
+        fs.rename(staged, target)
+        return
+      }
+      discard(aside)
+      fs.rename(target, aside)
+      try {
+        fs.rename(staged, target)
+      } catch (error) {
+        try {
+          fs.rename(aside, target)
+        } catch {}
+        throw error
+      }
+      discard(aside)
+    }
+
+    /**
+     * win32: a crash between the two renames of a rename-aside leaves `target` missing and its aside in place; this
+     * renames the aside back (a rollback's, else the forward step's) so recovery sees the target as it was.
+     */
+    private heal(target: string, seq: number): void {
+      if (!win || fs.lstat(target)) return
+      for (const aside of [asidePath(target, this.txID, seq, true), asidePath(target, this.txID, seq)]) {
+        if (fs.lstat(aside)) {
+          fs.rename(aside, target)
+          return
+        }
+      }
+    }
+
     private stageTree(dir: string, files: readonly TreeFile[], mode: number, staging: StagingArea): void {
       fs.mkdir(dir, mode)
       fs.chmod(dir, mode)
@@ -809,6 +924,7 @@ export function createApplier(config: ApplierConfig): Applier {
       }
       const target = this.resolve(entry.path, this.resolveOptions(entry))
       if (!target.ok) return txFail("recovery_required", `${entry.actionID}: ${target.message}; roll back instead`)
+      this.heal(target.value, entry.seq)
       const current = fileState(fs, target.value, { tree: entry.class === "harness" })
       if (entry.after && sameState(current, entry.after)) {
         this.persist({ entries: this.journal.entries.map((e) => (e.seq === entry.seq ? { ...e, status: "done" } : e)) })
@@ -835,18 +951,40 @@ export function createApplier(config: ApplierConfig): Applier {
 
     async rollbackAll(): Promise<TxOutcome> {
       const decided: RecoveryStep[] = []
+      const busy: Busy[] = []
+      /** Runs one entry's undo; a path in use (a running program) is noted and the rollback goes on. */
+      const tolerant = async (entry: JournalEntry, work: () => Promise<void> | void) => {
+        try {
+          await work()
+        } catch (error) {
+          const fallback = entry.path ? this.resolve(entry.path, this.resolveOptions(entry)) : undefined
+          const found = busyOf(error, fallback?.ok ? fallback.value : undefined, win)
+          if (!found) throw error
+          if (!busy.some((b) => b.path === found.path)) busy.push({ ...found, directory: fs.lstat(found.path)?.kind === "directory" })
+        }
+      }
       try {
         if (this.journal.state !== "rolling-back") this.persist({ state: "rolling-back" })
         for (const entry of [...this.journal.entries].reverse()) {
           if (entry.status === "undone" || entry.status === "skipped") {
             // An interrupted earlier rollback may have left this entry's staging (or a tree moved aside) behind.
-            const r = entry.path ? this.resolve(entry.path, this.resolveOptions(entry)) : undefined
-            if (r?.ok) this.removeStaging(r.value, entry.seq)
+            await tolerant(entry, () => {
+              const r = entry.path ? this.resolve(entry.path, this.resolveOptions(entry)) : undefined
+              if (r?.ok) this.removeStaging(r.value, entry.seq)
+            })
             continue
           }
-          decided.push({ seq: entry.seq, actionID: entry.actionID, decision: await this.undo(entry) })
+          await tolerant(entry, async () => {
+            decided.push({ seq: entry.seq, actionID: entry.actionID, decision: await this.undo(entry) })
+          })
+        }
+        if (busy.length > 0) {
+          // Everything else is undone; the transaction stays unfinished until the program has exited.
+          this.persist({ state: "failed" })
+          return { ...txFail("recovery_required", busyMessage(this.txID, busy, platform)), report: this.report() }
         }
         this.persist({ state: "rolled-back" })
+        sweepAsides(this.journal)
         this.cleanup()
         await hooks.onRecover?.(copy(this.journal), copy(decided))
         return { ok: true, report: this.report() }
@@ -890,6 +1028,7 @@ export function createApplier(config: ApplierConfig): Applier {
       }
       const target = resolved.value
       this.removeStaging(target, entry.seq)
+      this.heal(target, entry.seq)
       const current = fileState(fs, target, { tree: entry.class === "harness" })
       if (sameState(current, entry.before)) {
         await this.mark(entry, entry.after ? "undone" : "skipped")
@@ -906,6 +1045,14 @@ export function createApplier(config: ApplierConfig): Applier {
           await this.conflict(entry, target, "changed since hub wrote it; kept as it is", current)
           break
         case "restore-backup": {
+          // win32: the old entry rename-aside moved away is still there when it was in use: rename it back (the very
+          // file that may be running), rather than copying the backup over it.
+          const aside = asidePath(target, this.txID, entry.seq)
+          if (win && fs.lstat(aside) && sameState(fileState(fs, aside), entry.before)) {
+            this.replace(aside, target, asidePath(target, this.txID, entry.seq, true))
+            await this.mark(entry, "undone")
+            break
+          }
           // A symlink's backup is its target text; a file's is read and copied in chunks, never whole.
           const link = entry.backup && entry.before.symlink ? this.store.readBackup(this.txID, entry.backup.id) : undefined
           const file = entry.backup && !entry.before.symlink ? this.store.backupFile(this.txID, entry.backup.id) : undefined
@@ -921,7 +1068,7 @@ export function createApplier(config: ApplierConfig): Applier {
             await this.conflict(entry, target, "its backup changed while it was restored; left as hub wrote it", current)
             return "keep-user-edit"
           }
-          fs.rename(staged, target)
+          this.replace(staged, target, asidePath(target, this.txID, entry.seq, true))
           fs.fsyncDir(dirname(target))
           await this.mark(entry, "undone")
           break
@@ -944,6 +1091,13 @@ export function createApplier(config: ApplierConfig): Applier {
               return "keep-user-edit"
             }
             await this.mark(entry, "undone")
+          } else if (win && kind === "file") {
+            // A file hub created may be running now (hubctl.exe): move it aside, then delete it if it is not.
+            const aside = asidePath(target, this.txID, entry.seq, true)
+            discard(aside)
+            fs.rename(target, aside)
+            await this.mark(entry, "undone")
+            discard(aside)
           } else {
             fs.unlink(target)
             await this.mark(entry, "undone")

package/packages/cli/src/bootstrap/transaction/executor.ts

@@ -72,6 +72,11 @@ export interface StepContext {
   readonly context: ExecutionContext
   readonly host: HostInfo
   readonly now: () => number
+  /**
+   * The platform apply runs on (process.platform unless injected). On "win32" links differ: link-executable writes a
+   * cmd shim, directory links are junctions with an absolute target (Phase 2 contract).
+   */
+  readonly platform?: string
   /** The resolved, symlink-checked absolute path of the step's target (when it has one). */
   readonly target?: string
   /** The target's state now. */

package/packages/cli/src/bootstrap/transaction/fs.ts

@@ -5,6 +5,12 @@
 // Writes are only ever "create a new file exclusively" (O_CREAT|O_EXCL|O_NOFOLLOW, then fsync); replacing a file is
 // always stage-then-rename, so a reader (or a crash) sees the old file or the new one, never a torn mix. Large files
 // (a harness binary, hubctl itself) are written and read in chunks (createExclusive, readRange), never whole.
+//
+// On Windows (createNodeFs("win32"), Phase 2 contract): O_NOFOLLOW does not exist, so every open that must not
+// follow a link is preceded by an explicit lstat that refuses one (lstat reports junctions and symlinks alike as
+// links); there are no POSIX modes (lstat reports `mode: null`, chmod and fchmod are no-ops, files are created
+// writable); a directory cannot be opened for fsync (fsyncDir is a no-op); and a directory link is an NTFS junction
+// with an absolute target (no admin or Developer Mode needed), read back in canonical form (C:/…).
 import {
   chmodSync,
   closeSync,
@@ -26,11 +32,12 @@ import {
   writeSync,
 } from "node:fs"
 import type { EntryKind } from "../contracts/index.ts"
+import { canonicalWinLink, normalizeAbs } from "../discovery/util.ts"
 
 export interface EntryInfo {
   readonly kind: EntryKind
-  /** Permission bits (0..0o7777). */
-  readonly mode: number
+  /** Permission bits (0..0o7777); null where the platform has none (win32). */
+  readonly mode: number | null
   readonly size: number
 }
 
@@ -87,7 +94,8 @@ function kindOf(mode: number): EntryKind {
 
 const errno = (error: unknown) => (error as NodeJS.ErrnoException | undefined)?.code
 
-export const nodeFs: TxFs = {
+/** The POSIX filesystem (macOS, Linux). */
+const posixFs: TxFs = {
   lstat(path) {
     try {
       const s = lstatSync(path)
@@ -192,3 +200,134 @@ export const nodeFs: TxFs = {
     } catch {}
   },
 }
+
+export { canonicalWinLink }
+
+const linkError = (path: string) => Object.assign(new Error(`ELOOP: ${path} is a link; refusing to open it`), { code: "ELOOP", path })
+
+/** O_NOFOLLOW's guarantee where it does not exist: refuse a link (symlink or junction) at `path` right before an open. */
+function refuseLink(path: string): void {
+  let link = false
+  try {
+    link = lstatSync(path).isSymbolicLink()
+  } catch {}
+  if (link) throw linkError(path)
+}
+
+/**
+ * POSIX modes do not exist on Windows; Node maps a mode without 0o200 to a read-only file, which is never wanted.
+ * Opens use string flags ("wx", "r"): Bun on Windows does not honour numeric O_CREAT/O_EXCL from fs.constants
+ * (seen on Windows 11, Bun 1.3.5: O_CREAT|O_EXCL|O_WRONLY on a missing file fails with ENOENT, and on an existing
+ * junction opens it instead of failing).
+ */
+const WIN_CREATE_MODE = 0o666
+
+const parentOf = (p: string) => {
+  const at = Math.max(p.lastIndexOf("/"), p.lastIndexOf("\\"))
+  return at <= 0 ? p : p.slice(0, at)
+}
+const isAbsolute = (p: string) => p.startsWith("/") || /^[A-Za-z]:[\\/]/.test(p)
+
+const winFs: TxFs = {
+  ...posixFs,
+  lstat(path) {
+    const info = posixFs.lstat(path)
+    return info ? { ...info, mode: null } : undefined
+  },
+  readRange(path, offset, length) {
+    refuseLink(path)
+    const fd = openSync(path, "r")
+    try {
+      const out = new Uint8Array(length)
+      let got = 0
+      while (got < length) {
+        const n = readSync(fd, out, got, length - got, offset + got)
+        if (n === 0) break
+        got += n
+      }
+      return got === length ? out : out.subarray(0, got)
+    } finally {
+      closeSync(fd)
+    }
+  },
+  readlink: (path) => canonicalWinLink(readlinkSync(path)),
+  writeExclusive(path, data, _mode) {
+    refuseLink(path)
+    const fd = openSync(path, "wx", WIN_CREATE_MODE)
+    let ok = false
+    try {
+      const bytes = typeof data === "string" ? Buffer.from(data, "utf8") : data
+      let offset = 0
+      while (offset < bytes.byteLength) offset += writeSync(fd, bytes, offset, bytes.byteLength - offset)
+      fsyncSync(fd)
+      ok = true
+    } finally {
+      closeSync(fd)
+      if (!ok) {
+        try {
+          unlinkSync(path)
+        } catch {}
+      }
+    }
+  },
+  createExclusive(path, _mode) {
+    refuseLink(path)
+    const fd = openSync(path, "wx", WIN_CREATE_MODE)
+    let open = true
+    const finish = (complete: boolean) => {
+      if (!open) return
+      open = false
+      try {
+        if (complete) fsyncSync(fd)
+      } finally {
+        closeSync(fd)
+        if (!complete) {
+          try {
+            unlinkSync(path)
+          } catch {}
+        }
+      }
+    }
+    return {
+      write(chunk) {
+        if (!open) throw new Error(`${path} is already closed`)
+        let offset = 0
+        while (offset < chunk.byteLength) offset += writeSync(fd, chunk, offset, chunk.byteLength - offset)
+      },
+      close() {
+        try {
+          finish(true)
+        } catch (error) {
+          try {
+            unlinkSync(path)
+          } catch {}
+          throw error
+        }
+      },
+      abort: () => finish(false),
+    }
+  },
+  unlink(path) {
+    try {
+      unlinkSync(path)
+    } catch (error) {
+      // A junction is a directory link: some runtimes remove it with rmdir only (the target is never touched).
+      const code = errno(error)
+      if ((code === "EPERM" || code === "EISDIR" || code === "EACCES") && lstatSync(path).isSymbolicLink()) rmdirSync(path)
+      else throw error
+    }
+  },
+  mkdir: (path) => mkdirSync(path),
+  mkdirp: (path) => void mkdirSync(path, { recursive: true }),
+  symlink(target, path) {
+    const absolute = isAbsolute(target) ? target : `${parentOf(path)}/${target}`
+    symlinkSync(absolute, path, "junction")
+  },
+  chmod: () => {},
+  fsyncDir: () => {},
+}
+
+/** The filesystem for `platform` (default: this process's). */
+export const createNodeFs = (platform: string = process.platform): TxFs => (platform === "win32" ? winFs : posixFs)
+
+export const nodeFs: TxFs = createNodeFs()

package/packages/cli/src/bootstrap/transaction/shim.ts

@@ -0,0 +1,31 @@
+// The cmd shim that stands in for an executable symlink on Windows (Phase 2 contract): symlinks to executables need
+// Developer Mode or admin there, so link-executable writes `user-bin:<name>.cmd` holding exactly
+// `@"<native target>" %*\r\n` (ASCII). The applier journals it as a file it owns; readers that check "is this the
+// hub link to X" (setup verify, the user-bin link rule) parse it back with parseCmdShim.
+import { normalizeAbs } from "../discovery/util.ts"
+import { toNativePath } from "../contracts/index.ts"
+
+// Inside the quotes cmd still expands %VAR%; a quote would end them. Printable ASCII only.
+const UNSAFE = /[^\x20-\x7e]|["%]/
+
+/** `path` (canonical C:/… or native) as one double-quoted cmd word. Throws for a path cmd would not take literally. */
+export function cmdWord(path: string): string {
+  const native = toNativePath(path, "win32")
+  if (UNSAFE.test(native)) throw new Error(`cannot write a cmd shim for ${JSON.stringify(path)}: the path must be printable ASCII without " or %`)
+  return `"${native}"`
+}
+
+/** The shim's bytes for the canonical `target` (C:/… on Windows). Throws for a target cmd would not run literally. */
+export function cmdShim(target: string): Uint8Array {
+  return new TextEncoder().encode(`@${cmdWord(target)} %*\r\n`)
+}
+
+const SHIM = /^@"([\x20-\x7e]+)" %\*\r\n$/
+
+/** The canonical target of a hub cmd shim, or undefined when `bytes` are anything else. */
+export function parseCmdShim(bytes: Uint8Array): string | undefined {
+  if (bytes.byteLength > 4096) return undefined
+  const m = SHIM.exec(new TextDecoder("latin1").decode(bytes))
+  if (!m || UNSAFE.test(m[1]!)) return undefined
+  return normalizeAbs(m[1]!)
+}

package/packages/cli/src/bootstrap/transaction/state.ts

@@ -7,6 +7,9 @@ import type { TreeFile } from "./executor.ts"
 import type { TxFs } from "./fs.ts"
 import { fileDigest } from "./stream.ts"
 
+/** A FileState's mode, omitted where the platform has none (win32: lstat reports null, comparisons skip it). */
+const modeOf = (mode: number | null) => (mode === null ? {} : { mode })
+
 export const sha256Of = (data: Uint8Array | string): string => `sha256:${sha256Hex(data)}`
 
 export function fileState(fs: TxFs, path: string, options: { readonly tree?: boolean } = {}): FileState {
@@ -14,11 +17,11 @@ export function fileState(fs: TxFs, path: string, options: { readonly tree?: boo
   if (!info) return { exists: false }
   switch (info.kind) {
     case "file":
-      return { exists: true, sha256: fileDigest(fs, path), mode: info.mode }
+      return { exists: true, sha256: fileDigest(fs, path), ...modeOf(info.mode) }
     case "symlink":
       return { exists: true, symlink: true, sha256: sha256Of(fs.readlink(path)) }
     case "directory":
-      return options.tree ? { exists: true, sha256: treeDigest(fs, path), mode: info.mode } : { exists: true, mode: info.mode }
+      return options.tree ? { exists: true, sha256: treeDigest(fs, path), ...modeOf(info.mode) } : { exists: true, ...modeOf(info.mode) }
     default:
       return { exists: true }
   }
@@ -47,9 +50,11 @@ export function treeDigest(fs: TxFs, dir: string): string {
 
 /**
  * The digest treeDigest would compute for a directory holding exactly `files` (directories implied by their paths,
- * all with `dirMode`), so the journal can record a tree's state before it is staged.
+ * all with `dirMode`), so the journal can record a tree's state before it is staged. `modes: false` where the
+ * platform has none (win32): every entry's mode is null, as treeDigest reads it there.
  */
-export function treeDigestOfFiles(files: readonly TreeFile[], dirMode: number): string {
+export function treeDigestOfFiles(files: readonly TreeFile[], dirMode: number, options: { readonly modes?: boolean } = {}): string {
+  const withModes = options.modes !== false
   type Dir = Map<string, Dir | { readonly sha256: string; readonly mode: number }>
   const root: Dir = new Map()
   for (const f of files) {
@@ -71,9 +76,9 @@ export function treeDigestOfFiles(files: readonly TreeFile[], dirMode: number):
       const child = dir.get(name)!
       const childRel = rel ? `${rel}/${name}` : name
       if (child instanceof Map) {
-        entries.push({ rel: childRel, kind: "directory", mode: dirMode })
+        entries.push({ rel: childRel, kind: "directory", mode: withModes ? dirMode : null })
         walk(child, childRel)
-      } else entries.push({ rel: childRel, kind: "file", mode: child.mode, sha256: child.sha256 })
+      } else entries.push({ rel: childRel, kind: "file", mode: withModes ? child.mode : null, sha256: child.sha256 })
     }
   }
   walk(root, "")

package/packages/cli/src/credentials.ts

@@ -5,6 +5,7 @@ import { randomBytes } from "node:crypto"
 import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
 import path from "node:path"
 import type { Fetch } from "../../sdk/src/index.ts"
+import { defaultWinAcl, isWin32, writeOwnerOnlyFile, type SecretFileOptions } from "../../../src/win-acl.ts"
 
 export type Env = Record<string, string | undefined>
 
@@ -42,9 +43,11 @@ export function readLogin(file: string): Login | undefined {
 
 /**
  * Writes the login file, owner-only (0600; its directory 0700 when created), atomically: a private temporary file
- * next to it is renamed over it, so a reader never sees half a file and a failed write leaves the old one.
+ * next to it is renamed over it, so a reader never sees half a file and a failed write leaves the old one. On
+ * Windows the temporary file is restricted to the current user (an ACL) before the token is written (win-acl.ts).
  */
-export function writeLogin(file: string, login: Login): void {
+export function writeLogin(file: string, login: Login, options?: SecretFileOptions): void {
+  if (isWin32(options)) return writeOwnerOnlyFile(file, `${JSON.stringify({ url: login.url, token: login.token }, null, 2)}\n`, options?.acl ?? defaultWinAcl())
   mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 })
   const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`
   try {

package/packages/cli/src/main.ts

@@ -38,9 +38,10 @@ const presetRun = argv[0] === "preset" && argv[1] === "run"
 // `hubctl machine enroll` and `hub login` (device code) poll until the code is approved: Ctrl-C cancels them (exit 4,
 // nothing stored). `hubctl setup apply` / `recover` pass the signal to their probes and the verification launch, so
 // Ctrl-C fails the running step and the transaction rolls back, instead of the process dying between a write and its
-// journal entry.
+// journal entry. `setup verify` passes it to its probes too: they lead their own process group (process-tree.ts), so
+// the terminal's Ctrl-C reaches them only through this signal, which ends each probe's whole tree.
 const enroll = (argv[0] === "machine" && argv[1] === "enroll") || argv[0] === "login"
-const applying = argv[0] === "setup" && (argv[1] === "apply" || argv[1] === "recover")
+const applying = argv[0] === "setup" && (argv[1] === "apply" || argv[1] === "recover" || argv[1] === "verify")
 const controller = new AbortController()
 if (argv[0] === "watch" || argv[0] === "mcp" || nodeRun || claudeDaemon || claudeMcp || codexServe || presetRun || enroll || applying)
   for (const signal of ["SIGINT", "SIGTERM"] as const) process.once(signal, () => controller.abort())