@huynle/hub 0.6.1 → 0.7.2

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

@@ -0,0 +1,160 @@
+// The Claude Code HarnessSource (transaction/builtin.ts installHarnessExecutor): where the pinned binary comes from,
+// which upstream evidence is attempted for it, and how it becomes the install tree. The executor checks the pin and
+// the downloaded bytes' sha256 itself (mandatory, contracts §3.6.1); this source only adds the optional evidence:
+//
+//   gpg-manifest        upstream's per-release manifest.json and its detached signature, checked in-house
+//                       (openpgp.ts) against the pinned release-signing key; the signed manifest must list exactly
+//                       these bytes for this platform and version. No gpg binary is needed.
+//   macos-notarization  on macOS, /usr/bin/codesign (fixed argv, through the injected runner) on a private scratch
+//                       copy of the downloaded bytes: signed by Anthropic PBC's Developer ID, then notarized.
+//
+// The binary streams into the step's staging area (never held whole: HBS-12); the signed manifest is compared with
+// the digest the staging area recorded, and codesign gets a scratch copy written in chunks.
+//
+// Each is recorded as verified, unavailable (could not be checked here: no codesign, offline, unsigned release,
+// unknown key) or failed (checked and wrong); a failure rejects the artifact (checkHarnessEvidence). Nothing here
+// runs a shell, reads a credential or touches ~/.claude.
+import type { EvidenceResult, HarnessID, InstallHarness, VerifiedManifest } from "../../contracts/index.ts"
+import type { HarnessSource } from "../../transaction/builtin.ts"
+import type { TreeFile } from "../../transaction/executor.ts"
+import { TxError, txFail, txOk, type TxResult } from "../../transaction/result.ts"
+import { collect, TooLarge, type ByteReader, type StagedFile } from "../../transaction/stream.ts"
+import { CLAUDE_SIGNING_FINGERPRINT, verifyDetachedSignature } from "./openpgp.ts"
+import { DownloadTooLarge, type Downloader, type ProbeRunner, type Scratch } from "./ports.ts"
+
+export const UPSTREAM_RELEASES = "https://downloads.claude.ai/claude-code-releases"
+export const UPSTREAM_KEY_URL = "https://downloads.claude.ai/keys/claude-code.asc"
+/** Anthropic PBC's Apple Developer ID team (codesign -dv: "Developer ID Application: Anthropic PBC (Q6L2SF6YDW)"). */
+export const ANTHROPIC_TEAM_ID = "Q6L2SF6YDW"
+const IDENTITY = `anchor apple generic and certificate leaf[subject.OU] = "${ANTHROPIC_TEAM_ID}"`
+
+/** The fixed codesign invocations; the scratch file's path is the last argument. */
+export const CODESIGN = Object.freeze({
+  program: "/usr/bin/codesign",
+  identity: Object.freeze(["--verify", "--strict", `-R=${IDENTITY}`]),
+  notarized: Object.freeze(["--verify", "--strict", `-R=notarized and ${IDENTITY}`]),
+})
+
+const MANIFEST_MAX = 1 << 20
+const SIGNATURE_MAX = 64 << 10
+const KEY_MAX = 64 << 10
+const CODESIGN_TIMEOUT_MS = 60_000
+const UPSTREAM_BINARY = /^https:\/\/downloads\.claude\.ai\/claude-code-releases\/([0-9A-Za-z.+-]+)\/([a-z0-9-]+)\/claude$/
+
+/** Upstream's platform name for a hub target (the same names; upstream's musl builds are not hub targets). */
+export function upstreamPlatform(target: string): string | undefined {
+  return ["darwin-arm64", "darwin-x64", "linux-x64", "linux-arm64"].includes(target) ? target : undefined
+}
+
+export interface ClaudeSourceOptions {
+  readonly manifest: VerifiedManifest
+  readonly download: Downloader
+  /** codesign for macos-notarization; without it (or the scratch) notarization is unavailable. */
+  readonly runner?: ProbeRunner
+  readonly scratch?: Scratch
+  /** process.platform of this host. */
+  readonly platform: string
+  /** The release-signing key's pinned fingerprint (default CLAUDE_SIGNING_FINGERPRINT). */
+  readonly signingKey?: { readonly fingerprint: string }
+  /** What hub installed before (the history), for the downgrade policy. */
+  readonly installed?: { readonly version: string; readonly sha256: string }
+  readonly floor?: string
+  readonly allowDowngrade?: boolean
+}
+
+const result = (kind: EvidenceResult["kind"], status: EvidenceResult["status"], detail: string): EvidenceResult => ({ kind, status, detail: detail.replace(/\s+/g, " ").slice(0, 200) })
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+async function gpgManifest(options: ClaudeSourceOptions, action: InstallHarness, file: StagedFile): Promise<EvidenceResult> {
+  const kind = "gpg-manifest"
+  const m = UPSTREAM_BINARY.exec(action.source.url)
+  const platform = upstreamPlatform(action.target)
+  if (!m || m[1] !== action.version || !platform || m[2] !== platform) return result(kind, "unavailable", "the pinned URL is not upstream's release bucket for this version and platform")
+  const base = `${UPSTREAM_RELEASES}/${action.version}`
+  let manifest: Uint8Array
+  let signature: Uint8Array
+  let key: Uint8Array
+  try {
+    const small = async (url: string, max: number) => collect(await options.download.get(url, max), max)
+    ;[manifest, signature, key] = await Promise.all([small(`${base}/manifest.json`, MANIFEST_MAX), small(`${base}/manifest.json.sig`, SIGNATURE_MAX), small(UPSTREAM_KEY_URL, KEY_MAX)])
+  } catch {
+    return result(kind, "unavailable", `the signed manifest of ${action.version} could not be downloaded (upstream signs releases from 2.1.89 on)`)
+  }
+  const fingerprint = options.signingKey?.fingerprint ?? CLAUDE_SIGNING_FINGERPRINT
+  const signed = verifyDetachedSignature({ data: manifest, signature, publicKey: key, fingerprint })
+  if (signed.status !== "verified") return result(kind, signed.status, `manifest.json: ${signed.detail}`)
+  let doc: unknown
+  try {
+    doc = JSON.parse(new TextDecoder().decode(manifest))
+  } catch {
+    return result(kind, "failed", "the signed manifest.json is not JSON")
+  }
+  const entry = isRecord(doc) && isRecord(doc.platforms) ? doc.platforms[platform] : undefined
+  if (!isRecord(doc) || doc.version !== action.version) return result(kind, "failed", `the signed manifest is not for ${action.version}`)
+  const expected = action.sha256.replace(/^sha256:/, "")
+  if (!isRecord(entry) || entry.checksum !== expected || entry.size !== action.size || file.sha256 !== `sha256:${entry.checksum}`)
+    return result(kind, "failed", `the signed manifest lists other bytes for ${platform} than hub's pin`)
+  return result(kind, "verified", `upstream manifest.json signed by ${fingerprint} lists this binary`)
+}
+
+async function notarization(options: ClaudeSourceOptions, action: InstallHarness, binary: ByteReader): Promise<EvidenceResult> {
+  const kind = "macos-notarization"
+  if (options.platform !== "darwin" || !action.target.startsWith("darwin-")) return result(kind, "unavailable", "notarization is checked on macOS only")
+  const { runner, scratch } = options
+  if (!runner || !scratch) return result(kind, "unavailable", "no codesign runner in this hubctl")
+  const run = (args: readonly string[], file: string) => runner.run(CODESIGN.program, [...args, file], { env: { PATH: "/usr/bin:/bin" }, timeoutMs: CODESIGN_TIMEOUT_MS, maxOutputBytes: 64 << 10 })
+  try {
+    return await scratch.withFile(binary.stream(), async (file) => {
+      const identity = await run(CODESIGN.identity, file)
+      if (identity.kind !== "exited") return result(kind, "unavailable", `codesign could not run (${identity.kind})`)
+      if (identity.code !== 0) return result(kind, "failed", `the binary is not validly signed by Anthropic PBC (${ANTHROPIC_TEAM_ID}); codesign exit ${identity.code}`)
+      const notarized = await run(CODESIGN.notarized, file)
+      if (notarized.kind === "exited" && notarized.code === 0) return result(kind, "verified", `signed by Anthropic PBC (${ANTHROPIC_TEAM_ID}) and notarized by Apple`)
+      return result(kind, "unavailable", `signed by Anthropic PBC (${ANTHROPIC_TEAM_ID}), but the notarization could not be confirmed (offline?)`)
+    })
+  } catch {
+    return result(kind, "unavailable", "no scratch copy for codesign")
+  }
+}
+
+/** Mach-O (64-bit, either byte order, or universal) for macOS; ELF for Linux. */
+function nativeFor(target: string, bytes: Uint8Array): boolean {
+  const head = [...bytes.subarray(0, 4)]
+  const is = (magic: readonly number[]) => magic.every((b, i) => head[i] === b)
+  if (target.startsWith("darwin-")) return [[0xcf, 0xfa, 0xed, 0xfe], [0xfe, 0xed, 0xfa, 0xcf], [0xca, 0xfe, 0xba, 0xbe]].some(is)
+  if (target.startsWith("linux-")) return is([0x7f, 0x45, 0x4c, 0x46])
+  return false
+}
+
+export function createClaudeHarnessSource(options: ClaudeSourceOptions): HarnessSource {
+  return {
+    manifest: options.manifest,
+    async fetch(action, staging) {
+      if (action.harness !== "claude-code") throw new Error(`the Claude Code source cannot install ${action.harness}`)
+      // One byte more than pinned is still fetched, so a longer file is an integrity mismatch, not a download error.
+      // The body streams into the staging area; a longer one fails as soon as it runs past the limit.
+      let file: StagedFile
+      try {
+        file = await staging.write("claude", await options.download.get(action.source.url, action.size + 1), { maxBytes: action.size + 1 })
+      } catch (error) {
+        if (error instanceof DownloadTooLarge || error instanceof TooLarge) throw new TxError("integrity_mismatch", `${action.source.url} is larger than the pinned ${action.size} bytes`)
+        throw new TxError("offline", `${action.source.url} could not be downloaded`)
+      }
+      const evidence: EvidenceResult[] = []
+      for (const kind of action.evidence) {
+        if (kind === "gpg-manifest") evidence.push(await gpgManifest(options, action, file))
+        else if (kind === "macos-notarization") evidence.push(await notarization(options, action, staging.open(file)))
+      }
+      return { file, evidence }
+    },
+    async unpack(action, file, staging): Promise<TxResult<readonly TreeFile[]>> {
+      if (action.source.file !== "claude") return txFail("invalid", `the Claude Code pin must be upstream's raw binary "claude", not ${JSON.stringify(action.source.file)}`)
+      if (!nativeFor(action.target, staging.open(file).read(0, 4))) return txFail("invalid", `the downloaded file is not a native ${action.target} executable`)
+      // The tree is the staged download itself: the engine moves it into place (no copy).
+      return txOk([{ rel: "claude", staged: file, mode: 0o755 }])
+    },
+    installed: (harness: HarnessID) => (harness === "claude-code" ? options.installed : undefined),
+    floor: (harness: HarnessID) => (harness === "claude-code" ? options.floor : undefined),
+    allowDowngrade: options.allowDowngrade,
+  }
+}

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

@@ -0,0 +1,165 @@
+// Claude Code readiness (contracts §3.10): REQUIRED_PROBES["claude-code"], each real, passing and fresh.
+//
+//   version-exec     the binary hub resolved (hub's current version, or the program a wrapper or link resolves to;
+//                    never just the shim on PATH) runs `claude --version` (fixed argv, minimal environment, updates
+//                    switched off) and prints the expected version.
+//   provider-auth    `claude auth status` (fixed argv) exits 0 with a login method: the user's own login, made by
+//                    the user on this machine (`claude auth login`). hubctl never reads, copies or keeps a Claude
+//                    credential: the probe's output is parsed for the login method only and then dropped, and the
+//                    child gets the user's environment minus hub's own variables.
+//   spoke-connected  the injected spoke probe sees the claude-code hooks spoke connected, and the injected
+//                    conformance probe passes. Both are required: without either, the harness is not ready.
+//
+// Not ready means no capability: claudeReadiness offers "claude-code" only when every probe passes. The
+// verify-harness step classifies the probes (contract v1.2): an integrity failure (the binary) fails it with
+// harness_not_ready (so the transaction rolls back); a login or spoke that waits on the user fails it only with
+// requireReady (the default), and otherwise passes as "installed, not ready".
+import { harnessReadiness, isHarnessReady, type AdapterContext, type HarnessVerification, type Probe } from "../../contracts/index.ts"
+import type { ActionExecutor } from "../../transaction/executor.ts"
+import { txFail, txOk } from "../../transaction/result.ts"
+import { passesAsPending, type ReadinessGate } from "../readiness.ts"
+import type { ProbeRunner, RunResult } from "./ports.ts"
+
+export const VERSION_ARGV: readonly string[] = Object.freeze(["--version"])
+export const AUTH_STATUS_ARGV: readonly string[] = Object.freeze(["auth", "status"])
+/** Upstream's documented login methods (`claude auth status` JSON `authMethod`), "none" excluded. */
+export const AUTH_METHODS: readonly string[] = ["claude.ai", "oauth_token", "api_key", "api_key_helper", "third_party"]
+/** What the spoke must be (packages/claude-code daemon: harness claude-code, evidence hooks). */
+export const CLAUDE_SPOKE = { harness: "claude-code", evidence: "hooks" } as const
+
+const VERSION_TIMEOUT_MS = 15_000
+const AUTH_TIMEOUT_MS = 30_000
+const OUTPUT_MAX = 64 << 10
+const NO_UPDATES = { DISABLE_AUTOUPDATER: "1", DISABLE_UPDATES: "1" } as const
+
+/** The binary to verify, or why there is none. */
+export type ClaudeBinary = { readonly path: string; readonly version?: string } | { readonly problem: string }
+
+export interface SpokeHello {
+  readonly connected: boolean
+  readonly harness?: string
+  readonly evidence?: string
+  readonly features?: readonly string[]
+}
+
+export interface ClaudeProbes {
+  readonly runner: ProbeRunner
+  readonly binary: () => ClaudeBinary
+  /** Is the claude-code spoke connected to the hub (HBS-13: the daemon socket or the hub's machine view)? */
+  readonly spoke?: () => Promise<SpokeHello>
+  /** Does the connected spoke pass conformance? */
+  readonly conformance?: () => Promise<{ readonly ok: boolean; readonly detail?: string }>
+}
+
+const line = (s: string) => s.replace(/\s+/g, " ").trim().slice(0, 200)
+const why = (r: RunResult) => (r.kind === "exited" ? `exit ${r.code}` : r.kind === "error" ? "could not start" : r.kind)
+
+/** The user's environment for a probe, minus hub's own variables, with updates switched off. */
+function userEnv(env: AdapterContext["env"]): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const [k, v] of Object.entries(env)) if (v !== undefined && !k.startsWith("HUB_") && k !== "BUN_BE_BUN") out[k] = v
+  return { ...out, ...NO_UPDATES }
+}
+
+async function versionProbe(probes: ClaudeProbes, ctx: AdapterContext, bin: { path: string; version?: string }): Promise<Omit<Probe, "observedAt">> {
+  const env = { PATH: ctx.env.PATH ?? "/usr/bin:/bin", HOME: ctx.home, ...NO_UPDATES }
+  const r = await probes.runner.run(bin.path, VERSION_ARGV, { env, timeoutMs: VERSION_TIMEOUT_MS, maxOutputBytes: OUTPUT_MAX })
+  if (r.kind !== "exited" || r.code !== 0) return { kind: "version-exec", ok: false, detail: `${bin.path} --version did not run (${why(r)})` }
+  const version = /^\s*v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\b/.exec(r.stdout)?.[1]
+  if (!version) return { kind: "version-exec", ok: false, detail: `${bin.path} --version printed no version` }
+  if (bin.version && version !== bin.version) return { kind: "version-exec", ok: false, detail: `${bin.path} is ${version}, not the expected ${bin.version}` }
+  return { kind: "version-exec", ok: true, detail: `${version} at ${bin.path}` }
+}
+
+async function authProbe(probes: ClaudeProbes, ctx: AdapterContext, bin: { path: string }): Promise<Omit<Probe, "observedAt">> {
+  const login = "not logged in: log in on this machine yourself (`claude auth login`, or run `claude`)"
+  const r = await probes.runner.run(bin.path, AUTH_STATUS_ARGV, { env: userEnv(ctx.env), timeoutMs: AUTH_TIMEOUT_MS, maxOutputBytes: OUTPUT_MAX })
+  if (r.kind !== "exited") return { kind: "provider-auth", ok: false, detail: `claude auth status did not run (${why(r)})` }
+  if (r.code !== 0) return { kind: "provider-auth", ok: false, detail: login }
+  // Only the login method is read; everything else the command printed is dropped here.
+  let method: unknown
+  try {
+    method = (JSON.parse(r.stdout) as { authMethod?: unknown }).authMethod
+  } catch {}
+  if (method === "none") return { kind: "provider-auth", ok: false, detail: login }
+  return { kind: "provider-auth", ok: true, detail: typeof method === "string" && AUTH_METHODS.includes(method) ? `logged in (${method})` : "logged in" }
+}
+
+async function spokeProbe(probes: ClaudeProbes): Promise<Omit<Probe, "observedAt">> {
+  const fail = (detail: string) => ({ kind: "spoke-connected" as const, ok: false, detail })
+  if (!probes.spoke) return fail("no spoke probe in this hubctl")
+  if (!probes.conformance) return fail("no conformance probe in this hubctl")
+  let hello: SpokeHello
+  try {
+    hello = await probes.spoke()
+  } catch {
+    return fail("the claude-code spoke could not be reached")
+  }
+  if (!hello.connected) return fail("the claude-code spoke is not connected to the hub (is the daemon running and the machine enrolled?)")
+  if (hello.harness !== CLAUDE_SPOKE.harness || hello.evidence !== CLAUDE_SPOKE.evidence) return fail(`the connected spoke is ${hello.harness ?? "?"}/${hello.evidence ?? "?"}, not ${CLAUDE_SPOKE.harness}/${CLAUDE_SPOKE.evidence}`)
+  try {
+    const c = await probes.conformance()
+    if (!c.ok) return fail(`spoke conformance failed${c.detail ? `: ${c.detail}` : ""}`)
+  } catch {
+    return fail("spoke conformance could not run")
+  }
+  return { kind: "spoke-connected", ok: true, detail: "claude-code hooks spoke connected and conformant" }
+}
+
+/** Runs every required probe (passing or not) and reports each. */
+export async function verifyClaude(probes: ClaudeProbes, ctx: AdapterContext): Promise<HarnessVerification> {
+  const bin = probes.binary()
+  const found: Omit<Probe, "observedAt">[] = []
+  if ("problem" in bin) {
+    found.push({ kind: "version-exec", ok: false, detail: bin.problem }, { kind: "provider-auth", ok: false, detail: `not checked: ${bin.problem}` })
+  } else {
+    found.push(await versionProbe(probes, ctx, bin), await authProbe(probes, ctx, bin))
+  }
+  found.push(await spokeProbe(probes))
+  const observedAt = ctx.now()
+  return { harness: "claude-code", probes: found.map((p) => ({ ...p, detail: line(p.detail ?? ""), observedAt })) }
+}
+
+export interface ClaudeReadiness {
+  readonly ready: boolean
+  /** Offered only when ready. */
+  readonly capability?: "claude-code"
+  readonly problems: readonly string[]
+}
+
+export function claudeReadiness(verification: HarnessVerification, now: number): ClaudeReadiness {
+  const ready = verification.harness === "claude-code" && isHarnessReady(verification, now)
+  const problems = verification.probes.filter((p) => !p.ok).map((p) => `${p.kind}: ${p.detail ?? "failed"}`)
+  if (ready) return { ready, capability: "claude-code", problems: [] }
+  return { ready, problems: problems.length > 0 ? problems : ["the probes are missing or stale"] }
+}
+
+export interface ClaudeVerifyOptions extends ReadinessGate {
+  readonly verify: () => Promise<HarnessVerification>
+  readonly now: () => number
+  /** Sees every verification (ready or not), e.g. to record it or offer the capability. */
+  readonly onVerified?: (verification: HarnessVerification) => void
+}
+
+/** The verify-harness step for claude-code: an external effect that fails unless ready (or, v1.2, only pending). */
+export function claudeVerifyExecutor(options: ClaudeVerifyOptions): ActionExecutor<"verify-harness"> {
+  return {
+    kind: "verify-harness",
+    plan: () => ({ class: "external" }),
+    check: async (action) => (action.harness === "claude-code" ? txOk(undefined) : txFail("internal", `the Claude Code verifier cannot verify ${action.harness}`)),
+    change: async (action) =>
+      txOk({
+        type: "effect",
+        perform: async () => {
+          const verification = await options.verify()
+          options.onVerified?.(verification)
+          const classified = harnessReadiness(verification, options.now(), action.probes)
+          options.onReadiness?.(structuredClone(classified))
+          const readiness = claudeReadiness(verification, options.now())
+          if (readiness.ready) return txOk(undefined)
+          if (verification.harness === "claude-code" && passesAsPending(classified, options)) return txOk(undefined)
+          return txFail("harness_not_ready", `Claude Code is not ready: ${readiness.problems.join("; ")}`)
+        },
+      }),
+  }
+}

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

@@ -0,0 +1,103 @@
+// Unpacks a Codex release archive (.tar.gz) into the immutable install tree, without a tar binary, streaming: the
+// package inflates to ~0.5 GB, so the archive is read from the staging area in chunks (archive-stream.ts) and each
+// member is streamed into its own staging file, hashed as it is written (HBS-12; nothing is held whole). It only
+// ever sees a download the install-harness executor has already checked against hub's pinned digest
+// (CodexHarnessSource.unpack), and it is still strict, because the tree is installed as is:
+//
+//   - regular files and directories only: symlinks, hard links, devices and FIFOs are refused;
+//   - every name must be a safe relative path (no "..", no absolute path, no empty segment), after pax and GNU
+//     long-name records; duplicates are refused; header checksums must match;
+//   - modes keep only the permission bits (no setuid, setgid or sticky);
+//   - two layouts are accepted: the upstream package (bin/codex plus its helpers, codex-package-<triple>.tar.gz,
+//     what Codex's own install.sh installs) and the standalone binary (one codex-<triple> file, which becomes
+//     bin/codex). Either way the tree has bin/codex.
+import { isSafeRel } from "../../contracts/index.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"
+import { ArchiveError, readTarGz } from "../archive-stream.ts"
+
+/** The executable inside an installed Codex tree. */
+export const CODEX_BINARY_REL = "bin/codex"
+/** Upstream archives inflate to ~0.5 GB today; anything far beyond that is refused, as it inflates. */
+export const MAX_UNPACKED_BYTES = 2 * 1024 ** 3 - 1
+/** pax and GNU long-name records are small; a larger one is not a name. */
+const MAX_NAME_RECORD = 64 * 1024
+const STANDALONE = /^codex-[a-z0-9_]+-[a-z0-9_]+-[a-z0-9_]+(?:-[a-z0-9_]+)?$/
+
+const bad = (why: string) => txFail("invalid", `the Codex archive is not acceptable: ${why}`)
+
+function field(bytes: Uint8Array): string {
+  const end = bytes.indexOf(0)
+  return new TextDecoder().decode(end < 0 ? bytes : bytes.subarray(0, end))
+}
+
+/** "<len> key=value\n" records of a pax extended header. */
+function paxPath(body: Uint8Array): string | undefined {
+  const text = new TextDecoder().decode(body)
+  let path: string | undefined
+  let at = 0
+  while (at < text.length) {
+    const space = text.indexOf(" ", at)
+    const len = Number(text.slice(at, space))
+    if (space < 0 || !Number.isInteger(len) || len <= 0) break
+    const record = text.slice(space + 1, at + len - 1)
+    const eq = record.indexOf("=")
+    if (eq > 0 && record.slice(0, eq) === "path") path = record.slice(eq + 1)
+    at += len
+  }
+  return path
+}
+
+const normalize = (name: string) => name.replace(/^(?:\.\/)+/, "").replace(/\/+$/, "")
+
+/**
+ * The install tree of a verified Codex .tar.gz read from `reader`: every file is streamed into `staging` (judged
+ * before its body is read). `maxBytes` (default MAX_UNPACKED_BYTES) bounds what the archive inflates to.
+ */
+export async function unpackCodexFile(reader: ByteReader, staging: StagingArea, options: { readonly maxBytes?: number } = {}): Promise<TxResult<TreeFile[]>> {
+  const files: { rel: string; staged: StagedFile; mode: number }[] = []
+  const seen = new Set<string>()
+  let nextName: string | undefined
+  try {
+    await readTarGz(reader, { maxBytes: options.maxBytes ?? MAX_UNPACKED_BYTES }, async (member) => {
+      const { type } = member.header
+      if (type === "x") {
+        nextName = paxPath(await member.bytes(MAX_NAME_RECORD)) ?? nextName
+        return
+      }
+      if (type === "g") return
+      if (type === "L") {
+        nextName = field(await member.bytes(MAX_NAME_RECORD))
+        return
+      }
+      const raw = nextName ?? member.header.name
+      nextName = undefined
+      if (raw.startsWith("/")) throw new ArchiveError(`${JSON.stringify(raw)} is an absolute path`)
+      const name = normalize(raw)
+      if (type === "5") {
+        if (name !== "" && !isSafeRel(name)) throw new ArchiveError(`${JSON.stringify(raw)} leaves the install directory`)
+        return
+      }
+      if (type !== "0" && type !== "7") throw new ArchiveError(`${JSON.stringify(raw)} is not a regular file (links and devices are never installed)`)
+      if (!isSafeRel(name)) throw new ArchiveError(`${JSON.stringify(raw)} leaves the install directory`)
+      if (seen.has(name)) throw new ArchiveError(`${name} appears twice`)
+      seen.add(name)
+      const staged = await staging.write(name, member.body(), { maxBytes: member.header.size })
+      files.push({ rel: name, staged, mode: (member.header.mode ?? 0o644) & 0o777 })
+    })
+  } catch (error) {
+    if (error instanceof ArchiveError) return bad(error.message)
+    throw error
+  }
+  if (files.length === 1 && STANDALONE.test(files[0]!.rel)) return txOk([{ rel: CODEX_BINARY_REL, staged: files[0]!.staged, mode: 0o755 }])
+  if (!seen.has(CODEX_BINARY_REL)) return bad(`it has no ${CODEX_BINARY_REL}`)
+  return txOk(files)
+}
+
+/** unpackCodexFile over bytes in memory, the tree as bytes (small archives: tests, fixtures). */
+export async function unpackCodexArchive(bytes: Uint8Array, options: { readonly maxBytes?: number } = {}): Promise<TxResult<(TreeFile & { readonly bytes: Uint8Array })[]>> {
+  const staging = memoryStaging()
+  const r = await unpackCodexFile(bytesReader(bytes), staging, options)
+  return r.ok ? txOk(r.value.map((f) => ({ rel: f.rel, mode: f.mode, bytes: "bytes" in f ? f.bytes : staging.bytes(f.staged) }))) : r
+}

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

@@ -0,0 +1,60 @@
+// The Codex bootstrap adapter (HBS-09). Codex is the third harness in HARNESS_ORDER.
+//
+//   createCodexAdapter       the HarnessAdapter: discover (presence only), plan (planCodex: pinned install-harness,
+//                            select-harness-version, verify-harness with real probes; no ~/.codex edit unless the
+//                            opt-in TOML edit, which becomes a manual edit), verify (verifyCodex)
+//   createCodexHarnessSource the HarnessSource for the built-in install-harness executor (pinned download,
+//                            sigstore evidence, unpack)
+//   codexVerifyExecutor      the verify-harness executor (harness_not_ready unless advertised ready)
+//   codexCapabilities        the explicit, probe-backed capability advertisement
+//
+// Hub wiring reuses packages/codex: the app-server handshake (openAppServer) and stdio channel the Codex spoke uses
+// probe the app-server, and the spoke itself (hub codex-spoke serve) is what spoke-connected checks for.
+import type { DiscoverySnapshot, HarnessAdapter, HarnessPresence, VerifiedManifest } from "../../contracts/index.ts"
+import { codexPinFor, planCodex } from "./plan.ts"
+import { codexBinaryPath, verifyCodex, type CodexProbes } from "./verify.ts"
+
+export * from "./archive.ts"
+export * from "./sigstore.ts"
+export * from "./source.ts"
+export * from "./plan.ts"
+export * from "./verify.ts"
+
+export interface CodexAdapterOptions {
+  /** The verified hub release manifest (its codex pins). */
+  readonly manifest: VerifiedManifest
+  /** The injected probe capabilities; the binary and expected version come from the snapshot and the pin. */
+  readonly probes: Omit<CodexProbes, "binary" | "expectedVersion"> & Partial<Pick<CodexProbes, "binary">>
+  /** The discovery snapshot of this host (discover reads presence from it). */
+  readonly snapshot: () => DiscoverySnapshot | undefined
+  /** The hub-installed Codex recorded before (profile history), for rollback records. */
+  readonly previous?: { readonly version: string; readonly sha256: string }
+  /** Opt-in: ask for features.daemon_auto_start in ~/.codex/config.toml (a TOML manual edit). */
+  readonly ensureDaemonFeature?: boolean
+}
+
+export interface CodexAdapter extends HarnessAdapter {
+  readonly options: CodexAdapterOptions
+}
+
+const NOT_FOUND: HarnessPresence = { id: "codex", installed: false, health: { state: "unverified", probes: [] } }
+
+export function createCodexAdapter(options: CodexAdapterOptions): CodexAdapter {
+  const pinFor = (snapshot: DiscoverySnapshot | undefined) => (snapshot ? codexPinFor(options.manifest, snapshot.host.target) : undefined)
+  return {
+    id: "codex",
+    options,
+    async discover() {
+      const found = options.snapshot()?.harnesses.find((h) => h.id === "codex")
+      // Presence only: health stays unverified until verify runs the real probes.
+      return found ? { ...found, health: { state: "unverified", probes: [] } } : NOT_FOUND
+    },
+    plan: (input) => planCodex(input, { manifest: options.manifest, ...(options.previous ? { previous: options.previous } : {}), ...(options.ensureDaemonFeature ? { ensureDaemonFeature: true } : {}) }),
+    async verify(context) {
+      const snapshot = options.snapshot()
+      const pin = pinFor(snapshot)
+      const binary = options.probes.binary ?? (() => (snapshot ? codexBinaryPath(snapshot, { preferHub: pin !== undefined }) : undefined))
+      return verifyCodex(context, { ...options.probes, binary, ...(pin ? { expectedVersion: pin.version } : {}) })
+    },
+  }
+}

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

@@ -0,0 +1,129 @@
+// The Codex adapter's planner (HarnessAdapter.plan): pure in (snapshot, profile) and the adapter's fixed options.
+//
+//   install-harness         the artifact hub's verified manifest pins for Codex on this host's exact target, into
+//                           its own version directory (harnessVersionRef); evidence: exactly what the pin lists
+//                           (sigstore on Linux, none on macOS). No pin for the target: no install is planned (an
+//                           unpinned Codex is never installed), only verification.
+//   select-harness-version  makes that version current (harnessCurrentRef); a rollback makes the previous current.
+//   verify-harness          real probes only: the binary runs (version-exec), its app-server starts and answers
+//                           (api-health), its provider account is ready (provider-auth), and the hub sees the Codex
+//                           spoke (spoke-connected).
+//
+// When hub's own install already has the pinned version current, only verification is planned. A Codex the user
+// installed another way (brew, npm, Codex's install.sh into ~/.codex/packages) is never touched: hub installs and
+// runs its own pinned copy.
+//
+// ~/.codex is preserved: hub's Codex wiring needs no edit of it (the spoke passes `-c` overrides to the app-server it
+// starts, the wrapper passes `--enable daemon_auto_start` per run, and Codex ≥ 0.165 enables that feature by
+// default). The one optional edit, `ensureDaemonFeature` (for a user who turned the feature off in config.toml), is
+// a TOML merge-config, which the setup planner turns into an unmergeable-format manual edit: hub never writes TOML.
+import {
+  executionContextOf,
+  harnessCurrentRef,
+  harnessVersionRef,
+  resolvePathRef,
+  type Action,
+  type DiscoverySnapshot,
+  type HarnessPin,
+  type PathRef,
+  type PlanInput,
+  type Precondition,
+  type ProbeKind,
+  type VerifiedManifest,
+} from "../../contracts/index.ts"
+
+/** The probes verify-codex runs; each must pass, fresh, before Codex is advertised as ready. */
+export const CODEX_VERIFY_PROBES: readonly Exclude<ProbeKind, "presence">[] = ["version-exec", "api-health", "provider-auth", "spoke-connected"]
+
+/** Codex's config file, as discovery reads it (home:.codex/config.toml). */
+export const CODEX_CONFIG_REF: PathRef = { root: "home", rel: ".codex/config.toml" }
+
+export interface CodexPlanOptions {
+  /** The verified hub release manifest; its codex pins are the only Codex artifacts ever installed. */
+  readonly manifest: VerifiedManifest
+  /** The hub-installed version and digest recorded before (profile history); used only if discovery agrees. */
+  readonly previous?: { readonly version: string; readonly sha256: string }
+  /** Opt-in: ask for `[features] daemon_auto_start = true` in ~/.codex/config.toml (a manual edit). */
+  readonly ensureDaemonFeature?: boolean
+}
+
+const codexOf = (snapshot: DiscoverySnapshot) => snapshot.harnesses.find((h) => h.id === "codex")
+
+/** The pin for Codex on exactly this target, if the manifest has one. */
+export function codexPinFor(manifest: VerifiedManifest, target: string): HarnessPin | undefined {
+  return manifest.harnesses.find((h) => h.harness === "codex" && h.target === target)
+}
+
+function configPrecondition(snapshot: DiscoverySnapshot): Precondition | undefined {
+  const where = resolvePathRef(CODEX_CONFIG_REF, snapshot.roots, executionContextOf(snapshot))
+  if (!where.ok) return undefined
+  const found = snapshot.configs.find((c) => c.path === where.value)
+  return found?.sha256 ? { exists: true, sha256: found.sha256 } : { exists: false }
+}
+
+export function planCodex(input: PlanInput, options: CodexPlanOptions): Action[] {
+  const { snapshot, profile } = input
+  if (!profile.harnesses.includes("codex")) return []
+  const actions: Action[] = []
+  const pin = codexPinFor(options.manifest, snapshot.host.target)
+  const found = codexOf(snapshot)
+  const hubVersion = found?.installed && found.installMethod === "hub" ? found.version : undefined
+  if (pin && hubVersion !== pin.version) {
+    const previous = hubVersion !== undefined && options.previous?.version === hubVersion ? { previous: options.previous } : {}
+    actions.push(
+      {
+        id: "install-codex",
+        kind: "install-harness",
+        escalation: "user",
+        summary: `Install Codex ${pin.version} for ${pin.target} (pinned by hub ${options.manifest.release})`,
+        harness: "codex",
+        version: pin.version,
+        target: pin.target,
+        source: { manifest: options.manifest.release, url: pin.url, file: pin.file },
+        size: pin.size,
+        sha256: pin.sha256,
+        evidence: [...pin.evidence],
+        path: harnessVersionRef("codex", pin.version),
+        owner: "hub",
+        rollback: "restore-previous",
+        ...previous,
+      },
+      {
+        id: "select-codex",
+        kind: "select-harness-version",
+        escalation: "user",
+        summary: `Make Codex ${pin.version} the current version`,
+        harness: "codex",
+        version: pin.version,
+        path: harnessCurrentRef("codex"),
+        target: harnessVersionRef("codex", pin.version),
+        ...previous,
+      },
+    )
+  }
+  if (options.ensureDaemonFeature) {
+    const precondition = configPrecondition(snapshot)
+    if (precondition)
+      actions.push({
+        id: "codex-daemon-feature",
+        kind: "merge-config",
+        escalation: "user",
+        summary: "Turn on Codex's shared app-server daemon (features.daemon_auto_start) so the hub sees TUI threads",
+        path: CODEX_CONFIG_REF,
+        format: "toml",
+        owner: "harness:codex",
+        precondition,
+        set: [{ pointer: "/features/daemon_auto_start", value: true }],
+        preserveUnknown: true,
+      })
+  }
+  actions.push({
+    id: "verify-codex",
+    kind: "verify-harness",
+    escalation: "user",
+    summary: "Verify Codex really runs, its app-server answers, its provider account is ready and its spoke reaches the hub",
+    harness: "codex",
+    probes: [...CODEX_VERIFY_PROBES],
+  })
+  return actions
+}