swarm

type AcquireOpts struct {
	// HubURL overrides the hub fossil HTTP URL stamped into a fresh
	// session record. Resume reads HubURL from the existing record
	// and ignores this field. Empty → DefaultHubFossilURL.
	HubURL string

	// Hub is an in-process *coord.Hub. When set, the lease's
	// underlying coord.Leaf opens against this Hub directly
	// (LeafConfig.Hub) rather than via HubAddrs. Tests use this to
	// avoid spinning up a separate hub process; the CLI never sets
	// it.
	Hub *coord.Hub

	// Caps overrides fossil capabilities for the slot user on
	// Acquire. Resume ignores this. Empty → DefaultCaps.
	Caps string

	// ForceTakeover lets Acquire CAS-delete an existing same-host
	// session record on the slot. Recovery only — the typical path
	// is an explicit operator decision after `bones doctor`.
	ForceTakeover bool

	// NATSConn is a pre-connected NATS connection. If nil, the lease
	// dials info.NATSURL itself and the resulting connection is
	// closed when the lease is released. When set, the caller owns
	// the connection's lifetime.
	NATSConn *nats.Conn

	// Now is the time source for StartedAt and LastRenewed. nil →
	// time.Now().UTC. Tests inject a fixed clock.
	Now func() time.Time

	// NoAutosync disables the pre-commit hub pull on this lease's
	// underlying coord.Leaf. Default (false) keeps autosync ON,
	// which is the production default per ADR 0023's trunk-linearity
	// promise: every commit pulls from the hub before resolving the
	// trunk tip so the new commit's parent is the hub's-latest-tip,
	// producing one linear chain instead of N parallel forks.
	//
	// Set to true (CLI flag --no-autosync on swarm join / swarm
	// commit) when the caller has an explicit reason to operate in
	// branch-per-slot mode: offline tolerance, single-slot work
	// where no peer commits will race, or testing fan-in semantics.
	// Cost: one less hub HTTP round-trip per commit.
	NoAutosync bool
}

type CloseOpts struct {
	// CloseTaskOnSuccess, when true, calls coord.Leaf.Close on the
	// re-claimed task — closing the task in the bones-tasks bucket
	// in addition to releasing the claim hold. False just releases
	// the claim, leaving the task open for retry by the parent
	// dispatch. swarm close --result=success sets this true; fail
	// and fork leave it false.
	CloseTaskOnSuccess bool

	// NoArtifact, when true, bypasses the "success requires a commit
	// since join" precondition. Per #233 this is a structured boolean
	// opt-in (not a free-form reason string) so a hallucinated
	// rationale cannot leak into the audit trail; the lifecycle event
	// records `no_artifact: true` when set. Ignored when
	// CloseTaskOnSuccess is false (fail and fork results have no
	// artifact requirement).
	NoArtifact bool

	// Reaped, when true, tags the emitted lifecycle event as
	// EventSlotReap rather than EventSlotClose. Set by the
	// `bones swarm reap` verb so post-mortem analysis can tell
	// substrate-driven cleanup ("agent went silent") apart from
	// operator-driven close ("subagent reported done"). No effect
	// on the cleanup mechanics.
	Reaped bool

	// KeepWT, when true, retains the per-slot worktree directory
	// even on a successful close. Default behavior (KeepWT=false
	// + CloseTaskOnSuccess=true) removes the wt so it does not
	// accumulate across cycles. Failed and forked closes
	// (CloseTaskOnSuccess=false) always retain wt regardless of
	// this flag — the operator may need to inspect what the slot
	// left behind.
	KeepWT bool
}

type CommitResult struct {
	UUID       string
	PushResult *agent.SyncResult
	PushErr    error
	RenewErr   error
}

type Config struct {
	// NATSConn is the live NATS connection. Sessions 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 Event struct {
	TS         time.Time `json:"ts"`
	Kind       EventKind `json:"event"`
	Slot       string    `json:"slot"`
	TaskID     string    `json:"task_id,omitempty"`
	AgentID    string    `json:"agent_id,omitempty"`
	Host       string    `json:"host,omitempty"`
	Result     string    `json:"result,omitempty"`
	NoArtifact bool      `json:"no_artifact,omitempty"`
	CommitUUID string    `json:"commit_uuid,omitempty"`
}

type EventKind string

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

type JoinAutoResult struct {
	Slot    string
	WT      string
	TaskID  string
	AgentID string
	ReEntry bool
	Lease   *FreshLease
}

type ResumedLease 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"`
}

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

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

type TagSpec = agent.TagSpec

type WatcherConfig struct {
	// WorkspaceDir is the workspace root. Required — the watcher
	// removes `<workspaceDir>/.bones/swarm/<slot>/wt/` when reaping
	// a stale slot.
	WorkspaceDir string

	// Sessions is the swarm.Sessions handle the watcher reads from
	// and writes to. The watcher does not own the handle's lifetime;
	// the caller closes it when shutting the watcher down.
	Sessions *Sessions

	// TTL is the lease-TTL: any session whose LastRenewed exceeds
	// time.Now() - TTL is reaped. Zero falls back to
	// DefaultWatcherTTL.
	TTL time.Duration

	// Tick is the poll interval. Zero falls back to
	// DefaultWatcherTick.
	Tick time.Duration

	// Logger receives one Infof per reap and one Warnf per
	// substrate error. nil means "silent" (no log spam on the happy
	// path is the hard requirement; a nil logger keeps the watcher
	// from emitting any lines at all).
	Logger WatcherLogger

	// Now is the time source for staleness comparisons. nil →
	// time.Now().UTC. Tests inject a fixed clock.
	Now func() time.Time

	// LocalHostOnly, when true (the default), reaps only sessions
	// whose Host field matches this machine's hostname. Cross-host
	// stale sessions surface in the log but are not reaped — the
	// owning host's PID may still be making local progress, and a
	// remote reap would clobber it. Mirrors `bones swarm reap`'s
	// same-host policy.
	LocalHostOnly bool
}

type WatcherLogger interface {
	Infof(format string, args ...any)
	Warnf(format string, args ...any)
}