admincore

type APIError struct {
	Status int
	Msg    string
}

type AppHealthView struct {
	Name       string    `json:"name"`
	Scheme     string    `json:"scheme"`
	Target     string    `json:"target"`
	Reachable  bool      `json:"reachable"`
	RTTms      float64   `json:"rtt_ms"`
	Tier       string    `json:"tier"`
	StatusCode int       `json:"status_code,omitempty"`
	Error      string    `json:"error,omitempty"`
	At         time.Time `json:"at,omitzero"`
}

type AppUpsertParams struct {
	conf.AppConfig
	URL string `json:"url,omitempty"`
}

type AppstoreCatalogView struct {
	OK      bool     `json:"ok"`
	Catalog string   `json:"catalog"`
	Apps    []string `json:"apps"`
}

type AppstoreInstallParams struct {
	ID               string `json:"id"`
	Catalog          string `json:"catalog,omitempty"`
	Kubeconfig       string `json:"kubeconfig,omitempty"`
	Namespace        string `json:"namespace"`
	Release          string `json:"release,omitempty"`
	TimeoutSeconds   int    `json:"timeout_seconds,omitempty"`
	PollSeconds      int    `json:"poll_seconds,omitempty"`
	AllowScaleToZero bool   `json:"allow_scale_to_zero,omitempty"`
	NoRollback       bool   `json:"no_rollback,omitempty"`
	SaveKubeconfig   bool   `json:"save_kubeconfig,omitempty"`
	SaveCatalog      bool   `json:"save_catalog,omitempty"`
}

type AppstoreInstallResult struct {
	OK              bool     `json:"ok"`
	ID              string   `json:"id"`
	Catalog         string   `json:"catalog"`
	Manifest        string   `json:"manifest"`
	Namespace       string   `json:"namespace"`
	Release         string   `json:"release"`
	ObjectName      string   `json:"object_name"`
	Kubeconfig      string   `json:"kubeconfig"`
	Applied         int      `json:"applied"`
	Ready           int      `json:"ready"`
	Created         []string `json:"created,omitempty"`
	RolledBack      []string `json:"rolled_back,omitempty"`
	CleanupFailed   []string `json:"cleanup_failed,omitempty"`
	KubeconfigSaved bool     `json:"kubeconfig_saved,omitempty"`
	CatalogSaved    bool     `json:"catalog_saved,omitempty"`
}

type AppstoreShowResult struct {
	OK            bool     `json:"ok"`
	ID            string   `json:"id"`
	Catalog       string   `json:"catalog"`
	Manifest      string   `json:"manifest"`
	Name          string   `json:"name,omitempty"`
	Version       string   `json:"version,omitempty"`
	Description   string   `json:"description,omitempty"`
	Homepage      string   `json:"homepage,omitempty"`
	Categories    []string `json:"categories,omitempty"`
	Tags          []string `json:"tags,omitempty"`
	Featured      bool     `json:"featured,omitempty"`
	ChartRepo     string   `json:"chart_repo"`
	ChartName     string   `json:"chart_name"`
	ChartVersion  string   `json:"chart_version"`
	ClusterScoped bool     `json:"cluster_scoped,omitempty"`
	HasValues     bool     `json:"has_values"`
}

type AppstoreStatusParams struct {
	ID               string `json:"id"`
	Catalog          string `json:"catalog,omitempty"`
	Kubeconfig       string `json:"kubeconfig,omitempty"`
	Namespace        string `json:"namespace"`
	Release          string `json:"release,omitempty"`
	AllowScaleToZero bool   `json:"allow_scale_to_zero,omitempty"`
}

type AppstoreStatusResult struct {
	OK         bool   `json:"ok"`
	ID         string `json:"id"`
	Catalog    string `json:"catalog"`
	Manifest   string `json:"manifest"`
	Namespace  string `json:"namespace"`
	Release    string `json:"release"`
	ObjectName string `json:"object_name"`
	Kubeconfig string `json:"kubeconfig"`
	Installed  bool   `json:"installed"`
	AllReady   bool   `json:"all_ready"`
	Reason     string `json:"reason,omitempty"`
}

type AppstoreUninstallParams struct {
	ID             string `json:"id"`
	Catalog        string `json:"catalog,omitempty"`
	Kubeconfig     string `json:"kubeconfig,omitempty"`
	Namespace      string `json:"namespace"`
	Release        string `json:"release,omitempty"`
	TimeoutSeconds int    `json:"timeout_seconds,omitempty"`
	PollSeconds    int    `json:"poll_seconds,omitempty"`
}

type AppstoreUninstallResult struct {
	OK         bool     `json:"ok"`
	ID         string   `json:"id"`
	Catalog    string   `json:"catalog"`
	Manifest   string   `json:"manifest"`
	Namespace  string   `json:"namespace"`
	Release    string   `json:"release"`
	ObjectName string   `json:"object_name"`
	Kubeconfig string   `json:"kubeconfig"`
	Deleted    []string `json:"deleted,omitempty"`
	Failed     []string `json:"failed,omitempty"`
	Gone       int      `json:"gone,omitempty"`
}

type BackupApplier interface {
	Apply(cfg *conf.BackupConfig) error
	RunNow(ctx context.Context) ([]backup.Candidate, error)
	History(n int) ([]backup.Candidate, error)
}

type BackupParams struct {
	Enabled    bool     `json:"enabled"`
	Schedule   string   `json:"schedule"`
	Folders    []string `json:"folders"`
	LedgerPath string   `json:"ledger_path,omitempty"`
}

type BuiltinInstallParams struct {
	Name              string `json:"name"`
	Catalog           string `json:"catalog,omitempty"`
	Kubeconfig        string `json:"kubeconfig,omitempty"`
	TimeoutSeconds    int    `json:"timeout_seconds,omitempty"`
	PollSeconds       int    `json:"poll_seconds,omitempty"`
	CRDTimeoutSeconds int    `json:"crd_timeout_seconds,omitempty"`
	AllowScaleToZero  bool   `json:"allow_scale_to_zero,omitempty"`
	NoRollback        bool   `json:"no_rollback,omitempty"`
	SaveKubeconfig    bool   `json:"save_kubeconfig,omitempty"`
	SaveCatalog       bool   `json:"save_catalog,omitempty"`
}

type BuiltinInstallResult struct {
	BundleApplyResult
	Name         string `json:"name"`
	Catalog      string `json:"catalog"`
	Manifest     string `json:"manifest"`
	CatalogSaved bool   `json:"catalog_saved,omitempty"`
}

type BuiltinStatusParams struct {
	Name             string `json:"name"`
	Catalog          string `json:"catalog,omitempty"`
	Kubeconfig       string `json:"kubeconfig,omitempty"`
	AllowScaleToZero bool   `json:"allow_scale_to_zero,omitempty"`
}

type BuiltinStatusResult struct {
	BundleStatusResult
	Name     string `json:"name"`
	Catalog  string `json:"catalog"`
	Manifest string `json:"manifest"`
}

type BuiltinUninstallParams struct {
	Name           string `json:"name"`
	Catalog        string `json:"catalog,omitempty"`
	Kubeconfig     string `json:"kubeconfig,omitempty"`
	TimeoutSeconds int    `json:"timeout_seconds,omitempty"`
	PollSeconds    int    `json:"poll_seconds,omitempty"`
}

type BuiltinUninstallResult struct {
	BundleUninstallResult
	Name     string `json:"name"`
	Catalog  string `json:"catalog"`
	Manifest string `json:"manifest"`
}

type BuiltinView struct {
	Enabled   bool   `json:"enabled"`
	Available bool   `json:"available"`
	Target    string `json:"target,omitempty"`
}

type BuiltinsParams struct {
	Shell                 *bool    `json:"shell,omitempty"`
	Desktop               *bool    `json:"desktop,omitempty"`
	Clipboard             *bool    `json:"clipboard,omitempty"`
	SSH                   *bool    `json:"ssh,omitempty"`
	SSHAllowLocalForward  *bool    `json:"ssh_allow_local_forward,omitempty"`
	SSHAllowRemoteForward *bool    `json:"ssh_allow_remote_forward,omitempty"`
	SSHAllowAgentForward  *bool    `json:"ssh_allow_agent_forward,omitempty"`
	SSHForwardSockets     []string `json:"ssh_forward_sockets,omitempty"`
	SFTP                  *bool    `json:"sftp,omitempty"`
	// Files builtin (embedded File Browser). Files toggles the mount;
	// FilesAllowWrite flips read-only⇄read-write (all write ops together);
	// FilesScope sets the confined root (nil = leave unchanged, empty
	// string = the OS user's home). FilesAllowWrite is intentionally only
	// settable here on the loopback admin plane — the cloud-facing surface
	// has no path to it, which is what keeps "read-only by default" a real
	// guarantee rather than a default.
	Files           *bool   `json:"files,omitempty"`
	FilesAllowWrite *bool   `json:"files_allow_write,omitempty"`
	FilesScope      *string `json:"files_scope,omitempty"`
	Podman          *bool   `json:"podman,omitempty"`
	Sandbox         *bool   `json:"sandbox,omitempty"`
	Ollama          *bool   `json:"ollama,omitempty"`
	OllamaPool      *bool   `json:"ollama_pool,omitempty"`
	// WarmServing toggles the adaptive, considerate warm-serving plane:
	// keep a small conservative set of models resident (zero cold-start),
	// yielding (unloading) whenever the host is busy with the user's own
	// work and restoring when idle. Default ON for a paired Ollama node.
	// WarmBudgetFrac sets the fraction of usable memory dedicated to warm
	// preload (clamped to (0,1]; default 0.33). nil = leave unchanged.
	WarmServing            *bool           `json:"warm_serving,omitempty"`
	WarmBudgetFrac         *float64        `json:"warm_budget_frac,omitempty"`
	Otel                   *bool           `json:"otel,omitempty"`
	OtelPool               *bool           `json:"otel_pool,omitempty"`
	Ycode                  *bool           `json:"ycode,omitempty"`
	YcodeShare             *bool           `json:"ycode_share,omitempty"`
	YcodeShareRequireLogin *bool           `json:"ycode_share_require_login,omitempty"`
	YcodeShareSurfaces     map[string]bool `json:"ycode_share_surfaces,omitempty"`
	Cluster                *bool           `json:"cluster,omitempty"`
	ClusterAgent           *bool           `json:"cluster_agent,omitempty"`
	ClusterVirtual         []string        `json:"cluster_virtual,omitempty"`
	// UpdateMode is one of "auto" / "manual" / "never" (see
	// conf.UpdateMode* constants). Pointer-string so nil = "leave
	// unchanged"; non-nil with an invalid value is rejected by
	// SetBuiltins with a 400-class APIError.
	UpdateMode *string `json:"update_mode,omitempty"`
	// AutoRollback arms the auto-rollback watchdog's DESTRUCTIVE revert
	// (default off / observe-only). nil = leave unchanged.
	AutoRollback *bool `json:"auto_rollback,omitempty"`
	// Mesh toggles the libp2p mesh data plane (the peer node carrying
	// authenticated, NAT-traversing peer↔peer streams). MeshPort sets its
	// TCP+QUIC listen port (0 = ephemeral). nil = leave unchanged.
	Mesh     *bool `json:"mesh,omitempty"`
	MeshPort *int  `json:"mesh_port,omitempty"`
	// LANInference toggles the same-LAN direct-inference listener: a
	// LAN-reachable reverse proxy to the local inference server, advertised
	// to cloudbox so same-LAN callers reach this host's LLM directly (lower
	// latency, bypassing the relay). LANInferencePort sets its listen port
	// (0 = default 11435). This is a LAN-TRUST endpoint (no per-request
	// auth) — an explicit opt-in. nil = leave unchanged.
	LANInference     *bool `json:"lan_inference,omitempty"`
	LANInferencePort *int  `json:"lan_inference_port,omitempty"`
	// Shard is the Ollama sharding sub-feature: serve a model bigger than one
	// node by splitting it across mesh peers. nil = leave unchanged; *bool=false
	// opts OUT of the zero-config default (on for an owner-registered Ollama
	// node). ShardPeers selects worker hostnames (nil = leave; empty/["auto"] =
	// every same-LAN peer); ShardRole is "auto"/"leader"/"worker".
	Shard      *bool    `json:"shard,omitempty"`
	ShardPeers []string `json:"shard_peers,omitempty"`
	ShardRole  *string  `json:"shard_role,omitempty"`
	// Back-compat convenience for the generic bashy service "loom".
	Loom     *bool `json:"loom,omitempty"`
	LoomPort *int  `json:"loom_port,omitempty"`
	// Back-compat convenience for the generic bashy service "meet" (the
	// web chat room). Like Loom/LoomPort, but with NO mesh service — a
	// personal chat room has no peer consumer. The Command base
	// (["meet","service"]) is pinned in DefaultBashyServices so the
	// supervisor drives `bashy meet service {start,status,stop}`.
	Meet     *bool `json:"meet,omitempty"`
	MeetPort *int  `json:"meet_port,omitempty"`
	// BashyServices replaces the whole generic service set when non-nil.
	BashyServices []conf.BashyService `json:"bashy_services,omitempty"`
	// BashyVersion pins the bashy release the self-heal auto-install fetches
	// when bashy is missing ("" / "latest" = newest; a tag pins it). Takes
	// effect on the next restart. nil = leave unchanged.
	BashyVersion *string `json:"bashy_version,omitempty"`
	// Zot toggles running the Zot OCI registry as a managed external binary on a
	// loopback port, auto-exposed over the mesh as `registry`. ZotPort sets its
	// HTTP port (0 = default 5000). nil = leave unchanged.
	Zot     *bool `json:"zot,omitempty"`
	ZotPort *int  `json:"zot_port,omitempty"` // Seaweedfs toggles running SeaweedFS (object/blob store, S3 gateway) as a
	// managed external binary on a loopback port, auto-exposed over the mesh as
	// `s3`. SeaweedfsPort sets its S3 port (0 = default 8333). nil = unchanged.
	Seaweedfs     *bool `json:"seaweedfs,omitempty"`
	SeaweedfsPort *int  `json:"seaweedfs_port,omitempty"`
	// Kopia toggles running the Kopia snapshot-backup repository server as a
	// managed external binary on a loopback port, auto-exposed over the mesh as
	// `backup`. KopiaPort sets its port (0 = default 51515). nil = unchanged.
	Kopia     *bool `json:"kopia,omitempty"`
	KopiaPort *int  `json:"kopia_port,omitempty"`

	// Actrunner toggles running Gitea act_runner (the CI executor) as a managed
	// external binary. Unlike loom/zot it's a CONSUMER: it registers against a
	// Gitea instance and dials OUT. ActrunnerInstance is the Gitea base URL
	// (empty = local loom forge); ActrunnerToken is the registration token;
	// ActrunnerLabels are the executor labels (default "host:host"). nil = unchanged.
	Actrunner         *bool   `json:"actrunner,omitempty"`
	ActrunnerInstance *string `json:"actrunner_instance,omitempty"`
	ActrunnerToken    *string `json:"actrunner_token,omitempty"`
	ActrunnerLabels   *string `json:"actrunner_labels,omitempty"`
	// CloudDOEnabled toggles Digital Ocean provider support; CloudDOToken is the
	// DO API token (exported as DIGITALOCEAN_ACCESS_TOKEN). nil = unchanged.
	CloudDOEnabled *bool   `json:"cloud_do_enabled,omitempty"`
	CloudDOToken   *string `json:"cloud_do_token,omitempty"`
	// ActrunnerSandbox opts the runner into the tier-3 sandbox (container)
	// executor (runs-on: sandbox → OCI container via bashy podman), additive to
	// the host build lane. ActrunnerSandboxImage / ActrunnerDockerHost override
	// the image / DOCKER_HOST (empty docker-host = auto-resolve bashy podman).
	ActrunnerSandbox      *bool   `json:"actrunner_sandbox,omitempty"`
	ActrunnerSandboxImage *string `json:"actrunner_sandbox_image,omitempty"`
	ActrunnerDockerHost   *string `json:"actrunner_docker_host,omitempty"`

	// headlamp toggles deploying Headlamp (the operating UI) on the peer DKS
	// plane. HeadlampPort sets its supervised loopback forward port (0 = default
	// 18466). nil = leave unchanged. See docs/peer-dks-headlamp.md.
	Headlamp     *bool `json:"headlamp,omitempty"`
	HeadlampPort *int  `json:"headlamp_port,omitempty"`
}

type BuiltinsResult struct {
	OK             bool `json:"ok"`
	RestartPending bool `json:"restart_pending"`
}

type BundleApplyParams struct {
	// Kubeconfig is the venue. Empty falls back to the persisted
	// cluster.bundle_kubeconfig, then to the conventional peer
	// control-plane path (~/.kube/outpost-control-plane/k3s.yaml). It is
	// canonicalized (symlinks resolved) and refused when it lands on the
	// cloudbox kubeconfig — whichever source supplied it.
	Kubeconfig string `json:"kubeconfig,omitempty"`
	// Bundle is the manifest file or directory to apply (required).
	Bundle string `json:"bundle"`
	// TimeoutSeconds bounds the readiness wait for the whole bundle.
	// Default 300.
	TimeoutSeconds int `json:"timeout_seconds,omitempty"`
	// PollSeconds is the readiness re-check interval. Default 2.
	PollSeconds int `json:"poll_seconds,omitempty"`
	// CRDTimeoutSeconds bounds, per CRD, the Established+discovery wait
	// before dependent custom resources apply. Default 60.
	CRDTimeoutSeconds int `json:"crd_timeout_seconds,omitempty"`
	// AllowScaleToZero is the explicit opt-in for spec.replicas: 0
	// workloads counting as rolled out once drained.
	AllowScaleToZero bool `json:"allow_scale_to_zero,omitempty"`
	// NoRollback leaves objects this run created in place on failure
	// (still reported precisely).
	NoRollback bool `json:"no_rollback,omitempty"`
	// SaveKubeconfig persists a non-empty Kubeconfig as
	// cluster.bundle_kubeconfig after the venue guard accepts it, so
	// later applies can omit the path. Live — no restart.
	SaveKubeconfig bool `json:"save_kubeconfig,omitempty"`
}

type BundleApplyResult struct {
	OK bool `json:"ok"`
	// Kubeconfig is the CANONICAL venue the apply ran against (symlinks
	// resolved) — proof of which plane was touched.
	Kubeconfig string `json:"kubeconfig"`
	Applied    int    `json:"applied"`
	Ready      int    `json:"ready"`
	// Created / RolledBack / CleanupFailed are the transactional
	// accounting: what this run brought into existence, and (on the
	// failure path) what the cleanup removed or could not remove.
	Created         []string `json:"created,omitempty"`
	RolledBack      []string `json:"rolled_back,omitempty"`
	CleanupFailed   []string `json:"cleanup_failed,omitempty"`
	KubeconfigSaved bool     `json:"kubeconfig_saved,omitempty"`
}

type BundleCatalogView struct {
	OK       bool     `json:"ok"`
	Catalog  string   `json:"catalog"`
	Builtins []string `json:"builtins"`
}

type BundleKubeconfigView struct {
	OK bool `json:"ok"`
	// Kubeconfig is the persisted cluster.bundle_kubeconfig ("" when
	// unset — applies then default to the conventional peer path).
	Kubeconfig string `json:"kubeconfig"`
	// Default is the conventional peer path used when nothing is
	// persisted or passed.
	Default string `json:"default"`
}

type BundleObjectStatus struct {
	Kind      string `json:"kind"`
	Namespace string `json:"namespace,omitempty"`
	Name      string `json:"name"`
	Exists    bool   `json:"exists"`
	Ready     bool   `json:"ready"`
	Reason    string `json:"reason,omitempty"`
	// Installer marks an outpost.dhnt.io/lifecycle=installer object — judged
	// by its declared durable outputs, not by its own presence (a
	// ttlSecondsAfterFinished Job is reaped by design after success).
	Installer bool `json:"installer,omitempty"`
	// DeclaredOutput marks a row asserted from an installer's
	// outpost.dhnt.io/installs declaration rather than decoded from the
	// manifest.
	DeclaredOutput bool `json:"declared_output,omitempty"`
}

type BundleStatusParams struct {
	// Kubeconfig follows the same resolution and venue guard as
	// BundleApply.
	Kubeconfig string `json:"kubeconfig,omitempty"`
	// Bundle is the manifest file or directory to check (required).
	Bundle string `json:"bundle"`
	// AllowScaleToZero mirrors BundleApply's opt-in: without it a
	// spec.replicas: 0 workload reports not-ready with the same terminal
	// reason an apply would have failed on, instead of "scaled to zero".
	AllowScaleToZero bool `json:"allow_scale_to_zero,omitempty"`
}

type BundleStatusResult struct {
	OK bool `json:"ok"`
	// Kubeconfig is the CANONICAL venue the check ran against.
	Kubeconfig string `json:"kubeconfig"`
	// Installed is true only when every non-installer object exists AND
	// every installer's declared durable outputs exist. An installer's own
	// absence never decides it (see the bundleapply lifecycle contract).
	Installed bool `json:"installed"`
	// AllReady is true only when every asserted object (non-installer
	// bundle objects plus declared installer outputs) exists AND reports
	// Ready — the exact bar BundleApply's readiness wait confirms. A
	// garbage-collected installer does not count against it.
	AllReady bool                 `json:"all_ready"`
	Objects  []BundleObjectStatus `json:"objects"`
}

type BundleUninstallParams struct {
	// Kubeconfig follows the same resolution and venue guard as
	// BundleApply.
	Kubeconfig string `json:"kubeconfig,omitempty"`
	// Bundle is the manifest file or directory to remove (required).
	Bundle string `json:"bundle"`
	// TimeoutSeconds bounds an optional wait for the deleted objects to
	// actually vanish. 0 skips the wait (delete-and-return).
	TimeoutSeconds int `json:"timeout_seconds,omitempty"`
	// PollSeconds is the gone-check re-poll interval. Default 2.
	PollSeconds int `json:"poll_seconds,omitempty"`
}

type BundleUninstallResult struct {
	OK bool `json:"ok"`
	// Kubeconfig is the CANONICAL venue the uninstall ran against.
	Kubeconfig string `json:"kubeconfig"`
	// Deleted lists the objects (kind ns/name) this run removed, in
	// reverse apply order.
	Deleted []string `json:"deleted,omitempty"`
	// Failed lists objects that could NOT be deleted — left behind for
	// the operator to remove by hand.
	Failed []string `json:"failed,omitempty"`
	// Gone is the count confirmed absent after the wait (only meaningful
	// when TimeoutSeconds > 0).
	Gone int `json:"gone,omitempty"`
}

type ClusterLLMView struct {
	Configured         bool   `json:"configured"`
	Backend            string `json:"backend,omitempty"`
	State              string `json:"state"`
	Endpoint           string `json:"endpoint,omitempty"`
	Version            string `json:"version,omitempty"`
	HasAPIKey          bool   `json:"has_api_key"`
	MemberCount        int    `json:"member_count,omitempty"`
	AggregateVRAMBytes uint64 `json:"aggregate_vram_bytes,omitempty"`
}

type ClusterView struct {
	Enabled       bool     `json:"enabled"`
	Agent         bool     `json:"agent"`
	Virtual       []string `json:"virtual,omitempty"`
	APIURL        string   `json:"api_url,omitempty"`
	NodeName      string   `json:"node_name,omitempty"`
	HasToken      bool     `json:"has_token"`
	HasCA         bool     `json:"has_ca"`
	HasNodeToken  bool     `json:"has_node_token,omitempty"`
	HasSTCPSecret bool     `json:"has_stcp_secret,omitempty"`
	K8sAPIPort    int      `json:"k8s_api_port,omitempty"`
	// ControlPlane reports whether this host HOSTS the apiserver rather than
	// merely joining a cluster. Surfaced because it changes what the host is:
	// a control-plane host runs a tunnel server other machines depend on, so
	// restarting it is a cluster-wide event rather than a local one.
	//
	// NOT omitempty. This flag has a history of being dropped by config-write
	// paths (see mergePairing's inverted merge), and an omitempty bool renders
	// the dropped case and the never-hosted case identically as a missing key —
	// so `outpost status` answered "is this host the control plane?" with null
	// either way. An explicit false is the whole point of reporting it.
	ControlPlane bool `json:"control_plane"`
	// ControlPlaneKubeconfig is the path to the admin kubeconfig for the plane
	// this host HOSTS. Reported because it is the input the control-plane
	// reconcilers resolve at boot: an empty value means they declined to start,
	// which is directly observable here instead of only in the daemon log. It
	// is a path, not a credential — the file's contents never leave the host.
	ControlPlaneKubeconfig string `json:"control_plane_kubeconfig,omitempty"`
	TunnelBindAddr         string `json:"tunnel_bind_addr,omitempty"`
	TunnelBindPort         int    `json:"tunnel_bind_port,omitempty"`
	HasTunnelToken         bool   `json:"has_tunnel_token,omitempty"`
	TunnelLANExposed       bool   `json:"tunnel_lan_exposed,omitempty"`
	// JoinEndpoint names the PEER-hosted control plane this host joins, empty
	// when it joins the cloudbox-hosted one. The address is reportable; the
	// credential that goes with it is not, so only its presence appears here —
	// same treatment cluster.token and the tunnel token get.
	JoinEndpoint string `json:"join_endpoint,omitempty"`
	HasJoinToken bool   `json:"has_join_token,omitempty"`
	// HasCloudSTCPSecret reports whether cloudbox's own cluster STCP secret
	// is retained (cluster.cloud_stcp_secret) — the credential a
	// peer-joined worker's overlay-control relay needs to register on the
	// tailnet. Its absence is why a peer-flannel runtime refuses to start,
	// so the presence flag is what makes that refusal diagnosable from the
	// UI/MCP without reading daemon logs.
	HasCloudSTCPSecret bool `json:"has_cloud_stcp_secret,omitempty"`
	// PodNetworkMode is "overlay" (cloudbox allocated a per-node pod
	// CIDR), "peer-flannel" (a peer-hosted plane; stock flannel VXLAN
	// over the tailnet allocates from Node.spec.podCIDR — also
	// multi-node-correct, and PodCIDR is empty because this side does
	// not know it), or "single-node-fallback" (no CIDR: a fixed range
	// identical on every node, so pod IPs collide the moment a second
	// node joins). Read-only derived state,
	// not a config key — see runtime.ClassifyPodNetwork. PodCIDR is the
	// range that mode actually allocates from.
	PodNetworkMode string `json:"pod_network_mode,omitempty"`
	PodCIDR        string `json:"pod_cidr,omitempty"`
	// Observability fleet-aggregation URLs cloudbox provisioned for
	// this outpost. Empty when the AppStore observability bundle
	// isn't installed; non-empty means ycode is expected to
	// remote_write metrics / push logs / OTLP-export traces here
	// through the tailscale overlay.
	MetricsRemoteURL string `json:"metrics_remote_url,omitempty"`
	LogsRemoteURL    string `json:"logs_remote_url,omitempty"`
	TracesRemoteURL  string `json:"traces_remote_url,omitempty"`
}

type ControlPlaneParams struct {
	Enabled  *bool   `json:"enabled,omitempty"`
	BindAddr *string `json:"bind_addr,omitempty"`
	BindPort *int    `json:"bind_port,omitempty"`
}

type ControlPlaneResult struct {
	OK           bool   `json:"ok"`
	ControlPlane bool   `json:"control_plane"`
	BindAddr     string `json:"bind_addr"`
	BindPort     int    `json:"bind_port"`
	HasToken     bool   `json:"has_token"`
	// TunnelToken is empty unless the caller asked to reveal or rotate it.
	TunnelToken string `json:"tunnel_token,omitempty"`
	// STCPSecret is the SECOND credential a worker needs — it authorizes
	// reaching the published apiserver, where the token authorizes the tunnel
	// session itself. Revealed on the same terms as the token: a worker given
	// only one of the two fails, so handing over one without the other would
	// be a half-answer.
	STCPSecret string `json:"stcp_secret,omitempty"`
	// APIAddr is where the apiserver listens on THIS host — what the
	// publisher bridges workers to.
	APIAddr string `json:"api_addr,omitempty"`
	// LANExposed is true when the bind address is not loopback. Surfaced as
	// its own flag rather than left for the reader to infer from an address,
	// because "this host is accepting cluster joins from the network" is the
	// one property of this config worth noticing at a glance.
	LANExposed     bool `json:"lan_exposed"`
	RestartPending bool `json:"restart_pending"`
	// WorkerRejoinHint is the recovery instruction for a token rotation — set
	// only by RotateControlPlaneToken. A rotate that just prints "reconfigure
	// your workers" and stops is not a recovery path, it is a warning; this is
	// the actual command, safe to display because it never embeds a literal
	// secret (see ControlPlaneTokenRotationHint).
	WorkerRejoinHint string `json:"worker_rejoin_hint,omitempty"`
}

type ControlPlaneStatus struct {
	// Hosted is true when this host is configured to host a control plane.
	Hosted bool `json:"hosted"`

	// ContainerExists reports whether the control-plane container exists.
	ContainerExists bool `json:"container_exists"`
	// ContainerRunning reports whether the control-plane container is running.
	// Only meaningful when ContainerExists is true.
	ContainerRunning bool `json:"container_running"`

	// APIServerServing reports whether the apiserver is accepting HTTP connections.
	// Requires the container to be running; a dead container always has
	// APIServerServing false.
	APIServerServing bool `json:"apiserver_serving"`
	// APIServerStatusCode is the HTTP status when APIServerServing is true.
	APIServerStatusCode int `json:"apiserver_status_code,omitempty"`

	// Nodes is the list of cluster nodes joining this plane, with readiness status.
	// Empty when the plane is not hosted or cannot be queried.
	Nodes []Node `json:"nodes,omitempty"`
	// NodeCount is the number of nodes in the cluster.
	NodeCount int `json:"node_count"`

	// JoinEndpoint is the endpoint URL workers can use to join this control plane.
	// Empty when this host has not configured a join endpoint.
	JoinEndpoint string `json:"join_endpoint,omitempty"`

	// HasJoinToken reports whether a join token credential exists (presence only).
	HasJoinToken bool `json:"has_join_token"`
	// HasNodeToken reports whether a node token credential exists (presence only).
	HasNodeToken bool `json:"has_node_token"`
	// HasSTCPSecret reports whether an STCP secret credential exists (presence only).
	HasSTCPSecret bool `json:"has_stcp_secret"`

	// NodeAddrReconcilerRunning reports whether the apiserver→kubelet address
	// reconciler (internal/agent/nodeaddr) has actually started in this daemon.
	//
	// NOT omitempty, on purpose. False is the interesting value: it is the
	// exact state in which nodes go Ready and schedule pods while every
	// `kubectl logs` / `exec` / `top nodes` fails, because no Node ever
	// received the unique loopback ExternalIP the apiserver dials kubelets
	// through. Hiding a false here would hide the diagnosis.
	NodeAddrReconcilerRunning bool `json:"nodeaddr_reconciler_running"`
	// NodeAddrLastRunAt is when its most recent reconcile pass completed.
	NodeAddrLastRunAt time.Time `json:"nodeaddr_last_run_at,omitzero"`
	// NodeAddrLastError is its most recent pass error, empty when healthy.
	// Running-and-failing and never-started are different problems with
	// different fixes; this is what tells them apart.
	NodeAddrLastError string `json:"nodeaddr_last_error,omitempty"`

	// CheckedAt is when this status was last measured.
	CheckedAt time.Time `json:"checked_at,omitzero"`
}

type ControlPlaneStatusProber interface {
	// ProbeControlPlaneStatus returns the current health and readiness.
	ProbeControlPlaneStatus(ctx context.Context) (ControlPlaneStatus, error)
}

type Deps struct {
	// ConfigPath is where the persistent FileConfig lives. The Server
	// serializes all read-modify-write sequences against ConfigPath
	// under its own mutex.
	ConfigPath string

	// Apps is the live registry — admincore mutates it directly when
	// the operator adds/removes/toggles custom apps. Concurrent-safe.
	Apps *agent.AppRegistry

	// Outbound manages local mount paths that proxy through cloudbox
	// to remote outposts' apps. Optional — when nil the outbound
	// operations report "not configured" rather than panic.
	Outbound *agent.OutboundManager

	// Restart, when set, is invoked (debounced) after a save that
	// requires the tunnel or built-in routes to reload. Nil during
	// tests; admincore short-circuits ScheduleRestart in that case.
	Restart func()

	// CloudboxBase + CloudboxAccessToken + AgentName feed the outbound-
	// suggestions endpoint and the provisioning relay. CloudboxBase is
	// empty until pairing completes; admincore returns a clear error
	// instead of dialing nothing when the bearer is absent.
	CloudboxBase        string
	CloudboxAccessToken string
	AgentName           string

	// LLMPoolStatus, when set, returns the live pool diagnostic block
	// rendered into SafeView. Nil when the pool service wasn't wired
	// (Ollama off or daemon undetected). Closure rather than a concrete
	// type so admincore doesn't import the ollama package.
	LLMPoolStatus func() LLMPoolStatusView

	// PeerTiers, when set, returns the latest measured peer-locality tiers
	// (the p2p peer-plane probe's ground truth — TP/LAN/WAN per peer).
	// Closure so admincore doesn't import the peerplane package. Nil when
	// the service isn't wired.
	PeerTiers func() []PeerTierView

	// MeshStatus, when set, returns the libp2p mesh host's live status
	// (peer ID, listen addrs, connected-peer count). Closure so admincore
	// doesn't import the mesh package. Nil when the host isn't wired.
	MeshStatus func() *MeshStatusView

	// MeshForward, when set, is the mesh forwarder's operation surface
	// (expose/listen/forwards). Nil when the mesh data plane is off.
	MeshForward MeshForwardOps

	// MeshResolver, when set, queries the cloudbox service registry for the
	// peers exposing a named mesh service (the "who runs <service>" lookup).
	// Closure so admincore doesn't import the peerplane client. Nil when the
	// host isn't paired / mesh is off.
	MeshResolver func(service string) ([]MeshResolvedPeer, error)

	// MeshLinkInfoByHost, when set, returns the live mesh link class
	// ("tp"/"lan"/"wan"/"") AND the LAN label of the DIRECT connection to a
	// paired host — the accurate same-LAN signal that overrides cloudbox's
	// egress-IP location heuristic in PeerStatus, enriched with WHICH LAN the
	// link rides over. Closure so admincore doesn't import the mesh package; it
	// captures the rendezvous's host→peer-id map. Nil when the mesh data plane
	// is off.
	MeshLinkInfoByHost func(host string) MeshLinkInfo

	// MeshPeerIDByHost, when set, returns the libp2p peer id the mesh actually
	// connected to <host> with, or "" if none is known. Paired with MeshStatus
	// it answers the only question a transport chooser needs — "is there a live
	// DIRECT connection to this host right now?" — WITHOUT mDNS, multicast, a
	// per-host discovery flag, or a fresh dial. An existing direct connection is
	// itself the proof of reachability. Closure so admincore doesn't import the
	// mesh package. Nil when the mesh data plane is off.
	MeshPeerIDByHost func(host string) string

	// ShardTrigger, when set, tells <host> to LEAD a shard for <model> over
	// the mesh (no ssh). Closure so admincore doesn't import the shard /
	// peerplane packages; it captures the shard.Manager + host→peer-id
	// resolution. Nil when sharding / mesh isn't wired.
	ShardTrigger func(ctx context.Context, host, model string) error

	// ShardStatus, when set, returns a node's shard readiness over the mesh:
	// the local node when host == "", otherwise a resolved peer. Returns an
	// opaque value (a shard.StatusReport) the HTTP layers JSON-encode. Nil
	// when sharding / mesh isn't wired.
	ShardStatus func(ctx context.Context, host string) (any, error)

	// ShardLog, when set, returns a node's recent prima-rank shard logs over
	// the mesh: the local node when host == "", otherwise a resolved peer.
	// Closure (captures the shard.Manager + host→peer-id resolution). Nil when
	// sharding / mesh isn't wired.
	ShardLog func(ctx context.Context, host string) (string, error)

	// ClusterRuntimeDown, when set, SYNCHRONOUSLY stops this node's cluster
	// runtime container and — when purge is true — removes its persistent-
	// identity volumes (k3s node-id / tailscale machine key / CNI). LeaveCluster
	// calls it only when the node was actually active, and with a plane-
	// dependent purge: purge=true for a cloud-managed node, because cloudbox
	// has already deleted its Headscale registration and a stale machine key
	// would leave the overlay unable to converge on rejoin; purge=false for a
	// peer-joined worker, because leave never deregisters anything on the peer
	// plane and purging the local identity would desync it from a registration
	// that still exists there — the overlay identity is preserved instead.
	// Closure so admincore doesn't import the runtime package. Nil in tests /
	// when the cluster runtime isn't wired.
	ClusterRuntimeDown func(ctx context.Context, purge bool) error

	// AppHealth, when set, returns the latest per-app reachability
	// measurements (TCP/HTTP probes, no ICMP). Nil when the service
	// isn't wired.
	AppHealth func() []AppHealthView

	// Upgrader + UpgradeLedger feed the Update tab on the admin UI
	// and the corresponding MCP tools. Nil on unpaired hosts (the
	// route falls back to a graceful 404 — see handlers/server.go
	// for the gate). Threaded through admincore so the surface
	// stays uniform across MCP / REST / future CLI.
	Upgrader      *upgrade.Worker
	UpgradeLedger *upgrade.Ledger

	// Backup, when set, is the live scheduler+worker for the folder-
	// watcher backup feature (admincore/backup.go). Optional — when
	// nil, SetBackup still persists the config to FileConfig (so a
	// future restart with the manager wired picks it up) but cannot
	// re-register the scheduler entry live.
	Backup BackupApplier

	// ControlPlaneStatusProber, when set, probes the hosted control plane's
	// container health, apiserver readiness, and cluster node count. Nil when
	// the cluster runtime isn't wired (no hosted plane configured). The probe
	// reuses existing readiness surfaces (runtime.CheckServer, runtime.ProbeAPIServer,
	// cached LastServerHealth) and threads them through an interface seam for
	// testing. Closure-captured dependencies keep admincore focused.
	ControlPlaneStatusProber ControlPlaneStatusProber

	// BundleApplyClient, when set, builds the Kubernetes client
	// BundleApply drives — tests inject a deterministic fake here. Nil
	// means the production bundleapply.NewDynamicClient. The kubeconfig
	// argument is ALREADY canonicalized and venue-checked: admincore runs
	// bundleapply.ResolveVenue before calling the factory, so an injected
	// client can never bypass the cloudbox-venue guard.
	BundleApplyClient func(kubeconfig string) (bundleapply.ResourceClient, error)

	// PeerImage, when set, is the peer image distribution engine (the four
	// verbs publish / mesh-resolve / ensure / report) backing
	// admincore/peerimage.go. Nil when the feature is off or its prerequisites
	// (cluster runtime, recipe store) aren't met — the verbs then report
	// "not enabled" rather than panicking. Interface so admincore never
	// imports the peerimage wiring details, and so the parity tests can
	// substitute a recording fake.
	PeerImage PeerImageOps
}

type ExecSSHParams struct {
	// Name is the configured target alias (`outpost ssh add <name>`).
	Name string

	// Command is the literal command line to run on the remote host.
	// Quoting / escaping is the caller's responsibility — this is
	// fed verbatim to `ssh.Session.Run`.
	Command string

	// JumpOverride, when non-empty, overrides the target's persisted
	// Via field for this one call (analogous to ssh's `-J <alias>`).
	// Use the empty string to honor the on-disk Via.
	JumpOverride string

	// Timeout caps the remote process's wall-clock runtime. Default
	// 60s; capped at 600s server-side to keep MCP callers from
	// holding the connection forever.
	Timeout time.Duration

	// MaxStdout / MaxStderr cap captured output. Default 1 MiB / 256 KiB.
	MaxStdout int64
	MaxStderr int64

	// Stdin, when non-nil, is fed to the remote process. The MCP
	// surface accepts base64-encoded bytes and constructs an
	// io.Reader here; CLI callers (outpost repair remote-binary,
	// etc.) can pass any io.Reader directly. Closed when copy
	// completes (sshclient does this).
	Stdin io.Reader
}

type ExecSSHResult struct {
	Stdout          []byte `json:"stdout"`
	Stderr          []byte `json:"stderr"`
	ExitCode        int    `json:"exit_code"`
	StdoutTruncated bool   `json:"stdout_truncated,omitempty"`
	StderrTruncated bool   `json:"stderr_truncated,omitempty"`
}

type KubeconfigResult struct {
	OK             bool        `json:"ok"`
	Cluster        ClusterView `json:"cluster"`
	RestartPending bool        `json:"restart_pending"`
	// Peer is true when LeaveCluster acted on a node that had joined a
	// PEER-hosted control plane rather than the cloudbox-hosted one. Surfaced
	// so a caller (the CLI) knows to SKIP the cloudbox reclaim: cloudbox never
	// issued this node, the peer plane did, and the worker holds no admin
	// credential to delete the Node object from that plane's apiserver — that
	// deletion is the control-plane host's garbage-collection story, not the
	// worker's. omitempty so the cloud path's result is unchanged.
	Peer bool `json:"peer,omitempty"`
}

type LLMPoolStatusView struct {
	Enabled     bool      `json:"enabled"`
	Running     bool      `json:"running"`
	LastPushAt  time.Time `json:"last_push_at,omitzero"`
	LastModels  int       `json:"last_models"`
	PushCount   int64     `json:"push_count"`
	LastError   string    `json:"last_error,omitempty"`
	MaxParallel int       `json:"max_parallel"`
	InFlight    int       `json:"in_flight"`
	CloudboxURL string    `json:"cloudbox_url,omitempty"`
	OllamaURL   string    `json:"ollama_url,omitempty"`
}

type MeshConsumeView struct {
	Service   string `json:"service"`
	PeerID    string `json:"peer_id"`
	LocalAddr string `json:"local_addr"`
}

type MeshForwardOps interface {
	Expose(service, addr string) error
	Unexpose(service string) error
	Listen(peerID, service, localAddr string) (boundAddr string, err error)
	CloseListen(addr string) error
	Forwards() MeshForwardView
}

type MeshForwardView struct {
	Exposed   map[string]string  `json:"exposed"`
	Listeners []MeshListenerView `json:"listeners"`
}

type MeshHostLinkView struct {
	Found     bool     `json:"found"`
	PeerID    string   `json:"peer_id,omitempty"`
	Direct    bool     `json:"direct"`
	LinkClass string   `json:"link_class,omitempty"`
	Remote    []string `json:"remote,omitempty"`
}

type MeshLinkInfo struct {
	Class string
	LAN   string
}

type MeshListenerView struct {
	Addr    string `json:"addr"`
	PeerID  string `json:"peer_id"`
	Service string `json:"service"`
}

type MeshPeerConnView struct {
	ID        string   `json:"id"`
	Direct    bool     `json:"direct"`
	LinkClass string   `json:"link_class"`
	Remote    []string `json:"remote,omitempty"`
}

type MeshResolvedPeer struct {
	Host     string   `json:"host"`
	PeerID   string   `json:"peer_id"`
	Services []string `json:"services"`
}

type MeshServiceView struct {
	Name string `json:"name"`
	Addr string `json:"addr"`
}

type MeshStatusView struct {
	PeerID         string             `json:"peer_id"`
	ListenAddrs    []string           `json:"listen_addrs,omitempty"`
	ConnectedPeers int                `json:"connected_peers"`
	Peers          []MeshPeerConnView `json:"peers,omitempty"`
}

type MirrorJobView struct {
	Source  string `json:"source"`
	Service string `json:"service"`
	LANOnly bool   `json:"lan_only"`
}

type MirrorView struct {
	Enabled bool            `json:"enabled"`
	Jobs    []MirrorJobView `json:"jobs"`
}

type NetworkingParams struct {
	// LocalAddr — bind for the matrix-tunnel ingress. Empty to clear.
	// Use *string so callers can distinguish "leave alone" (nil) from
	// "clear to default" (pointer to "").
	LocalAddr *string `json:"local_addr,omitempty"`
	// VNCAddr — upstream for the /desktop bridge.
	VNCAddr *string `json:"vnc_addr,omitempty"`
	// AdminAddr — bind for the admin UI + MCP listener.
	AdminAddr *string `json:"admin_addr,omitempty"`
	// AdminUsers — when non-nil, replaces the entire allowlist. Pass
	// an empty slice to revert to the legacy "anyone with the OS
	// password is admin" mode.
	AdminUsers *[]string `json:"admin_users,omitempty"`

	// DiscoveryEnabled flips the mDNS + HTTP discovery master switch.
	DiscoveryEnabled *bool `json:"discovery_enabled,omitempty"`
	// SSHListenAddr binds the LAN-direct SSH listener. Empty disables.
	SSHListenAddr *string `json:"ssh_listen_addr,omitempty"`
	// DiscoveryHTTPListenAddr binds the /api/v1/discover/* listener.
	DiscoveryHTTPListenAddr *string `json:"discovery_http_listen_addr,omitempty"`
	// PeerTrustPolicy is one of "same-owner" / "same-cloudbox" /
	// "tofu-allow". Validated server-side.
	PeerTrustPolicy *string `json:"peer_trust_policy,omitempty"`

	// ClusterLLMEndpoint is the base URL of an intra-home
	// distributed-inference backend (GPUStack). Empty disables detection.
	// Validated as an http(s) URL. Read once at boot (the detector is
	// built in main.go), so a change restarts like the bind fields.
	ClusterLLMEndpoint *string `json:"cluster_llm_endpoint,omitempty"`
	// ClusterLLMAPIKey is the optional Bearer key for that backend's
	// management API. Empty to clear.
	ClusterLLMAPIKey *string `json:"cluster_llm_api_key,omitempty"`
}

type NetworkingResult struct {
	OK             bool `json:"ok"`
	RestartPending bool `json:"restart_pending"`
}

type Node struct {
	// Name is the node's registered name.
	Name string `json:"name"`
	// Ready reports whether the node is ready to accept workloads.
	Ready bool `json:"ready"`
}

type NodeTokenResult struct {
	OK        bool   `json:"ok"`
	NodeToken string `json:"node_token"`
	// Endpoint is the tunnel address a worker pairs the token with, so the
	// caller can render the whole join line without a second round-trip.
	Endpoint string `json:"endpoint,omitempty"`
}

type OutboundParams struct {
	Path       string `json:"path"`
	Name       string `json:"name"`
	Host       string `json:"host"`
	User       string `json:"user"`
	Scheme     string `json:"scheme,omitempty"`
	LocalPort  int    `json:"local_port,omitempty"`
	TTLSeconds int64  `json:"ttl_seconds,omitempty"`
}

type OutboundSuggestion struct {
	Host         string `json:"host"`
	OsUser       string `json:"os_user,omitempty"`
	Name         string `json:"name"`
	Scheme       string `json:"scheme,omitempty"`
	RequireLogin bool   `json:"require_login"`
	IndexPath    string `json:"index_path,omitempty"`
	Title        string `json:"title,omitempty"`
	Online       bool   `json:"online"`
	Shared       bool   `json:"shared,omitempty"`
}

type PairParams struct {
	Server     string `json:"server,omitempty"`
	Code       string `json:"code"`
	Name       string `json:"name"`
	Title      string `json:"title,omitempty"`
	AuthURL    string `json:"auth_url,omitempty"`
	ClientOnly bool   `json:"client_only,omitempty"`
}

type PairResult struct {
	OK             bool   `json:"ok"`
	AgentName      string `json:"agent_name"`
	RestartPending bool   `json:"restart_pending"`
}

type PeerImageOps interface {
	Publish(ctx context.Context, name, body string) (peerimage.Publication, error)
	Publications() ([]peerimage.Publication, error)
	MeshResolve(ctx context.Context, service string, minimum int) (peerimage.ResolveResult, error)
	Ensure(ctx context.Context, name string) (peerimage.EnsureResult, error)
	Report(ctx context.Context, ch peerimage.Challenge) (peerimage.Report, error)
}

type PeerImageVerb string

type PeerPlaneParams struct {
	// Endpoint is the peer's tunnel server as host or host:port. A bare host
	// takes conf.DefaultTunnelBindPort.
	Endpoint *string `json:"endpoint,omitempty"`
	// Token is the peer's cluster.tunnel_token.
	Token *string `json:"token,omitempty"`
	// STCPSecret authorizes this worker's visitor of the published apiserver.
	STCPSecret *string `json:"stcp_secret,omitempty"`
	// NodeToken is the k3s join token the hosting side prints with
	// `outpost cluster token`.
	NodeToken *string `json:"node_token,omitempty"`
	// APIPort is the LOCAL port this worker's visitor binds the joined
	// apiserver on (cluster.k8s_api_port). Optional; 0 means the 6443 default.
	APIPort *int `json:"api_port,omitempty"`

	// VKBundle is the peer-issued least-privilege virtual-kubelet credential —
	// the FIFTH join value, needed only when a virtual runtime is selected.
	// Minted on the hosting machine with `outpost cluster control-plane
	// vk-credential`; the node token above cannot stand in for it (a k3s
	// node-join token is not an apiserver bearer credential, so presenting it
	// there gets a 401 that reads like a network fault). Applying it writes
	// cluster.ca + cluster.token + cluster.allowed_namespaces and clears any
	// stale client-cert pair — the bundle is authoritative for all three.
	VKBundle *string `json:"vk_bundle,omitempty"`

	// Agent / Virtual select which Nodes this worker registers on the joined
	// plane — cluster.runtimes.agent and cluster.runtimes.virtual, the same
	// two fields SetBuiltins writes and with the same partial-update rules
	// (nil leaves the persisted value alone; a non-nil Virtual REPLACES the
	// complete set, so a non-nil empty slice deselects every virtual backend).
	//
	// A peer plane can host virtual-kubelet nodes as-is: vknode's kubeconfig
	// loader already accepts the client-certificate credentials k3s issues, as
	// distinct from a cloudbox-minted bearer token (see vknode/kubeconfig.go).
	// So this is selection, not new runtime support — before it existed a
	// worker could only reach a vk node by hand-editing agent.json.
	//
	// Leaving BOTH nil preserves the historical behaviour exactly: the join
	// falls through to selecting the agent runtime, and only when nothing is
	// selected already.
	Agent   *bool    `json:"cluster_agent,omitempty"`
	Virtual []string `json:"cluster_virtual,omitempty"`
}

type PeerPlaneResult struct {
	OK bool `json:"ok"`
	// Joined is true when a peer endpoint is configured, i.e. this host joins
	// a plane OTHER than the cloudbox-hosted one.
	Joined   bool   `json:"joined"`
	Endpoint string `json:"endpoint,omitempty"`
	APIPort  int    `json:"api_port,omitempty"`

	HasToken      bool `json:"has_token"`
	HasSTCPSecret bool `json:"has_stcp_secret"`
	HasNodeToken  bool `json:"has_node_token"`

	// HasVKCredential / VKCredentialKind report whether a virtual-kubelet node
	// on this worker can authenticate to the joined apiserver, and with which
	// credential form ("token" from a vk bundle, or "client-cert" when the
	// operator provisioned a k3s client-certificate pair by hand). Presence
	// only — the credential itself is never returned.
	HasVKCredential  bool   `json:"has_vk_credential"`
	VKCredentialKind string `json:"vk_credential_kind,omitempty"`
	// AllowedNamespaces is the fail-closed namespace policy the vk nodes
	// enforce. Namespace NAMES are policy, not secrets, so they are reported
	// verbatim — an operator debugging "every pod is denied" needs to see the
	// list, not a boolean.
	AllowedNamespaces []string `json:"allowed_namespaces,omitempty"`

	// ClusterEnabled reflects cluster.enabled AFTER the operation. Surfaced
	// because a join that persisted its credentials but left cluster mode off
	// looks successful and does nothing.
	ClusterEnabled bool `json:"cluster_enabled"`
	RestartPending bool `json:"restart_pending"`

	// RuntimeAgent / RuntimeVirtual report the runtime selection AFTER the
	// operation — which Nodes this worker will register. Reported because the
	// join's default is implicit (agent when nothing was selected), so without
	// this an operator cannot tell a defaulted selection from one they made.
	RuntimeAgent   bool     `json:"runtime_agent"`
	RuntimeVirtual []string `json:"runtime_virtual,omitempty"`
}

type PeerTierView struct {
	Host              string    `json:"host"`
	Tier              string    `json:"tier"`
	RTTms             float64   `json:"rtt_ms"`
	Addr              string    `json:"addr,omitempty"`
	EgressSameLANHint bool      `json:"egress_same_lan_hint"`
	At                time.Time `json:"at,omitzero"`
}

type SSHTargetView = conf.SSHTarget

type SafeView struct {
	AgentName   string `json:"agent_name"`
	ServerAddr  string `json:"server_addr"`
	ServerPort  int    `json:"server_port"`
	CloudboxURL string `json:"cloudbox_url,omitempty"`
	Protocol    string `json:"protocol,omitempty"`
	RemotePort  int    `json:"remote_port"`
	AuthURL     string `json:"auth_url,omitempty"`
	HasToken    bool   `json:"has_token"`
	LocalAddr   string `json:"local_addr,omitempty"`
	VNCAddr     string `json:"vnc_addr,omitempty"`
	AdminAddr   string `json:"admin_addr,omitempty"`
	// Wave 3A discovery + LAN-direct knobs (all default off).
	DiscoveryEnabled        bool                `json:"discovery_enabled"`
	SSHListenAddr           string              `json:"ssh_listen_addr,omitempty"`
	DiscoveryHTTPListenAddr string              `json:"discovery_http_listen_addr,omitempty"`
	PeerTrustPolicy         string              `json:"peer_trust_policy,omitempty"`
	AssignedHostname        string              `json:"assigned_hostname,omitempty"`
	OAuth2Email             string              `json:"oauth2_email,omitempty"`
	AdminUsers              []string            `json:"admin_users"`
	Apps                    []conf.AppConfig    `json:"apps"`
	ShellEnabled            bool                `json:"shell_enabled"`
	DesktopEnabled          bool                `json:"desktop_enabled"`
	ClipboardEnabled        bool                `json:"clipboard_enabled"`
	SSHEnabled              bool                `json:"ssh_enabled"`
	SSHAllowLocalForward    bool                `json:"ssh_allow_local_forward"`
	SSHAllowRemoteForward   bool                `json:"ssh_allow_remote_forward"`
	SSHAllowAgentForward    bool                `json:"ssh_allow_agent_forward"`
	SSHForwardSockets       []string            `json:"ssh_forward_sockets"`
	SFTPEnabled             bool                `json:"sftp_enabled"`
	FilesEnabled            bool                `json:"files_enabled"`
	FilesAllowWrite         bool                `json:"files_allow_write"`
	FilesScope              string              `json:"files_scope"`
	ClientOnly              bool                `json:"client_only"`
	Podman                  BuiltinView         `json:"podman"`
	Sandbox                 BuiltinView         `json:"sandbox"`
	Ollama                  BuiltinView         `json:"ollama"`
	OllamaPoolEnabled       bool                `json:"ollama_pool_enabled"`
	WarmServingEnabled      bool                `json:"warm_serving_enabled"`
	WarmBudgetFrac          float64             `json:"warm_budget_frac,omitempty"`
	WarmDesired             []string            `json:"warm_desired,omitempty"`
	LANInferenceEnabled     bool                `json:"lan_inference_enabled"`
	LANInferencePort        int                 `json:"lan_inference_port,omitempty"`
	MeshEnabled             bool                `json:"mesh_enabled"`
	MeshPort                int                 `json:"mesh_port,omitempty"`
	BashyServices           []conf.BashyService `json:"bashy_services,omitempty"`
	BashyVersion            string              `json:"bashy_version,omitempty"`
	ShardEnabled            bool                `json:"shard_enabled"`
	LoomEnabled             bool                `json:"loom_enabled"`
	LoomPort                int                 `json:"loom_port,omitempty"`
	MeetEnabled             bool                `json:"meet_enabled"`
	MeetPort                int                 `json:"meet_port,omitempty"`
	ZotEnabled              bool                `json:"zot_enabled"`
	ZotPort                 int                 `json:"zot_port,omitempty"`
	SeaweedfsEnabled        bool                `json:"seaweedfs_enabled"`
	SeaweedfsPort           int                 `json:"seaweedfs_port,omitempty"`
	KopiaEnabled            bool                `json:"kopia_enabled"`
	KopiaPort               int                 `json:"kopia_port,omitempty"`
	ActrunnerEnabled        bool                `json:"actrunner_enabled"`
	ActrunnerInstance       string              `json:"actrunner_instance,omitempty"`
	ActrunnerLabels         string              `json:"actrunner_labels,omitempty"`
	ActrunnerSandbox        bool                `json:"actrunner_sandbox"`
	ActrunnerSandboxImage   string              `json:"actrunner_sandbox_image,omitempty"`
	ActrunnerDockerHost     string              `json:"actrunner_docker_host,omitempty"`
	HeadlampEnabled         bool                `json:"headlamp_enabled"`
	HeadlampPort            int                 `json:"headlamp_port,omitempty"`
	CloudDOEnabled          bool                `json:"cloud_do_enabled"`
	HasCloudDOToken         bool                `json:"has_cloud_do_token"`
	OtelEnabled             bool                `json:"otel_enabled"`
	OtelPoolEnabled         bool                `json:"otel_pool_enabled"`
	Ycode                   YcodeView           `json:"ycode"`
	YcodeShareEnabled       bool                `json:"ycode_share_enabled"`
	YcodeShareRequireLogin  bool                `json:"ycode_share_require_login"`
	// YcodeShareSurfaces is the catalog rendered as effective state:
	// every entry the SPA might offer, with the boolean folding the
	// per-surface overlay against the catalog's DefaultOn. The SPA
	// renders one toggle row per entry; the value drives the switch.
	YcodeShareSurfaces []YcodeShareSurfaceView `json:"ycode_share_surfaces"`
	UpdateMode         string                  `json:"update_mode"`
	LLMPool            LLMPoolStatusView       `json:"llm_pool"`
	PeerTiers          []PeerTierView          `json:"peer_tiers,omitempty"`
	Mesh               *MeshStatusView         `json:"mesh,omitempty"`
	AppHealth          []AppHealthView         `json:"app_health,omitempty"`
	ClusterLLM         ClusterLLMView          `json:"cluster_llm"`
	Cluster            ClusterView             `json:"cluster"`
	ControlPlane       *ControlPlaneStatus     `json:"control_plane,omitempty"`
	Outbound           []agent.OutboundView    `json:"outbound"`
	Defaults           map[string]string       `json:"defaults"`
}

type Server struct {
	// contains filtered or unexported fields
}

type StatusView struct {
	Configured          bool            `json:"configured"`
	AgentName           string          `json:"agent_name,omitempty"`
	ServerAddr          string          `json:"server_addr,omitempty"`
	CloudboxURL         string          `json:"cloudbox_url,omitempty"`
	CurrentOSUser       string          `json:"current_os_user,omitempty"`
	Build               agent.BuildInfo `json:"build"`
	BinaryPath          string          `json:"binary_path,omitempty"`
	ControlPlaneSummary string          `json:"control_plane_summary,omitempty"`
}

type Suggestion struct {
	Name     string `json:"name"`
	Scheme   string `json:"scheme"`
	Socket   string `json:"socket,omitempty"`
	Host     string `json:"host,omitempty"`
	Port     int    `json:"port,omitempty"`
	Role     string `json:"role"`
	Source   string `json:"source"`             // "wellKnown" | "ycodeManifest"
	Note     string `json:"note,omitempty"`     // human-readable hint
	Existing bool   `json:"existing,omitempty"` // already registered with this name
	Managed  bool   `json:"managed,omitempty"`  // bashy start/status/stop service
}

type UpgradeOverview struct {
	Build             agent.BuildInfo       `json:"build"`
	BinaryPath        string                `json:"binary_path,omitempty"`
	UpdateMode        string                `json:"update_mode"`
	RollbackAvailable bool                  `json:"rollback_available"`
	CurrentSource     *UpgradeSource        `json:"current_source,omitempty"`
	Pending           *upgrade.Envelope     `json:"pending,omitempty"`
	History           []upgrade.LedgerEntry `json:"history"`
}

type UpgradeSource struct {
	Kind      string    `json:"kind"`          // "cloudbox" / "cli-url" / "cli-local" / "unknown"
	URL       string    `json:"url,omitempty"` // GitHub release URL for cloudbox / cli-url paths
	ReleaseID string    `json:"release_id,omitempty"`
	At        time.Time `json:"at,omitzero"`
}

type VKCredentialResult struct {
	OK bool `json:"ok"`
	// Bundle is the opaque one-line value a worker passes to
	// `outpost cluster join --vk-bundle`.
	Bundle string `json:"bundle"`
	// Namespaces is the allow-list embedded in the bundle — the namespace
	// policy the worker will enforce fail-closed.
	Namespaces []string `json:"namespaces"`
	// Endpoint is the tunnel address a worker pairs the bundle with, so the
	// caller can render the whole join line without a second round-trip.
	Endpoint string `json:"endpoint,omitempty"`
}

type YcodeShareSurfaceView struct {
	Name      string `json:"name"`
	Path      string `json:"path"`
	Label     string `json:"label"`
	Enabled   bool   `json:"enabled"`
	DefaultOn bool   `json:"default_on"`
}

type YcodeView struct {
	Enabled           bool   `json:"enabled"`
	Running           bool   `json:"running"`
	Installed         bool   `json:"installed"`
	StaleManifest     bool   `json:"stale_manifest"`
	PlatformSupported bool   `json:"platform_supported"`
	BinaryPath        string `json:"binary_path,omitempty"`
	APIEndpoint       string `json:"api_endpoint,omitempty"`
	Version           string `json:"version,omitempty"`
	DownloadURL       string `json:"download_url"`
}