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 FindHarnessAncestor(startPID int) (int, string)
- func IsRuntimeProcess(pid int, runtime string) bool
- func NewID() (string, error)
- func ProcessAlive(pid int) bool
- func Prune(dir string) (int, error)
- type AutoRegisterHints
- type ProcessEvidence
- type Record
- func InferRecordForProcess(startPID int, hints AutoRegisterHints) (Record, error)
- func Lookup(dir string, pid int) (Record, bool)
- func LookupByWBSessionID(dir, wbSessionID string) (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)
- func ResolveOrRegisterForProcess(dir string, startPID int, hints AutoRegisterHints) (Record, bool, error)
- 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.
const Unknown = "unknown"
Unknown is what a park-time registration records for an identity field WB was neither told nor able to observe. `wb session list` already shows it for sessions that registered without a model, so it reads as a known gap rather than as a confident lie: a wrong runtime or model is worse than an admitted missing one, and neither is a reason to refuse to park work.
Variables ¶
This section is empty.
Functions ¶
func FindHarnessAncestor ¶ added in v0.153.0
FindHarnessAncestor is the exported form of findHarnessAncestor, for a caller outside this package that needs to know whether a real harness process sits above one it is about to attribute work to before deciding to register a session at all — e.g. internal/worktrees' claim-time auto-registration (wb#631, wb#645 review m7), which must not create a session record for wb's own short-lived PID when no harness is found above it.
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.
func NewID ¶ added in v0.60.0
NewID returns an opaque WB session identity. It is independent of every runtime-specific identifier and safe to carry in file and tmux names.
func ProcessAlive ¶ added in v0.132.0
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. ProcessAlive reports whether a recorded process identity still exists. A PID is only ever a liveness coordinate, never an identity, and a permission error still proves the process exists. It is exported so that every WB subsystem answers this question the same way on every platform.
Types ¶
type AutoRegisterHints ¶ added in v0.104.3
type AutoRegisterHints struct {
PID int
Runtime string
Model string
NativeHarnessID string
// WBSessionID targets one already-registered session instead of resolving
// or registering from this process. It never creates a registration.
WBSessionID string
}
AutoRegisterHints is what a caller explicitly declared about the session it is about to park. A populated field is never overridden by inference: a declaration always outranks an observation.
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"`
// RegisteredAtPark records that this registration was created by
// `wb session park` from what it could observe, rather than declared by an
// explicit `wb session register`. It is provenance, not a lesser status: a
// reader that sees an inferred runtime or model needs to know the session
// never announced them itself.
RegisteredAtPark bool `json:"registered_at_park,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 InferRecordForProcess ¶ added in v0.104.3
func InferRecordForProcess(startPID int, hints AutoRegisterHints) (Record, error)
InferRecordForProcess builds the registration WB would write for a caller that never registered. Every field is either declared by the caller, read from an environment declaration the session already exported, observed from the process tree, or recorded as Unknown. Nothing is invented.
func LookupByWBSessionID ¶ added in v0.104.3
LookupByWBSessionID finds one live registered session by its stable WB session ID. It is how an explicit --wb-session-id targets a session that registered from a process this one is not descended from.
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 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.
func ResolveOrRegisterForProcess ¶ added in v0.104.3
func ResolveOrRegisterForProcess(dir string, startPID int, hints AutoRegisterHints) (Record, bool, error)
ResolveOrRegisterForProcess returns the session that owns startPID, registering one from observable evidence when nothing is registered yet. The second result reports whether this call created that registration.
Requiring a prior `wb session register` before `wb session park` cost more than it protected: an agent that hit the precondition mid-task hand-rolled its own parking instead of using the verb, which is exactly the outcome the verb exists to prevent. Park is therefore free to register the caller first. That is not guessing an owner — nothing here is attributed to some other session — it is WB writing down the identity of the process that asked to be parked, marking it as inferred, and continuing.
Source Files