@huynle/hub 0.7.1 → 0.7.2

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

@@ -0,0 +1,244 @@
+// What `hubctl setup` keeps between commands (HBS-13 integration item 7). Everything is secret-free, validated when
+// read and written, and reached only through symlink-checked paths under the state root (next to the applier's own
+// journal, contract LOCK_PATH):
+//
+//   the setup request    `setup preview --out <file>`: the SetupPreview plus the profile and choices apply must
+//                        re-plan with, so `setup apply --preview <file>` needs nothing else (the Ansible role's argv)
+//   state:hub/bootstrap/state.json
+//                        the applied profile, its choices and catalog revision, the last committed transaction and
+//                        plan digest, and the security floors this machine has seen (hubctl and each harness's
+//                        pinned minimumVersion), which only rise
+//   state:hub/bootstrap/requests/<hex>.json
+//                        the request each applied plan was made from, by plan digest (resume, drift and verify
+//                        re-plan from it); the plan itself is the engine's journal/<txID>.plan.json
+//
+// The journals stay the record of used preview nonces (the engine reads them).
+import {
+  bool,
+  Checker,
+  compareVersions,
+  digest,
+  ENROLLMENT_MODES,
+  findSecrets,
+  HARNESS_ORDER,
+  header,
+  int,
+  isRecord,
+  oneOf,
+  semver,
+  shape,
+  text,
+  validatePathRef,
+  validateSetupPreview,
+  type ArtifactManifest,
+  type EnrollmentMode,
+  type HarnessID,
+  type PathRef,
+  type Profile,
+  type Result,
+  type RootMapping,
+  type SetupPreview,
+} from "../bootstrap/contracts/index.ts"
+import { loadProfile } from "../bootstrap/profiles/versions.ts"
+import { nodeFs, type TxFs } from "../bootstrap/transaction/fs.ts"
+import { resolveTarget } from "../bootstrap/transaction/resolve.ts"
+import { errnoOf } from "../bootstrap/transaction/result.ts"
+
+export const SETUP_REQUEST_SCHEMA = "hub.setup-request"
+export const BOOTSTRAP_STATE_SCHEMA = "hub.bootstrap-state"
+
+/** What the user chose at preview, besides the profile; apply re-plans with exactly these. */
+export interface SetupChoices {
+  /** Inline (a planned enroll-machine, with `server`) or separate (`hubctl machine enroll`). */
+  readonly enrollment?: EnrollmentMode
+  /** --confirm-activation at preview: plan loading the services (apply needs the flag again). */
+  readonly activate?: boolean
+  /** --allow-downgrade at preview (apply needs the flag again). */
+  readonly allowDowngrade?: boolean
+  /** node.json settings for a launch node. */
+  readonly node?: { readonly workspaceRoots: readonly string[]; readonly slots?: number; readonly labels?: Readonly<Record<string, string>> }
+  /** One bounded verification launch. */
+  readonly launch?: { readonly harness: HarnessID; readonly workspace: PathRef }
+  /** The hub to enroll with inline. */
+  readonly server?: string
+  readonly machineName?: string
+}
+
+export interface SetupRequest {
+  readonly schema: typeof SETUP_REQUEST_SCHEMA
+  readonly version: 1
+  readonly preview: SetupPreview
+  readonly profile: Profile
+  readonly choices: SetupChoices
+}
+
+export interface Floors {
+  readonly hubctl?: string
+  readonly harnesses: Partial<Record<HarnessID, string>>
+}
+
+export interface BootstrapState {
+  readonly schema: typeof BOOTSTRAP_STATE_SCHEMA
+  readonly version: 1
+  /** The profile of the last committed apply. */
+  readonly profile?: Profile
+  readonly choices?: SetupChoices
+  /** The built-in catalog revision that profile was made from (profile.revision). */
+  readonly catalogRevision?: number
+  readonly txID?: string
+  readonly planDigest?: string
+  readonly floors: Floors
+}
+
+const EMPTY: BootstrapState = { schema: BOOTSTRAP_STATE_SCHEMA, version: 1, floors: { harnesses: {} } }
+
+function checkChoices(c: Checker, path: string, value: unknown): void {
+  const r = shape(c, path, value, [], ["enrollment", "activate", "allowDowngrade", "node", "launch", "server", "machineName"])
+  if (!r) return
+  oneOf(c, `${path}/enrollment`, r.enrollment, ENROLLMENT_MODES)
+  bool(c, `${path}/activate`, r.activate)
+  bool(c, `${path}/allowDowngrade`, r.allowDowngrade)
+  if (r.node !== undefined) {
+    const n = shape(c, `${path}/node`, r.node, ["workspaceRoots"], ["slots", "labels"])
+    if (n) {
+      if (!Array.isArray(n.workspaceRoots) || n.workspaceRoots.length > 64) c.add(`${path}/node/workspaceRoots`, "invalid_value", "expected a list of at most 64 paths")
+      else n.workspaceRoots.forEach((w, i) => text(c, `${path}/node/workspaceRoots/${i}`, w, 4096))
+      int(c, `${path}/node/slots`, n.slots, 1, 64)
+      if (n.labels !== undefined && (!isRecord(n.labels) || Object.values(n.labels).some((v) => typeof v !== "string"))) c.add(`${path}/node/labels`, "invalid_value", "labels are strings")
+    }
+  }
+  if (r.launch !== undefined) {
+    const l = shape(c, `${path}/launch`, r.launch, ["harness", "workspace"])
+    if (l) {
+      oneOf(c, `${path}/launch/harness`, l.harness, HARNESS_ORDER)
+      c.merge(`${path}/launch/workspace`, validatePathRef(l.workspace))
+    }
+  }
+  text(c, `${path}/server`, r.server, 2048)
+  text(c, `${path}/machineName`, r.machineName, 64)
+}
+
+/** A setup request read back from a file: validated, never cast; the profile is migrated to the current version. */
+export function validateSetupRequest(value: unknown): Result<SetupRequest> {
+  const c = new Checker()
+  const r = shape(c, "", value, ["schema", "version", "preview", "profile", "choices"])
+  if (!r) return c.result(undefined)
+  header(c, "", r, SETUP_REQUEST_SCHEMA, 1)
+  c.merge("/preview", validateSetupPreview(r.preview))
+  const profile = loadProfile(r.profile)
+  c.merge("/profile", profile)
+  checkChoices(c, "/choices", r.choices)
+  // The preview is checked by its own validator (its token field is a preview token, not a credential).
+  for (const p of findSecrets({ profile: r.profile, choices: r.choices })) c.add(p, "secret", "setup requests never carry credentials")
+  if (c.issues.length > 0) return c.result(undefined)
+  return c.result({ ...r, profile: profile.ok ? profile.value.profile : r.profile })
+}
+
+function validateState(value: unknown): Result<BootstrapState> {
+  const c = new Checker()
+  const r = shape(c, "", value, ["schema", "version", "floors"], ["profile", "choices", "catalogRevision", "txID", "planDigest"])
+  if (!r) return c.result(undefined)
+  header(c, "", r, BOOTSTRAP_STATE_SCHEMA, 1)
+  if (r.profile !== undefined) c.merge("/profile", loadProfile(r.profile))
+  if (r.choices !== undefined) checkChoices(c, "/choices", r.choices)
+  int(c, "/catalogRevision", r.catalogRevision, 1, 1_000_000)
+  text(c, "/txID", r.txID, 64, /^tx_[A-Za-z0-9_-]+$/)
+  if (r.planDigest !== undefined) digest(c, "/planDigest", r.planDigest)
+  const f = shape(c, "/floors", r.floors, ["harnesses"], ["hubctl"])
+  if (f) {
+    if (f.hubctl !== undefined) semver(c, "/floors/hubctl", f.hubctl)
+    const h = shape(c, "/floors/harnesses", f.harnesses, [], HARNESS_ORDER)
+    if (h) for (const id of HARNESS_ORDER) if (h[id] !== undefined) semver(c, `/floors/harnesses/${id}`, h[id])
+  }
+  for (const p of findSecrets(value)) c.add(p, "secret", "the bootstrap state never carries credentials")
+  return c.result(value)
+}
+
+const max = (a: string | undefined, b: string | undefined) => (a === undefined ? b : b === undefined ? a : compareVersions(a, b) >= 0 ? a : b)
+
+/** The floors after seeing a verified manifest: the highest of what was seen and what it pins for `target`. */
+export function raiseFloors(floors: Floors, manifest: Pick<ArtifactManifest, "minimumVersion" | "harnesses">, target: string): Floors {
+  const harnesses: Partial<Record<HarnessID, string>> = { ...floors.harnesses }
+  for (const pin of manifest.harnesses) if (pin.target === target && pin.minimumVersion) harnesses[pin.harness] = max(harnesses[pin.harness], pin.minimumVersion)
+  const hubctl = max(floors.hubctl, manifest.minimumVersion)
+  return { ...(hubctl ? { hubctl } : {}), harnesses }
+}
+
+const decode = (bytes: Uint8Array) => new TextDecoder().decode(bytes)
+
+export class BootstrapStateStore {
+  readonly statePath: string
+  private readonly requestDir: string
+
+  constructor(
+    private readonly roots: readonly RootMapping[],
+    private readonly fs: TxFs = nodeFs,
+  ) {
+    const state = this.resolve("hub/bootstrap/state.json")
+    this.statePath = state
+    this.requestDir = `${state.slice(0, state.lastIndexOf("/"))}/requests`
+  }
+
+  private resolve(rel: string): string {
+    const r = resolveTarget({ root: "state", rel }, this.roots, this.fs)
+    if (!r.ok) throw new Error(`the hub state directory is unusable: ${r.message}`)
+    return r.value
+  }
+
+  read(): BootstrapState {
+    const info = this.fs.lstat(this.resolve("hub/bootstrap/state.json"))
+    if (!info) return EMPTY
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(decode(this.fs.readFile(this.statePath)))
+    } catch {
+      throw new Error(`the bootstrap state ${this.statePath} cannot be read; inspect it before setting up again`)
+    }
+    const checked = validateState(parsed)
+    if (!checked.ok) throw new Error(`the bootstrap state ${this.statePath} is not valid (${checked.issues[0]!.message})`)
+    return checked.value
+  }
+
+  write(state: BootstrapState): void {
+    const checked = validateState(state)
+    if (!checked.ok) throw new Error(`refusing to write an invalid bootstrap state: ${checked.issues[0]!.path} ${checked.issues[0]!.message}`)
+    this.writeAtomic(this.resolve("hub/bootstrap/state.json"), state)
+  }
+
+  /** Records the request a plan was made from, under its plan digest. */
+  writeRequest(request: SetupRequest): void {
+    const checked = validateSetupRequest(request)
+    if (!checked.ok) throw new Error(`refusing to store an invalid setup request: ${checked.issues[0]!.message}`)
+    this.writeAtomic(this.resolve(`hub/bootstrap/requests/${request.preview.planDigest.slice("sha256:".length)}.json`), request)
+  }
+
+  readRequest(planDigest: string): SetupRequest | undefined {
+    if (!/^sha256:[0-9a-f]{64}$/.test(planDigest)) return undefined
+    const path = this.resolve(`hub/bootstrap/requests/${planDigest.slice("sha256:".length)}.json`)
+    if (!this.fs.lstat(path)) return undefined
+    try {
+      const r = validateSetupRequest(JSON.parse(decode(this.fs.readFile(path))))
+      return r.ok && r.value.preview.planDigest === planDigest ? r.value : undefined
+    } catch {
+      return undefined
+    }
+  }
+
+  private writeAtomic(path: string, value: unknown): void {
+    const dir = path.slice(0, path.lastIndexOf("/"))
+    if (!this.fs.lstat(dir)) this.fs.mkdirp(dir, 0o700)
+    else if (this.fs.lstat(dir)?.kind !== "directory") throw new Error(`${dir} is not a directory`)
+    const tmp = `${path}.tmp`
+    try {
+      if (this.fs.lstat(tmp)) this.fs.unlink(tmp)
+      this.fs.writeExclusive(tmp, `${JSON.stringify(value, null, 2)}\n`, 0o600)
+      this.fs.rename(tmp, path)
+      this.fs.fsyncDir(dir)
+    } catch (error) {
+      try {
+        if (this.fs.lstat(tmp)) this.fs.unlink(tmp)
+      } catch {}
+      throw errnoOf(error) ? new Error(`cannot write ${path} (${errnoOf(error)})`) : error
+    }
+  }
+}

package/packages/cli/src/setup/user-bin.ts

@@ -0,0 +1,39 @@
+// The user-bin link rule (contract §7.6 A6, HBS-12 E4), shared by the setup's harness links (contributors.ts) and
+// the OpenCode plugin's `hub` link (src/spoke/launchers.ts): hub links a command into user-bin (~/.local/bin) only
+// when nothing is there or what is there is a link of hub's own, and only when no other command of that name is on
+// PATH. A user's binary is never shadowed or replaced. Pure: callers read the facts (lstat, readlink, PATH).
+
+/** What is at the link path now, not following a final symlink. */
+export type UserBinEntry = "missing" | "file" | "directory" | "symlink" | "other"
+
+/**
+ * - in-place: the link is already there, pointing at the target.
+ * - create: nothing there: link it.
+ * - replace: a link of hub's own pointing elsewhere: re-point it.
+ * - foreign: something of the user's is there: leave it.
+ * - shadowed: another command of that name comes first on PATH: leave it.
+ */
+export type UserBinLinkDecision = "in-place" | "create" | "replace" | "foreign" | "shadowed"
+
+export interface UserBinLinkFacts {
+  readonly entry: UserBinEntry
+  /** The absolute path a symlink at the link path points to. */
+  readonly pointsTo?: string
+  /** The absolute path the link should point to. */
+  readonly target: string
+  /** The link path itself. */
+  readonly linkPath: string
+  /** Whether a link pointing here is hub's own (its harness directory, its launchers). */
+  readonly hubOwned: (pointsTo: string) => boolean
+  /** The first command of that name on PATH, as found (not followed); undefined when none. */
+  readonly foundOnPath?: string
+}
+
+export function userBinLinkDecision(facts: UserBinLinkFacts): UserBinLinkDecision {
+  const { entry, pointsTo } = facts
+  if (entry === "symlink" && pointsTo === facts.target) return "in-place"
+  const hubOwned = entry === "symlink" && pointsTo !== undefined && facts.hubOwned(pointsTo)
+  if (entry !== "missing" && !hubOwned) return "foreign"
+  if (facts.foundOnPath !== undefined && facts.foundOnPath !== facts.linkPath) return "shadowed"
+  return entry === "missing" ? "create" : "replace"
+}

package/packages/cli/src/spoke-services.ts

@@ -0,0 +1,109 @@
+// `hub claude-code install | uninstall | status` and `hub codex-spoke install | uninstall | status`: the harness
+// spokes' per-user services (`hub claude-code daemon`, `hub codex-spoke serve`) as a launchd agent (macOS) or a
+// systemd user unit (Linux), rendered from the templates embedded in this program the way `hub node install` writes
+// the node's (node.ts). `hub claude` and `hub codex` start these processes on demand; installed, they keep running, so the hub
+// can place claude-code and codex launches on the machine without a wrapper run first. Like `hub node install`,
+// nothing here starts a process: loading, unloading and inspecting the service are printed for the user, never run.
+import path from "node:path"
+import { claudeBinary, codexBinary, findExecutable } from "../../node/src/harnesses.ts"
+import { readSpokeCredentials } from "../../node/src/config.ts"
+import { socketPath } from "../../claude-code/src/paths.ts"
+import { daemonSocketPath, readServicePid } from "../../codex/src/paths.ts"
+import type { Env } from "./credentials"
+import { installService, serviceCheckLines, serviceState, serviceStateLine, uninstallService, type ExtraEnvironment, type NodeCommandOutput, type NodeIo, type ServiceSpec, type ServiceState } from "./node"
+
+/** The subcommands `hub claude-code` and `hub codex-spoke` take for their service (the others are the spokes' own). */
+export const SERVICE_VERBS = ["install", "uninstall", "status"] as const
+export type ServiceVerb = (typeof SERVICE_VERBS)[number]
+export const isServiceVerb = (verb: string | undefined): verb is ServiceVerb => (SERVICE_VERBS as readonly string[]).includes(verb ?? "")
+
+/** Where config.json and the hub state dir are (shared by every hub spoke). */
+const HUB_PLACES = ["HUB_SPOKE_CONFIG", "XDG_CONFIG_HOME", "HUB_STATE_DIR"] as const
+
+export const CLAUDE_CODE_SERVICE: ServiceSpec = {
+  service: "claude-code",
+  command: "hub claude-code",
+  label: "io.github.huynle.hub-claude-code",
+  unit: "hub-claude-code.service",
+  log: "claude-code.log",
+  // The hooks find the daemon by HUB_CLAUDE_SOCKET / HUB_STATE_DIR: the service must listen where they look.
+  carried: [...HUB_PLACES, "HUB_CLAUDE_SOCKET", "HUB_CLAUDE_BIN"],
+  elsewhere: "Run `hub claude-code daemon` under your own service manager (or let `hub claude` start it)",
+}
+
+export const CODEX_SPOKE_SERVICE: ServiceSpec = {
+  service: "codex-spoke",
+  command: "hub codex-spoke",
+  label: "io.github.huynle.hub-codex-spoke",
+  unit: "hub-codex-spoke.service",
+  log: "codex-spoke.log",
+  // HUB_CODEX_CONFIG (one override per line) is not carried: a unit's Environment= cannot hold several lines.
+  carried: [...HUB_PLACES, "CODEX_HOME", "HUB_CODEX_BIN", "HUB_CODEX_DAEMON_SOCKET"],
+  elsewhere: "Run `hub codex-spoke serve` under your own service manager (or let `hub codex` start it)",
+}
+
+const SPECS = { "claude-code": CLAUDE_CODE_SERVICE, "codex-spoke": CODEX_SPOKE_SERVICE } as const
+
+/** The codex-spoke unit runs the Codex `hubctl setup` installed (HUB_CODEX_BIN), unless the shell names another. */
+const codexEnvironment: ExtraEnvironment = (io): Record<string, string> => {
+  const bin = codexBinary(io.env, io.home)
+  return path.isAbsolute(bin) && !io.env.HUB_CODEX_BIN ? { HUB_CODEX_BIN: bin } : {}
+}
+const EXTRA: Partial<Record<keyof typeof SPECS, ExtraEnvironment>> = { "codex-spoke": codexEnvironment }
+export type SpokeServiceName = keyof typeof SPECS
+export const spokeServiceSpec = (name: SpokeServiceName): ServiceSpec => SPECS[name]
+
+/** Why the installed service would not do anything yet (never the token). */
+function readiness(env: Env, home: string): string[] {
+  return readSpokeCredentials(env, home) ? [] : ["this machine is not enrolled with a hub yet (no machine token in config.json): enroll it with `hubctl machine enroll --server <hub URL>`; until then the service exits and is restarted"]
+}
+
+export function installSpokeService(name: SpokeServiceName, io: NodeIo, options: { readonly dryRun: boolean }): NodeCommandOutput {
+  return installService(SPECS[name], io, options, readiness(io.env, io.home), EXTRA[name])
+}
+
+export function uninstallSpokeService(name: SpokeServiceName, io: NodeIo, options: { readonly dryRun: boolean }): NodeCommandOutput {
+  return uninstallService(SPECS[name], io, options)
+}
+
+export interface SpokeServiceStatus {
+  readonly service: ServiceState
+  readonly enrolled?: { readonly server: string; readonly machineID?: string }
+  /** The harness CLI as this shell finds it (the service looks on its own PATH, see the unit). */
+  readonly harness: { readonly bin: string; readonly found?: string }
+  /** claude-code: the daemon's socket (hooks look there). */
+  readonly socket?: string
+  /** codex-spoke: the running service's pid (its pid file), and the Codex daemon socket it attaches to. */
+  readonly running?: number
+  readonly daemonSocket?: string
+}
+
+export function spokeServiceStatus(name: SpokeServiceName, io: NodeIo): SpokeServiceStatus {
+  const credentials = readSpokeCredentials(io.env, io.home)
+  const bin = name === "claude-code" ? claudeBinary(io.env, io.home) : codexBinary(io.env, io.home)
+  const found = findExecutable(bin, io.env)
+  const base = {
+    service: serviceState(SPECS[name], io, EXTRA[name]),
+    ...(credentials ? { enrolled: { server: credentials.server, ...(credentials.machineID ? { machineID: credentials.machineID } : {}) } } : {}),
+    harness: { bin, ...(found ? { found } : {}) },
+  }
+  if (name === "claude-code") return { ...base, socket: socketPath(io.env, io.home) }
+  const running = readServicePid(io.env, io.home)
+  const daemonSocket = daemonSocketPath(io.env, io.home)
+  return { ...base, ...(running !== undefined ? { running } : {}), ...(daemonSocket ? { daemonSocket } : {}) }
+}
+
+export function spokeServiceStatusText(name: SpokeServiceName, status: SpokeServiceStatus): string {
+  const spec = SPECS[name]
+  const lines = [serviceStateLine(spec, status.service)]
+  lines.push(status.enrolled ? `machine: enrolled with ${status.enrolled.server}${status.enrolled.machineID ? ` as ${status.enrolled.machineID}` : ""}` : "machine: not enrolled (enroll it with `hubctl machine enroll --server <hub URL>`)")
+  const what = name === "claude-code" ? "Claude Code CLI" : "Codex CLI"
+  lines.push(status.harness.found ? `${what}: ${status.harness.found}` : `${what}: ${status.harness.bin} not found on this shell's PATH (no hub launches${name === "claude-code" ? "" : " of new threads"} until it is)`)
+  if (status.socket) lines.push(`daemon socket: ${status.socket}`)
+  if (name === "codex-spoke") {
+    lines.push(status.running !== undefined ? `running: pid ${status.running}` : "running: no")
+    lines.push(`Codex daemon socket: ${status.daemonSocket ?? "off"}`)
+  }
+  lines.push(...serviceCheckLines(status.service))
+  return lines.join("\n")
+}

package/packages/cli/src/watch.ts

@@ -0,0 +1,28 @@
+// `hub watch`: GET /api/agent/watch (SSE, through the SDK) printed as JSON lines, one per event, until interrupted.
+// Heartbeats are skipped (the SDK does). The hub closing the stream or the stream breaking is an error.
+import { HubTransportError } from "../../sdk/src/index.ts"
+import type { Credentials } from "./credentials"
+import { CliError, cliError, clientFor, EXIT } from "./http"
+
+/** One compact JSON line per event (non-JSON data is printed as is). */
+const line = (data: string) => {
+  try {
+    return JSON.stringify(JSON.parse(data))
+  } catch {
+    return data
+  }
+}
+
+const AGAIN = "Run `hub watch` again"
+
+export async function watch(credentials: Credentials, options: { blocked?: boolean; session?: string }, write: (line: string) => void, signal?: AbortSignal): Promise<void> {
+  try {
+    for await (const event of clientFor(credentials).watch({ ...options, ...(signal ? { signal } : {}) })) write(`${line(event.data)}\n`)
+  } catch (cause) {
+    if (signal?.aborted) return
+    if (cause instanceof HubTransportError && cause.kind === "stream") throw new CliError(EXIT.other, cause.message, AGAIN)
+    throw cliError(cause, credentials)
+  }
+  if (signal?.aborted) return
+  throw new CliError(EXIT.other, "the watch stream ended (the hub closed it)", AGAIN)
+}

package/packages/codex/package.json

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

package/packages/codex/src/main.ts

@@ -3,13 +3,14 @@
 // token in the spoke's config.json, read-only), keeps a pid file in <hub state dir>/codex/spoke.pid (one service per
 // user: a second one refuses while the first runs) and attaches to the shared Codex daemon's socket when present.
 //
-// Settings (environment): HUB_CODEX_BIN (default `codex` on PATH), HUB_CODEX_DAEMON_SOCKET (another socket, or
+// Settings (environment): HUB_CODEX_BIN (default: the Codex `hubctl setup` installed, else `codex` on PATH), HUB_CODEX_DAEMON_SOCKET (another socket, or
 // "off"), HUB_CODEX_CONFIG (Codex config overrides for the app-server the spoke starts, one key=value per line,
 // passed as -c; Codex's files are never written).
 import { spawnSync } from "node:child_process"
 import { openSync, closeSync, readFileSync, rmSync, writeSync } from "node:fs"
 import { configPath } from "../../../src/config.ts"
 import { readSpokeCredentials } from "../../node/src/config.ts"
+import { codexBinary } from "../../node/src/harnesses.ts"
 import pkg from "../package.json" with { type: "json" }
 import { codexStateDir, ensurePrivateDir, daemonSocketPath, pidFile, readServicePid } from "./paths.ts"
 import { startCodexSpoke } from "./spoke.ts"
@@ -85,7 +86,7 @@ async function serve(io: CodexMainIo): Promise<number> {
     return 1
   }
   try {
-    const codexBin = io.env.HUB_CODEX_BIN || "codex"
+    const codexBin = codexBinary(io.env, io.home)
     const env: Record<string, string | undefined> = { ...io.env }
     delete env.BUN_BE_BUN
     const daemonSocket = daemonSocketPath(io.env, io.home)

package/packages/codex/src/spoke.ts

@@ -17,6 +17,9 @@ import { CodexSessions, type ThreadDescription } from "./sessions.ts"
 import { spawnStdioChannel } from "./stdio.ts"
 import { connectUnixWebSocket } from "./websocket.ts"
 
+/** The words that start Codex's app-server on stdio (the spoke's own app-server, and `hubctl setup verify`). */
+export const CODEX_APP_SERVER_ARGS: readonly string[] = Object.freeze(["app-server", "--listen", "stdio://"])
+
 export const HARNESS = "codex"
 export const DEFAULT_POLL_MS = 2000
 const LIST_PAGES_MAX = 20
@@ -124,7 +127,7 @@ export function startCodexSpoke(options: CodexSpokeOptions): CodexSpoke {
     own ??= (async () => {
       const child = spawnStdioChannel({
         command: options.codexBin,
-        args: [...(options.codexBinArgs ?? []), "app-server", "--listen", "stdio://", ...(options.codexArgs ?? [])],
+        args: [...(options.codexBinArgs ?? []), ...CODEX_APP_SERVER_ARGS, ...(options.codexArgs ?? [])],
         env: options.env,
         log: (line) => log(`codex app-server: ${line}`),
       })

package/packages/codex/src/wrapper.ts

@@ -5,12 +5,13 @@
 // arguments, its exit code passed through. On a machine that is not enrolled (no machine token) or when the service
 // cannot be started, Codex runs as usual without the hub, and the command says why.
 //
-// Settings (environment): HUB_CODEX_BIN (default `codex` on PATH); see main.ts for the service's.
+// Settings (environment): HUB_CODEX_BIN (default: the Codex `hubctl setup` installed, else `codex` on PATH); see main.ts for the service's.
 import { spawn } from "node:child_process"
 import { closeSync, openSync } from "node:fs"
 import path from "node:path"
 import { configPath } from "../../../src/config.ts"
 import { readSpokeCredentials } from "../../node/src/config.ts"
+import { codexBinary } from "../../node/src/harnesses.ts"
 import { codexStateDir, ensurePrivateDir, readServicePid } from "./paths.ts"
 
 const SERVICE_START_MS = 8000
@@ -87,7 +88,10 @@ function spawnCodex(bin: string, args: readonly string[], env: Env, stderr: (s:
   })
 }
 
-export async function runCodex(args: readonly string[], io: CodexIo): Promise<number> {
+export async function runCodex(args: readonly string[], given: CodexIo): Promise<number> {
+  // A hub-installed Codex is what both this run and the spoke it starts use (HUB_CODEX_BIN is passed on).
+  const bin = codexBinary(given.env, given.home)
+  const io: CodexIo = path.isAbsolute(bin) && !given.env.HUB_CODEX_BIN ? { ...given, env: { ...given.env, HUB_CODEX_BIN: bin } } : given
   let hub = false
   try {
     hub = await ensureService(io)
@@ -96,5 +100,5 @@ export async function runCodex(args: readonly string[], io: CodexIo): Promise<nu
   }
   const env: Record<string, string | undefined> = { ...io.env }
   delete env.BUN_BE_BUN
-  return spawnCodex(io.env.HUB_CODEX_BIN || "codex", hub ? [...DAEMON_ARGS, ...args] : [...args], env, io.stderr)
+  return spawnCodex(bin, hub ? [...DAEMON_ARGS, ...args] : [...args], env, io.stderr)
 }

package/packages/node/package.json

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

package/packages/node/src/harnesses.ts

@@ -2,11 +2,16 @@
 // runtime starts nothing itself: a host launch's session is created by the machine's service spoke of its harness
 // (placement also needs that spoke connected with "launch"), so this only says what can run here:
 // - opencode: always (its service spoke is the OpenCode plugin, which the node cannot see);
-// - claude-code: when the Claude Code CLI is found: HUB_CLAUDE_BIN (absolute, or a name on PATH), else `claude` on
-//   PATH; the Claude Code spoke daemon (`hub claude-code daemon`) creates its launch sessions;
+// - claude-code: when the Claude Code CLI is found (claudeBinary: HUB_CLAUDE_BIN, hub's claude-code.json, else `claude` on
+//   PATH); the Claude Code spoke daemon (`hub claude-code daemon`) creates its launch sessions;
+// - codex: when the Codex CLI is found (codexBinary); the Codex spoke (`hub codex-spoke serve`) creates them;
 // - node.json `harnesses` overrides detection either way (true offers a harness, false withholds it).
-import { accessSync, constants, statSync } from "node:fs"
+//
+// Which binary (claudeBinary, codexBinary): the explicit setting, then the one `hubctl setup` installed, then PATH.
+import { accessSync, constants, readFileSync, statSync } from "node:fs"
+import { homedir } from "node:os"
 import path from "node:path"
+import { configPath } from "../../../src/config.ts"
 
 type Env = Readonly<Record<string, string | undefined>>
 
@@ -18,6 +23,8 @@ export interface DetectHarnessesOptions {
   readonly env?: Env
   /** node.json `harnesses`. */
   readonly overrides?: Readonly<Record<string, boolean>>
+  /** Where hub's config and data are (default os.homedir()). */
+  readonly home?: string
 }
 
 function executable(file: string): boolean {
@@ -47,7 +54,9 @@ export function findExecutable(name: string, env: Env): string | undefined {
 export function detectHarnesses(options: DetectHarnessesOptions = {}): string[] {
   const env = options.env ?? process.env
   const found = new Set<string>(["opencode"])
-  if (findExecutable(env.HUB_CLAUDE_BIN || "claude", env)) found.add("claude-code")
+  const home = options.home ?? homedir()
+  if (findExecutable(claudeBinary(env, home), env)) found.add("claude-code")
+  if (findExecutable(codexBinary(env, home), env)) found.add("codex")
   for (const [name, on] of Object.entries(options.overrides ?? {})) {
     if (on) found.add(name)
     else found.delete(name)
@@ -58,3 +67,29 @@ export function detectHarnesses(options: DetectHarnessesOptions = {}): string[]
   }
   return [...found].sort((a, b) => rank(a) - rank(b))
 }
+
+/**
+ * The Claude Code CLI to run: HUB_CLAUDE_BIN, else the absolute `binary` in hub's own claude-code.json (next to
+ * config.json, so it follows HUB_SPOKE_CONFIG; `hubctl setup` writes it when it installed Claude Code), else `claude`
+ * on PATH. A claude-code.json that is unreadable, or names a relative path, is ignored.
+ */
+export function claudeBinary(env: Env, home: string = homedir()): string {
+  if (env.HUB_CLAUDE_BIN) return env.HUB_CLAUDE_BIN
+  try {
+    const file = path.join(path.dirname(configPath(env as Record<string, string | undefined>, home)), "claude-code.json")
+    const binary = (JSON.parse(readFileSync(file, "utf8")) as { binary?: unknown }).binary
+    if (typeof binary === "string" && path.isAbsolute(binary)) return binary
+  } catch {}
+  return "claude"
+}
+
+/**
+ * The Codex CLI to run: HUB_CODEX_BIN, else the Codex `hubctl setup` installed (data/hub/harnesses/codex/current/
+ * bin/codex, under XDG_DATA_HOME or ~/.local/share) when it is there, else `codex` on PATH.
+ */
+export function codexBinary(env: Env, home: string = homedir()): string {
+  if (env.HUB_CODEX_BIN) return env.HUB_CODEX_BIN
+  const data = env.XDG_DATA_HOME && path.isAbsolute(env.XDG_DATA_HOME) ? env.XDG_DATA_HOME : path.join(home, ".local", "share")
+  const current = path.join(data, "hub", "harnesses", "codex", "current", "bin", "codex")
+  return executable(current) ? current : "codex"
+}

package/packages/node/src/run.ts

@@ -79,7 +79,7 @@ export async function runNode(options: RunNodeOptions): Promise<number> {
 
   if (options.signal.aborted) return 0
   const openshell = config.openshell?.enabled ? await setupOpenShell(config, credentials, options, env, log) : undefined
-  const harnesses = detectHarnesses({ env, ...(config.harnesses ? { overrides: config.harnesses } : {}) })
+  const harnesses = detectHarnesses({ env, home, ...(config.harnesses ? { overrides: config.harnesses } : {}) })
   const runtimes: Runtime[] = [new HostRuntime({ roots: config.workspaceRoots, harnesses }), ...(openshell ? [openshell.runtime] : [])]
 
   const daemon = new NodeDaemon({

package/packages/preset/package.json

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

package/packages/protocol/package.json

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

package/packages/runtime-openshell/package.json

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

package/packages/runtime-sdk/package.json

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

package/packages/sdk/package.json

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