@huynle/hub 0.7.1 → 0.7.3

package/packages/cli/src/bootstrap/preview/links.ts

@@ -0,0 +1,31 @@
+// Symlink facts for the paths a plan would write, read through the probe (lstat and realpath only).
+import { executionContextOf, rootPathIn, type DiscoverySnapshot } from "../contracts/index.ts"
+import type { DiscoveryProbe } from "../discovery/probe.ts"
+import { join, normalizeAbs } from "../discovery/util.ts"
+import type { LinkInspector } from "./plan.ts"
+
+/** Link facts read through the probe (lstat/realpath only), against each root as this hubctl sees it (v1.1 rootPathIn). */
+export function inspectLinks(probe: DiscoveryProbe, snapshot: DiscoverySnapshot): LinkInspector {
+  const context = executionContextOf(snapshot)
+  return (ref) => {
+    const root = snapshot.roots.find((r) => r.id === ref.root)
+    if (!root) return undefined
+    const base = rootPathIn(root, context)
+    const parts = ref.rel.split("/")
+    let current = base
+    for (let i = 0; i < parts.length; i++) {
+      current = join(current, parts[i]!)
+      const kind = probe.lstat(current)
+      if (kind === "missing") return undefined
+      if (kind !== "symlink") continue
+      // The edit belongs in the file the link leads to: the deepest existing part, resolved, plus the rest.
+      const rest = parts.slice(i + 1)
+      for (let k = rest.length; k >= 0; k--) {
+        const real = normalizeAbs(probe.realpath([current, ...rest.slice(0, k)].join("/")))
+        if (real) return { linkPath: current, resolvedPath: [real, ...rest.slice(k)].join("/").replace(/^\/\//, "/") }
+      }
+      return { linkPath: current, resolvedPath: [current, ...rest].join("/") }
+    }
+    return undefined
+  }
+}

package/packages/cli/src/bootstrap/preview/plan.ts

@@ -0,0 +1,242 @@
+// planSetup: a pure function of (snapshot, profile, link facts, planners), with no clock and no randomness, so
+// the same host and choices always give the same plan and planDigest. Harness adapters and other contributors
+// propose typed actions; planSetup adds the steps every plan needs (the state directory, real verification of
+// every chosen harness, opt-in runtime checks), drops exact duplicates, refuses conflicting ones, never implies
+// escalation, puts the actions in dependency order, and replaces any config write behind a symlink with a
+// ManualEdit blocker (decision Q8). Writes that cannot become a manual edit are refused.
+//
+// v1.1: the snapshot digest is the contract's snapshotDigest; `enrollment: "separate"` (from the caller or the
+// profile) leaves enroll-machine out, so the direct and Ansible paths plan the same digest; a merge into a format
+// hubctl cannot edit losslessly (TOML) becomes an unmergeable-format ManualEdit for the file in this execution
+// context; refusals use escalation_required and no_service_manager.
+import {
+  actionPaths,
+  canonicalJSON,
+  checkTarget,
+  enrollmentModeOf,
+  executionContextOf,
+  fail,
+  HARNESS_ORDER,
+  manualEditFor,
+  ok,
+  REQUIRED_PROBES,
+  resolvePathRef,
+  snapshotDigest,
+  unmergeableEditFor,
+  validateAction,
+  validateDiscoverySnapshot,
+  validateProfile,
+  validateSetupPlan,
+  type Action,
+  type ActionKind,
+  type AdapterRegistry,
+  type DiscoverySnapshot,
+  type EnrollmentMode,
+  type HarnessID,
+  type Issue,
+  type ManualEdit,
+  type PathRef,
+  type PlanInput,
+  type PreviewEvidence,
+  type Profile,
+  type Result,
+  type SetupPlan,
+} from "../contracts/index.ts"
+
+/** What a contributor plans from: the adapters' input, and the actions planned before it (adapters first). */
+export type ContributorInput = PlanInput & { readonly planned?: readonly Action[] }
+
+/** Proposes actions for a plan; must be deterministic in its input (like HarnessAdapter.plan). */
+export type PlanContributor = (input: ContributorInput) => readonly Action[]
+
+/** A symlink found between a root and a path the plan would write. */
+export interface LinkFact {
+  readonly linkPath: string
+  /** Where the target really is (the file the edit belongs in). */
+  readonly resolvedPath: string
+}
+
+/** The first symlink under the root on the way to `ref`, if any. */
+export type LinkInspector = (ref: PathRef) => LinkFact | undefined
+
+export interface PlanSources {
+  /** Harness adapters; each chosen harness's adapter plans for it, in HARNESS_ORDER. */
+  readonly adapters?: AdapterRegistry
+  /** Further planners (services, enrollment, launches), after the adapters. */
+  readonly contributors?: readonly PlanContributor[]
+  /**
+   * v1.1: "separate" leaves enroll-machine out of the plan (the machine is enrolled by its own `hubctl machine
+   * enroll`); default: the profile's enrollment mode, else "inline". Apply must re-plan with the same option.
+   */
+  readonly enrollment?: EnrollmentMode
+}
+
+export interface PlannedSetup {
+  readonly plan: SetupPlan
+  readonly blockers: readonly ManualEdit[]
+  readonly evidence: readonly PreviewEvidence[]
+}
+
+/** The contract's canonical snapshot digest (v1.1: defined once, in contracts/discovery.ts), re-exported. */
+export { snapshotDigest }
+
+/** Execution phases: each action kind runs after everything it depends on. */
+const PHASE: Readonly<Record<ActionKind, number>> = {
+  "ensure-directory": 0,
+  "install-artifact": 1,
+  "link-executable": 2,
+  "install-harness": 3,
+  // v1.1: a freshly installed version is made current right after it is installed (and before it is verified).
+  "select-harness-version": 3.5,
+  "write-file": 4,
+  "merge-config": 4,
+  "register-mcp-server": 4,
+  // v1.1: a removed component's service is unloaded, then its unit removed, before new services are installed.
+  "deactivate-service": 4.8,
+  "remove-service": 4.9,
+  "install-service": 5,
+  "enroll-machine": 6,
+  "verify-harness": 7,
+  "verify-runtime": 8,
+  "activate-service": 9,
+  "launch-session": 10,
+}
+
+const HARNESS_LABEL: Readonly<Record<HarnessID, string>> = { opencode: "OpenCode", "claude-code": "Claude Code", codex: "Codex" }
+
+/**
+ * The bootstrap state a committed apply writes (setup/state.ts). Its presence means the state directory exists, so a
+ * rerun leaves state-dir out. Taking the apply lock creates the directory but not this file, so the preview and
+ * apply's locked re-plan agree on a fresh host.
+ */
+export const APPLIED_STATE: PathRef = { root: "state", rel: "hub/bootstrap/state.json" }
+
+const STATE_DIR: Action = { id: "state-dir", kind: "ensure-directory", escalation: "user", summary: "Create the hub state directory", path: { root: "state", rel: "hub" }, mode: 0o700 }
+
+const verifyHarness = (harness: HarnessID): Action => ({
+  id: `verify-${harness}`,
+  kind: "verify-harness",
+  escalation: "user",
+  summary: `Verify ${HARNESS_LABEL[harness]} really runs, reaches its provider and connects to the hub`,
+  harness,
+  probes: REQUIRED_PROBES[harness].filter((p): p is Exclude<typeof p, "presence"> => p !== "presence"),
+})
+
+/** link-executable and select-harness-version replace their own final symlink atomically: it is not written through. */
+const replacesFinalLink = (action: Action) => action.kind === "link-executable" || action.kind === "select-harness-version"
+const parentOf = (ref: PathRef): PathRef | undefined => (ref.rel.includes("/") ? { root: ref.root, rel: ref.rel.slice(0, ref.rel.lastIndexOf("/")) } : undefined)
+
+export const issuesAt = (prefix: string, r: Result<unknown>): Issue[] => (r.ok ? [] : r.issues.map((i) => ({ ...i, path: `${prefix}${i.path}` })))
+const failed = <T>(issues: readonly Issue[]): Result<T> => ({ ok: false, issues: [...issues] })
+
+/** Plans a setup. Pure: the same inputs always give the same plan. */
+export function planSetup(
+  input: {
+    readonly snapshot: DiscoverySnapshot
+    readonly profile: Profile
+    readonly links: LinkInspector
+    /** Whether a regular file exists at a path (read-only; preview passes the probe's). */
+    readonly fileExists?: (ref: PathRef) => boolean
+  } & PlanSources,
+): Result<PlannedSetup> {
+  const snap = validateDiscoverySnapshot(input.snapshot)
+  const prof = validateProfile(input.profile)
+  if (!snap.ok || !prof.ok) return failed([...issuesAt("/snapshot", snap), ...issuesAt("/profile", prof)])
+  const snapshot = snap.value
+  const profile = prof.value
+  const target = checkTarget(snapshot.host.target)
+  if (!target.ok || !snapshot.host.supported) return failed(issuesAt("/snapshot/host/target", target.ok ? fail("", "unsupported_platform", "unsupported host") : target))
+  if (profile.services.length > 0 && snapshot.managers.service === "none")
+    return fail("/profile/services", "no_service_manager", `the ${profile.id} profile installs services, but this host has no user service manager (launchd or systemd --user)`)
+
+  // Collect: the state dir, then each chosen harness's adapter actions, then the other contributors.
+  const planInput: PlanInput = { snapshot, profile }
+  const groups: Action[][] = [input.fileExists?.(APPLIED_STATE) ? [] : [STATE_DIR]]
+  const harnessGroup = new Map<HarnessID, Action[]>()
+  for (const id of HARNESS_ORDER) {
+    if (!profile.harnesses.includes(id)) continue
+    const group = [...(input.adapters?.get(id)?.plan(planInput) ?? [])]
+    harnessGroup.set(id, group)
+    groups.push(group)
+  }
+  for (const contribute of input.contributors ?? []) groups.push([...contribute({ ...planInput, planned: groups.flat() })])
+  // v1.1: a separate enrollment is its own step; the plan never enrolls.
+  if ((input.enrollment ?? enrollmentModeOf(profile)) === "separate") for (const group of groups) group.splice(0, group.length, ...group.filter((a) => a.kind !== "enroll-machine"))
+  // Every chosen harness is verified by real probes (presence is never readiness); runtimes are checked, never installed.
+  const all = () => groups.flat()
+  for (const [id, group] of harnessGroup) if (!all().some((a) => a.kind === "verify-harness" && a.harness === id)) group.push(verifyHarness(id))
+  groups.push(profile.runtimes.map((runtime) => ({ id: `verify-${runtime}`, kind: "verify-runtime", escalation: "user", summary: `Check ${runtime} (opt-in)`, runtime }) as Action))
+
+  // Validate every proposed action; drop exact duplicates, refuse conflicting ones.
+  const issues: Issue[] = []
+  const byID = new Map<string, Action>()
+  const actions: Action[] = []
+  all().forEach((action, i) => {
+    const checked = validateAction(action)
+    if (!checked.ok) return void issues.push(...issuesAt(`/actions/${i}`, checked))
+    const seen = byID.get(action.id)
+    if (seen) {
+      if (canonicalJSON(seen) !== canonicalJSON(action)) issues.push({ path: `/actions/${i}/id`, code: "duplicate", message: `two different actions are both named ${action.id}` })
+      return
+    }
+    byID.set(action.id, action)
+    actions.push(action)
+  })
+  if (issues.length > 0) return failed(issues)
+
+  // Escalation is never implied; services must have their manager's root; writes never go through a symlink.
+  const blockers: ManualEdit[] = []
+  const kept: Action[] = []
+  for (const action of actions) {
+    if (action.escalation === "elevated" && profile.escalation !== "explicit") {
+      issues.push({ path: `/actions/${action.id}`, code: "escalation_required", message: `${action.id} needs escalation, which the ${profile.id} profile never allows` })
+      continue
+    }
+    const unmapped = actionPaths(action).find((ref) => !snapshot.roots.some((r) => r.id === ref.root))
+    if (unmapped) {
+      issues.push({ path: `/actions/${action.id}`, code: "unmapped_root", message: `this host has no ${unmapped.root} root` })
+      continue
+    }
+    const link = "path" in action ? input.links(replacesFinalLink(action) ? parentOf(action.path) ?? action.path : action.path) : undefined
+    if (replacesFinalLink(action) && !parentOf(action.path)) {
+      // A link directly in its root: only the root itself could be a link (the applier refuses that), not the
+      // link the action replaces.
+      kept.push(action)
+      continue
+    }
+    if (!link && action.kind === "merge-config" && action.format === "toml") {
+      // v1.1: hubctl cannot edit TOML losslessly; the user gets the exact edit for the file as this hubctl sees it.
+      const where = resolvePathRef(action.path, snapshot.roots, executionContextOf(snapshot))
+      const edit = where.ok ? unmergeableEditFor(action, where.value) : undefined
+      if (edit) blockers.push(edit)
+      else issues.push({ path: `/actions/${action.id}`, code: "unmapped_root", message: `this host has no ${action.path.root} root` })
+      continue
+    }
+    if (!link) {
+      kept.push(action)
+      continue
+    }
+    const edit = manualEditFor(action, link)
+    if (edit) blockers.push(edit)
+    else issues.push({ path: `/actions/${action.id}`, code: "symlink", message: `${link.linkPath} is a symbolic link; refusing to write through it` })
+  }
+  if (issues.length > 0) return failed(issues)
+
+  const ordered = kept.map((a, i) => ({ a, i })).sort((x, y) => PHASE[x.a.kind] - PHASE[y.a.kind] || x.i - y.i).map((x) => x.a)
+  const plan: SetupPlan = {
+    schema: "hub.setup-plan",
+    version: 1,
+    hostFingerprint: snapshot.host.fingerprint,
+    snapshotDigest: snapshotDigest(snapshot),
+    target: snapshot.host.target,
+    profile: { id: profile.id, version: profile.version },
+    requiresEscalation: ordered.some((a) => a.escalation === "elevated"),
+    activatesServices: ordered.some((a) => a.kind === "activate-service"),
+    actions: ordered,
+  }
+  const valid = validateSetupPlan(plan)
+  if (!valid.ok) return failed(issuesAt("/plan", valid))
+  // Upstream evidence for a pinned harness download is checked on the downloaded bytes, at apply.
+  const evidence: PreviewEvidence[] = ordered.flatMap((a) => (a.kind === "install-harness" ? a.evidence.map((kind) => ({ actionID: a.id, kind, status: "deferred" as const })) : []))
+  return ok({ plan, blockers, evidence })
+}

package/packages/cli/src/bootstrap/preview/preview.ts

@@ -0,0 +1,104 @@
+// Previews (`hubctl setup preview`) and their revalidation at apply time. previewSetup discovers the host, plans
+// (planSetup) and issues a preview token bound to the host fingerprint, the snapshot digest and the plan digest,
+// valid for at most 15 minutes, with a single-use nonce. revalidateApply never trusts that token: it rediscovers,
+// re-plans and compares (revalidatePreview), then refuses while a manual edit or failed evidence remains. Both only
+// read, through the probe.
+import {
+  executionContextOf,
+  fail,
+  ok,
+  planDigest,
+  PREVIEW_MAX_TTL_MS,
+  previewApplicable,
+  revalidatePreview,
+  validatePreviewToken,
+  validateSetupPreview,
+  resolvePathRef,
+  type DiscoverySnapshot,
+  type PathRef,
+  type PreviewToken,
+  type Profile,
+  type Result,
+  type SetupPreview,
+} from "../contracts/index.ts"
+import { discover } from "../discovery/discover.ts"
+import type { DiscoveryProbe } from "../discovery/probe.ts"
+import { inspectLinks } from "./links.ts"
+import { planSetup, type PlannedSetup, type PlanSources } from "./plan.ts"
+
+const randomNonce = (): string => {
+  const bytes = new Uint8Array(18)
+  crypto.getRandomValues(bytes)
+  return Buffer.from(bytes).toString("base64url")
+}
+
+export interface PreviewRequest extends PlanSources {
+  readonly probe: DiscoveryProbe
+  readonly profile: Profile
+  readonly now: number
+  /** Injected for tests; otherwise 18 random bytes, base64url. */
+  readonly nonce?: string
+  /** Token lifetime, at most (and by default) 15 minutes. */
+  readonly ttlMs?: number
+}
+
+function discoverAndPlan(probe: DiscoveryProbe, profile: Profile, now: number, sources: PlanSources): Result<{ snapshot: DiscoverySnapshot } & PlannedSetup> {
+  const snap = discover(probe, { now })
+  if (!snap.ok) return snap
+  const fileExists = (ref: PathRef) => {
+    const where = resolvePathRef(ref, snap.value.roots, executionContextOf(snap.value))
+    return where.ok && probe.lstat(where.value) === "file"
+  }
+  const planned = planSetup({ snapshot: snap.value, profile, links: inspectLinks(probe, snap.value), fileExists, adapters: sources.adapters, contributors: sources.contributors, enrollment: sources.enrollment })
+  return planned.ok ? ok({ snapshot: snap.value, ...planned.value }) : planned
+}
+
+/** Discovers, plans and issues a preview. Writes nothing. */
+export function previewSetup(request: PreviewRequest): Result<SetupPreview> {
+  const ttl = request.ttlMs ?? PREVIEW_MAX_TTL_MS
+  if (!Number.isInteger(ttl) || ttl <= 0 || ttl > PREVIEW_MAX_TTL_MS) return fail("/ttlMs", "invalid_value", `a preview lives 1 ms..${PREVIEW_MAX_TTL_MS / 60_000} minutes`)
+  const planned = discoverAndPlan(request.probe, request.profile, request.now, request)
+  if (!planned.ok) return planned
+  const { plan, blockers, evidence } = planned.value
+  const digest = planDigest(plan)
+  const token: PreviewToken = {
+    schema: "hub.preview-token",
+    version: 1,
+    planDigest: digest,
+    hostFingerprint: plan.hostFingerprint,
+    snapshotDigest: plan.snapshotDigest,
+    issuedAt: request.now,
+    expiresAt: request.now + ttl,
+    nonce: request.nonce ?? randomNonce(),
+  }
+  return validateSetupPreview({ schema: "hub.setup-preview", version: 1, plan, planDigest: digest, token, blockers, evidence })
+}
+
+export interface ApplyCheck extends PlanSources {
+  readonly token: unknown
+  readonly probe: DiscoveryProbe
+  readonly profile: Profile
+  readonly now: number
+  /** Nonces consumed by earlier applies (from the journals). */
+  readonly usedNonces: ReadonlySet<string>
+}
+
+/**
+ * Whether apply may run the previewed plan: rediscovers and re-plans now, then checks the token against the fresh
+ * host fingerprint, snapshot and plan (revalidatePreview), and refuses while a manual edit or failed evidence
+ * remains. On success, returns the freshly made plan (never one read back from the preview).
+ */
+export function revalidateApply(check: ApplyCheck): Result<{ readonly token: PreviewToken; readonly snapshot: DiscoverySnapshot } & PlannedSetup> {
+  const token = validatePreviewToken(check.token)
+  if (!token.ok) return token
+  const fresh = discoverAndPlan(check.probe, check.profile, check.now, check)
+  if (!fresh.ok) return fresh
+  const valid = revalidatePreview(token.value, { now: check.now, hostFingerprint: fresh.value.snapshot.host.fingerprint, plan: fresh.value.plan, usedNonces: check.usedNonces })
+  if (!valid.ok) return valid
+  const gate = previewApplicable({ schema: "hub.setup-preview", version: 1, plan: fresh.value.plan, planDigest: planDigest(fresh.value.plan), token: valid.value, blockers: fresh.value.blockers, evidence: fresh.value.evidence })
+  if (!gate.ok) return gate
+  return ok({ token: valid.value, ...fresh.value })
+}
+
+/** A preview document read back from disk or another process: validated, never cast. */
+export const parsePreview = (raw: unknown): Result<SetupPreview> => validateSetupPreview(raw)

package/packages/cli/src/bootstrap/preview/render.ts

@@ -0,0 +1,30 @@
+// The preview for people. Paths under the home directory are shown as ~/…; the token's nonce is never printed.
+import type { PathRef, SetupPreview } from "../contracts/index.ts"
+
+const tilde = (path: string, home?: string) => (home && (path === home || path.startsWith(`${home}/`)) ? `~${path.slice(home.length)}` : path)
+const ref = (r: PathRef) => `${r.root}:${r.rel}`
+
+/** The preview for people: the steps, the consents apply will ask for, and each manual edit with the file it belongs in. */
+export function renderPreview(preview: SetupPreview, home?: string): string[] {
+  const { plan } = preview
+  const lines = [`Setup plan for ${plan.target} (${plan.profile.id}), ${plan.actions.length} step(s):`]
+  plan.actions.forEach((a, i) => lines.push(`  ${i + 1}. ${a.summary}${a.escalation === "elevated" ? " [needs --escalate]" : ""}`))
+  if (plan.requiresEscalation) lines.push("Apply needs --escalate: some steps write system locations.")
+  if (plan.activatesServices) lines.push("Apply needs --confirm-activation: it loads user services.")
+  for (const e of preview.evidence) lines.push(`Evidence ${e.kind} for ${e.actionID}: ${e.status}`)
+  if (preview.blockers.length > 0) {
+    lines.push(`${preview.blockers.length} change(s) must be made by hand, because hubctl will not write the config itself:`)
+    for (const b of preview.blockers) {
+      const why = b.linkPath ? `linked from ${tilde(b.linkPath, home)}` : "hubctl cannot edit this format losslessly"
+      lines.push(`  - in ${tilde(b.resolvedPath, home)} (${why}, ${ref(b.path)}):`)
+      const c = b.change
+      if (c.op === "merge") for (const s of c.set) lines.push(`      set ${s.pointer} = ${JSON.stringify(s.value)}`)
+      else if (c.op === "register-mcp-server") lines.push(`      register the hub MCP server "${c.name}" for ${c.harness} (hubctl mcp)`)
+      else lines.push(`      write asset ${c.asset} (${c.sha256}, mode ${c.mode.toString(8)})`)
+    }
+    lines.push("Make these edits, then run the preview again.")
+  }
+  lines.push(`Plan ${preview.planDigest}; the preview expires at ${new Date(preview.token.expiresAt).toISOString()}.`)
+  return lines
+}
+

package/packages/cli/src/bootstrap/profiles/audit.ts

@@ -0,0 +1,87 @@
+// Audit-only verification. `hubctl setup verify` (or any check that must not change the machine) audits the host
+// against a profile: it reports each harness and runtime the profile names, and plans only read-only probe actions
+// (verify-harness, verify-runtime) for what is there. The plan is a valid contract SetupPlan, so the same applier
+// runs it; checkReadOnly lets that applier prove, before it starts, that an audit plan writes nothing.
+import {
+  Checker,
+  ok,
+  PLAN_SCHEMA,
+  PLAN_VERSION,
+  snapshotDigest,
+  validateSetupPlan,
+  type ActionKind,
+  type DiscoverySnapshot,
+  type Result,
+  type SetupPlan,
+  type VerifyHarness,
+  type VerifyRuntime,
+} from "../contracts/index.ts"
+import { desiredState, type DesiredState } from "./desired.ts"
+
+/** The only action kinds an audit may contain: probes that change nothing on disk or in the session manager. */
+export const READ_ONLY_KINDS: readonly ActionKind[] = Object.freeze(["verify-harness", "verify-runtime"])
+
+export interface AuditFinding {
+  /** "harness:<id>" or "runtime:<id>". */
+  readonly subject: string
+  /** missing: not installed (an audit never installs). unverified/verified/failed: discovery's health. present: a runtime found. */
+  readonly status: "missing" | "unverified" | "verified" | "failed" | "present"
+  readonly owner?: "hub" | "user"
+}
+
+export interface AuditReport {
+  readonly mode: "audit"
+  /** Always zero: an audit never writes. */
+  readonly writes: 0
+  readonly desired: DesiredState
+  /** Probe-only plan for this snapshot (checkReadOnly accepts it). */
+  readonly plan: SetupPlan
+  readonly findings: readonly AuditFinding[]
+}
+
+export function auditProfile(profile: unknown, snapshotDoc: unknown): Result<AuditReport> {
+  const desired = desiredState(profile, snapshotDoc)
+  if (!desired.ok) return desired
+  const snapshot = snapshotDoc as DiscoverySnapshot
+  const findings: AuditFinding[] = []
+  const actions: (VerifyHarness | VerifyRuntime)[] = []
+  for (const harness of desired.value.harnesses) {
+    const found = snapshot.harnesses.find((h) => h.id === harness.id)
+    if (harness.presence === "missing" || !found) {
+      findings.push({ subject: `harness:${harness.id}`, status: "missing", owner: harness.owner })
+      continue
+    }
+    findings.push({ subject: `harness:${harness.id}`, status: found.health.state, owner: harness.owner })
+    actions.push({ id: `audit-${harness.id}`, kind: "verify-harness", escalation: "user", summary: `Verify ${harness.id} (audit, read-only)`, harness: harness.id, probes: harness.verify })
+  }
+  for (const runtime of desired.value.runtimes) {
+    findings.push({ subject: `runtime:${runtime.id}`, status: "present" })
+    actions.push({ id: `audit-${runtime.id}`, kind: "verify-runtime", escalation: "user", summary: `Check ${runtime.id} (audit, read-only)`, runtime: runtime.id })
+  }
+  const plan: SetupPlan = {
+    schema: PLAN_SCHEMA,
+    version: PLAN_VERSION,
+    hostFingerprint: snapshot.host.fingerprint,
+    snapshotDigest: snapshotDigest(snapshot),
+    target: desired.value.target,
+    profile: desired.value.profile,
+    requiresEscalation: false,
+    activatesServices: false,
+    actions,
+  }
+  const checked = validateSetupPlan(plan)
+  if (!checked.ok) return checked
+  return ok({ mode: "audit", writes: 0, desired: desired.value, plan, findings })
+}
+
+/**
+ * Refuses a plan with any action that is not a read-only probe (each one is named). A valid plan's escalation and
+ * activation flags are exact (validateSetupPlan), so a probe-only plan never escalates or activates.
+ */
+export function checkReadOnly(plan: SetupPlan): Result<SetupPlan> {
+  const c = new Checker()
+  plan.actions.forEach((action, i) => {
+    if (!READ_ONLY_KINDS.includes(action.kind)) c.add(`/actions/${i}`, "inconsistent", `${action.kind} changes the machine; an audit only probes`)
+  })
+  return c.result(plan)
+}

package/packages/cli/src/bootstrap/profiles/catalog.ts

@@ -0,0 +1,49 @@
+// The built-in profiles hubctl offers, as contract Profile documents. The catalog has a revision: a later hubctl may
+// ship different defaults under a new revision (profile upgrades then keep every field the user chose; see
+// upgrade.ts). Defaults are always the safe ones: no escalation, OpenShell only when asked for, launches bounded.
+// v1.1: every catalog profile records the revision it comes from (Profile.revision), so a rebase knows its base.
+import { fail, HARNESS_ORDER, HARNESS_SERVICE, PROFILE_IDS, validateProfile, type HarnessID, type Profile, type ProfileID, type Result, type ServiceID } from "../contracts/index.ts"
+
+export interface ProfileCatalog {
+  readonly revision: number
+  readonly profiles: Readonly<Record<ProfileID, Profile>>
+}
+
+/** The bound on a launch when the user chose none. */
+export const DEFAULT_LAUNCH_S = 3600
+
+const base = { schema: "hub.bootstrap-profile", version: 2, revision: 1, runtimes: [], escalation: "never" } as const
+
+export const PROFILE_CATALOG: ProfileCatalog = Object.freeze({
+  revision: 1,
+  profiles: Object.freeze({
+    "session-only": { ...base, id: "session-only", harnesses: ["opencode"], services: [], launch: { enabled: false } },
+    "launch-node": { ...base, id: "launch-node", harnesses: ["opencode"], services: ["node"], launch: { enabled: true, maxDurationS: DEFAULT_LAUNCH_S } },
+    "full-harness": {
+      ...base,
+      id: "full-harness",
+      harnesses: [...HARNESS_ORDER],
+      services: ["node", "claude-code", "codex-spoke"],
+      launch: { enabled: true, maxDurationS: DEFAULT_LAUNCH_S },
+    },
+  } satisfies Record<ProfileID, Profile>),
+})
+
+export interface ProfileChoices {
+  /** The harnesses to set up (any order; they are put in HARNESS_ORDER). Default: the profile's. */
+  readonly harnesses?: readonly HarnessID[]
+  /** Opt in to OpenShell discovery and verification (never installed or configured). */
+  readonly openshell?: boolean
+}
+
+/** Every spoke service the chosen harnesses run (full-harness only), after the node service. */
+const spokeServices = (harnesses: readonly HarnessID[]): ServiceID[] => harnesses.flatMap((h) => HARNESS_SERVICE[h] ?? [])
+
+/** A built-in profile with the user's choices applied, validated against the contract. */
+export function defaultProfile(id: ProfileID, choices: ProfileChoices = {}, catalog: ProfileCatalog = PROFILE_CATALOG): Result<Profile> {
+  if (!(PROFILE_IDS as readonly string[]).includes(id) || !catalog.profiles[id]) return fail("/id", "invalid_value", `expected one of ${PROFILE_IDS.join(", ")}`)
+  const preset = catalog.profiles[id]
+  const harnesses = choices.harnesses ? [...choices.harnesses].sort((a, b) => HARNESS_ORDER.indexOf(a) - HARNESS_ORDER.indexOf(b)) : preset.harnesses
+  const services = choices.harnesses && id === "full-harness" ? (["node", ...spokeServices(harnesses)] as ServiceID[]) : preset.services
+  return validateProfile({ ...preset, harnesses, services, runtimes: choices.openshell ? ["openshell"] : preset.runtimes })
+}

package/packages/cli/src/bootstrap/profiles/desired.ts

@@ -0,0 +1,96 @@
+// Profile → desired state: what this host should end up with, as a pure function of (profile, discovery snapshot).
+// It is a description, never a write: the planner turns it into actions, the audit mode only verifies it. Hosts it
+// cannot serve fail explicitly (an unsupported target, services without a user service manager, OpenShell that is
+// absent or was not discovered) instead of being half-configured. OpenShell is verify-only: hubctl never installs
+// or configures it. A harness the user installed some other way stays theirs (owner "user"): hub verifies it and
+// never replaces it.
+import {
+  Checker,
+  fail,
+  REQUIRED_PROBES,
+  validateDiscoverySnapshot,
+  validateProfile,
+  type DiscoverySnapshot,
+  type HarnessID,
+  type Profile,
+  type ProbeKind,
+  type ProfileID,
+  type Result,
+  type RuntimeID,
+  type ServiceID,
+  type ServiceManagerID,
+} from "../contracts/index.ts"
+
+export interface DesiredHarness {
+  readonly id: HarnessID
+  readonly presence: "installed" | "missing"
+  /** hub: installed (or to be installed) by hubctl from a pinned artifact. user: installed another way; never replaced. */
+  readonly owner: "hub" | "user"
+  /** The version discovery found, when installed. */
+  readonly version?: string
+  /** The real probes readiness needs. */
+  readonly verify: readonly Exclude<ProbeKind, "presence">[]
+}
+
+export interface DesiredService {
+  readonly id: ServiceID
+  readonly manager: ServiceManagerID
+  /** Services are only ever activated on explicit confirmation. */
+  readonly activation: "explicit"
+}
+
+export interface DesiredRuntime {
+  readonly id: RuntimeID
+  readonly mode: "verify-only"
+}
+
+export interface DesiredState {
+  readonly profile: { readonly id: ProfileID; readonly version: Profile["version"] }
+  readonly target: string
+  readonly harnesses: readonly DesiredHarness[]
+  readonly services: readonly DesiredService[]
+  readonly runtimes: readonly DesiredRuntime[]
+  readonly launch: Profile["launch"]
+  readonly escalation: Profile["escalation"]
+}
+
+export function desiredState(profileDoc: unknown, snapshotDoc: unknown): Result<DesiredState> {
+  const c = new Checker()
+  const checkedProfile = validateProfile(profileDoc)
+  const checkedSnapshot = validateDiscoverySnapshot(snapshotDoc)
+  c.merge("/profile", checkedProfile)
+  c.merge("/snapshot", checkedSnapshot)
+  if (!checkedProfile.ok || !checkedSnapshot.ok) return c.result(undefined)
+  const profile = checkedProfile.value
+  const snapshot: DiscoverySnapshot = checkedSnapshot.value
+
+  if (!snapshot.host.supported) return fail("/snapshot/host/target", "unsupported_platform", `cannot set up ${snapshot.host.target}`)
+  const manager = snapshot.managers.service
+  if (profile.services.length > 0 && manager === "none")
+    c.add("/profile/services", "no_service_manager", `${profile.id} runs services, but this host has no user service manager (launchd or systemd --user)`)
+  const runtimes = profile.runtimes.map((id, i): DesiredRuntime => {
+    const found = snapshot.runtimes.find((r) => r.id === id)
+    if (!found) c.add(`/profile/runtimes/${i}`, "unsupported_platform", `discovery did not check ${id}; it is verified only after discovery finds it`)
+    else if (!found.present) c.add(`/profile/runtimes/${i}`, "unsupported_platform", `${id} is not present on this host; hubctl verifies it but never installs it`)
+    return { id, mode: "verify-only" }
+  })
+
+  const harnesses = profile.harnesses.map((id): DesiredHarness => {
+    const found = snapshot.harnesses.find((h) => h.id === id)
+    const verify = REQUIRED_PROBES[id].filter((k): k is Exclude<ProbeKind, "presence"> => k !== "presence")
+    if (!found?.installed) return { id, presence: "missing", owner: "hub", verify }
+    return { id, presence: "installed", owner: found.installMethod === "hub" ? "hub" : "user", ...(found.version ? { version: found.version } : {}), verify }
+  })
+  const services = manager === "none" ? [] : profile.services.map((id): DesiredService => ({ id, manager, activation: "explicit" }))
+  const launch = profile.launch.enabled ? { enabled: true, maxDurationS: profile.launch.maxDurationS } : { enabled: false }
+
+  return c.result<DesiredState>({
+    profile: { id: profile.id, version: profile.version },
+    target: snapshot.host.target,
+    harnesses,
+    services,
+    runtimes,
+    launch,
+    escalation: profile.escalation,
+  })
+}