@huynle/hub 0.7.1 → 0.7.3

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

@@ -0,0 +1,456 @@
+// The composition root of `hubctl setup` (HBS-13): one place that builds the harness adapters, the plan
+// contributors and the apply executors from the independently tested bootstrap modules, so preview and apply use the
+// SAME adapter registry, contributors and options (and so plan the same digest), and apply executes the fresh plan
+// revalidateApply returns.
+//
+//   adapters      OpenCode, Claude Code, Codex (HARNESS_ORDER), each with its real probes, the machine-credential
+//                 spoke probe (spoke-probe.ts) and its pinned-artifact source
+//   contributors  hubctl itself (contributors.ts), the node services (node-services/plan.ts), a profile downgrade's
+//                 typed service removal (profiles/upgrade.ts), inline enrollment
+//   executors     builtinExecutors + the node-service executors + the per-harness dispatchers (dispatch.ts) + the
+//                 enroll-machine and verify-runtime executors below
+//
+// Nothing here runs a shell: processes are started only by the adapters' fixed-argv runners and the service
+// manager's fixed-call runner. Every capability that reaches outside is a port the tests replace.
+import { realpathSync } from "node:fs"
+import nodePath from "node:path"
+import {
+  createAdapterRegistry,
+  executionContextOf,
+  HARNESS_ORDER,
+  ok,
+  resolvePathRef,
+  rootPathIn,
+  type AdapterContext,
+  type DiscoverySnapshot,
+  type HarnessAdapter,
+  type HarnessID,
+  type HarnessReadiness,
+  type HarnessVerification,
+  type PathRef,
+  type Profile,
+  type ProgramLayout,
+  type Result,
+  type RootMapping,
+  type ServiceManagerID,
+  type VerifiedManifest,
+} from "../bootstrap/contracts/index.ts"
+import { claudeVerifyExecutor, createClaudeAdapter, createClaudeHarnessSource, httpsDownloader as claudeDownloader, nodeRunner as claudeNodeRunner, tempScratch, type ProbeRunner as ClaudeProbeRunner } from "../bootstrap/adapters/claude/index.ts"
+import { codexVerifyExecutor, createCodexAdapter, createCodexHarnessSource, httpsDownloader as codexDownloader, nodeProbeRunner as codexNodeRunner, stdioAppServerLauncher, type AppServerLauncher, type ProbeRunner as CodexProbeRunner } from "../bootstrap/adapters/codex/index.ts"
+import {
+  createServiceControl,
+  nodeServiceExecutors,
+  planNodeServices,
+  serviceAssets,
+  spawnManagerRunner,
+  unitPathResolver,
+  type LaunchDriver,
+  type LaunchReport,
+  type ManagerRunner,
+  type NodeServiceControl,
+  type NodeServicesPlan,
+} from "../bootstrap/adapters/node-services/index.ts"
+import { createOpencodeHarness, type Download, type ProcessRunner } from "../bootstrap/adapters/opencode/index.ts"
+import type { ReadinessGate } from "../bootstrap/adapters/readiness.ts"
+import { discover } from "../bootstrap/discovery/discover.ts"
+import { pathDirs, which } from "../bootstrap/discovery/executables.ts"
+import type { DiscoveryProbe } from "../bootstrap/discovery/probe.ts"
+import { machineEnroll, type EnrollPrompt } from "../bootstrap/enrollment/enroll.ts"
+import type { ConfigCredentialStore } from "../bootstrap/enrollment/store.ts"
+import type { PlanSources } from "../bootstrap/preview/plan.ts"
+import { installedHarnesses, installedServiceUnits, rollbackHistory, type TransactionRecord } from "../bootstrap/profiles/history.ts"
+import { planProfileChange } from "../bootstrap/profiles/upgrade.ts"
+import { builtinExecutors, type HarnessSource, type HubctlSource } from "../bootstrap/transaction/builtin.ts"
+import { createApplier, type Applier } from "../bootstrap/transaction/engine.ts"
+import type { ActionExecutor, ExecutorMap } from "../bootstrap/transaction/executor.ts"
+import { nodeFs, type TxFs } from "../bootstrap/transaction/fs.ts"
+import { fileDigest } from "../bootstrap/transaction/stream.ts"
+import { txFail, txOk } from "../bootstrap/transaction/result.ts"
+import { TxStore } from "../bootstrap/transaction/store.ts"
+import { checkOpenShell } from "../openshell.ts"
+import { enrollmentContributor, harnessLinkContributor, HUBCTL_REF, hubctlContributor, refusing, type InstalledInspector, type PathInspector } from "./contributors.ts"
+import { dispatchByHarness, dispatchHarnessSource } from "./dispatch.ts"
+import { claudeSpokeProbes, codexSpokeStatus, opencodeSpokeProbe, type PresenceOptions } from "./spoke-probe.ts"
+import type { BootstrapState, SetupChoices } from "./state.ts"
+
+/** The capabilities that reach outside, replaced in tests. Production defaults are the adapters' own. */
+export interface RuntimePorts {
+  readonly opencodeRunner?: ProcessRunner
+  readonly opencodeDownload?: Download
+  readonly claudeRunner?: ClaudeProbeRunner
+  readonly codexRunner?: CodexProbeRunner
+  readonly codexAppServer?: AppServerLauncher
+  /** The service manager's fixed-call runner (default: launchctl / systemctl --user, spawned without a shell). */
+  readonly serviceRunner?: ManagerRunner
+  /** The bounded verification launch (launch-session); without one a planned launch is refused at preflight. */
+  readonly launchDriver?: LaunchDriver
+  /** The bytes of this hubctl (install-artifact copies the running, digest-checked binary). */
+  readonly hubctlBytes?: () => Uint8Array | undefined
+  readonly fs?: TxFs
+  readonly uid?: number
+}
+
+export interface RuntimeDeps {
+  readonly env: Readonly<Record<string, string | undefined>>
+  readonly home: string
+  readonly now: () => number
+  readonly probe: DiscoveryProbe
+  /** How this process runs (programLayout of process.execPath and argv[1]). */
+  readonly layout: ProgramLayout
+  /** hubctl's own version (the app-server client version). */
+  readonly version: string
+  readonly manifest?: VerifiedManifest
+  readonly store: ConfigCredentialStore
+  readonly state: BootstrapState
+  readonly fetch?: typeof fetch
+  readonly signal?: AbortSignal
+  readonly stderr: (s: string) => void
+  readonly ports?: RuntimePorts
+}
+
+/** Everything one plan was made with: preview and apply build it from the same profile and choices. */
+export interface PlanBundle {
+  readonly sources: PlanSources
+  /** The node-services plan of the last planning run (its units are what install-service writes). */
+  readonly node: () => NodeServicesPlan | undefined
+  readonly history: readonly TransactionRecord[]
+}
+
+/** The consent and readiness choices apply makes (never part of the plan, so never part of its digest). */
+export interface ApplyChoices {
+  readonly allowDowngrade?: boolean
+  /**
+   * v1.2: fail (and roll back) unless every harness is ready (`--require-ready`). Without it a harness that only waits
+   * on the user (provider login, spoke) is committed as installed, not ready; an integrity failure still rolls back.
+   */
+  readonly requireReady?: boolean
+  /** Harnesses that must be ready regardless (the --verify-launch harness: the launch needs it). */
+  readonly strict?: readonly HarnessID[]
+  /** Sees each harness's classified readiness (the apply report). */
+  readonly onReadiness?: (readiness: HarnessReadiness) => void
+}
+
+/** The readiness gate of one harness's verify-harness step (contract v1.2): strict only when asked or launched. */
+export function readinessGate(consent: ApplyChoices, harness: HarnessID): ReadinessGate {
+  return { requireReady: consent.requireReady === true || (consent.strict ?? []).includes(harness), ...(consent.onReadiness ? { onReadiness: consent.onReadiness } : {}) }
+}
+
+export interface SetupRuntime {
+  readonly deps: RuntimeDeps
+  discover(): Result<DiscoverySnapshot>
+  plan(profile: Profile, choices: SetupChoices): Promise<PlanBundle>
+  executors(bundle: PlanBundle, snapshot: DiscoverySnapshot, consent: ApplyChoices): ExecutorMap
+  applier(snapshot: DiscoverySnapshot, executors: ExecutorMap): Applier
+  verify(harnesses: readonly HarnessID[]): Promise<HarnessVerification[]>
+  /** This host's transactions (oldest first), from the journals and their plans. */
+  history(snapshot: DiscoverySnapshot): TransactionRecord[]
+  /** The hubctl the services and MCP clients run: user-bin:hubctl when the plan installs it, else this process. */
+  serviceLayout(snapshot: DiscoverySnapshot): ProgramLayout
+}
+
+/**
+ * What the files a plan would write hold now, read-only through the applier's filesystem: a regular file's digest
+ * (in chunks; hubctl is ~105 MB) and whether a path is a symlink to a target, in the snapshot's execution context.
+ */
+export function installedInspector(snapshot: DiscoverySnapshot, fs: TxFs): InstalledInspector {
+  const where = (ref: PathRef) => {
+    const r = resolvePathRef(ref, snapshot.roots, executionContextOf(snapshot))
+    return r.ok ? r.value : undefined
+  }
+  return {
+    sha256: (ref) => {
+      const file = where(ref)
+      try {
+        return file && fs.lstat(file)?.kind === "file" ? fileDigest(fs, file) : undefined
+      } catch {
+        return undefined
+      }
+    },
+    linksTo: (ref, target) => {
+      const link = where(ref)
+      const to = where(target)
+      try {
+        return link !== undefined && to !== undefined && fs.lstat(link)?.kind === "symlink" && nodePath.resolve(nodePath.dirname(link), fs.readlink(link)) === to
+      } catch {
+        return false
+      }
+    },
+  }
+}
+
+/** Paths and PATH as the probe sees them (read-only), in the snapshot's execution context. */
+export function pathInspector(snapshot: DiscoverySnapshot, probe: DiscoveryProbe): PathInspector {
+  const where = (ref: PathRef) => {
+    const r = resolvePathRef(ref, snapshot.roots, executionContextOf(snapshot))
+    return r.ok ? r.value : undefined
+  }
+  return {
+    where,
+    entry: (ref) => {
+      const p = where(ref)
+      return p ? probe.lstat(p) : "missing"
+    },
+    linkTarget: (ref) => {
+      const p = where(ref)
+      if (!p || probe.lstat(p) !== "symlink") return undefined
+      const text = probe.readlink(p)
+      return text === undefined ? undefined : nodePath.resolve(nodePath.dirname(p), text)
+    },
+    onPath: (name) => which(probe, pathDirs(probe), name),
+  }
+}
+
+/** A manifest that pins nothing (no --manifest): Codex is then only verified, never installed. */
+const NO_PINS = { release: "0.0.0", harnesses: [], artifacts: [] } as unknown as VerifiedManifest
+
+export function createSetupRuntime(deps: RuntimeDeps): SetupRuntime {
+  const ports = deps.ports ?? {}
+  const fs = ports.fs ?? nodeFs
+  let snapshot: DiscoverySnapshot | undefined
+  const context = (): AdapterContext => ({ env: deps.env, home: deps.home, platform: deps.probe.platform, arch: deps.probe.arch, now: deps.now, ...(deps.signal ? { signal: deps.signal } : {}) })
+  const presence: PresenceOptions = { credential: () => deps.store.read(), ...(deps.fetch ? { fetch: deps.fetch } : {}), ...(deps.signal ? { signal: deps.signal } : {}) }
+  const floors = deps.state.floors
+
+  const fresh = (): Result<DiscoverySnapshot> => {
+    const r = discover(deps.probe, { now: deps.now() })
+    if (r.ok) snapshot = r.value
+    return r
+  }
+
+  function history(snap: DiscoverySnapshot): TransactionRecord[] {
+    try {
+      const store = new TxStore(fs, snap.roots, executionContextOf(snap))
+      const journals = store.journals()
+      const plans = journals.flatMap((j) => store.readPlan(j) ?? [])
+      const r = rollbackHistory(journals, { hostFingerprint: snap.host.fingerprint, plans })
+      return r.ok ? r.value : []
+    } catch {
+      return []
+    }
+  }
+
+  function adapters(installed: ReturnType<typeof installedHarnesses>, allowDowngrade: boolean) {
+    const manifest = deps.manifest
+    const prior = (h: HarnessID) => (installed[h] ? { version: installed[h]!.version, sha256: installed[h]!.sha256 } : undefined)
+    const opencode = createOpencodeHarness({
+      probe: deps.probe,
+      ...(manifest ? { manifest } : {}),
+      ...(ports.opencodeRunner ? { runner: ports.opencodeRunner } : {}),
+      ...(ports.opencodeDownload ? { download: ports.opencodeDownload } : {}),
+      spoke: opencodeSpokeProbe(presence),
+      installed: () => prior("opencode"),
+      floor: () => floors.harnesses.opencode,
+      allowDowngrade,
+    })
+    const claudeRunner = ports.claudeRunner ?? claudeNodeRunner()
+    const claudePrior = prior("claude-code")
+    const claudeFloor = floors.harnesses["claude-code"]
+    const claude = createClaudeAdapter({
+      ...(manifest ? { manifest } : {}),
+      ...(claudePrior ? { installed: claudePrior } : {}),
+      ...(claudeFloor ? { floor: claudeFloor } : {}),
+      allowDowngrade,
+      probe: deps.probe,
+      probes: { runner: claudeRunner, ...claudeSpokeProbes(presence) },
+    })
+    const codexPrior = prior("codex")
+    const codex = createCodexAdapter({
+      manifest: manifest ?? NO_PINS,
+      probes: { runner: ports.codexRunner ?? codexNodeRunner, appServer: ports.codexAppServer ?? stdioAppServerLauncher(), spoke: codexSpokeStatus(presence), clientVersion: deps.version },
+      snapshot: () => snapshot,
+      ...(codexPrior ? { previous: codexPrior } : {}),
+    })
+    const sources: Partial<Record<HarnessID, HarnessSource>> = {}
+    if (manifest) {
+      if (opencode.source) sources.opencode = opencode.source
+      sources["claude-code"] = createClaudeHarnessSource({
+        manifest,
+        download: claudeDownloader(),
+        runner: claudeRunner,
+        scratch: tempScratch(),
+        platform: deps.probe.platform,
+        ...(claudePrior ? { installed: claudePrior } : {}),
+        ...(claudeFloor ? { floor: claudeFloor } : {}),
+        allowDowngrade,
+      })
+      sources.codex = createCodexHarnessSource({ manifest, download: codexDownloader(), installed: () => prior("codex"), floor: () => floors.harnesses.codex, allowDowngrade })
+    }
+    return { opencode, claude, codex, sources }
+  }
+
+  function serviceLayout(snap: DiscoverySnapshot): ProgramLayout {
+    const root = snap.roots.find((r) => r.id === "user-bin")
+    const installs = deps.manifest?.artifacts.some((a) => a.target === snap.host.target)
+    if (root && installs) return { kind: "standalone", executable: `${rootPathIn(root, executionContextOf(snap))}/${HUBCTL_REF.rel}` }
+    return deps.layout
+  }
+
+  async function plan(profile: Profile, choices: SetupChoices): Promise<PlanBundle> {
+    const snap = snapshot ?? (fresh().ok ? snapshot : undefined)
+    const records = snap ? history(snap) : []
+    const { opencode, claude, codex } = adapters(installedHarnesses(records), choices.allowDowngrade === true)
+    const registry = createAdapterRegistry()
+    for (const a of [opencode.adapter, claude, codex] as HarnessAdapter[]) registry.register(a)
+    let enrolledWith: string | undefined
+    try {
+      enrolledWith = (await deps.store.read())?.server
+    } catch {}
+    let nodePlan: NodeServicesPlan | undefined
+    const contributors = [
+      hubctlContributor({ ...(deps.manifest ? { manifest: deps.manifest } : {}), ...(snap ? { installed: installedInspector(snap, fs) } : {}) }),
+      refusing((input) => {
+        const planned = planNodeServices(input, {
+          layout: serviceLayout(input.snapshot),
+          ...(choices.node ? { node: choices.node } : {}),
+          ...(choices.activate ? { activate: true } : {}),
+          environment: deps.env,
+          ...(choices.launch ? { launch: choices.launch } : {}),
+        })
+        if (!planned.ok) return planned
+        nodePlan = planned.value
+        return ok(planned.value.actions)
+      }),
+      refusing((input) => {
+        const before = deps.state.profile
+        if (!before) return ok([])
+        const manager = input.snapshot.managers.service
+        const services = manager === "none" ? undefined : { manager: manager as ServiceManagerID, installed: installedServiceUnits(records, manager as ServiceManagerID) }
+        const change = planProfileChange(before, input.profile, { allowDowngrade: choices.allowDowngrade === true, ...(services ? { services } : {}) })
+        return change.ok ? ok(change.value.actions) : change
+      }),
+      ...(snap ? [harnessLinkContributor(pathInspector(snap, deps.probe))] : []),
+      enrollmentContributor({ ...(choices.server ? { server: choices.server } : {}), machineName: choices.machineName ?? "machine", enrolledWith }),
+    ]
+    return { sources: { adapters: registry, contributors, ...(choices.enrollment ? { enrollment: choices.enrollment } : {}) }, node: () => nodePlan, history: records }
+  }
+
+  function control(snap: DiscoverySnapshot): NodeServiceControl | undefined {
+    if (snap.managers.service === "none") return undefined
+    let run = ports.serviceRunner
+    if (!run) {
+      const systemctl = which(deps.probe, [...pathDirs(deps.probe), "/usr/bin", "/bin"], "systemctl") ?? "/usr/bin/systemctl"
+      run = spawnManagerRunner({ programs: { launchctl: "/bin/launchctl", systemctl }, env: deps.env })
+    }
+    return createServiceControl({ run, uid: ports.uid ?? deps.probe.uid, unitPath: unitPathResolver(snap.roots, executionContextOf(snap)) })
+  }
+
+  function hubctlSource(): HubctlSource | undefined {
+    const manifest = deps.manifest
+    if (!manifest) return undefined
+    return {
+      manifest,
+      fetch: async () => {
+        const bytes = ports.hubctlBytes?.()
+        if (bytes) return bytes
+        // The standalone executable itself (~105 MB): the executor digests it and the engine copies it in chunks,
+        // checking the digest again while it copies; it is never read whole.
+        if (deps.layout.kind === "standalone") return { path: realpathSync(deps.layout.executable) }
+        throw new Error("this hubctl is not the standalone release binary; run the hubctl you downloaded from the release to install it")
+      },
+      ...(floors.hubctl ? { floor: floors.hubctl } : {}),
+    }
+  }
+
+  function enrollExecutor(): ActionExecutor<"enroll-machine"> {
+    const ref: PathRef = { root: "config", rel: "hub/config.json" }
+    return {
+      kind: "enroll-machine",
+      plan: () => ({ class: "credential", path: ref }),
+      check: async (_action, ctx) =>
+        ctx.target === deps.store.location ? txOk(undefined) : txFail("usage", `the machine credential lives in ${deps.store.location} (HUB_SPOKE_CONFIG); enroll it separately with hubctl machine enroll`),
+      change: async (action) =>
+        txOk({
+          type: "effect",
+          perform: async () => {
+            const r = await machineEnroll({
+              server: action.server,
+              machineName: action.machineName,
+              store: deps.store,
+              ...(deps.fetch ? { fetch: deps.fetch } : {}),
+              ...(deps.signal ? { signal: deps.signal } : {}),
+              onPrompt: (p: EnrollPrompt) => deps.stderr(enrollPromptText(p)),
+            })
+            return r.envelope.ok ? txOk(undefined) : txFail(r.envelope.error!.code, r.envelope.error!.message)
+          },
+        }),
+      undo: async () => {
+        try {
+          await deps.store.clear()
+          return txOk(undefined)
+        } catch (error) {
+          return txFail("internal", (error as Error).message)
+        }
+      },
+    }
+  }
+
+  const verifyRuntime: ActionExecutor<"verify-runtime"> = {
+    kind: "verify-runtime",
+    plan: () => ({ class: "external" }),
+    change: async () =>
+      txOk({
+        type: "effect",
+        perform: async () => {
+          const report = await checkOpenShell({ env: deps.env as Record<string, string | undefined>, home: deps.home })
+          return report.ok ? txOk(undefined) : txFail("harness_not_ready", "OpenShell is not ready (`hubctl node openshell check` shows why)")
+        },
+      }),
+  }
+
+  function executors(bundle: PlanBundle, snap: DiscoverySnapshot, consent: ApplyChoices): ExecutorMap {
+    const allowDowngrade = consent.allowDowngrade === true
+    const gate = (h: HarnessID) => readinessGate(consent, h)
+    const { opencode, claude, codex, sources } = adapters(installedHarnesses(bundle.history), allowDowngrade)
+    const services = control(snap)
+    const hubctl = hubctlSource()
+    const builtin = builtinExecutors({
+      // Lazy: the node plan exists once apply's re-plan ran the contributor; only its exact units are written.
+      renderService: (action) => {
+        const node = bundle.node()
+        return node ? serviceAssets(node).renderService(action) : undefined
+      },
+      ...(services ? { services } : {}),
+      ...(hubctl ? { hubctl } : {}),
+      ...(deps.manifest ? { harness: dispatchHarnessSource({ manifest: deps.manifest, sources, allowDowngrade }) } : {}),
+    })
+    const oc = opencode.executors(context, gate("opencode"))
+    const launchProbe = ports.launchDriver ? { driver: ports.launchDriver, ...(deps.signal ? { signal: deps.signal } : {}), onReport: (r: LaunchReport) => deps.stderr(launchReportText(r)) } : undefined
+    return {
+      ...builtin,
+      ...nodeServiceExecutors({ ...(services ? { control: services } : {}), ...(launchProbe ? { probe: launchProbe } : {}) }),
+      "register-mcp-server": dispatchByHarness("register-mcp-server", { opencode: oc["register-mcp-server"]! }),
+      "verify-harness": dispatchByHarness("verify-harness", {
+        opencode: oc["verify-harness"]!,
+        "claude-code": claudeVerifyExecutor({ verify: () => claude.verify(context()), now: deps.now, ...gate("claude-code") }),
+        codex: codexVerifyExecutor({ verify: (ctx) => codex.verify(ctx), context, ...gate("codex") }),
+      }),
+      "enroll-machine": enrollExecutor(),
+      "verify-runtime": verifyRuntime,
+    }
+  }
+
+  function applier(snap: DiscoverySnapshot, map: ExecutorMap): Applier {
+    return createApplier({ roots: snap.roots, context: executionContextOf(snap), host: { fingerprint: snap.host.fingerprint, target: snap.host.target }, executors: map, fs, now: deps.now, keepBackups: true })
+  }
+
+  async function verify(harnesses: readonly HarnessID[]): Promise<HarnessVerification[]> {
+    const snap = fresh()
+    const { opencode, claude, codex } = adapters(snap.ok ? installedHarnesses(history(snap.value)) : {}, false)
+    const by: Record<HarnessID, HarnessAdapter> = { opencode: opencode.adapter, "claude-code": claude, codex }
+    const out: HarnessVerification[] = []
+    for (const id of HARNESS_ORDER) if (harnesses.includes(id)) out.push(await by[id].verify(context()))
+    return out
+  }
+
+  return { deps, discover: fresh, plan, executors, applier, verify, history, serviceLayout }
+}
+
+/** What `machine enroll` (and an inline enrollment) shows while it waits; never a credential. */
+export function enrollPromptText(p: EnrollPrompt): string {
+  if (p.autoApproved) return "hubctl: the local hub approved this machine by itself\n"
+  return `hubctl: approve this machine on the hub: ${p.approveURL}\nhubctl: and check it shows the code ${p.userCode} (it expires at ${new Date(p.expiresAt).toISOString()})\n${p.warning ? `hubctl: warning: ${p.warning}\n` : ""}`
+}
+
+export function launchReportText(r: LaunchReport): string {
+  return `${r.stages.map((s) => `hubctl: verification launch, ${s.stage}: ${s.ok ? "ok" : "failed"}${s.detail ? ` (${s.detail})` : ""}`).join("\n")}\n`
+}

package/packages/cli/src/setup/spoke-probe.ts

@@ -0,0 +1,120 @@
+// spoke-connected readiness (HBS-13 integration item 6): whether the hub sees a harness's spoke of this machine.
+// One read-only GET /spoke/presence with the machine credential (src/central/http.ts spokePresence), under the
+// enrollment policy: https, or plain http to a loopback hub only (checkServerURL); never across a redirect, never to
+// an insecure stored hub, and nothing at all without a stored credential. The answer lists only the harness, the
+// evidence level and the features of each connected spoke; details never carry the token.
+import type { MachineCredential } from "../bootstrap/contracts/index.ts"
+import type { SpokeHello } from "../bootstrap/adapters/claude/verify.ts"
+import type { SpokeStatus } from "../bootstrap/adapters/codex/verify.ts"
+import type { SpokeProbe } from "../bootstrap/adapters/opencode/verify.ts"
+import { checkServerURL } from "../bootstrap/enrollment/policy.ts"
+
+export interface ConnectedSpoke {
+  readonly harness: string
+  readonly evidence: string
+  readonly features: readonly string[]
+}
+
+export type Presence = { readonly ok: true; readonly spokes: readonly ConnectedSpoke[] } | { readonly ok: false; readonly detail: string }
+
+export interface PresenceOptions {
+  /** The stored machine credential (CredentialStore.read). */
+  readonly credential: () => Promise<MachineCredential | undefined>
+  readonly fetch?: typeof fetch
+  readonly timeoutMs?: number
+  readonly signal?: AbortSignal
+}
+
+const TIMEOUT_MS = 10_000
+const word = /^[A-Za-z0-9._-]{1,64}$/
+
+function parse(body: unknown): readonly ConnectedSpoke[] | undefined {
+  const spokes = (body as { spokes?: unknown } | null)?.spokes
+  if (!Array.isArray(spokes)) return undefined
+  const out: ConnectedSpoke[] = []
+  for (const s of spokes) {
+    const { harness, evidence, features } = (s ?? {}) as Record<string, unknown>
+    if (typeof harness !== "string" || !word.test(harness) || typeof evidence !== "string" || !word.test(evidence)) return undefined
+    const list = Array.isArray(features) ? features.filter((f): f is string => typeof f === "string" && word.test(f)) : []
+    out.push({ harness, evidence, features: list })
+  }
+  return out
+}
+
+/** The hub's answer to "which spokes of this machine are connected?". */
+export async function spokePresence(options: PresenceOptions): Promise<Presence> {
+  let credential: MachineCredential | undefined
+  try {
+    credential = await options.credential()
+  } catch {
+    return { ok: false, detail: "the machine credential store cannot be read" }
+  }
+  if (!credential) return { ok: false, detail: "this machine is not enrolled (run `hubctl machine enroll`)" }
+  const server = checkServerURL(credential.server)
+  if (!server) return { ok: false, detail: "the stored hub URL is not https (plain http only on loopback), so the hub was not asked" }
+  const signals = [AbortSignal.timeout(options.timeoutMs ?? TIMEOUT_MS), ...(options.signal ? [options.signal] : [])]
+  let response: Response
+  try {
+    response = await (options.fetch ?? fetch)(`${server}/spoke/presence`, { method: "GET", headers: { authorization: `Bearer ${credential.token}` }, redirect: "manual", signal: AbortSignal.any(signals) })
+  } catch (cause) {
+    return { ok: false, detail: `could not reach ${server} (${(cause as { name?: string })?.name ?? "error"})` }
+  }
+  if (response.status !== 200) {
+    void response.body?.cancel().catch(() => {})
+    if (response.status === 401 || response.status === 403) return { ok: false, detail: `${server} rejected the machine credential (revoked or unknown)` }
+    if (response.status === 404) return { ok: false, detail: `${server} does not answer spoke presence queries (an older hub)` }
+    return { ok: false, detail: `${server} could not answer (HTTP ${response.status})` }
+  }
+  let body: unknown
+  try {
+    body = await response.json()
+  } catch {
+    return { ok: false, detail: `${server} sent an invalid presence answer` }
+  }
+  const spokes = parse(body)
+  return spokes ? { ok: true, spokes } : { ok: false, detail: `${server} sent an invalid presence answer` }
+}
+
+const LABEL: Readonly<Record<string, string>> = { opencode: "OpenCode", "claude-code": "Claude Code", codex: "Codex" }
+
+async function find(options: PresenceOptions, harness: string): Promise<{ readonly spoke?: ConnectedSpoke; readonly detail: string }> {
+  const p = await spokePresence(options)
+  if (!p.ok) return { detail: p.detail }
+  const spoke = p.spokes.find((s) => s.harness === harness)
+  return spoke ? { spoke, detail: `the hub sees this machine's ${LABEL[harness]} spoke (${spoke.evidence})` } : { detail: `the hub does not see this machine's ${LABEL[harness]} spoke connected` }
+}
+
+/** OpenCode's SpokeProbe. */
+export function opencodeSpokeProbe(options: PresenceOptions): SpokeProbe {
+  return {
+    async connected() {
+      const r = await find(options, "opencode")
+      return { ok: r.spoke !== undefined, detail: r.detail }
+    },
+  }
+}
+
+/** The Claude Code adapter's spoke and conformance probes: the hooks spoke must be connected as a hooks spoke. */
+export function claudeSpokeProbes(options: PresenceOptions): { spoke(): Promise<SpokeHello>; conformance(): Promise<{ readonly ok: boolean; readonly detail?: string }> } {
+  return {
+    async spoke() {
+      const r = await find(options, "claude-code")
+      return r.spoke ? { connected: true, harness: r.spoke.harness, evidence: r.spoke.evidence, features: r.spoke.features } : { connected: false }
+    },
+    async conformance() {
+      const r = await find(options, "claude-code")
+      if (!r.spoke) return { ok: false, detail: r.detail }
+      return r.spoke.evidence === "hooks" ? { ok: true, detail: "connected as a hooks spoke" } : { ok: false, detail: `the Claude Code spoke reports ${r.spoke.evidence} evidence, not hooks` }
+    },
+  }
+}
+
+/** The Codex adapter's SpokeStatus. */
+export function codexSpokeStatus(options: PresenceOptions): SpokeStatus {
+  return {
+    async codex() {
+      const r = await find(options, "codex")
+      return { connected: r.spoke !== undefined, detail: r.detail }
+    },
+  }
+}