swarm

type Config struct {
	// NATSConn is the live NATS connection. Manager does not dial; the
	// caller owns connect/disconnect lifecycle. Required.
	NATSConn *nats.Conn

	// BucketName overrides DefaultBucketName. Empty string falls back
	// to the package default.
	BucketName string

	// TTL overrides DefaultTTL on bucket creation. Zero falls back to
	// the package default. Ignored if the bucket already exists with
	// a different TTL — JetStream KV is not destructive on Update.
	TTL time.Duration
}

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

type Session struct {
	// Slot is the slot name (matches the plan's `[slot: X]` annotation).
	// Doubles as the KV bucket key — slot is the primary identifier.
	Slot string `json:"slot"`

	// TaskID identifies the task this slot is currently working on.
	// Lookup against bones-tasks for full task state; this field is a
	// denormalized pointer used by `bones swarm status` and the close
	// verb so they don't need a second lookup.
	TaskID string `json:"task_id"`

	// AgentID is "slot-<name>" — the slot's fossil + coord identity.
	// Matches the agent_id used for the holds and presence buckets so
	// claim ownership and liveness join cleanly across substrates.
	AgentID string `json:"agent_id"`

	// Host is os.Hostname() of the machine running the leaf. Different
	// from the workspace host means another machine owns this slot;
	// `bones swarm` verbs abort with a clear cross-host error rather
	// than try to manage a remote leaf process.
	Host string `json:"host"`

	// LeafPID is the host-local PID of the bones CLI process that
	// wrote this record at join time. Informational only — every
	// swarm verb is its own short-lived CLI invocation, so this PID
	// is already-dead by the time any later verb reads it. Kept as a
	// debugging crumb (a pid that was alive at join means the join
	// did happen on this host) but NOT a liveness signal; use
	// LastRenewed for active/stale classification instead.
	LeafPID int `json:"leaf_pid"`

	// HubURL is the hub fossil HTTP URL recorded at join time. Later
	// verbs read this so they can post-commit push the slot's
	// leaf.fossil to the hub via /xfer without re-deriving the URL
	// from a flag. Empty on records written by older clients;
	// callers fall back to the join-flag default.
	HubURL string `json:"hub_url,omitempty"`

	// StartedAt is when this session record was first written.
	// Immutable once set; later renewals only touch LastRenewed.
	StartedAt time.Time `json:"started_at"`

	// LastRenewed is updated on every `swarm commit` (which heartbeats
	// the session) and used by `bones doctor` to flag stale entries.
	// This is the canonical active/stale signal — see LeafPID for the
	// "why we don't use the pid" discussion.
	LastRenewed time.Time `json:"last_renewed"`
}