@huynle/hub 0.7.1 → 0.7.3

package/packages/cli/src/bootstrap/adapters/node-services/plan.ts

@@ -0,0 +1,222 @@
+// Plans a persistent launch node: the typed actions that configure `hub node` (a lossless merge of node.json), write
+// its service unit and the chosen harness spokes' units (install-service, from the embedded templates, pinned by the
+// rendered unit's digest), load them only when the user explicitly asked to (activate-service, confirm: "explicit";
+// apply also needs --confirm-activation), and optionally prove the setup with one bounded launch inside a configured
+// workspace root (launch-session). Linger is never planned: it is an opt-in note, since keeping a user's services
+// running after logout is a login setting hubctl does not change.
+//
+// Pure and deterministic: the same snapshot, profile and options always plan the same actions and units, so a
+// re-plan at apply gives the same digest. No action carries a command, and no unit carries a credential.
+import {
+  HARNESS_SERVICE,
+  resolvePathRef,
+  validateAction,
+  type Action,
+  type ConfigSet,
+  type HarnessID,
+  type InstallService,
+  type Issue,
+  type PathRef,
+  type PlanInput,
+  type ProgramLayout,
+  type Result,
+  type ServiceID,
+} from "../../contracts/index.ts"
+import type { PlanContributor } from "../../preview/plan.ts"
+import { renderServiceUnit, SERVICE_ENVIRONMENT, type RenderedUnit } from "./render.ts"
+import { checkNodeSettings, inside, serviceContextOf, type NodeSettings, type ServiceContext } from "./validate.ts"
+
+export interface NodeServicesOptions {
+  /** The hubctl the services start (programLayout of this process). */
+  readonly layout: ProgramLayout
+  /** node.json settings ({workspaceRoots, slots?, labels?}); required when the profile has the node service. */
+  readonly node?: unknown
+  /** Explicit consent, given at preview: plan loading the services. Never a default. */
+  readonly activate?: boolean
+  /** Opt-in: the user wants the services kept running while logged out (a note; hubctl changes no login setting). */
+  readonly linger?: boolean
+  /** The user's environment; only each service's own settings (SERVICE_ENVIRONMENT) are carried, others ignored. */
+  readonly environment?: Readonly<Record<string, string | undefined>>
+  /** One bounded verification launch, inside a workspace root (needs `activate` and a launch-enabled profile). */
+  readonly launch?: { readonly harness: HarnessID; readonly workspace: PathRef }
+}
+
+export interface NodeServicesPlan {
+  readonly actions: readonly Action[]
+  /** The rendered units, in the order of their install-service actions. */
+  readonly units: readonly RenderedUnit[]
+  readonly settings?: NodeSettings
+  readonly context?: ServiceContext
+  /** Secret-free guidance for the preview (activation not requested, linger). */
+  readonly notes: readonly string[]
+}
+
+export const NODE_CONFIG_REF: PathRef = { root: "config", rel: "hub/node.json" }
+const CONFIG_DIR: PathRef = { root: "config", rel: "hub" }
+
+const LABEL: Readonly<Record<ServiceID, string>> = { node: "hub node", "claude-code": "Claude Code spoke", "codex-spoke": "Codex spoke" }
+const SERVICE_HARNESS: Readonly<Partial<Record<ServiceID, HarnessID>>> = Object.fromEntries(Object.entries(HARNESS_SERVICE).map(([h, s]) => [s, h]))
+const BIN_SETTING: Readonly<Partial<Record<HarnessID, string>>> = { "claude-code": "HUB_CLAUDE_BIN", codex: "HUB_CODEX_BIN" }
+
+const failed = <T>(issues: readonly Issue[]): Result<T> => ({ ok: false, issues: [...issues] })
+const prefixed = (prefix: string, r: Result<unknown>): Issue[] => (r.ok ? [] : r.issues.map((i) => ({ ...i, path: `${prefix}${i.path}` })))
+
+/** The harnesses a service serves: the node all chosen ones, a spoke its own. */
+const servedBy = (service: ServiceID, harnesses: readonly HarnessID[]): HarnessID[] => (service === "node" ? [...harnesses] : [SERVICE_HARNESS[service]!])
+
+function environmentFor(service: ServiceID, served: readonly HarnessID[], ctx: ServiceContext, environment: NodeServicesOptions["environment"]): Record<string, string> {
+  const env: Record<string, string> = {}
+  for (const key of SERVICE_ENVIRONMENT[service]) {
+    const v = environment?.[key]
+    if (v) env[key] = v
+  }
+  // The harness binary the service starts is the one discovery found in this context, not whatever its PATH holds.
+  for (const harness of served) {
+    const key = BIN_SETTING[harness]
+    const bin = ctx.harnessBins[harness]
+    if (key && bin && SERVICE_ENVIRONMENT[service].includes(key)) env[key] = bin
+  }
+  return env
+}
+
+function nodeConfigAction(raw: Record<string, unknown>, settings: NodeSettings, input: PlanInput, ctx: ServiceContext): Action[] {
+  const set: ConfigSet[] = [{ pointer: "/workspaceRoots", value: [...settings.workspaceRoots] }]
+  if (raw.slots !== undefined) set.push({ pointer: "/slots", value: settings.slots })
+  if (raw.labels !== undefined) set.push({ pointer: "/labels", value: { ...settings.labels } })
+  const where = resolvePathRef(NODE_CONFIG_REF, input.snapshot.roots, ctx.context)
+  const hostWhere = resolvePathRef(NODE_CONFIG_REF, input.snapshot.roots, "host")
+  const known = input.snapshot.configs.find((f) => (where.ok && f.path === where.value) || (hostWhere.ok && f.path === hostWhere.value))
+  const precondition = known?.sha256 ? { exists: true, sha256: known.sha256 } : { exists: false }
+  return [
+    { id: "hub-config-dir", kind: "ensure-directory", escalation: "user", summary: "Create the hub config directory", path: CONFIG_DIR, mode: 0o700 },
+    {
+      id: "node-config",
+      kind: "merge-config",
+      escalation: "user",
+      summary: `Set the launch node's workspace roots (${settings.workspaceRoots.join(", ")}) in node.json`,
+      path: NODE_CONFIG_REF,
+      format: "json",
+      owner: "hub",
+      precondition,
+      set,
+      preserveUnknown: true,
+    },
+  ]
+}
+
+/** The node-services actions for (snapshot, profile); refuses settings or contexts it cannot serve. */
+export function planNodeServices(input: PlanInput, options: NodeServicesOptions): Result<NodeServicesPlan> {
+  const { profile } = input
+  if (profile.services.length === 0) {
+    if (options.launch) return failed([{ path: "/launch", code: "inconsistent", message: `the ${profile.id} profile runs no node to launch on` }])
+    return { ok: true, value: { actions: [], units: [], notes: [] } }
+  }
+  const harnesses = [...new Set(profile.services.flatMap((s) => servedBy(s, profile.harnesses)))]
+  const context = serviceContextOf({ snapshot: input.snapshot, harnesses, layout: options.layout })
+  if (!context.ok) return context as Result<never>
+  const ctx = context.value
+
+  const actions: Action[] = []
+  const issues: Issue[] = []
+  let settings: NodeSettings | undefined
+  if (profile.services.includes("node")) {
+    if (options.node === undefined) issues.push({ path: "/node", code: "missing_field", message: "a launch node needs its workspace roots: pass --workspace-root <dir> (repeat it for more than one), or list them in node.json workspaceRoots" })
+    else {
+      const checked = checkNodeSettings(options.node, { snapshot: input.snapshot })
+      if (!checked.ok) issues.push(...prefixed("/node", checked))
+      else {
+        settings = checked.value
+        actions.push(...nodeConfigAction(options.node as Record<string, unknown>, settings, input, ctx))
+      }
+    }
+  }
+
+  const units: RenderedUnit[] = []
+  for (const service of profile.services) {
+    const environment = environmentFor(service, servedBy(service, profile.harnesses), ctx, options.environment)
+    const unit = renderServiceUnit({ service, manager: ctx.manager, layout: options.layout, home: ctx.home, environment })
+    if (!unit.ok) {
+      issues.push(...prefixed(`/services/${service}`, unit))
+      continue
+    }
+    units.push(unit.value)
+    actions.push({
+      id: `install-${service}-service`,
+      kind: "install-service",
+      escalation: "user",
+      summary: `Write the ${LABEL[service]} ${ctx.manager === "launchd" ? "launchd agent" : "systemd --user unit"} (${unit.value.name})`,
+      service,
+      manager: ctx.manager,
+      path: unit.value.path,
+      asset: unit.value.asset,
+      sha256: unit.value.sha256,
+    })
+  }
+
+  if (options.activate)
+    for (const service of profile.services)
+      actions.push({ id: `activate-${service}-service`, kind: "activate-service", escalation: "user", summary: `Load the ${LABEL[service]} service (explicitly confirmed)`, service, manager: ctx.manager, confirm: "explicit" })
+
+  if (options.launch) issues.push(...checkLaunch(input, options, ctx, settings))
+  if (issues.length > 0) return failed(issues)
+  if (options.launch)
+    actions.push({
+      id: `verify-launch-${options.launch.harness}`,
+      kind: "launch-session",
+      escalation: "user",
+      summary: `Launch one bounded ${options.launch.harness} session (at most ${profile.launch.maxDurationS} s) to prove the node end to end`,
+      harness: options.launch.harness,
+      workspace: options.launch.workspace,
+      maxDurationS: profile.launch.maxDurationS!,
+    })
+
+  for (const action of actions) {
+    const valid = validateAction(action)
+    if (!valid.ok) issues.push(...prefixed(`/actions/${action.id}`, valid))
+  }
+  if (issues.length > 0) return failed(issues)
+  return { ok: true, value: { actions, units, ...(settings ? { settings } : {}), context: ctx, notes: notesFor(options, ctx) } }
+}
+
+function checkLaunch(input: PlanInput, options: NodeServicesOptions, ctx: ServiceContext, settings: NodeSettings | undefined): Issue[] {
+  const launch = options.launch!
+  const { profile } = input
+  if (!profile.launch.enabled || profile.launch.maxDurationS === undefined) return [{ path: "/launch", code: "inconsistent", message: `the ${profile.id} profile does not launch sessions` }]
+  if (!options.activate) return [{ path: "/launch", code: "inconsistent", message: "a verification launch needs the node running: confirm activation too" }]
+  if (!profile.harnesses.includes(launch.harness)) return [{ path: "/launch/harness", code: "inconsistent", message: `the ${profile.id} profile does not set up ${launch.harness}` }]
+  const where = resolvePathRef(launch.workspace, input.snapshot.roots, ctx.context)
+  if (!where.ok) return prefixed("/launch/workspace", where)
+  if (settings && !settings.workspaceRoots.some((root) => inside(where.value, root)))
+    return [{ path: "/launch/workspace", code: "invalid_path", message: `${where.value} is outside the node's workspace roots` }]
+  return []
+}
+
+function notesFor(options: NodeServicesOptions, ctx: ServiceContext): string[] {
+  const notes: string[] = []
+  if (!options.activate) notes.push("The services are installed but not loaded: pass --confirm-activation to load them (hubctl never loads a service without it).")
+  if (ctx.manager === "systemd-user")
+    notes.push(
+      options.linger
+        ? "To keep the services running while you are logged out, run `loginctl enable-linger` yourself; hubctl does not change login settings."
+        : "systemd --user services stop when you log out; keeping them running (linger) is opt-in.",
+    )
+  else notes.push("launchd user agents run while you are logged in.")
+  return notes
+}
+
+/** A planner contributor (preview/plan.ts). Validate with planNodeServices first: a contributor cannot refuse. */
+export function nodeServicesContributor(options: NodeServicesOptions): PlanContributor {
+  return (input) => {
+    const planned = planNodeServices(input, options)
+    if (!planned.ok) throw new Error(`node services cannot be planned: ${planned.issues.map((i) => `${i.code} ${i.path}: ${i.message}`).join("; ")}`)
+    return planned.value.actions
+  }
+}
+
+/** The applier's renderService (BuiltinDeps): exactly the planned units, nothing else. */
+export function serviceAssets(planned: NodeServicesPlan): { readonly renderService: (action: InstallService) => Uint8Array | undefined } {
+  return {
+    renderService: (action) =>
+      planned.units.find((u) => u.asset === action.asset && u.service === action.service && u.manager === action.manager && u.path.root === action.path.root && u.path.rel === action.path.rel)?.bytes,
+  }
+}

package/packages/cli/src/bootstrap/adapters/node-services/render.ts

@@ -0,0 +1,183 @@
+// Renders the per-user service units of `hub node` and the harness spokes (`hub claude-code daemon`, `hub
+// codex-spoke serve`) from the templates embedded in hubctl (EMBEDDED_ASSETS, release/assets.ts), never from
+// scripts/ on disk, with the executable contract's argv (serviceArgv): a word list of absolute, single-line paths,
+// one launchd <string> per word, or one systemd ExecStart= word per word (quoted and escaped). A unit carries only
+// the service's own settings (where its config, state and harness binary are), each single-line, absolute and
+// never a credential: the machine token stays in the CredentialStore, which the service reads at run time.
+//
+// BUN_BE_BUN=1 (in every template) makes a Bun-compiled executable act as the bun CLI: it is what lets an OpenCode
+// binary run hub-cli.js, so only the script layout keeps it. A standalone hubctl with it would run `bun node run`
+// (a missing module) and crash-loop, so its units never mention it.
+//
+// Rendering is pure: the same input always gives the same bytes, so a plan can pin the unit's digest
+// (install-service.sha256) and apply can render it again and compare.
+import {
+  Checker,
+  EMBEDDED_ASSETS,
+  isAbsolutePath,
+  isSecretValue,
+  pointer,
+  serviceArgv,
+  SERVICE_COMMANDS,
+  sha256Hex,
+  type PathRef,
+  type ProgramLayout,
+  type Result,
+  type ServiceID,
+  type ServiceManagerID,
+} from "../../contracts/index.ts"
+import { EMBEDDED_TEXT } from "../../release/assets.ts"
+
+/** The settings each service may carry into its unit (as `hub <service> install` carries them today). */
+export const SERVICE_ENVIRONMENT: Readonly<Record<ServiceID, readonly string[]>> = Object.freeze({
+  node: ["HUB_SPOKE_CONFIG", "XDG_CONFIG_HOME", "HUB_CLAUDE_BIN", "HUB_CODEX_BIN"],
+  "claude-code": ["HUB_SPOKE_CONFIG", "XDG_CONFIG_HOME", "HUB_STATE_DIR", "HUB_CLAUDE_SOCKET", "HUB_CLAUDE_BIN"],
+  "codex-spoke": ["HUB_SPOKE_CONFIG", "XDG_CONFIG_HOME", "HUB_STATE_DIR", "CODEX_HOME", "HUB_CODEX_BIN", "HUB_CODEX_DAEMON_SOCKET"],
+})
+
+/** The named root each manager's units live in. */
+export const UNIT_ROOT: Readonly<Record<ServiceManagerID, "launch-agents" | "systemd-user">> = Object.freeze({ launchd: "launch-agents", "systemd-user": "systemd-user" })
+
+export interface RenderInput {
+  readonly service: ServiceID
+  readonly manager: ServiceManagerID
+  /** How the service starts hubctl (programLayout of the hubctl that plans and applies). */
+  readonly layout: ProgramLayout
+  /** The home directory as the service sees it (the execution context's view). */
+  readonly home: string
+  /** Settings to carry, from SERVICE_ENVIRONMENT[service] only. */
+  readonly environment?: Readonly<Record<string, string>>
+  /** The command that writes the unit by hand ("hub node"): its header then names its install/uninstall (default: hubctl setup). */
+  readonly writtenBy?: string
+}
+
+export interface RenderedUnit {
+  /** The EMBEDDED_ASSETS id it was rendered from. */
+  readonly asset: string
+  readonly service: ServiceID
+  readonly manager: ServiceManagerID
+  /** Where it is installed: the manager's root and the asset's file name. */
+  readonly path: PathRef
+  /** The launchd label or the systemd unit name (what the service manager calls it). */
+  readonly name: string
+  readonly argv: readonly string[]
+  readonly text: string
+  readonly bytes: Uint8Array
+  readonly sha256: string
+}
+
+export const assetIDFor = (service: ServiceID, manager: ServiceManagerID): string => `service/${manager}/${service}`
+
+/** The launchd label or systemd unit name of a service under a manager. */
+export function serviceName(service: ServiceID, manager: ServiceManagerID): string {
+  const file = EMBEDDED_ASSETS[assetIDFor(service, manager)]!.installAs
+  return manager === "launchd" ? file.replace(/\.plist$/, "") : file
+}
+
+const xml = (text: string) => text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;")
+
+/** A word for a systemd command line or assignment: % and $ escaped, quoted when not plain (as node.ts does). */
+const sd = (word: string) => {
+  const escaped = word.replaceAll("%", "%%").replaceAll("$", "$$$$")
+  return /^[A-Za-z0-9_./:@+=,-]+$/.test(escaped) ? escaped : `"${escaped.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`
+}
+
+/** A home usable inside a systemd assignment without quoting (Environment=PATH=<home>/...). */
+const SYSTEMD_HOME = /^\/[A-Za-z0-9_./@+,:-]*$/
+const PLACEHOLDER = /__[A-Z]+__/
+
+/** The template's BUN_BE_BUN=1 setting, per manager (removed for the standalone layout). */
+const BUN_BE_BUN: Readonly<Record<ServiceManagerID, RegExp>> = Object.freeze({
+  "systemd-user": /^Environment=BUN_BE_BUN=1\n/m,
+  launchd: /\n[ \t]*<key>BUN_BE_BUN<\/key>\s*<string>1<\/string>/,
+})
+
+const header = (asset: string, by?: string) =>
+  by ? `Written by ${by} install from the embedded asset ${asset}; ${by} uninstall removes it.` : `Written by hubctl setup from the embedded asset ${asset}; hubctl removes it only while it is unchanged.`
+
+function checkEnvironment(c: Checker, service: ServiceID, environment: Readonly<Record<string, string>>): [string, string][] {
+  const allowed = SERVICE_ENVIRONMENT[service]
+  const out: [string, string][] = []
+  for (const key of Object.keys(environment).sort()) {
+    const value = environment[key]!
+    const at = pointer("/environment", key)
+    if (!allowed.includes(key)) c.add(at, "invalid_value", `the ${service} service does not carry ${key}`)
+    else if (typeof value === "string" && isSecretValue(value)) c.add(at, "secret", "service units never carry credentials")
+    else if (!isAbsolutePath(value)) c.add(at, "invalid_value", `${key} must be an absolute, single-line path`)
+    else out.push([key, value])
+  }
+  return out
+}
+
+function renderSystemd(c: Checker, asset: string, template: string, argv: readonly string[], command: readonly string[], home: string, env: [string, string][], by?: string): string {
+  const execLine = /^ExecStart=(.*)$/m
+  const found = template.match(execLine)?.[1]
+  if (found !== "__ARGV__" && found !== `__RUNTIME__ __ENTRY__ ${command.join(" ")}`) c.add("/asset", "inconsistent", `${asset} does not start the ${command.join(" ")} command`)
+  const body = template.slice(Math.max(0, template.indexOf("[Unit]")))
+  const extra = env.map(([key, value]) => `\nEnvironment=${sd(`${key}=${value}`)}`).join("")
+  return `# ${header(asset, by)}\n${body}`
+    .replace(execLine, () => `ExecStart=${argv.map(sd).join(" ")}`)
+    .replaceAll("__HOME__", home.replaceAll("%", "%%"))
+    .replace(/(Environment=PATH=[^\n]*)/, (line) => `${line}${extra}`)
+}
+
+function renderLaunchd(c: Checker, asset: string, template: string, argv: readonly string[], command: readonly string[], home: string, env: [string, string][], by?: string): string {
+  const programArguments = /(<key>ProgramArguments<\/key>\s*<array>)([\s\S]*?)(\n\s*<\/array>)/
+  const match = template.match(programArguments)
+  const words = [...(match?.[2] ?? "").matchAll(/<string>([^<]*)<\/string>/g)].map((m) => m[1])
+  const expected = [["__ARGV__"], ["__RUNTIME__", "__ENTRY__", ...command]]
+  if (!expected.some((e) => e.length === words.length && e.every((w, i) => w === words[i]))) c.add("/asset", "inconsistent", `${asset} does not start the ${command.join(" ")} command`)
+  const indent = (match?.[2] ?? "").match(/\n(\s*)<string>/)?.[1] ?? "    "
+  const extra = env.map(([key, value]) => `\n${indent}<key>${key}</key>\n${indent}<string>${xml(value)}</string>`).join("")
+  return template
+    .replace(/<!--[\s\S]*?-->/, () => `<!-- ${header(asset, by)} -->`)
+    .replace(programArguments, (_all, open: string, _words: string, close: string) => `${open}${argv.map((w) => `\n${indent}<string>${xml(w)}</string>`).join("")}${close}`)
+    .replaceAll("__HOME__", xml(home))
+    .replace(/(<key>PATH<\/key>\s*<string>[^<]*<\/string>)/, (line) => `${line}${extra}`)
+}
+
+/** The unit for `service` under `manager`, rendered from its embedded template. */
+export function renderServiceUnit(input: RenderInput): Result<RenderedUnit> {
+  const c = new Checker()
+  const asset = assetIDFor(input.service, input.manager)
+  const entry = EMBEDDED_ASSETS[asset]
+  const template = EMBEDDED_TEXT[asset]
+  if (!entry || template === undefined) {
+    c.add("/service", "invalid_value", `no embedded template for ${input.service} under ${input.manager}`)
+    return c.result(undefined)
+  }
+  let argv: string[] = []
+  try {
+    argv = serviceArgv(input.layout, input.service)
+  } catch (error) {
+    c.add("/layout", "invalid_path", (error as Error).message)
+  }
+  const homeOK = isAbsolutePath(input.home) && input.home !== "/" && (input.manager !== "systemd-user" || SYSTEMD_HOME.test(input.home))
+  if (!homeOK) c.add("/home", "invalid_path", "the service's home must be an absolute, normalized directory other than /")
+  const env = checkEnvironment(c, input.service, input.environment ?? {})
+  if (c.issues.length > 0) return c.result(undefined)
+
+  const command = SERVICE_COMMANDS[input.service]
+  const raw =
+    input.manager === "systemd-user"
+      ? renderSystemd(c, asset, template, argv, command, input.home, env, input.writtenBy)
+      : renderLaunchd(c, asset, template, argv, command, input.home, env, input.writtenBy)
+  const asBun = input.layout.kind === "script"
+  const text = asBun ? raw : raw.replace(BUN_BE_BUN[input.manager], "")
+  if (!asBun && text.includes("BUN_BE_BUN")) c.add("/asset", "inconsistent", `${asset} sets BUN_BE_BUN, which a standalone hubctl must not get`)
+  if (PLACEHOLDER.test(text)) c.add("/asset", "inconsistent", `${asset} has a placeholder this hubctl does not fill`)
+  if (isSecretValue(text)) c.add("/environment", "secret", "service units never carry credentials")
+  if (c.issues.length > 0) return c.result(undefined)
+  const bytes = new TextEncoder().encode(text)
+  return c.result<RenderedUnit>({
+    asset,
+    service: input.service,
+    manager: input.manager,
+    path: { root: UNIT_ROOT[input.manager], rel: entry.installAs },
+    name: serviceName(input.service, input.manager),
+    argv,
+    text,
+    bytes,
+    sha256: `sha256:${sha256Hex(bytes)}`,
+  })
+}

package/packages/cli/src/bootstrap/adapters/node-services/validate.ts

@@ -0,0 +1,197 @@
+// What a persistent launch node may be configured with, and where its services may run.
+//
+// Node settings (node.json): workspace roots must be narrow project directories, never /, a top-level directory,
+// the home itself, a parent of it, another user's home, or hub's own config/state/unit directories; roots are
+// distinct and never nested; slots are bounded; labels are plain and never a credential or the node's own os/arch.
+//
+// Same runtime context: a service runs where the service manager that loads it runs. It must be the same runtime
+// and filesystem context as the harness it serves and the paths in its unit. So the adapter refuses
+//   - a harness reached through a container shim (the harness and its repositories live in a container, while this
+//     host has none: a host service would find no harness and the wrong paths);
+//   - inside a container, a unit directory that is a host directory mounted in (the host's manager would run the
+//     unit with the container's paths);
+//   - any program, harness or workspace path that is the other side's view of a mounted root.
+import { labelsProblem, NODE_ROOTS_MAX } from "../../../../../protocol/src/index.ts"
+import {
+  Checker,
+  checkTarget,
+  executionContextOf,
+  fail,
+  findSecrets,
+  isAbsolutePath,
+  isRecord,
+  pointer,
+  rootPathIn,
+  sha256Hex,
+  shape,
+  type DiscoverySnapshot,
+  type ExecutionContext,
+  type HarnessID,
+  type ProgramLayout,
+  type Result,
+  type RootMapping,
+  type ServiceManagerID,
+} from "../../contracts/index.ts"
+import { UNIT_ROOT } from "./render.ts"
+
+/** Concurrent launches when the settings name none (the node's own default, packages/node DEFAULT_SLOTS). */
+export const DEFAULT_SLOTS = 4
+/** The bootstrap configures at most this many slots; a larger node is configured by hand. */
+export const BOOTSTRAP_SLOTS_MAX = 64
+/** Labels the node sets itself. */
+export const RESERVED_LABELS = ["os", "arch"] as const
+
+export interface NodeSettings {
+  readonly workspaceRoots: readonly string[]
+  readonly slots: number
+  readonly labels: Readonly<Record<string, string>>
+}
+
+export interface NodePlaces {
+  /** The discovery the plan is made from: its roots and execution context. */
+  readonly snapshot: Pick<DiscoverySnapshot, "roots" | "topology">
+}
+
+/** Whether `path` is `dir` or inside it. */
+export const inside = (path: string, dir: string) => path === dir || path.startsWith(dir === "/" ? "/" : `${dir}/`)
+const parentOf = (path: string) => path.slice(0, path.lastIndexOf("/")) || "/"
+
+/** Mount prefixes as the *other* context sees them (a path under one is not valid where the service runs). */
+function otherViews(roots: readonly RootMapping[], context: ExecutionContext): string[] {
+  return roots.flatMap((r) => (r.containerPath !== undefined && r.containerPath !== r.path ? [context === "container" ? r.path : r.containerPath] : []))
+}
+
+function thisViews(roots: readonly RootMapping[], context: ExecutionContext): string[] {
+  return roots.map((r) => rootPathIn(r, context))
+}
+
+/** Whether `path` is the other context's view of a mounted root (and not also valid in this context). */
+const foreignPath = (path: string, roots: readonly RootMapping[], context: ExecutionContext) =>
+  otherViews(roots, context).some((v) => inside(path, v)) && !thisViews(roots, context).some((v) => inside(path, v))
+
+function rootProblem(root: unknown, roots: readonly RootMapping[], context: ExecutionContext): { code: "invalid_path" | "inconsistent"; message: string } | undefined {
+  if (!isAbsolutePath(root)) return { code: "invalid_path", message: "a workspace root is an absolute, normalized, single-line path" }
+  if (foreignPath(root, roots, context)) return { code: "inconsistent", message: `${root} is how the other side of the container mount sees it; give the path the service sees` }
+  if (root === "/" || root.split("/").length < 3) return { code: "invalid_path", message: `${root} is too broad for a workspace root` }
+  const home = roots.find((r) => r.id === "home")
+  const homePath = home ? rootPathIn(home, context) : undefined
+  if (homePath && inside(homePath, root)) return { code: "invalid_path", message: `${root} is the whole home or a parent of it; name a project directory inside it` }
+  if (homePath && parentOf(root) === parentOf(homePath)) return { code: "invalid_path", message: `${root} is another user's home` }
+  for (const r of roots) {
+    if (r.id === "home") continue
+    const dir = rootPathIn(r, context)
+    if (inside(root, dir) || inside(dir, root)) return { code: "invalid_path", message: `${root} holds hub's own ${r.id} directory` }
+  }
+  return undefined
+}
+
+/** Validates and normalizes the launch node's settings for this host. */
+export function checkNodeSettings(value: unknown, places: NodePlaces): Result<NodeSettings> {
+  const c = new Checker()
+  const r = shape(c, "", value, ["workspaceRoots"], ["slots", "labels"])
+  if (!r) return c.result(undefined)
+  const context = executionContextOf(places.snapshot)
+  const roots = places.snapshot.roots
+  const workspaceRoots: string[] = []
+  if (r.workspaceRoots !== undefined) {
+    if (!Array.isArray(r.workspaceRoots) || r.workspaceRoots.length === 0) c.add("/workspaceRoots", "invalid_value", "a launch node needs at least one workspace root")
+    else if (r.workspaceRoots.length > NODE_ROOTS_MAX) c.add("/workspaceRoots", "invalid_value", `at most ${NODE_ROOTS_MAX} workspace roots`)
+    else
+      r.workspaceRoots.forEach((root: unknown, i: number) => {
+        const at = pointer("/workspaceRoots", i)
+        const problem = rootProblem(root, roots, context)
+        if (problem) return c.add(at, problem.code, problem.message)
+        const path = root as string
+        if (workspaceRoots.some((w) => inside(path, w) || inside(w, path))) return c.add(at, "duplicate", `${path} repeats or nests another workspace root`)
+        workspaceRoots.push(path)
+      })
+  }
+  let slots = DEFAULT_SLOTS
+  if (r.slots !== undefined) {
+    if (Number.isInteger(r.slots) && (r.slots as number) >= 1 && (r.slots as number) <= BOOTSTRAP_SLOTS_MAX) slots = r.slots as number
+    else c.add("/slots", "invalid_value", `slots must be a whole number from 1 to ${BOOTSTRAP_SLOTS_MAX}`)
+  }
+  let labels: Record<string, string> = {}
+  if (r.labels !== undefined) {
+    const problem = labelsProblem(r.labels)
+    if (findSecrets(r.labels).length > 0) c.add("/labels", "secret", "labels never carry credentials")
+    else if (problem) c.add("/labels", "invalid_value", problem)
+    else if (isRecord(r.labels) && RESERVED_LABELS.some((k) => k in (r.labels as object))) c.add("/labels", "invalid_value", `the node sets ${RESERVED_LABELS.join(" and ")} itself`)
+    else labels = Object.fromEntries(Object.entries(r.labels as Record<string, string>).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+  }
+  return c.result<NodeSettings>({ workspaceRoots, slots, labels })
+}
+
+export interface RenderedConfig {
+  readonly text: string
+  readonly bytes: Uint8Array
+  readonly sha256: string
+}
+
+/** node.json for validated settings: the same settings always give the same bytes. */
+export function renderNodeConfig(settings: NodeSettings): RenderedConfig {
+  const labels = Object.fromEntries(Object.entries(settings.labels).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+  const text = `${JSON.stringify({ workspaceRoots: settings.workspaceRoots, slots: settings.slots, labels }, null, 2)}\n`
+  const bytes = new TextEncoder().encode(text)
+  return { text, bytes, sha256: `sha256:${sha256Hex(bytes)}` }
+}
+
+export interface ServiceContextInput {
+  readonly snapshot: DiscoverySnapshot
+  /** The harnesses the services serve (the node: every chosen harness; a spoke: its own). */
+  readonly harnesses: readonly HarnessID[]
+  /** The hubctl the services start. */
+  readonly layout: ProgramLayout
+}
+
+export interface ServiceContext {
+  readonly context: ExecutionContext
+  readonly manager: ServiceManagerID
+  /** Home as the service sees it. */
+  readonly home: string
+  /** Each installed harness's real binary in this context (a wrapper resolved), carried into the unit. */
+  readonly harnessBins: Partial<Record<HarnessID, string>>
+}
+
+/** Where this host's services run, refusing any mismatch with the harness's runtime and filesystem context. */
+export function serviceContextOf(input: ServiceContextInput): Result<ServiceContext> {
+  const { snapshot } = input
+  const context = executionContextOf(snapshot)
+  const manager = snapshot.managers.service
+  if (manager === "none") return fail("/managers/service", "no_service_manager", "this host has no user service manager (launchd or systemd --user)")
+  const target = checkTarget(snapshot.host.target)
+  if (!target.ok) return target as Result<never>
+  if (target.value.serviceManager !== manager) return fail("/managers/service", "inconsistent", `${snapshot.host.target} services run under ${target.value.serviceManager}, not ${manager}`)
+
+  const c = new Checker()
+  const unitRoot = snapshot.roots.find((r) => r.id === UNIT_ROOT[manager])
+  const home = snapshot.roots.find((r) => r.id === "home")
+  if (!unitRoot) c.add("/roots", "unmapped_root", `this host has no ${UNIT_ROOT[manager]} root`)
+  if (!home) c.add("/roots", "unmapped_root", "this host has no home root")
+  if (unitRoot && context === "container" && unitRoot.containerPath !== undefined)
+    c.add("/roots", "inconsistent", `the ${unitRoot.id} directory is the host's ${unitRoot.path}, mounted into this container: the host's ${manager} would run the unit outside the container`)
+
+  const program = input.layout.kind === "standalone" ? [input.layout.executable] : [input.layout.runtime, input.layout.entry]
+  for (const word of program)
+    if (isAbsolutePath(word) && foreignPath(word, snapshot.roots, context)) c.add("/layout", "inconsistent", `${word} is the other side's view of a container mount; the service could not start it`)
+
+  const harnessBins: Partial<Record<HarnessID, string>> = {}
+  for (const id of input.harnesses) {
+    const presence = snapshot.harnesses.find((h) => h.id === id)
+    if (!presence?.installed || !presence.path) continue
+    const shim = snapshot.topology.shims.find((s) => s.path === presence.path)
+    if (shim?.kind === "container-shim") {
+      c.add(
+        `/harnesses/${id}`,
+        "inconsistent",
+        `${id} at ${presence.path} is a shim into a container${shim.resolvesTo ? ` (${shim.resolvesTo})` : ""}: the harness and its repositories live there, so set up the service inside that container`,
+      )
+      continue
+    }
+    const bin = shim?.kind === "wrapper" && shim.resolvesTo ? shim.resolvesTo : presence.path
+    if (foreignPath(bin, snapshot.roots, context)) c.add(`/harnesses/${id}`, "inconsistent", `${id} at ${bin} is the other side's view of a container mount`)
+    else harnessBins[id] = bin
+  }
+  if (c.issues.length > 0) return c.result(undefined)
+  return c.result<ServiceContext>({ context, manager, home: rootPathIn(home!, context), harnessBins })
+}