Documentation
¶
Overview ¶
Package session records which agent sessions are running on this machine.
WB is a short-lived command with no daemon, so it cannot observe a session starting. A session announces itself once — from a harness start-up hook, or by hand — and everything WB writes afterwards can be attributed to it without each command being told again.
A record is a claim, not an observation. WB stores what it was told, adds only what it can see for itself (its own version and binary path), and evaluates liveness at read time from the declared PID.
Index ¶
- Constants
- func IsRuntimeProcess(pid int, runtime string) bool
- func NewID() (string, error)
- func Prune(dir string) (int, error)
- type ProcessEvidence
- type Record
- func Lookup(dir string, pid int) (Record, bool)
- func LookupExact(dir string, pid int) (Record, bool, error)
- func MarkParked(dir string, pid int, parkedID string) (Record, error)
- func MarkResumed(dir string, pid int, parkedID, successorWBSessionID string) (Record, error)
- func Register(dir string, record Record) (Record, error)
- func ResolveForProcess(dir string, startPID int) (Record, bool)
- type View
Constants ¶
const ( StateLive = "live" StateGone = "gone" StateParked = "parked" StateResumed = "resumed" )
Liveness states, matching the vocabulary used for worktree owners.
const DirName = "sessions"
DirName is the directory under WB's home that holds session records.
Variables ¶
This section is empty.
Functions ¶
func IsRuntimeProcess ¶ added in v0.98.0
IsRuntimeProcess reports whether pid is the declared harness runtime. This is intentionally narrower than matching arbitrary command-line text: the executable basename identifies the runtime and its role argument identifies the Codex app-server process.
Types ¶
type ProcessEvidence ¶ added in v0.98.0
ProcessEvidence is the kernel-reported identity of a live process. The executable name and positional arguments are kept separate so a nested configuration path cannot make a shell look like a harness.
type Record ¶
type Record struct {
PID int `json:"pid"`
WBSessionID string `json:"wb_session_id,omitempty"`
Machine string `json:"machine,omitempty"`
Runtime string `json:"runtime,omitempty"`
Model string `json:"model,omitempty"`
NativeHarnessID string `json:"native_harness_id,omitempty"`
TmuxName string `json:"tmux_name,omitempty"`
PredecessorWBSessionID string `json:"predecessor_wb_session_id,omitempty"`
HandoffID string `json:"handoff_id,omitempty"`
// AgentID is the legacy spelling for a harness-native session ID. It stays
// readable and writable so existing hooks and PID records continue to
// work; new integrations should use NativeHarnessID.
AgentID string `json:"agent_id,omitempty"`
// WBVersion and WBPath describe the binary that took the registration.
// Several WB builds can coexist — a release on PATH and a local build
// under test — and knowing which one a session used is what makes
// otherwise inexplicable behaviour explicable.
WBVersion string `json:"wb_version,omitempty"`
WBPath string `json:"wb_path,omitempty"`
StartedAt time.Time `json:"started_at"`
// Lifecycle is the local registry projection. Parked sessions remain
// addressable but are never considered live/claimable.
Lifecycle string `json:"lifecycle,omitempty"`
ParkedSessionID string `json:"parked_session_id,omitempty"`
}
Record is one agent session's self-declaration.
func LookupExact ¶ added in v0.60.0
LookupExact reads one live registration through no-follow descriptors and proves that the filename, payload PID, and current process all agree. It is used at the tmux delivery boundary where a path-following convenience read would let a swapped record redirect message bytes.
func MarkParked ¶ added in v0.60.0
MarkParked records the non-live registry projection for a session. The original declaration remains untouched in the PID index. A no-replace lifecycle marker changes the live projection while keeping the source auditable and ensuring session resolution cannot treat a parked owner as active.
func MarkResumed ¶ added in v0.60.0
MarkResumed appends the terminal local registry projection without rewriting either the immutable PID registration or the parked history. An identical retry repairs a crash after the parked-session store finalized.
func Register ¶
Register writes a session record, replacing any record for the same PID. Re-registering is deliberately allowed: a session that restarts its harness or corrects its model should not have to find and delete the old file.
func ResolveForProcess ¶
ResolveForProcess finds the registered session that owns a process, by walking up from startPID and returning the first ancestor that registered and is still live.
This is not the process-tree guessing WB otherwise refuses to do. It matches only against PIDs that explicitly declared themselves, so it confirms a declaration rather than inventing one: an unregistered ancestor is never treated as an owner. Depth is bounded because a corrupted /proc chain must not spin.
Source Files