package cgroup

import "errors"

// ErrUnknown is HostProcs saying it cannot tell how many processes a host
// has left: the platform has no cgroup v2 to read (darwin, windows), or the
// agent runs without a delegated subtree, so its exec children share the
// agent's own cgroup and cannot be told apart. A caller records it as "not
// stopped", never as zero (the offline move's source report, Task 3 of
// docs/superpowers/plans/2026-10-20-offline-operator-move.md).
var ErrUnknown = errors.New("cgroup: the host's processes cannot be counted on this box")

// HostProcs counts the processes left for host on this box:
//
//   - in the host's exec cgroup, root/carlos-exec@<host> (ExecName), and
//     every cgroup below it (an exec child's sidecar and worker groups);
//   - when unit is set, in the cgroup directory unit names and every cgroup
//     below it. unit is an absolute path in the cgroup filesystem: for a
//     nested row the host's slice, which holds its run, generation, seed,
//     sidecar and cmd units alike.
//
// root is the delegated subtree (Manager.Root). A cgroup that does not
// exist holds no process and counts 0. An empty root is ErrUnknown, since
// without delegation the exec children run in the agent's own cgroup.
// Reading never writes, moves or signals anything.
func HostProcs(root, host, unit string) (int, error) {
	return hostProcs(root, host, unit)
}