@huynle/hub 0.7.1 → 0.7.2

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

@@ -0,0 +1,204 @@
+# OpenCode harness adapter (HBS-06)
+
+The OpenCode `HarnessAdapter` for the bootstrap (contracts §3.10, §3.6.1, §3.12.1 and §5 in
+`docs/bootstrap-contracts.md`). It only imports the frozen contracts and the transaction, discovery and preview
+modules. Every capability is injected.
+
+| File | Role |
+|---|---|
+| `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. |
+| `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. |
+
+## Behaviour
+
+- **Install.** OpenCode is installed only from the pin in hub's verified manifest for the host's exact target, into
+  `data:hub/harnesses/opencode/<version>`. That version is then made `current`.
+  - An OpenCode the user installed (native, brew or npm) is kept by default (`install: "if-missing"`).
+  - A hub-managed OpenCode at an older version gets the pinned version installed next to it. A newer one is never
+    downgraded by planning.
+  - Without a pin, a missing OpenCode is `unpinned_artifact`.
+  - A pin below 2.0.0 is refused, because the Hub plugin needs OpenCode 2.
+- **Config.** OpenCode 2 uses `plugins: (string | {package, options?})[]` and `mcp.servers.<name>` (from
+  `@opencode/schema` 2.0.26, `config/plugin.js` and `mcp.js`). hubctl edits `config:opencode/opencode.jsonc` if it
+  exists, otherwise `opencode.json`. When neither exists, it creates `opencode.json`. The config is read only if
+  the snapshot lists it, and must still have the snapshot's digest, otherwise `preview_stale`.
+  - **Plugin.** If the Hub plugin is absent, it is appended to `/plugins`.
+    - These count as registered: an exact npm entry, an unpinned npm entry, or a custom source (a `github:huynle/hub`
+      spec or a checkout named `hub`).
+    - These are drift, fixed by one set on that entry (or on its `package` field only): an older pin, or the legacy
+      `@huynle/opencode-voice`.
+    - These are refused as `conflict`: a duplicate (including across `plugins` and the OpenCode 1 key `plugin`, or
+      across both files), or a pin newer than this hubctl.
+  - **MCP.** `mcp.servers.hub = {type: "local", command: [<authority>, "mcp"]}`.
+    - A `hub`/`hubctl mcp` server at another path (the plugin's launcher in the state dir, or a plugin cache) is
+      stale. Only its `command` is replaced; `environment`, `disabled` and other fields stay.
+    - These are refused: a foreign server named `hub`, or hub's MCP server under another name.
+  - **Authority.** The authority is `user-bin:hubctl` by default, or `user-bin:hub` (the same command surface). Any
+    other root or name (`state:hub/bin/…`, `data:…/node_modules/…`) is refused when the adapter is built.
+  - **Unparseable files.** Unparseable JSONC, or JSONC with duplicate keys, is `manual_edit_required`.
+- **Symlinked configs.** The adapter plans normally. `planSetup` replaces both config actions with `symlinked-config`
+  manual edits that name the dotfiles file. Nothing is written through the link.
+- **Readiness.** A planned or applied install is never readiness. The three required probes are:
+  - `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.
+  - `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
+  to activate its plugins, and the CLI fails with HTTP 503 "Location plugins did not finish activating". The
+  `--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).
+
+  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.
+
+  Contract v1.2 classifies them: `version-exec` is an integrity probe (its failure rolls the apply back);
+  `provider-auth` and `spoke-connected` wait on the user (`opencode auth login`, starting OpenCode), so by default
+  the `verify-harness` step commits OpenCode as installed, not ready (`requireReady: false`, set by `hubctl setup
+  apply` unless `--require-ready`). The executor's own default stays strict.
+- **Rollback.** All rollback goes through the engine. The new version directory is removed, `current` is restored
+  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`).
+
+## Upstream source of OpenCode 2.x (researched 2026-10-28)
+
+| Channel | Finding | Source |
+|---|---|---|
+| GitHub releases | `sst/opencode` redirects to **`anomalyco/opencode`** (HTTP 301). The 2.x CLI is published there as tag **`v2.2.0`** (2026-10-27, by github-actions[bot], from `dev`). The same repository still ships a **1.x line** (`v1.19.5`, 2026-10-28). Because 1.19.5 is newer, GitHub's "latest release" is the 1.x line: never use `latest`, pin the exact tag. | https://github.com/anomalyco/opencode/releases/tag/v2.2.0, https://api.github.com/repos/anomalyco/opencode/releases |
+| Release assets (v2.2.0) | CLI archives: `opencode-darwin-arm64.zip`, `opencode-darwin-x64.zip` (and `-baseline`), `opencode-linux-x64.tar.gz` (and `-baseline`, `-musl`, `-baseline-musl`), `opencode-linux-arm64.tar.gz` (and `-musl`), plus Windows zips, `opencode-desktop-*` apps and a `SHA256SUMS` file. | release page above |
+| Archive layout | Checked with HTTP range reads, without downloading the archives. The zip has one entry, `opencode` (deflate, unix mode 0100755, 220 826 080 bytes uncompressed). The tar.gz has one ustar (GNU) entry, `opencode`, mode 0755. The uncompressed darwin-arm64 size equals the size of the locally installed `~/.opencode/bin/opencode`, which reports `opencode v2.2.0`. | range requests on the asset URLs |
+| Authenticity | No signatures: no `.sig`, `.asc`, `.sigstore` or attestation assets. `SHA256SUMS` is unsigned. GitHub's API reports a per-asset `digest`. Both only help to cross-check the pinned digest (contract §5: OpenCode is vouched for only by hub's pin). | release API `assets[].digest`, `SHA256SUMS` |
+| npm `opencode-ai` | dist-tag `latest` = **1.19.5**. No 2.x versions are published: this is the 1.x line. | https://registry.npmjs.org/opencode-ai |
+| npm `@opencode/cli` | dist-tag `latest` = **2.2.0**, repository `anomalyco/opencode`. This is the 2.x CLI on npm under its new name. The SDK this repo uses (`@opencode/client`, `@opencode/plugin` ^2.0.26) comes from the same repository. | https://registry.npmjs.org/@opencode%2fcli |
+
+**Recommendation.** Pin the **GitHub release archives of `anomalyco/opencode`, exact tag `v2.x.y`**, not npm:
+
+- An npm install runs a package manager, with lifecycle scripts and platform-specific optional dependencies. That
+  is an installer, which `install-harness` must never carry (T21).
+- The release archive is a single file, which hubctl checks against the pin and unpacks itself.
+
+| Target | Asset | Format |
+|---|---|---|
+| `darwin-arm64` | `opencode-darwin-arm64.zip` | zip (deflate) |
+| `darwin-x64` | `opencode-darwin-x64-baseline.zip` | zip (deflate) |
+| `linux-x64` (glibc) | `opencode-linux-x64-baseline.tar.gz` | tar.gz |
+| `linux-arm64` (glibc) | `opencode-linux-arm64.tar.gz` | tar.gz |
+
+**Use the `-baseline` assets on x64.** The non-baseline x64 builds require AVX2 and die with `SIGILL` (exit 132)
+on CPUs without it: older Intel/AMD hosts and QEMU guests with the default `kvm64` CPU model. hubctl itself is built
+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
+`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)
+
+```json
+{
+  "pin": {
+    "harness": "opencode",
+    "version": "2.2.0",
+    "target": "darwin-arm64",
+    "url": "https://github.com/anomalyco/opencode/releases/download/v2.2.0/opencode-darwin-arm64.zip",
+    "file": "opencode-darwin-arm64.zip",
+    "size": "<bytes you measured>",
+    "sha256": "sha256:<hex you computed>",
+    "evidence": [],
+    "minimumVersion": "2.0.0"
+  },
+  "review": { "by": "<your GitHub handle>", "on": "<YYYY-MM-DD>", "checked": ["upstream-release", "digest-redownloaded", "evidence-listed"] }
+}
+```
+
+Repeat the entry for `darwin-x64` (`opencode-darwin-x64-baseline.zip`), `linux-x64`
+(`opencode-linux-x64-baseline.tar.gz`) and
+`linux-arm64` (`opencode-linux-arm64.tar.gz`). `size` must be an integer. The placeholders above are deliberately
+invalid, so an unfilled template fails `bootstrap-release-pins.test.ts`.
+
+### Reviewer instructions
+
+1. Open the release page for the tag. Confirm it is the 2.x line, published by the upstream workflow, and that the
+   asset name is exactly the target's asset in the table above.
+2. Download the asset yourself, then measure and hash it:
+   `curl -fsSLo f "$URL" && wc -c < f && shasum -a 256 f`.
+3. Cross-check against both upstream values: the asset's line in the release's `SHA256SUMS`, and `assets[].digest`
+   from `https://api.github.com/repos/anomalyco/opencode/releases/tags/v<version>`. If any value differs, stop.
+4. List the archive and confirm it holds exactly one regular file, `opencode`: `unzip -Z1 f` or `tar -tzvf f`. The
+   adapter refuses anything else.
+5. Keep `evidence: []`, because OpenCode publishes no signatures. Set `minimumVersion` to `2.0.0`, or higher to
+   raise the floor after a security release.
+6. Fill in `review` and open the PR. Someone other than the author reviews it (`release/README.md`).
+
+## Integration requirements (HBS-13)
+
+HBS-13 made these edits (`packages/cli/src/setup/`, docs/bootstrap-contracts.md §7): A1 at the composition layer
+(refusals become envelope errors), A2 (`setup/dispatch.ts`), the spoke probe (`GET /spoke/presence`), the launchers
+(they prefer `~/.local/bin/hubctl`) and A4 (the shared fixtures use `plugins`). A3, A5 and A6 stay open (§7.6).
+The original list:
+
+- **Construction.** `packages/cli/src/cli.ts` (setup preview, apply and recover):
+  - Build `createOpencodeHarness({ probe: createNodeProbe(), manifest: <verified manifest>, pluginVersion?: <hubctl
+    version>, spoke: <SpokeProbe>, installed, floor, allowDowngrade })`.
+  - Register `.adapter` in the `AdapterRegistry` passed to **both** `previewSetup` and `revalidateApply`, with
+    identical options, so the plan digests match.
+- **Refusals.** `planSetup` calls `adapter.plan()`, which **throws `OpencodePlanError`** (`code`: `conflict`,
+  `manual_edit_required`, `unpinned_artifact`, `preview_stale` or `invalid`). Catch it around
+  `previewSetup`/`revalidateApply` and print it as the envelope error with `exitFor(code)`. Amendment A1 would make
+  this unnecessary.
+- **Executors.** The `ExecutorMap` holds one executor per kind. `register-mcp-server` and `verify-harness` must
+  dispatch on `action.harness` to each adapter's executor: `harness.executors(() => adapterContext)` for OpenCode.
+  `builtinExecutors({ harness })` takes one `HarnessSource`, so the integrator needs a source that dispatches on
+  `action.harness` (OpenCode: `harness.source`). See A2.
+- **Adapter context.** `AdapterContext.env` must be the user's real `process.env`: the provider probe needs the user's
+  own provider configuration. `now: Date.now`.
+- **Spoke probe.** The hub needs a machine-credential query that answers "is an OpenCode spoke of this machine
+  connected?". Today `GET /api/machines` (user auth) lists `processes` per machine. Without a `SpokeProbe`, OpenCode
+  is never ready, which is correct; since contract v1.2 it only blocks a strict (`--require-ready`) apply.
+- **Authority.** The MCP server runs `user-bin:hubctl`, which this plan's `install-artifact` installs.
+  `src/spoke/launchers.ts` writes `hub`/`hubctl` launchers into the hub state dir that run the CLI bundle from the
+  plugin's install (cache) directory. They must not become what services or MCP clients depend on. Suggested
+  change: when a standalone `user-bin:hubctl` exists, the launchers exec it instead of the bundle.
+- **No dependencies.** No new dependency and no `package.json` change. zlib, `child_process` and fetch come from the
+  runtime.
+
+## Amendment requests (contracts are not modified here)
+
+- **A1.** `HarnessAdapter.plan` returns only `Action[]`, so it cannot report a refusal or findings (drift, unpinned
+  plugin, stale MCP authority).
+  - Proposal: `plan` may return `{ actions, findings?, refusal?: {code, message} }`, or `planSetup` catches a
+    contract-defined `PlanRefusal` and returns it as a failed `Result`. Findings would appear in the `SetupPreview`
+    (a new optional `findings[]`).
+- **A2.** `ExecutorMap` and `BuiltinDeps.harness` allow one executor and one source per kind, but three adapters
+  each supply `register-mcp-server`, `verify-harness` and a `HarnessSource`.
+  - Proposal: a `harnessDispatch` helper in `transaction/`, or `ExecutorMap` entries keyed `kind` →
+    `Record<HarnessID, ActionExecutor>` for harness-scoped kinds.
+- **A3.** An unparseable JSONC config is only a bare `manual_edit_required` at plan time. The planner turns TOML,
+  not broken JSONC, into an `unmergeable-format` manual edit.
+  - Proposal: let an adapter mark a config action unmergeable, so the user gets the structured edit.
+- **A4.** The shared fixtures use OpenCode 1 keys: `ACTIONS["merge-config"]` sets `/plugin/-`, and the discovery
+  fixture's `OPENCODE_CONFIG` has `plugin: []`. OpenCode 2 uses `plugins`.
+- **A5.** `install-harness.previous` and `select-harness-version.previous` need a `sha256` of the previous version,
+  which discovery does not record, so the adapter omits `previous`.
+  - Proposal: discovery records the tree digest of a hub-managed version directory, or the history supplies it.
+- **A6.** Nothing puts a hub-installed OpenCode on PATH, because `link-executable` is reserved for the hub ↔ hubctl
+  alias.
+  - Proposal: allow `link-executable` from `user-bin:opencode` to `harnessCurrentRef("opencode")/bin/opencode`, or
+    decide that services and launches always use the absolute path.
+
+## Open questions
+
+- Should the plugin default to being pinned to hubctl's own version? Today it is unpinned unless `pluginVersion` is
+  passed, and an existing unpinned entry is kept as the user's choice.
+- `OPENCODE_CONFIG` / `OPENCODE_CONFIG_DIR` and project-level configs are not considered: discovery reports only
+  `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

@@ -0,0 +1,205 @@
+// What the OpenCode adapter gives the transactional applier (transaction/executor.ts): the HarnessSource for its
+// pinned downloads and the executors for the two action kinds the built-ins leave to adapters.
+//
+//   HarnessSource        fetch: exactly the URL hub's verified manifest pins (checkHarnessPin), bounded by the
+//                        pinned size, over https only, streamed into the step's staging area (never held whole);
+//                        OpenCode publishes no upstream evidence, so only the pinned digest vouches for the bytes
+//                        (installHarnessExecutor checks the staging area's digest before unpack is called).
+//                        unpack: archive.ts (streams the binary into the staging area).
+//   register-mcp-server  hubctl's `mcp` at the stable authority under mcp.servers.hub, decided from the file as it is
+//                        at apply (config.ts) and spliced in by the lossless JSONC merge; only while the file is as
+//                        previewed (precondition); a foreign "hub" server is a conflict. Journal class config: backed up,
+//                        so a rollback restores it unless the user changed it since.
+//   verify-harness       runs the adapter's real probes and classifies them (contract v1.2, harnessReadiness): an
+//                        integrity failure (the binary is missing, does not run, is not the pinned version) fails
+//                        the apply (harness_not_ready), which rolls the transaction back; with requireReady (the
+//                        default) so does anything short of isHarnessReady; without it, a harness that only waits on
+//                        the user (provider login, spoke) passes as "installed, not ready" (onReadiness).
+import {
+  checkHarnessPin,
+  harnessReadiness,
+  isHarnessReady,
+  PROBE_MAX_AGE_MS,
+  type AdapterContext,
+  type HarnessAdapter,
+  type HarnessID,
+  type HarnessVerification,
+  type InstallHarness,
+  type PathRef,
+  type VerifiedManifest,
+} from "../../contracts/index.ts"
+import type { HarnessSource } from "../../transaction/builtin.ts"
+import type { ActionExecutor, ExecutorMap, StepContext } from "../../transaction/executor.ts"
+import { mergeConfigText } from "../../transaction/json-merge.ts"
+import { txFail, txOk } from "../../transaction/result.ts"
+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"
+
+// ---------- downloads ----------
+
+export interface DownloadLimits {
+  /** The pinned size: a longer body is refused while it streams. */
+  readonly maxBytes: number
+  readonly signal?: AbortSignal
+}
+
+/**
+ * Fetches a body (no verification: the executor checks it against the pin): bytes, or chunks as they arrive (the
+ * source streams them into the staging area).
+ */
+export type Download = (url: string, limits: DownloadLimits) => Promise<ByteSource>
+
+/**
+ * A Download over fetch: https only (every hop: the final URL too), refused once it exceeds the limit. The status
+ * and declared length are checked before it resolves; the body then streams, chunk by chunk, and fails as soon as
+ * it runs past the limit.
+ */
+export function httpsDownload(fetchImpl: (url: string, init?: RequestInit) => Promise<Response> = fetch): Download {
+  return async (url, limits) => {
+    if (!url.startsWith("https://")) throw new Error(`refusing to download ${url}: https only`)
+    const response = await fetchImpl(url, { redirect: "follow", ...(limits.signal ? { signal: limits.signal } : {}) })
+    if (response.url && !response.url.startsWith("https://")) throw new Error(`refusing ${url}: it redirected to a non-https location`)
+    if (!response.ok) throw new Error(`download of ${url} failed: HTTP ${response.status}`)
+    const declared = Number(response.headers.get("content-length") ?? "")
+    if (Number.isFinite(declared) && declared > limits.maxBytes) throw new Error(`${url} is larger than the pinned ${limits.maxBytes} bytes`)
+    return responseChunks(response, limits.maxBytes, () => new Error(`${url} is larger than the pinned ${limits.maxBytes} bytes`))
+  }
+}
+
+// ---------- the harness source ----------
+
+export interface OpencodeSourceOptions {
+  readonly manifest: VerifiedManifest
+  readonly download: Download
+  /** The OpenCode hub has installed and made current (downgrade policy), from the integrator's install history. */
+  readonly installed?: () => { readonly version: string; readonly sha256: string } | undefined
+  /** The highest OpenCode floor this machine has seen. */
+  readonly floor?: () => string | undefined
+  /** Explicit --allow-downgrade. */
+  readonly allowDowngrade?: boolean
+}
+
+const onlyOpencode = (harness: HarnessID) => {
+  if (harness !== "opencode") throw new Error(`the OpenCode harness source cannot install ${harness}`)
+}
+
+/** The HarnessSource for OpenCode artifacts (installHarnessExecutor verifies every byte against the pin). */
+export function createOpencodeHarnessSource(options: OpencodeSourceOptions): HarnessSource {
+  return {
+    manifest: options.manifest,
+    async fetch(action: InstallHarness, staging) {
+      onlyOpencode(action.harness)
+      const pin = checkHarnessPin(options.manifest, action)
+      if (!pin.ok) throw new Error(`refusing to download ${action.source.url}: it is not the artifact hub ${options.manifest.release} pins (${pin.issues[0]!.message})`)
+      const body = await options.download(pin.value.url, { maxBytes: pin.value.size })
+      const file = await staging.write(action.source.file, body, { maxBytes: pin.value.size })
+      // OpenCode publishes no signatures (contract §5): there is no upstream evidence to attempt.
+      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}`),
+    installed: (harness) => (harness === "opencode" ? options.installed?.() : undefined),
+    floor: (harness) => (harness === "opencode" ? options.floor?.() : undefined),
+    ...(options.allowDowngrade ? { allowDowngrade: true } : {}),
+  }
+}
+
+// ---------- executors ----------
+
+function preconditionHolds(ctx: StepContext, precondition: { readonly exists: boolean; readonly sha256?: string }): boolean {
+  const o = ctx.original
+  if (o.symlink) return false
+  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). */
+export function opencodeMcpExecutor(options: { readonly authority?: PathRef } = {}): ActionExecutor<"register-mcp-server"> {
+  const authorityRef = options.authority ?? DEFAULT_AUTHORITY
+  checkAuthority(authorityRef)
+  return {
+    kind: "register-mcp-server",
+    plan: (action) => ({ class: "config", path: action.path }),
+    check: async (action, ctx) => {
+      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 })
+      return authority.ok ? txOk(undefined) : authority
+    },
+    change: async (_action, ctx) => {
+      const authority = ctx.resolve(authorityRef, { finalMayBeSymlink: true })
+      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)
+      if (!sets.ok) return sets
+      if (sets.value.length === 0) return txOk({ type: "none", reason: "hubctl's MCP server is already registered" })
+      const merged = mergeConfigText(text, ctx.target!.endsWith(".jsonc") ? "jsonc" : "json", sets.value)
+      if (!merged.ok) return merged
+      return txOk({ type: "file", bytes: new TextEncoder().encode(merged.value), mode: ctx.current.mode ?? 0o600, replace: "backup" })
+    },
+  }
+}
+
+
+/** verify-harness for OpenCode: ready (isHarnessReady), or only waiting on the user without requireReady; else it fails. */
+export function opencodeVerifyExecutor(
+  options: {
+    readonly adapter: HarnessAdapter
+    readonly context: () => AdapterContext
+    /** Sees every verification (for the apply report); cannot change it. */
+    readonly onVerification?: (verification: HarnessVerification) => void
+  } & ReadinessGate,
+): ActionExecutor<"verify-harness"> {
+  return {
+    kind: "verify-harness",
+    plan: () => ({ class: "external" }),
+    check: async (action) => (action.harness === options.adapter.id ? txOk(undefined) : txFail("invalid", `this executor verifies ${options.adapter.id}, not ${action.harness}`)),
+    change: async (action) =>
+      txOk({
+        type: "effect",
+        perform: async () => {
+          const context = options.context()
+          const verification = await options.adapter.verify(context)
+          options.onVerification?.(structuredClone(verification))
+          const now = context.now()
+          const readiness = harnessReadiness(verification, now, action.probes)
+          options.onReadiness?.(structuredClone(readiness))
+          // Every required probe (isHarnessReady) and every probe the action asks for: present, passing, fresh.
+          const missing = action.probes.filter((kind) => !passing(verification, kind, now))
+          if (verification.harness === "opencode" && isHarnessReady(verification, now) && missing.length === 0) return txOk(undefined)
+          if (verification.harness === "opencode" && passesAsPending(readiness, options)) return txOk(undefined)
+          const failed = verification.probes.filter((p) => !p.ok)
+          const why = [
+            ...failed.map((p) => `${p.kind}${p.detail ? ` (${p.detail})` : ""}`),
+            ...missing.filter((kind) => !failed.some((p) => p.kind === kind)).map((kind) => `${kind} (not run, or stale)`),
+          ]
+          return txFail("harness_not_ready", `OpenCode is installed but not ready: ${why.join("; ") || "required probes missing"}`)
+        },
+      }),
+  }
+}
+
+/** The clock skew isHarnessReady tolerates (contracts/harness.ts). */
+const CLOCK_SKEW_MS = 60_000
+
+/** One probe kind present, passing and fresh (the same rule as isHarnessReady, for one kind). */
+const passing = (v: HarnessVerification, kind: string, now: number) => {
+  const probes = v.probes.filter((p) => p.kind === kind)
+  return probes.length > 0 && probes.every((p) => p.ok && p.observedAt <= now + CLOCK_SKEW_MS && now - p.observedAt <= PROBE_MAX_AGE_MS)
+}
+
+/** The OpenCode executors to merge over builtinExecutors (see the integration notes in README.md). */
+export function opencodeExecutors(options: {
+  readonly adapter: HarnessAdapter
+  readonly context: () => AdapterContext
+  readonly authority?: PathRef
+  readonly onVerification?: (verification: HarnessVerification) => void
+} & ReadinessGate): Pick<ExecutorMap, "register-mcp-server" | "verify-harness"> {
+  return {
+    "register-mcp-server": opencodeMcpExecutor(options.authority ? { authority: options.authority } : {}),
+    "verify-harness": opencodeVerifyExecutor(options),
+  }
+}

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

@@ -0,0 +1,91 @@
+// 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
+// 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.
+//
+// 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
+// read, and the binary is streamed straight into a staging file, hashed as it is written. Nothing is held whole.
+import { ArchiveError, readTarGz, zipMemberData, zipMembers } from "../archive-stream.ts"
+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. */
+export const OPENCODE_BINARY_REL = "bin/opencode"
+const BINARY_NAME = "opencode"
+/** 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
+
+const invalid = (file: string, why: string) => txFail("invalid", `${file}: ${why}; refusing to install it`)
+
+/** An archive member name, normalized: "./x" and "x/" are fine; empty, absolute, "..", backslashes and NUL are not. */
+function memberName(raw: string): string | undefined {
+  if (raw.startsWith("/") || raw.includes("\\") || raw.includes("\u0000")) return undefined
+  const parts = raw.split("/").filter((p) => p !== "" && p !== ".")
+  if (parts.some((p) => p === "..")) return undefined
+  return parts.join("/")
+}
+
+/** 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 {
+  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`)
+  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> {
+  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 })
+  })
+  return binary
+}
+
+async function fromZip(reader: ByteReader, staging: StagingArea, maxBytes: number): 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
+  if (!chosen) return undefined
+  return staging.write(BINARY_NAME, 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.
+ */
+export async function unpackOpencodeFile(file: string, reader: ByteReader, staging: StagingArea, options: { readonly maxBytes?: number } = {}): Promise<TxResult<TreeFile[]>> {
+  const maxBytes = options.maxBytes ?? MAX_UNPACKED_BYTES
+  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)")
+  let binary: StagedFile | undefined
+  try {
+    binary = zip ? await fromZip(reader, staging, maxBytes) : await fromTarGz(reader, staging, maxBytes)
+  } 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 }])
+}
+
+/** 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[]>> {
+  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
+}