Documentation
¶
Overview ¶
Package proclive captures a process's identity (PID plus a start-time fingerprint) and later reports whether that exact process is still alive.
It exists to detect agent sessions left in an ACTIVE state when the owning process went away — a clean exit, a crash, a kill, a closed terminal, or a reboot — without firing a SessionStop hook. Recording the owner's identity at turn start lets `entire status` / `entire doctor` notice the process is gone immediately, instead of waiting out a coarse inactivity timeout.
This package is a leaf: it imports only the standard library and golang.org/x/sys/unix. It must NOT import session, strategy, agent, or cli, so those packages can depend on it without an import cycle.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Identity ¶
type Identity struct {
// PID is the operating-system process id of the owner.
PID int `json:"pid"`
// Start is an opaque, per-platform process start-time fingerprint. It need
// only be stable for the process lifetime and distinct across PID reuse
// within a single boot; the Boot guard invalidates it across reboots.
Start string `json:"start"`
// Boot identifies the current OS boot. A mismatch at check time means the
// machine rebooted, so the recorded PID cannot still be the same process.
Boot string `json:"boot,omitempty"`
// Host is the hostname where the identity was recorded. PIDs are only
// meaningful on their own machine, so a mismatch yields Unknown.
Host string `json:"host,omitempty"`
// Name is the owning process's executable name (comm). Diagnostic only.
Name string `json:"name,omitempty"`
}
Identity fingerprints the process that owns a session turn. It is persisted in session state and later passed to Check. The zero value means "no owner recorded" and always yields LivenessUnknown.
func ResolveOwner ¶
ResolveOwner walks up the process tree from the current process and returns the Identity of the first ancestor that is not our own hook binary or a shell — i.e. the long-lived agent that owns this session.
It returns (zero, false) when no such ancestor can be determined: an unsupported platform, a truncated/looping tree, or only transient ancestors. In that case the caller should record no owner and let liveness degrade to the time-based fallback. Resolving to nothing is always safer than recording a guessed PID, which could later be (mis)read as a live or dead owner.
type Liveness ¶
type Liveness int
Liveness is the result of checking a recorded process Identity.
const ( // LivenessUnknown means liveness could not be determined: the identity is // empty, was recorded on another host, or the platform cannot introspect // processes. Callers should fall back to a time-based heuristic. LivenessUnknown Liveness = iota // LivenessAlive means the recorded process is still running. LivenessAlive // LivenessDead means the recorded process is gone (exited, killed, or the // machine rebooted) or its PID has been reused by a different process. LivenessDead )
func Check ¶
Check reports whether the process recorded in id is still alive.
Precedence: an empty identity or a host mismatch is Unknown (cannot judge); a boot mismatch means a reboot, so the process is Dead; a missing PID or a start-fingerprint mismatch (PID reuse) is Dead; otherwise Alive. An unsupported platform is always Unknown so callers fall back to a timeout.
Source Files