@huynle/hub 0.8.3 → 0.8.5

package/packages/cli/package.json

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

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

@@ -0,0 +1,87 @@
+# Phase 2: hubctl on Windows (session-only), shared contract
+
+Design: `docs/plans/2026-11-05-machine-setup-installer-design.md` §3 (Phase 2). Decision: Brain `1bwf3cqx`. Four
+workstreams build against this file in parallel; change it only through the integrator. The foundation below is
+already on `feat/ms2` (commit after `bbb8d43a`).
+
+## Foundation (done; do not change without the integrator)
+
+- **Canonical paths** (`contracts/validate.ts` `isAbsolutePath`): POSIX `/a/b` or Windows `C:/a/b` (upper-case drive,
+  `/` separators, roots `/` and `C:/`). UNC (`\\server`, `//server`) and device paths (`\\?\`, `\\.\`) are never
+  canonical. Contracts, plans, journals and snapshots hold canonical paths only.
+- **Edges**: `discovery/util.ts` `normalizeAbs` turns a host's native path into a canonical one (backslashes → `/`,
+  drive upper-cased); `contracts/validate.ts` `toNativePath(p, process.platform)` turns it back for external programs
+  (icacls, error messages). Node's `fs` accepts canonical `C:/…` paths directly on Windows, so fs calls need no
+  conversion. `isWindowsPath(p)` tells them apart. `join` and `resolvePathRef` handle the `C:/` root.
+- **Target**: `windows-x64` is in `SUPPORTED_TARGETS` with `platform: "windows"`, `libc: "none"`,
+  `serviceManager: "none"` (type `TargetServiceManager`), `bunTarget: "bun-windows-x64-baseline"`. `windows-arm64`
+  stays unsupported. `targetOf("win32", "x64", "none")` is `windows-x64`.
+
+## Windows host layout (all workstreams)
+
+Same XDG-style layout under the user's profile as on macOS/Linux (it is what OpenCode itself uses on Windows):
+
+| Root | Windows path |
+|---|---|
+| `home` | `%USERPROFILE%` (canonical, e.g. `C:/Users/dacra`); `HOME` wins when set and absolute |
+| `config` | `$XDG_CONFIG_HOME` or `home/.config` |
+| `state` | as today (`resolveHubStateDir`), else `home/.local/state` |
+| `data` | `$XDG_DATA_HOME` or `home/.local/share` |
+| `user-bin` | `home/.local/bin` (install.ps1 adds it to the user PATH) |
+| `system-bin`, `launch-agents`, `systemd-user` | not mapped on Windows |
+
+Executables on `windows-x64` carry `.exe` in their PathRefs (`user-bin:hubctl.exe`, harness `…/bin/opencode.exe`).
+
+## Install primitives on win32 (transaction workstream implements; adapters/planner rely on them)
+
+- **`link-executable`** (the `hub` alias, `opencode` on PATH): on win32 the planner names the link
+  `user-bin:<name>.cmd` and the applier writes a **cmd shim** instead of a symlink: exactly
+  `@"<native target>" %*\r\n` (ASCII). Journaled as a file it owns; rollback removes/restores it. No symlinks for
+  executables on Windows (they need Developer Mode or admin).
+- **Directory "current" links** (`select-harness` and friends): an NTFS **junction** (`fs.symlinkSync(target, path,
+  "junction")`), no admin needed. `lstat` reports junctions as symbolic links, so `checkNoSymlinkEscape` still refuses
+  to write *through* one.
+- **Replacing a file that may be running** (`hubctl.exe` while OpenCode runs `hubctl mcp`): rename-aside: move the old
+  file to `<name>.old-<txid>` in the same directory, move the staged file in, delete the aside file when possible
+  (else leave it; a later apply or `setup recover` cleans `*.old-*`). Rollback renames back. Names are
+  `<name>.old-<txID>-<seq>` (`-undo` during a rollback). When the aside is the running hubctl.exe itself (a rollback
+  that removes hubctl), `setup rollback`/`recover` start a hidden `cmd.exe` with a fixed command line that deletes it
+  once it is no longer running (`setup/self-aside.ts`).
+- **`O_NOFOLLOW`** is undefined on Windows: replace it with an explicit `lstat` reparse-point check right before the
+  open, and refuse links.
+- **File modes**: Windows has no POSIX modes. Journals record `mode: null` ("not applicable") for win32 entries;
+  comparisons skip it. The machine credential and other secret files get an owner-only ACL instead (next section).
+
+## Secrets on win32 (transaction workstream)
+
+Files that are 0600 on POSIX (`config.json` with the machine token, `cli.json`, preview files with tokens) are, on
+win32, created empty, restricted with `icacls <native> /inheritance:r /grant:r *<current user SID>:(F)` **before** the
+secret is written, then moved into place (the ACL travels with the move). Checks that today refuse `mode & 0o077`
+(e.g. `packages/node/src/opencode-warm.ts:323`) instead verify on win32 that the ACL has no allow entry for anyone but
+the current user, SYSTEM and Administrators. Keep a small helper (`win-acl.ts`) both sides import; tests inject the
+`icacls` runner.
+
+## Profiles on a target without services
+
+`session-only` works on `windows-x64`. `launch-node` and `full-harness` are refused at preview with
+`unsupported_platform` and the message "needs user services, which hubctl does not install on Windows yet". The
+server (`/install.ps1`) and the console already allow only `session-only` on Windows.
+
+## install.ps1 (scripts workstream)
+
+Switches from the plugin path to hubctl, mirroring install.sh: download `hubctl-windows-x64.exe`,
+`HUBCTL_SHA256SUMS`, `hubctl-manifest.json` from `{{RELEASE_BASE}}` (env `HUB_INSTALL_RELEASE_BASE` overrides, as in
+install.sh), check the sha256 with `Get-FileHash`, then `machine status --json` / `machine enroll --server …
+[--allow-insecure-http]` / `setup preview --profile session-only --enrollment separate --manifest … --out …` /
+`setup apply` / `setup verify` with install.sh's exit-code handling (15 → done with next steps; 10 → manual edits),
+and finally add `%USERPROFILE%\.local\bin` to the user PATH (`[Environment]::SetEnvironmentVariable('Path', …,
+'User')`, only when missing) and say to open a new terminal. Never `exit`; ASCII only; PowerShell 5.1 and 7.
+
+## Release (release workstream)
+
+`hubctl-windows-x64.exe` is built (`--target bun-windows-x64-baseline`, `.exe` outfile), listed in the manifest and
+`HUBCTL_SHA256SUMS`, and smoke-tested on `windows-latest` in `release.yml`. The OpenCode harness pin for
+`windows-x64` follows the reviewed-pin process (`release/README.md`): the agent may prepare the entry with a
+re-downloaded digest, but the `review` block must be filled in by the owner (flag it, never self-review).
+A local **dev release** script builds hubctl for chosen targets with a throwaway trust root and signs a manifest with
+a throwaway key, so the integrator can test on real machines through `HUB_RELEASE_BASE` without the release key.

package/packages/cli/src/bootstrap/adapters/claude/node.ts

@@ -1,60 +1,28 @@
 // Default Node implementations of the Claude Code adapter's ports (ports.ts). The integrator (HBS-13) passes them;
 // tests inject fakes.
 //
-//   nodeRunner       spawn(file, args) with shell: false, exactly the given environment, stdin closed, stderr
-//                    dropped, stdout capped, and a hard timeout (SIGKILL). The only process starter here.
+//   nodeRunner       the bounded runner (../process-tree.ts): shell: false, exactly the given environment, stdin
+//                    closed, stderr dropped, stdout capped, and a hard timeout that ends the whole process tree;
+//                    whatever the probe left running when it exited is ended too. The only process starter here.
 //   httpsDownloader  https only (also after redirects), non-2xx refused, the body streamed and capped
 //                    (DownloadTooLarge, as soon as it runs past the limit).
 //   tempScratch      a 0700 directory under the system temp dir with one 0600 file (written as its content
 //                    streams), removed afterwards.
-import { spawn } from "node:child_process"
 import { closeSync, mkdtempSync, openSync, rmSync, writeSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { chunksOf, responseChunks } from "../../transaction/stream.ts"
+import { runBounded, type BoundedOptions } from "../process-tree.ts"
 import { DownloadTooLarge, type Downloader, type ProbeRunner, type RunResult, type Scratch } from "./ports.ts"
 
-export function nodeRunner(): ProbeRunner {
+export function nodeRunner(options: BoundedOptions = {}): ProbeRunner {
   return {
-    run: (file, args, options) =>
-      new Promise<RunResult>((resolve) => {
-        let settled = false
-        const done = (r: RunResult) => {
-          if (settled) return
-          settled = true
-          clearTimeout(timer)
-          resolve(r)
-        }
-        let child: ReturnType<typeof spawn>
-        try {
-          child = spawn(file, [...args], { shell: false, env: { ...options.env }, stdio: ["ignore", "pipe", "ignore"], windowsHide: true })
-        } catch (error) {
-          return resolve({ kind: "error", message: error instanceof Error ? error.message : String(error) })
-        }
-        const timer = setTimeout(() => {
-          child.kill("SIGKILL")
-          done({ kind: "timeout" })
-        }, options.timeoutMs)
-        const chunks: Buffer[] = []
-        let size = 0
-        child.stdout?.on("data", (chunk: Buffer) => {
-          if (size >= options.maxOutputBytes) return
-          const part = chunk.subarray(0, options.maxOutputBytes - size)
-          chunks.push(part)
-          size += part.length
-        })
-        child.on("error", (error: NodeJS.ErrnoException) => done(error.code === "ENOENT" ? { kind: "not-found" } : { kind: "error", message: error.code ?? "spawn failed" }))
-        // Settle once the process exited and its stdout ended (whichever comes last), or on "close".
-        let exitCode: number | undefined
-        let ended = !child.stdout
-        const finish = () => {
-          if (exitCode !== undefined && ended) done({ kind: "exited", code: exitCode, stdout: Buffer.concat(chunks).toString("utf8") })
-        }
-        child.stdout?.on("end", () => ((ended = true), finish()))
-        child.stdout?.on("close", () => ((ended = true), finish()))
-        child.on("exit", (code, signal) => ((exitCode = code ?? (signal ? -1 : 0)), finish()))
-        child.on("close", (code) => ((exitCode ??= code ?? -1), (ended = true), finish()))
-      }),
+    run: async (file, args, run) => {
+      const r = await runBounded({ file, args, env: run.env, timeoutMs: run.timeoutMs, maxOutputBytes: run.maxOutputBytes, overflow: "truncate" }, options)
+      if (r.spawnError) return r.spawnError.code === "ENOENT" ? { kind: "not-found" } : { kind: "error", message: r.spawnError.code ?? "spawn failed" }
+      if (r.timedOut) return { kind: "timeout" }
+      return { kind: "exited", code: r.exitCode ?? -1, stdout: r.stdout }
+    },
   }
 }
 

package/packages/cli/src/bootstrap/adapters/codex/verify.ts

@@ -16,7 +16,6 @@
 // Probes run with a minimal environment (PATH, HOME, CODEX_HOME, locale): never the hub token or a provider key. A
 // probe's detail is one short line with emails and credential-shaped words removed. codexCapabilities advertises
 // Codex as ready only when isHarnessReady holds and its app-server answered, each probe fresh.
-import { execFile } from "node:child_process"
 import { openAppServer } from "../../../../../codex/src/app-server.ts"
 import type { Channel } from "../../../../../codex/src/jsonrpc.ts"
 import { CODEX_APP_SERVER_ARGS } from "../../../../../codex/src/spoke.ts"
@@ -38,6 +37,7 @@ import {
 } from "../../contracts/index.ts"
 import type { ActionExecutor } from "../../transaction/executor.ts"
 import { txFail, txOk } from "../../transaction/result.ts"
+import { runBounded, type BoundedOptions } from "../process-tree.ts"
 import { passesAsPending, type ReadinessGate } from "../readiness.ts"
 
 export interface ProbeResult {
@@ -275,20 +275,27 @@ export function codexVerifyExecutor(
   }
 }
 
-/** A ProbeRunner over execFile: the word list as is (no shell), bounded output and time. */
-export const nodeProbeRunner: ProbeRunner = {
-  run: (argv, options) =>
-    new Promise((resolve) => {
+/**
+ * A ProbeRunner over the bounded runner (process-tree.ts): the word list as is (no shell), bounded output and time,
+ * and nothing the probe starts outlives it (a timeout or an abort ends its tree; what it left running is reaped).
+ */
+export function probeRunner(options: BoundedOptions = {}): ProbeRunner {
+  return {
+    run: async (argv, run) => {
       const [file, ...args] = argv
-      if (!file) return resolve({ exitCode: null, stdout: "", error: "empty argv" })
-      execFile(file, args, { env: options.env, timeout: options.timeoutMs, maxBuffer: 64 * 1024, shell: false, windowsHide: true, ...(options.signal ? { signal: options.signal } : {}) }, (error, stdout) => {
-        if (!error) return resolve({ exitCode: 0, stdout: String(stdout) })
-        const code = (error as NodeJS.ErrnoException & { code?: unknown }).code
-        resolve(typeof code === "number" ? { exitCode: code, stdout: String(stdout ?? "") } : { exitCode: null, stdout: String(stdout ?? ""), error: message(error) })
-      })
-    }),
+      if (!file) return { exitCode: null, stdout: "", error: "empty argv" }
+      const r = await runBounded({ file, args, env: run.env, timeoutMs: run.timeoutMs, maxOutputBytes: 64 * 1024, overflow: "kill", ...(run.signal ? { signal: run.signal } : {}) }, options)
+      if (r.spawnError) return { exitCode: null, stdout: "", error: message(r.spawnError) }
+      if (r.exitCode !== null) return { exitCode: r.exitCode, stdout: r.stdout }
+      const why = r.timedOut ? `timed out after ${run.timeoutMs} ms` : r.aborted ? "cancelled" : r.overflowed ? "printed too much" : "killed by a signal"
+      return { exitCode: null, stdout: r.stdout, error: `${file} ${why}` }
+    },
+  }
 }
 
+/** The CLI's runner: probeRunner with the platform's process tree. */
+export const nodeProbeRunner: ProbeRunner = probeRunner()
+
 /** Starts the app-server with the packages/codex stdio channel (`argsBefore`: tests run a fake server script). */
 export const stdioAppServerLauncher = (options: { readonly argsBefore?: readonly string[] } = {}): AppServerLauncher => ({
   start(binary, env) {

package/packages/cli/src/bootstrap/adapters/opencode/README.md

@@ -9,7 +9,7 @@ modules. Every capability is injected.
 | `config.ts` | Reads an OpenCode 2 config (JSONC) and classifies the Hub plugin entry and the `hub` MCP server: absent, registered, drift, or a refusal. It computes the exact JSON-pointer sets for the lossless merge. |
 | `plan.ts` | `planOpencode` and `createOpencodeAdapter`. The pinned `install-harness` comes first, then `select-harness-version`, `merge-config` (plugin), `register-mcp-server` and `verify-harness`. The planner is pure and deterministic. |
 | `verify.ts` | Real readiness probes through a fixed-argv `ProcessRunner` (no shell). `locateOpencodeBinary` finds the binary that really runs. |
-| `archive.ts` | A streaming unpacker for the upstream zip and tar.gz (`../archive-stream.ts`). It accepts exactly one regular file, `opencode`, streams it into the step's staging area and installs it as `bin/opencode` with mode 0755. `unpackOpencodeArchive` is the in-memory form for small fixtures. |
+| `archive.ts` | A streaming unpacker for the upstream zip and tar.gz (`../archive-stream.ts`). It accepts exactly one regular file, `opencode` (`opencode.exe` in a zip on Windows targets), streams it into the step's staging area and installs it as `bin/opencode` (`bin/opencode.exe`) with mode 0755. `unpackOpencodeArchive` is the in-memory form for small fixtures. |
 | `apply.ts` | The `HarnessSource` (the pinned URL only, https only, bounded by the pinned size, streamed into the staging area), the `register-mcp-server` and `verify-harness` executors, and `httpsDownload` (the body as chunks). |
 | `index.ts` | `createOpencodeHarness`, the single entry point for the integrator. |
 
@@ -46,8 +46,12 @@ modules. Every capability is injected.
   - `version-exec`: `<binary> --version` must report OpenCode ≥ 2.0.0, and exactly the hub `current` version when
     hub manages the binary. The binary is hub's `current` binary, otherwise what PATH resolves to. A container shim
     is refused.
-  - `provider-auth`: `<binary> models` must list at least one `provider/model`. This sends no prompt and costs
-    nothing. A stronger `ProviderProbe` can be injected.
+  - `provider-auth`: `<binary> models --standalone` must list at least one `provider/model`. This sends no prompt
+    and costs nothing. `--standalone` runs a private server inside the probe: it tests exactly the installed binary
+    and starts no background service (`opencode serve --service`). Without it the first probe started that service
+    from the hub-installed version directory, where it kept running after verify; on Windows it kept that directory
+    busy, so `hubctl setup rollback` could not remove it (Phase 2 end-to-end run). A stronger `ProviderProbe` can
+    be injected.
   - `spoke-connected`: an injected `SpokeProbe`. Without one, the probe fails, so OpenCode is never ready by default.
 
   On a cold start (the first use of a directory) OpenCode 2's background service can take longer than the CLI's ~5 s
@@ -55,6 +59,11 @@ modules. Every capability is injected.
   `--version` and `models` probes retry once, after 1 s, on exactly that failure (`ACTIVATION_FAILURE`, read from the
   child's output only to recognise it); any other failure is reported at once (HBS-12).
 
+  Every probe runs through the bounded runner (`../process-tree.ts`): nothing it starts outlives it. A timeout, a
+  cancel or too much output ends its whole process tree, and whatever it left running when it exited is ended too
+  (POSIX: its own process group; Windows: `taskkill /T /F` from System32, and the exited probe's children found by a
+  fixed CIM query).
+
   Details are built by the adapter, never copied from harness output. Anything that looks like a credential is
   withheld. The child process gets the user's own environment, and nothing from it is recorded.
 
@@ -66,6 +75,35 @@ modules. Every capability is injected.
   from its backup, and the config is restored from its backup, except when the user changed it after hub wrote it.
   Then it is kept and reported as a conflict (`bootstrap-adapter-opencode-apply.test.ts`).
 
+## Windows (`windows-x64`, Phase 2: session-only)
+
+See `../../PHASE2-CONTRACT.md` for the shared rules. For this adapter:
+
+- **Archive.** The asset is `opencode-windows-x64-baseline.zip`. Baseline is used for the same reason as on the other
+  x64 targets, and matches hubctl's own `bun-windows-x64-baseline`. Its only member is `opencode.exe`, zipped on a
+  FAT host, so there are no unix modes and the member's kind follows its name. It is installed as
+  `data:hub/harnesses/opencode/<version>/bin/opencode.exe`. The unpacker takes the binary name from the
+  install-harness action's `target`, so a Windows binary is never installed for a POSIX target, or the other way
+  round. A tar.gz is refused for Windows.
+- **Release assets (v2.2.0).** `opencode-windows-x64.zip` (118 610 002 bytes, needs AVX2),
+  `opencode-windows-x64-baseline.zip` (118 610 005 bytes) and `opencode-windows-arm64.zip`. All three are listed in
+  the release's `SHA256SUMS` and in the API's `assets[].digest`.
+- **Pin.** The windows-x64 pin is prepared, not reviewed, in `../../release/harness-pins.pending.json`. Only the dev
+  release includes it (`../../release/README.md`).
+- **MCP authority.** `user-bin:hubctl.exe`, the real executable (`authorityFor`). The `hub` alias is a cmd shim
+  (`user-bin:hub.cmd`) on Windows, and a `.cmd` cannot be the MCP command because OpenCode starts it without a
+  shell. So `authority: user-bin:hub` is refused on Windows. `.exe` names are refused on POSIX targets.
+- **Config path form.** The command is written as the native path (`C:\Users\…\.local\bin\hubctl.exe`, through
+  `toNativePath`):
+  - CreateProcess would accept `C:/…` too.
+  - The native form is what OpenCode's Windows users and docs write, so a user reading the config recognises it.
+  - It survives `cmd.exe`, should anything route the command through a shell (`/` starts a switch there).
+
+  Matching is lenient: an existing entry in either separator form and any letter case counts as registered (NTFS is
+  case-insensitive). A `hub`/`hubctl` program with `.exe` or `.cmd` at another path counts as stale.
+- **Readiness.** The probes run `…/current/bin/opencode.exe`. `nodeProcessRunner` takes a canonical absolute path
+  (POSIX or `C:/…`) and passes the OS its native form.
+
 ## Upstream source of OpenCode 2.x (researched 2026-10-28)
 
 | Channel | Finding | Source |
@@ -95,7 +133,7 @@ on CPUs without it: older Intel/AMD hosts and QEMU guests with the default `kvm6
 for the same baseline (`bun-<os>-x64-baseline`, contracts §3.1), so a host that runs hubctl can run the harness it
 installs. The baseline build runs on AVX2 CPUs too, at a small speed cost.
 
-The musl and Windows assets are out of scope (decision Q7, §3.1). The URL is
+The musl assets are out of scope (decision Q7, §3.1). Windows is Phase 2 (above). The URL is
 `https://github.com/anomalyco/opencode/releases/download/v<version>/<asset>`. `evidence` is always `[]`.
 
 ### Proposed `harness-pins.json` entries (template: fill in only from your own download)
@@ -200,5 +238,3 @@ The original list:
   `config:opencode/opencode.json(c)`.
 - Is `opencode models` strong enough as `provider-auth`, or should HBS-13 inject a one-token completion probe that
   costs money?
-- `opencode models` talks to the background service by default (the 2.x CLI also has `--standalone`). Should the
-  probe pin `--standalone`, so it tests exactly the binary that was installed?

package/packages/cli/src/bootstrap/adapters/opencode/apply.ts

@@ -36,7 +36,7 @@ import { responseChunks, type ByteSource } from "../../transaction/stream.ts"
 import { passesAsPending, type ReadinessGate } from "../readiness.ts"
 import { unpackOpencodeFile } from "./archive.ts"
 import { mcpServerSets } from "./config.ts"
-import { checkAuthority, DEFAULT_AUTHORITY } from "./plan.ts"
+import { authorityFor, checkAuthority, DEFAULT_AUTHORITY, mcpCommandPath } from "./plan.ts"
 
 // ---------- downloads ----------
 
@@ -100,7 +100,9 @@ export function createOpencodeHarnessSource(options: OpencodeSourceOptions): Har
       return { file, evidence: [] }
     },
     unpack: async (action, file, staging) =>
-      action.harness === "opencode" ? unpackOpencodeFile(action.source.file, staging.open(file), staging) : txFail("invalid", `the OpenCode harness source cannot unpack ${action.harness}`),
+      action.harness === "opencode"
+        ? unpackOpencodeFile(action.source.file, staging.open(file), staging, { target: action.target })
+        : txFail("invalid", `the OpenCode harness source cannot unpack ${action.harness}`),
     installed: (harness) => (harness === "opencode" ? options.installed?.() : undefined),
     floor: (harness) => (harness === "opencode" ? options.floor?.() : undefined),
     ...(options.allowDowngrade ? { allowDowngrade: true } : {}),
@@ -115,10 +117,19 @@ function preconditionHolds(ctx: StepContext, precondition: { readonly exists: bo
   return precondition.exists ? o.exists && o.sha256 === precondition.sha256 : !o.exists
 }
 
-/** register-mcp-server for OpenCode: hubctl's mcp at `authority` (default user-bin:hubctl). */
+/**
+ * register-mcp-server for OpenCode: hubctl's mcp at `authority` (default user-bin:hubctl), for the host's target
+ * (authorityFor: user-bin:hubctl.exe on Windows, written as its native path, mcpCommandPath).
+ */
 export function opencodeMcpExecutor(options: { readonly authority?: PathRef } = {}): ActionExecutor<"register-mcp-server"> {
-  const authorityRef = options.authority ?? DEFAULT_AUTHORITY
-  checkAuthority(authorityRef)
+  const given = options.authority ?? DEFAULT_AUTHORITY
+  checkAuthority(given)
+  const authorityOf = (ctx: StepContext) => {
+    const ref = authorityFor(given, ctx.host.target)
+    if (!ref.ok) return ref
+    const resolved = ctx.resolve(ref.value, { finalMayBeSymlink: true })
+    return resolved.ok ? txOk(mcpCommandPath(resolved.value, ctx.host.target)) : resolved
+  }
   return {
     kind: "register-mcp-server",
     plan: (action) => ({ class: "config", path: action.path }),
@@ -126,11 +137,11 @@ export function opencodeMcpExecutor(options: { readonly authority?: PathRef } =
       if (action.harness !== "opencode") return txFail("invalid", `this executor registers MCP servers with OpenCode, not ${action.harness}`)
       if (action.name !== "hub") return txFail("invalid", `hubctl's MCP server is registered as "hub", not ${JSON.stringify(action.name)}`)
       if (!preconditionHolds(ctx, action.precondition)) return txFail("conflict", `${ctx.target} changed since the preview; nothing was overwritten (preview again)`)
-      const authority = ctx.resolve(authorityRef, { finalMayBeSymlink: true })
+      const authority = authorityOf(ctx)
       return authority.ok ? txOk(undefined) : authority
     },
     change: async (_action, ctx) => {
-      const authority = ctx.resolve(authorityRef, { finalMayBeSymlink: true })
+      const authority = authorityOf(ctx)
       if (!authority.ok) return authority
       const text = ctx.current.exists ? new TextDecoder().decode(ctx.fs.readFile(ctx.target!)) : undefined
       const sets = mcpServerSets(text, authority.value)

package/packages/cli/src/bootstrap/adapters/opencode/archive.ts

@@ -1,10 +1,11 @@
 // Unpacking a verified OpenCode release archive into the files of its immutable version directory (contract §3.6.1,
 // data:hub/harnesses/opencode/<version>). Upstream (github.com/anomalyco/opencode releases) ships exactly one file,
 // `opencode`, in a zip for macOS (opencode-darwin-<arch>.zip, deflate) and a gzipped tar for Linux
-// (opencode-linux-<arch>.tar.gz). The executor has already checked the download against hub's pinned digest; this
+// (opencode-linux-<arch>.tar.gz); on Windows exactly one file, `opencode.exe`, in a zip made on a FAT host
+// (opencode-windows-x64-baseline.zip: no unix modes, so the kind follows the name). The executor has already checked the download against hub's pinned digest; this
 // still refuses anything an archive could smuggle in: links, devices, names that climb out or are absolute, extra
 // files (an installer script beside the binary), a duplicate, or no binary at all. The binary always becomes
-// bin/opencode, mode 0755.
+// bin/opencode, mode 0755 (bin/opencode.exe on Windows targets, where modes do not apply and the applier records none).
 //
 // Streaming (HBS-12: a 4 GB host was OOM-killed holding the archive and the ~350 MB binary several times over): the
 // archive is read from the staging area in chunks (archive-stream.ts), every member is judged before its body is
@@ -14,9 +15,17 @@ import type { TreeFile } from "../../transaction/executor.ts"
 import { txFail, txOk, type TxResult } from "../../transaction/result.ts"
 import { bytesReader, memoryStaging, type ByteReader, type StagedFile, type StagingArea } from "../../transaction/stream.ts"
 
-/** Where the binary goes inside the version directory. */
+/** Where the binary goes inside the version directory (POSIX targets; opencodeBinaryRel for any target). */
 export const OPENCODE_BINARY_REL = "bin/opencode"
-const BINARY_NAME = "opencode"
+
+/** Whether `target` is a Windows target (its executables carry .exe, PHASE2-CONTRACT.md). */
+export const isWindowsTarget = (target: string | undefined): boolean => target !== undefined && target.startsWith("windows-")
+
+/** The binary's name inside the upstream archive (and inside bin/) for `target`: opencode, or opencode.exe on Windows. */
+export const opencodeBinaryName = (target?: string): string => (isWindowsTarget(target) ? "opencode.exe" : "opencode")
+
+/** Where the binary goes inside the version directory for `target`. */
+export const opencodeBinaryRel = (target?: string): string => `bin/${opencodeBinaryName(target)}`
 /** A generous bound on what one release may unpack to (the 2.2.0 binary is about 350 MB). */
 export const MAX_UNPACKED_BYTES = 1024 * 1024 * 1024
 
@@ -31,60 +40,68 @@ function memberName(raw: string): string | undefined {
 }
 
 /** Judges one member: undefined to skip it (the archive's own root directory), "binary" to unpack it. */
-function judge(raw: string, kind: "file" | "directory" | "other", hasBinary: boolean): "binary" | undefined {
+function judge(raw: string, kind: "file" | "directory" | "other", hasBinary: boolean, binaryName: string): "binary" | undefined {
   const name = memberName(raw)
   if (name === undefined) throw new ArchiveError(`the member ${JSON.stringify(raw)} has an unsafe name`)
   if (kind === "directory" && name === "") return undefined
   if (kind !== "file") throw new ArchiveError(`${JSON.stringify(raw)} is not a regular file (links and devices are never installed)`)
-  if (name !== BINARY_NAME) throw new ArchiveError(`unexpected member ${JSON.stringify(raw)} (an OpenCode release holds only the ${BINARY_NAME} binary)`)
-  if (hasBinary) throw new ArchiveError(`${BINARY_NAME} appears twice`)
+  if (name !== binaryName) throw new ArchiveError(`unexpected member ${JSON.stringify(raw)} (an OpenCode release for this target holds only the ${binaryName} binary)`)
+  if (hasBinary) throw new ArchiveError(`${binaryName} appears twice`)
   return "binary"
 }
 
 const tarKind = (type: string) => (type === "0" || type === "7" ? "file" : type === "5" ? "directory" : "other")
 
-async function fromTarGz(reader: ByteReader, staging: StagingArea, maxBytes: number): Promise<StagedFile | undefined> {
+async function fromTarGz(reader: ByteReader, staging: StagingArea, maxBytes: number, binaryName: string): Promise<StagedFile | undefined> {
   let binary: StagedFile | undefined
   // Symlinks (2), hard links (1), devices (3, 4), FIFOs (6), and pax/GNU headers that could rename a member (x, g,
   // L, K) are all "other": refused.
   await readTarGz(reader, { maxBytes }, async (member) => {
-    if (judge(member.header.name, tarKind(member.header.type), binary !== undefined) !== "binary") return
-    binary = await staging.write(BINARY_NAME, member.body(), { maxBytes: member.header.size })
+    if (judge(member.header.name, tarKind(member.header.type), binary !== undefined, binaryName) !== "binary") return
+    binary = await staging.write(binaryName, member.body(), { maxBytes: member.header.size })
   })
   return binary
 }
 
-async function fromZip(reader: ByteReader, staging: StagingArea, maxBytes: number): Promise<StagedFile | undefined> {
+async function fromZip(reader: ByteReader, staging: StagingArea, maxBytes: number, binaryName: string): Promise<StagedFile | undefined> {
   // The whole directory is judged before any member is inflated.
   const members = zipMembers(reader, { maxBytes })
   let chosen: (typeof members)[number] | undefined
-  for (const m of members) if (judge(m.name, m.kind, chosen !== undefined) === "binary") chosen = m
+  for (const m of members) if (judge(m.name, m.kind, chosen !== undefined, binaryName) === "binary") chosen = m
   if (!chosen) return undefined
-  return staging.write(BINARY_NAME, zipMemberData(reader, chosen), { maxBytes: chosen.size })
+  return staging.write(binaryName, zipMemberData(reader, chosen), { maxBytes: chosen.size })
 }
 
 /**
  * The install tree of a verified OpenCode archive named `file` (its format follows the upstream asset name), read
  * from `reader`; the binary is streamed into `staging`. `maxBytes` (default MAX_UNPACKED_BYTES) bounds what it
- * inflates to.
+ * inflates to. `target` (the install-harness action's target) picks the binary: `opencode.exe` → bin/opencode.exe
+ * on Windows (a zip only), `opencode` → bin/opencode elsewhere (the default).
  */
-export async function unpackOpencodeFile(file: string, reader: ByteReader, staging: StagingArea, options: { readonly maxBytes?: number } = {}): Promise<TxResult<TreeFile[]>> {
+export interface UnpackOptions {
+  readonly maxBytes?: number
+  readonly target?: string
+}
+
+export async function unpackOpencodeFile(file: string, reader: ByteReader, staging: StagingArea, options: UnpackOptions = {}): Promise<TxResult<TreeFile[]>> {
   const maxBytes = options.maxBytes ?? MAX_UNPACKED_BYTES
+  const binaryName = opencodeBinaryName(options.target)
   const zip = file.endsWith(".zip")
   if (!zip && !file.endsWith(".tar.gz") && !file.endsWith(".tgz")) return invalid(file, "not an OpenCode CLI archive (expected .zip or .tar.gz)")
+  if (!zip && isWindowsTarget(options.target)) return invalid(file, "OpenCode for Windows ships as a .zip")
   let binary: StagedFile | undefined
   try {
-    binary = zip ? await fromZip(reader, staging, maxBytes) : await fromTarGz(reader, staging, maxBytes)
+    binary = zip ? await fromZip(reader, staging, maxBytes, binaryName) : await fromTarGz(reader, staging, maxBytes, binaryName)
   } catch (error) {
     if (error instanceof ArchiveError) return invalid(file, error.message)
     throw error
   }
-  if (!binary) return invalid(file, `no ${BINARY_NAME} binary inside`)
-  return txOk([{ rel: OPENCODE_BINARY_REL, staged: binary, mode: 0o755 }])
+  if (!binary) return invalid(file, `no ${binaryName} binary inside`)
+  return txOk([{ rel: opencodeBinaryRel(options.target), staged: binary, mode: 0o755 }])
 }
 
 /** unpackOpencodeFile over bytes in memory, the tree as bytes (small archives: tests, fixtures). */
-export async function unpackOpencodeArchive(file: string, bytes: Uint8Array, options: { readonly maxBytes?: number } = {}): Promise<TxResult<TreeFile[]>> {
+export async function unpackOpencodeArchive(file: string, bytes: Uint8Array, options: UnpackOptions = {}): Promise<TxResult<TreeFile[]>> {
   const staging = memoryStaging()
   const r = await unpackOpencodeFile(file, bytesReader(bytes), staging, options)
   return r.ok ? txOk(r.value.map((f) => ("staged" in f ? { rel: f.rel, mode: f.mode, bytes: staging.bytes(f.staged) } : f))) : r

package/packages/cli/src/bootstrap/adapters/opencode/config.ts

@@ -28,7 +28,7 @@ export const MCP_SUBCOMMAND = "mcp"
 const HUB_PROGRAMS = new Set(["hub", "hubctl"])
 
 export interface DesiredRegistration {
-  /** The absolute path of the stable hubctl authority the MCP server runs. */
+  /** The absolute path of the stable hubctl authority the MCP server runs (native on Windows: plan.ts mcpCommandPath). */
   readonly authority: string
   /** Pin the plugin to this exact version (this hubctl's own); unpinned when absent. */
   readonly pluginVersion?: string
@@ -67,6 +67,22 @@ export interface ConfigInspection {
 type Value = null | boolean | number | string | Value[] | { [key: string]: Value }
 const isObject = (v: unknown): v is { [key: string]: Value } => typeof v === "object" && v !== null && !Array.isArray(v)
 const basename = (p: string) => p.slice(p.lastIndexOf("/") + 1)
+/** A Windows path in either form: C:/… (canonical) or C:\… (native, as OpenCode's config on Windows holds it). */
+const WINDOWS_PATH = /^[A-Za-z]:[\\/]/
+/** The program a command path names: its last segment; on Windows without .exe/.cmd and case-folded. */
+const programName = (p: string): string => {
+  if (!WINDOWS_PATH.test(p)) return basename(p)
+  return p
+    .slice(Math.max(p.lastIndexOf("/"), p.lastIndexOf("\\")) + 1)
+    .replace(/\.(exe|cmd)$/i, "")
+    .toLowerCase()
+}
+/** Whether two command paths are the same file: exact on POSIX; on Windows either separator and any case (NTFS). */
+export const samePath = (a: string, b: string): boolean => {
+  if (!WINDOWS_PATH.test(a) || !WINDOWS_PATH.test(b)) return a === b
+  const fold = (p: string) => p.replace(/\\/g, "/").toLowerCase()
+  return fold(a) === fold(b)
+}
 
 /** The desired plugin spec: `@huynle/hub`, or `@huynle/hub@<version>` when pinned. */
 export const pluginSpec = (desired: { readonly pluginVersion?: string }): string => (desired.pluginVersion ? `${HUB_PLUGIN_PACKAGE}@${desired.pluginVersion}` : HUB_PLUGIN_PACKAGE)
@@ -144,7 +160,7 @@ const isHubMcp = (server: Value): server is { [key: string]: Value } & { command
   Array.isArray(server.command) &&
   server.command.length === 2 &&
   server.command.every((w) => typeof w === "string") &&
-  HUB_PROGRAMS.has(basename(server.command[0] as string)) &&
+  HUB_PROGRAMS.has(programName(server.command[0] as string)) &&
   server.command[1] === MCP_SUBCOMMAND
 
 function inspectMcp(config: { [key: string]: Value }, desired: DesiredRegistration, findings: Finding[]): TxResult<McpState> {
@@ -159,7 +175,7 @@ function inspectMcp(config: { [key: string]: Value }, desired: DesiredRegistrati
   const server = servers[HUB_MCP_NAME]
   if (server === undefined) return txOk({ state: "absent" })
   if (!isHubMcp(server)) return txFail("conflict", `another MCP server is already named "${HUB_MCP_NAME}" in the OpenCode config; hubctl will not replace it`)
-  if (server.command[0] === desired.authority) return txOk({ state: "registered" })
+  if (samePath(server.command[0]!, desired.authority)) return txOk({ state: "registered" })
   findings.push({ code: "mcp-stale-authority", message: `the hub MCP server runs ${server.command[0]}; it becomes ${desired.authority}` })
   return txOk({ state: "stale", found: server.command[0]! })
 }

package/packages/cli/src/bootstrap/adapters/opencode/index.ts

@@ -11,7 +11,7 @@ import type { ExecutorMap } from "../../transaction/executor.ts"
 import type { ReadinessGate } from "../readiness.ts"
 import { createOpencodeHarnessSource, httpsDownload, opencodeExecutors, type Download } from "./apply.ts"
 import { createOpencodeAdapter, type OpencodePlanOptions } from "./plan.ts"
-import { locateOpencodeBinary, nodeProcessRunner, verifyOpencode, type ProcessRunner, type ProviderProbe, type SpokeProbe } from "./verify.ts"
+import { hubManagedVersion, locateOpencodeBinary, nodeProcessRunner, verifyOpencode, type ProcessRunner, type ProviderProbe, type SpokeProbe } from "./verify.ts"
 
 export * from "./archive.ts"
 export * from "./config.ts"
@@ -44,9 +44,6 @@ export interface OpencodeHarness {
   executors(context: () => AdapterContext, gate?: ReadinessGate): Pick<ExecutorMap, "register-mcp-server" | "verify-harness">
 }
 
-/** The version directory a hub-managed binary lives in (data:hub/harnesses/opencode/<version>/bin/opencode). */
-const HUB_VERSION = /\/hub\/harnesses\/opencode\/([^/]+)\/bin\/opencode$/
-
 export function createOpencodeHarness(options: OpencodeHarnessOptions): OpencodeHarness {
   const { probe } = options
   const runner = options.runner ?? nodeProcessRunner
@@ -59,7 +56,7 @@ export function createOpencodeHarness(options: OpencodeHarnessOptions): Opencode
     // Located fresh at every verification: after an install, `current` points at the new version.
     const located = locateOpencodeBinary(probe)
     const binary = located.ok ? located.value : undefined
-    const expectVersion = binary ? HUB_VERSION.exec(binary)?.[1] : undefined
+    const expectVersion = binary ? hubManagedVersion(binary) : undefined
     return verifyOpencode(context, { runner, binary, ...(options.spoke ? { spoke: options.spoke } : {}), ...(options.provider ? { provider: options.provider } : {}), ...(expectVersion ? { expectVersion } : {}) })
   }
   const adapter = createOpencodeAdapter({ ...options, readConfig: (path) => probe.readFile(path), discover: presence, verify })