cli

Documentation

Overview

In-tree Local Network probing for `leo doctor`.

macOS attributes a network connection to the *responsible* process, not necessarily the one calling connect(2). leo's tmux server is started as a child of the signed leo binary precisely so agent panes inherit leo's Local Network grant (see internal/tmux/server.go). That inheritance can lapse — e.g. once the daemon that created the server has exited — and when it does, third-party binaries under agent sessions are silently denied.

A probe run from the leo CLI process cannot see any of that: leo's own binary holds the grant outright, so it always succeeds. Discriminating requires two things at once — run inside the tmux tree, and run a THIRD-PARTY binary (Apple platform binaries are exempt from Local Network TCC and would report a false pass).

`leo service reparent` — the explicit, operator-chosen repair for a tmux server whose Local Network attribution has lapsed.

Leo adopts a surviving tmux server across daemon restarts on purpose: that is what keeps agent sessions alive through `leo update`. The cost is that the signed leo process macOS holds responsible for every agent pane can be long gone, and when the grant lapses agents lose LAN access while leo itself looks perfectly healthy (see internal/tmux/ownership.go and `leo doctor`).

Recycling the server restores the invariant but terminates every live agent session, so it is never done automatically — an automatic respawn would fire on every `leo update` and bounce every agent. This command makes the repair available, states its cost up front, and confirms before acting.

Index

• Variables
• func Execute() error
• type Finding
• type LocalNetworkStatus
• type Severity
• type StatusAgentState
• type StatusAgentsSummary
• type StatusNextScheduledRun
• type StatusReport
• type StatusTaskIssue
• type StatusTasksSummary
• type StatusWeb

Variables

var Version = "dev"

Functions

func Execute

func Execute() error

Types

type Finding

type Finding struct {
	Severity Severity `json:"severity"`
	Check    string   `json:"check"`
	Message  string   `json:"message"`
}

Finding is a single validation result.

type LocalNetworkStatus

type LocalNetworkStatus struct {
	// State is one of "granted", "denied", "undetermined", or "n/a" (non-macOS).
	State string
	// Detail is a short human-readable explanation of how State was derived.
	Detail string
	// Triggered reports whether the consent-raising probe (mDNS multicast
	// send + group join) was attempted.
	Triggered bool
	// ProbeResult carries the raw dial/error text from the connectivity
	// probe, useful for debugging a misclassification.
	ProbeResult string
	// TreeState is the verdict from probing inside leo's tmux server with a
	// third-party binary — the path agents actually use. Empty when no verdict
	// was reachable (no server, no probe binary), in which case TreeProbe says
	// why. This, not ProbeResult, is what State reflects when both disagree.
	TreeState string
	// TreeProbe carries the in-tree probe's raw output or the reason no
	// verdict was reached.
	TreeProbe string
	// TreeBinary is the absolute path of the third-party binary used in-tree.
	TreeBinary string
}

LocalNetworkStatus is the structured result of the macOS Local Network privacy check performed by checkLocalNetwork. It's shared by the darwin and non-darwin implementations so `leo doctor` can render a consistent report regardless of platform.

type Severity

type Severity string

Severity classifies a validation finding.

const (
	SeverityError Severity = "ERROR"
	SeverityWarn  Severity = "WARN"
	SeverityInfo  Severity = "INFO"
)

type StatusAgentState

type StatusAgentState struct {
	Name      string    `json:"name"`
	Status    string    `json:"status"`
	StartedAt time.Time `json:"started_at,omitempty"`
	Restarts  int       `json:"restarts,omitempty"`
}

StatusAgentState mirrors agent.Record but trims fields for the status report.

type StatusAgentsSummary

type StatusAgentsSummary struct {
	Running   int `json:"running"`
	Suspended int `json:"suspended"`
	Total     int `json:"total"`
}

StatusAgentsSummary holds live ephemeral-agent counts, reported by the daemon (empty/zero when the daemon isn't running).

type StatusNextScheduledRun

type StatusNextScheduledRun struct {
	Name string    `json:"name"`
	Next time.Time `json:"next"`
}

StatusNextScheduledRun points at the nearest upcoming task fire time.

type StatusReport

type StatusReport struct {
	LeoVersion  string                  `json:"leo_version"`
	HomePath    string                  `json:"home_path"`
	ConfigValid bool                    `json:"config_valid"`
	ConfigError string                  `json:"config_error,omitempty"`
	Service     string                  `json:"service"`
	Daemon      string                  `json:"daemon"`
	Web         *StatusWeb              `json:"web,omitempty"`
	Agents      StatusAgentsSummary     `json:"agents"`
	AgentStates []StatusAgentState      `json:"agent_states,omitempty"`
	BadAgents   []string                `json:"bad_agents,omitempty"`
	Tasks       StatusTasksSummary      `json:"tasks"`
	TaskIssues  []StatusTaskIssue       `json:"task_issues,omitempty"`
	Templates   int                     `json:"templates,omitempty"`
	Next        *StatusNextScheduledRun `json:"next_scheduled_run,omitempty"`
}

StatusReport is the structured representation of `leo status`, used by --json.

type StatusTaskIssue

type StatusTaskIssue struct {
	Name    string `json:"name"`
	Problem string `json:"problem"`
}

StatusTaskIssue describes a basic task problem surfaced from status.

type StatusTasksSummary

type StatusTasksSummary struct {
	Enabled int `json:"enabled"`
	Total   int `json:"total"`
}

StatusTasksSummary holds task counts.

type StatusWeb

type StatusWeb struct {
	Bind     string `json:"bind"`
	Port     int    `json:"port"`
	Loopback bool   `json:"loopback"`
	URL      string `json:"url"`
}

StatusWeb captures the resolved web UI config for the status report.