remote

type AcceptOptions struct {
	// Agent is the already-authenticated identity of the peer. The hello
	// frame's AgentID is checked against it; a mismatch is fatal.
	Agent AgentRecord
	// Executor is the durable driver this session attaches to.
	Executor *Executor
	// IssuedCredential is non-empty when this connection redeemed an
	// enrollment token, in which case the credential is handed to the agent
	// in the welcome frame. A freshly enrolling agent does not yet know its
	// own ID, so the hello identity check is relaxed for exactly this case.
	IssuedCredential string
	// Now overrides the clock for tests.
	Now func() time.Time
	// HeartbeatPoll overrides how often the watchdog checks for silence.
	// Zero uses half the heartbeat interval, which keeps detection latency a
	// fraction of the deadline. Tests set it small so a timeout transition
	// can be exercised in milliseconds against a synthetic clock instead of
	// waiting out a real 45-second deadline.
	HeartbeatPoll time.Duration
}

type AgentCapabilities struct {
	OS   string `json:"os"`
	Arch string `json:"arch"`
	// CPUs is the number of logical cores visible to the agent.
	CPUs int `json:"cpus,omitempty"`
	// MemoryMB is total system memory in megabytes; 0 when undetectable.
	MemoryMB int `json:"memory_mb,omitempty"`
	// ContainerRuntimes lists runtimes found on PATH ("docker", "podman"),
	// so the control plane can route container workloads to a device that
	// can actually honour them.
	ContainerRuntimes []string `json:"container_runtimes,omitempty"`
	// Harnesses lists agent CLIs found on PATH ("claude", "codex", ...). A
	// device without the harness a project needs should not be sent its work.
	Harnesses []string `json:"harnesses,omitempty"`
	// WorkDirRoot is the directory the agent confines every workload to.
	// Reported so an operator can see the sandbox boundary from the UI.
	WorkDirRoot string `json:"workdir_root,omitempty"`
	// WorkspaceProvisioning reports that this device can materialise a git
	// workspace itself — it has git on PATH and a build that knows how to use
	// it. Advertised rather than assumed because the failure it prevents is
	// silent: a device without git would answer the start frame and run the
	// harness against an empty tree.
	WorkspaceProvisioning bool `json:"workspace_provisioning,omitempty"`
	// WriteBack reports that this device can return a finished task's work
	// product — it has git and a build that knows how to commit and bundle.
	// Advertised for the same reason WorkspaceProvisioning is, and against the
	// same silent failure at the other end of the run: a device that cannot
	// write back does not say so, it just keeps the work.
	WriteBack bool `json:"write_back,omitempty"`
	// BranchBundles reports that this device can build a workload's tree from
	// a branch the hub ships with the start frame (protocol v16, Task 20367).
	// It needs git, like WorkspaceProvisioning and WriteBack, and is
	// advertised for the same reason: without it a feature placed here would
	// run on its base commit with none of its work.
	BranchBundles bool `json:"branch_bundles,omitempty"`
	// MaxConcurrent is the agent's ceiling on simultaneous workloads.
	MaxConcurrent int `json:"max_concurrent,omitempty"`
	// Virtualization reports that this device can actually start a
	// hypervisor-backed sandbox: /dev/kvm exists and the agent can open it
	// read-write.
	//
	// Advertised for the same reason WorkspaceProvisioning and WriteBack are,
	// against the same shape of silent failure — but this one is the only
	// capability here that the control plane would otherwise assert on the
	// device's behalf. Whether a payload is virtualized was treated as purely a
	// property of the runtime name an admin configured, which is true of the
	// *intent* and not of the *ability*: naming kata for a device with no
	// nested virtualization produced a hub that reported a hypervisor boundary
	// that could never exist. Only the device can answer this, so only the
	// device does.
	//
	// False on a v9+ agent is load-bearing: see Executor.Capabilities, which
	// stops claiming Virtualized, and Executor.Start, which refuses the
	// dispatch rather than letting QEMU fail inside the sandbox.
	//
	// This is deliberately *only* about a hypervisor. gVisor needs no /dev/kvm
	// — its Sentry is a userspace kernel — so a device reporting false here can
	// still serve a kernel-isolated sandbox under runsc, and KernelIsolated is
	// never narrowed by it.
	Virtualization bool `json:"virtualization,omitempty"`
	// USBDevices is the USB hardware attached to the device, as the kernel
	// enumerates it (Task 20345). It is what an admin chooses from when giving
	// a virtual executor's sandboxes a device, and it is a snapshot: the hub
	// re-reads it on demand with an inventory frame, and a selection is
	// resolved against the device's own live view at every dispatch.
	USBDevices []executor.USBDevice `json:"usb_devices,omitempty"`
	// PacketFilter reports that the agent can install a host-side IP filter
	// on a sandbox bridge — nft(8) is present and the agent holds
	// CAP_NET_ADMIN. PacketFilterIssue says why not when it cannot.
	//
	// A virtual executor with a firewall is refused on a device that reports
	// false, because the only alternative is a sandbox whose firewall exists
	// in the control plane's database and nowhere on the machine. Below v14
	// the field is absent, which the hub reads as "cannot" — there is no
	// firewall-capable agent older than the field.
	PacketFilter      bool   `json:"packet_filter,omitempty"`
	PacketFilterIssue string `json:"packet_filter_issue,omitempty"`
	// DenialLog reports that the agent reads its sandboxes' packet log and
	// reports what their firewalls refused (Task 20437): it bound an NFLOG
	// group with the CAP_NET_ADMIN its packet filter already has.
	// DenialLogIssue says why not when it cannot. Absent below v24, which the
	// hub reads as "cannot".
	DenialLog      bool   `json:"denial_log,omitempty"`
	DenialLogIssue string `json:"denial_log_issue,omitempty"`
	// ForwardedUSB reports that the agent can attach a forwarded USB device
	// on its host — vhci_hcd is loaded and the agent may write its attach
	// file — and ForwardedL2 that it can create a TAP and move it into a
	// container sandbox (Task 20430). The issues say why not. Absent below
	// v22, which the hub reads as "cannot".
	ForwardedUSB      bool   `json:"forwarded_usb,omitempty"`
	ForwardedUSBIssue string `json:"forwarded_usb_issue,omitempty"`
	ForwardedL2       bool   `json:"forwarded_l2,omitempty"`
	ForwardedL2Issue  string `json:"forwarded_l2_issue,omitempty"`
	// OCIRuntimes are the low-level runtimes the device's container engine
	// has registered ("runc", "runsc", "kata"), so the dashboard can offer
	// them instead of asking an admin to type a name the device may not know.
	OCIRuntimes []string `json:"oci_runtimes,omitempty"`
	// Labels are free-form selectors (region, site, gpu) set on the device,
	// with `cloop executor agent --label`. They are the device's own claim, and
	// stored with the rest of its advertisement only: the labels a grant to a
	// label selector is matched against are the ones on the device's
	// credential, which the hub recorded at enrollment (Task 20432), and
	// nothing reads these to decide one.
	Labels map[string]string `json:"labels,omitempty"`

	// UpdateChannel is the channel the device installs builds from (Task
	// 20376): "stable", releases only, or "edge", signed builds of commits on
	// main as well. An operator on the device chooses it, with a drop-in the
	// hub has no way to change; the hub reads it only to decide what the
	// Upgrade dialog and the auto-update policy offer. Absent from an agent
	// older than the field, which the hub reads as stable — there is no
	// edge-capable agent older than it, so no protocol bump is needed: the
	// field is its own capability flag.
	UpdateChannel string `json:"update_channel,omitempty"`
	// RemoteUpgrade reports that the device can carry out an upgrade the hub
	// asks for: it has the root helper (install --remote-upgrade), or the
	// agent runs as root, and cosign is installed to verify what it fetches.
	// RemoteUpgradeIssue says why not when it cannot. Both absent means an
	// agent older than the fields, whose answer is unknown.
	RemoteUpgrade      bool   `json:"remote_upgrade,omitempty"`
	RemoteUpgradeIssue string `json:"remote_upgrade_issue,omitempty"`
	// BuildSequence is the agent build's first-parent position on main (Task
	// 20380), the number the device's root helper orders installs by: it
	// refuses a build whose sequence is lower than the installed one's. The
	// hub reads it to show in the fleet inventory, to never offer a device a
	// build it would refuse, and for hub doctor to say how far behind its own
	// build a device is. Absent from a build that was not stamped with one —
	// and from every agent older than the field, which the hub reads the same
	// way: unknown. Informational to the hub, so no protocol bump: the
	// device's own installer is what enforces the order.
	BuildSequence int `json:"build_sequence,omitempty"`
	// HostKernel is the device's own kernel as the agent reads it — uname,
	// /proc/version, the boot ID — the reference an isolation probe's evidence
	// is compared with (Task 20439, protocol v26). The probe's reply carries a
	// fresh reading too; this one is for the fleet view. Absent from an older
	// agent, whose runtimes the hub then cannot verify.
	HostKernel *isolationprobe.Evidence `json:"host_kernel,omitempty"`
}

type AgentRecord struct {
	AgentID string `json:"agent_id"`
	Name    string `json:"name"`
	// SecretHash is hex-encoded SHA-256 of the credential secret.
	SecretHash  string            `json:"secret_hash"`
	WorkDirRoot string            `json:"workdir_root,omitempty"`
	Labels      map[string]string `json:"labels,omitempty"`
	CreatedAt   time.Time         `json:"created_at"`
	LastSeen    time.Time         `json:"last_seen,omitempty"`
	RevokedAt   time.Time         `json:"revoked_at,omitempty"`
	// EnrollmentID records which token minted this agent, so revoking a
	// leaked token can also reach the identity it produced.
	EnrollmentID string `json:"enrollment_id,omitempty"`
}

type AttachClosePayload struct {
	SessionID string `json:"session_id"`
	// Reason is a short human-readable cause, shown to the operator.
	Reason string `json:"reason,omitempty"`
	// ExitCode is the command's status when the device observed one. -1 means
	// it did not (killed, or the session was closed from the hub end).
	ExitCode int `json:"exit_code,omitempty"`
}

type AttachDataPayload struct {
	SessionID string `json:"session_id"`
	Data      []byte `json:"data"`
}

type AttachOpenPayload struct {
	// SessionID is minted by the hub and scopes every later frame.
	SessionID string `json:"session_id"`
	// Command is the argv to run. Empty means the agent's default shell.
	Command []string `json:"command,omitempty"`
	// TTY requests a pseudo-terminal on the device.
	TTY bool `json:"tty,omitempty"`
	// Stdin reports that this session may deliver input. When false the agent
	// must give the command no input descriptor at all — the read-only
	// guarantee is enforced on the device, not by the hub declining to send.
	Stdin bool `json:"stdin,omitempty"`
	// Rows and Cols are the initial geometry; ignored without a TTY.
	Rows uint16 `json:"rows,omitempty"`
	Cols uint16 `json:"cols,omitempty"`
	// Env carries extra "K=V" entries for the command (TERM, in practice).
	Env []string `json:"env,omitempty"`
}

type AttachOpenedPayload struct {
	SessionID string `json:"session_id"`
	// TTY reports whether the device actually allocated a terminal. It can be
	// false on a request that asked for one — a device without a pty
	// implementation degrades to pipes rather than refusing — and the hub tells
	// the operator instead of letting them wonder why there is no prompt.
	TTY bool `json:"tty"`
}

type AttachResizePayload struct {
	SessionID string `json:"session_id"`
	Rows      uint16 `json:"rows"`
	Cols      uint16 `json:"cols"`
}

type BranchChunkPayload struct {
	// Offset is where Data starts in the bundle.
	Offset int64 `json:"offset"`
	// Data is the slice.
	Data []byte `json:"data"`
	// Total is the bundle's full size, repeated on every chunk so a device can
	// refuse an oversized transfer on its first frame instead of its last.
	Total int64 `json:"total"`
}

type Bundle struct {
	// Server is the control-plane WebSocket URL the device dials.
	Server string `json:"server"`
	// Token is the single-use enrollment token.
	Token string `json:"token"`
	// Pin is the hub's SPKI fingerprint ("sha256:<base64>"), or "" when the
	// control plane has no TLS certificate configured. An empty pin is not a
	// silent downgrade: the device still refuses plaintext to a non-loopback
	// host, so an unpinned bundle can only be used against a server with a
	// publicly-trusted certificate, or over loopback.
	Pin string `json:"pin,omitempty"`
	// EnrollmentID identifies the minted token for revocation.
	EnrollmentID string `json:"enrollment_id"`
	// Name is the operator-facing label the device will carry.
	Name string `json:"name"`
	// WorkDirRoot is the filesystem root the device confines workloads to.
	WorkDirRoot string `json:"workdir_root,omitempty"`
	// ExpiresAt is when the token stops being redeemable.
	ExpiresAt time.Time `json:"expires_at"`
}

type ByePayload struct {
	Reason string `json:"reason,omitempty"`
	// Reconnect tells the peer whether to come back. False means the
	// credential was revoked or the agent deregistered, so an agent that
	// obeys it stops hammering a control plane that will never accept it.
	Reconnect bool `json:"reconnect"`
}

type Conn interface {
	// ReadFrame blocks until a frame arrives, ctx is cancelled, or the peer
	// goes away (io.EOF / net.ErrClosed).
	ReadFrame(ctx context.Context) (Frame, error)
	// WriteFrame sends one frame.
	WriteFrame(ctx context.Context, f Frame) error
	// Close terminates the connection. Idempotent.
	Close(reason string) error
}

type DenialsPayload struct {
	denylog.Batch
}

type DeviceClosePayload struct {
	ChannelID string `json:"channel_id"`
	Reason    string `json:"reason,omitempty"`
}

type DeviceDataPayload struct {
	ChannelID string `json:"channel_id"`
	Data      []byte `json:"data"`
}

type DeviceOpenPayload struct {
	// ChannelID is minted by the hub and scopes every later frame.
	ChannelID string `json:"channel_id"`
	// Kind is executor.ForwardedUSB or executor.ForwardedL2.
	Kind string `json:"kind"`
	// Name is the sandbox-facing handle the device is given under.
	Name string `json:"name"`
	// Label describes the device, for the device's own log.
	Label string `json:"label,omitempty"`
	// ForwarderID and BindingID identify the forwarder and the binding that
	// authorised the device, for the device's log.
	ForwarderID string `json:"forwarder_id,omitempty"`
	BindingID   string `json:"binding_id,omitempty"`
	// BusID, for USB, is the bus id the forwarder exports: what the agent's
	// OP_REQ_IMPORT names.
	BusID string `json:"bus_id,omitempty"`
	// Interface, for L2, is the sandbox-side shape of the segment; the agent
	// fills Source with the TAP it creates.
	Interface *executor.HostInterface `json:"interface,omitempty"`
}

type DeviceOpenedPayload struct {
	ChannelID string `json:"channel_id"`
	// For USB: the vhci port, and the bus id and node the device enumerated
	// as on the agent's host.
	VHCIPort   int    `json:"vhci_port,omitempty"`
	LocalBusID string `json:"local_bus_id,omitempty"`
	Node       string `json:"node,omitempty"`
	// For L2: the TAP the agent created.
	TAP string `json:"tap,omitempty"`
}

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

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

type EnrollmentRecord struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	// SecretHash is hex-encoded SHA-256 of the token secret.
	SecretHash  string            `json:"secret_hash"`
	WorkDirRoot string            `json:"workdir_root,omitempty"`
	Labels      map[string]string `json:"labels,omitempty"`
	CreatedAt   time.Time         `json:"created_at"`
	ExpiresAt   time.Time         `json:"expires_at"`
	CreatedBy   string            `json:"created_by,omitempty"`
	// RedeemedAt is zero until redemption. Non-zero is what makes the token
	// single-use: redemption is a conditional update that only succeeds while
	// this is still zero, so two concurrent redemptions cannot both win.
	RedeemedAt      time.Time `json:"redeemed_at,omitempty"`
	RedeemedAgentID string    `json:"redeemed_agent_id,omitempty"`
	RevokedAt       time.Time `json:"revoked_at,omitempty"`
}

type ErrorPayload struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

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

type ExpiredLease struct {
	LeaseID string
	Reason  string
}

type ExpiredLeaseSweeper func(now time.Time) []ExpiredLease

type Finding struct {
	Name    string `json:"name"`
	Level   string `json:"level"`
	Message string `json:"message"`
	Fix     string `json:"fix,omitempty"`
}

type Frame struct {
	// V is the protocol version of this frame.
	V int `json:"v"`
	// Type discriminates Payload.
	Type FrameType `json:"type"`
	// ID correlates a response with its request. Empty for unsolicited
	// frames such as log chunks and terminal status reports.
	ID string `json:"id,omitempty"`
	// Handle scopes the frame to one workload. Empty for session-level
	// frames (hello, welcome, heartbeat, bye).
	Handle string `json:"handle,omitempty"`
	// Payload is the type-specific body, decoded by the Decode* helpers.
	Payload json.RawMessage `json:"payload,omitempty"`
}

type FrameType string

type HarnessInstallOutcome struct {
	// Installed reports that the harness is runnable on the device now. True
	// for AlreadyPresent too: the question was "can you run this", not "did
	// you do work".
	Installed bool
	// AlreadyPresent marks the harness as having been there before the ask,
	// which happens when two dispatches race for one device.
	AlreadyPresent bool
	// Harness, Path and Version describe what the device has. Path is worth
	// surfacing: an install under a home directory is the thing an operator
	// debugging PATH needs to see.
	Harness string
	Path    string
	Version string
	// Reason explains a failure, in terms the operator can act on.
	Reason string
}

type HarnessInstalledPayload struct {
	// Installed reports that the harness is now runnable on this device. It is
	// true both for a fresh install and for AlreadyPresent, because the
	// question the hub asked was "can you run this now", not "did you do work".
	Installed bool `json:"installed"`

	// AlreadyPresent distinguishes "it was already here" from "I fetched it",
	// so the hub can tell a race against a concurrent dispatch from an install
	// it actually caused, and log accordingly.
	AlreadyPresent bool `json:"already_present,omitempty"`

	// Harness echoes what was installed, so a log line or an audit row is
	// self-describing rather than needing the request beside it.
	Harness string `json:"harness,omitempty"`

	// Path is where the binary landed and Version what it reports. Both are
	// diagnostic, and Path earns its place: the official installer puts Claude
	// Code in ~/.local/bin, which is not on a service manager's default PATH,
	// and an operator debugging "installed but still not found" needs to see
	// the directory the agent had to add.
	Path    string `json:"path,omitempty"`
	Version string `json:"version,omitempty"`

	// Reason explains a failure. Always set when Installed is false: the
	// refusals here have entirely different fixes — no installer for this
	// harness, no bash on the device, no network, the script exited non-zero —
	// and a bare "install failed" would make them indistinguishable in the one
	// place an operator reads them.
	Reason string `json:"reason,omitempty"`
}

type HeartbeatAckPayload struct {
	Seq uint64 `json:"seq"`
	// ServerTime lets the agent log clock skew, which is the usual cause of
	// otherwise inexplicable credential-expiry failures on edge devices with
	// no RTC.
	ServerTime time.Time `json:"server_time"`
}

type HeartbeatPayload struct {
	// Seq increments per heartbeat, letting the control plane log gaps.
	Seq uint64 `json:"seq"`
	// ActiveHandles is what the agent believes is still running. The control
	// plane reconciles: a handle it thinks is running but the agent has
	// forgotten is resolved as failed rather than left hanging forever.
	ActiveHandles []string `json:"active_handles,omitempty"`
	// LoadPercent is a coarse 0-100 busy signal for scheduling; -1 unknown.
	LoadPercent int `json:"load_percent,omitempty"`
}

type HelloPayload struct {
	// ProtocolVersion is the newest version the agent speaks. The control
	// plane replies with the version actually negotiated.
	ProtocolVersion int `json:"protocol_version"`
	// AgentID is the identity the credential was issued to. It is checked
	// against the authenticated identity, never trusted on its own — a frame
	// claiming to be another agent is a session-fatal error.
	AgentID string `json:"agent_id"`
	// Name is the operator-facing label chosen at enrollment.
	Name string `json:"name,omitempty"`
	// AgentVersion is the cloop build running on the device, for diagnosing
	// version-skew problems from the control plane.
	AgentVersion string `json:"agent_version,omitempty"`
	// Capabilities is what this device can run; the scheduler matches on it.
	Capabilities AgentCapabilities `json:"capabilities"`
	// Resume lists workloads still running from a previous connection,
	// with the offset each one's log stream reached. A reconnecting agent
	// uses this to hand the control plane back its in-flight work instead of
	// orphaning it.
	Resume []ResumeHandle `json:"resume,omitempty"`
}

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

type HubOptions struct {
	// Store is the enrollment/credential persistence. Required.
	Store Store
	// Registry is where connected agents are registered as executors. Nil
	// uses executor.DefaultRegistry.
	Registry *executor.Registry
	// OnStatusChange mirrors executor connectivity into durable storage. It
	// is a callback rather than a *statedb.DB so this package stays free of
	// a storage dependency, matching how the registry takes a binding lookup.
	OnStatusChange func(executorID, status string, at time.Time)
	// OnEnroll is called after a device successfully redeems an enrollment
	// token, so the caller can write an executors-table row for it.
	OnEnroll func(agent AgentRecord, caps AgentCapabilities)
	// OnConnect is called after *every* successful handshake, including the
	// one that enrolled the device, carrying what the agent just advertised
	// about itself.
	//
	// It exists because OnEnroll fires once, ever. A device's build version
	// and capabilities are exactly the facts that change when an operator
	// upgrades it, so recording them only at enrollment meant the stored copy
	// was frozen at whatever the device was running the day it joined —
	// reproducing, in the storage layer, the same staleness the hardcoded
	// agent version produced on the wire. An upgraded device would have gone
	// on being reported as its year-old self.
	//
	// Distinct from OnEnroll rather than replacing it: enrollment is an
	// auditable one-time event that also establishes CreatedAt and the minting
	// token, and collapsing the two would either lose that or re-assert it on
	// every reconnect.
	OnConnect func(agent AgentRecord, caps AgentCapabilities, agentVersion string)
	// OnRevokeAck receives an agent's acknowledgement of a lease revocation,
	// so the caller can write the audit row. It fires for replayed
	// revocations too — the ones delivered long after the operator pressed
	// the button — which is the only signal that a queued revocation landed.
	OnRevokeAck func(executorID, leaseID string, ack RevokedPayload)
	// HandleStore persists handle identity for every executor this hub builds,
	// so a restart still recognises the workloads its devices are running
	// (Task 20191). Nil is the pre-Task-20191 behaviour; see
	// Options.HandleStore for what that costs.
	//
	// One store for the whole hub rather than one per agent: rows are scoped by
	// executor ID inside the store, and a per-agent factory — the shape
	// WorkspaceSource needs, because a *grant* is issued to a subject — would
	// invite an implementation that scoped by something else and let one
	// device's executor adopt another's handles.
	HandleStore executor.HandleStore
	// WorkspaceSource builds the credential source for one agent's executor.
	//
	// It is a factory rather than a single source because a grant is issued to
	// a *subject*: pkg/executor/gitcreds binds the executor ID at construction
	// so that a lease taken for edge-1 can never be satisfied by a grant issued
	// to edge-2. Nil leaves every executor without one, in which case a
	// workload naming a grant is refused rather than dispatched to fetch a
	// private repository anonymously.
	WorkspaceSource func(executorID string) executor.WorkspaceCredentialSource
	// SandboxSource resolves an executor's admin-configured sandbox settings:
	// whether payloads run on that device's host or in a container on it, and
	// under which engine, runtime and image (Task 20307).
	//
	// A factory taking the executor ID, like WorkspaceSource, because the
	// configuration is per executor — and the inner function takes no arguments
	// and returns an error, because it is re-read on every dispatch and a failed
	// read must be able to refuse one. See Options.Sandbox for why that refusal
	// is the only safe answer.
	//
	// Nil leaves every executor unconfigured, which is the pre-Task-20307
	// behaviour: payloads run as host processes on the device.
	SandboxSource func(executorID string) func() (executor.SandboxSettings, error)
	// AutoInstallHarness reports whether this hub may ask a device to install a
	// missing harness from that harness's official installer (Task 20336).
	//
	// Deployment-wide rather than per-executor, unlike SandboxSource. Sandbox
	// mode describes one machine's containment and genuinely differs between
	// devices; "may this control plane run a vendor install script on the
	// machines it manages" is a policy about the deployment, and per-device
	// copies of it would be a setting an operator has to remember to re-apply
	// to every device they ever enroll.
	//
	// Nil means enabled. See Options.AutoInstallHarness.
	AutoInstallHarness func() bool
	// ImagePolicy reads the hub's image trust policy for every executor this
	// hub builds, which enforces it on the image a project names before a
	// dispatch to its device (Task 20424). See Options.ImagePolicy.
	//
	// Deployment-wide, like AutoInstallHarness: the policy is the hub's, and
	// a device holding a copy of its own would be deciding its own
	// containment.
	ImagePolicy func() (imagepolicy.Policy, error)
	// ImageResolver and ImageVerifier stand in for the registry and for
	// cosign, for tests. Nil uses the real ones; see Options.
	ImageResolver imagepolicy.Resolver
	ImageVerifier imagepolicy.Verifier
	// ResultBudget bounds the returned work every executor this hub builds
	// may have it hold in memory (Task 20399). Nil uses the process-wide
	// DefaultResultBudget, whose limits the caller sets from
	// executors.remote; see Options.ResultBudget.
	ResultBudget *ResultBudget
	// ExternalURL is what this deployment calls itself, e.g.
	// https://cloop.example.com. Its origin is always an accepted WebSocket
	// Origin, which is what makes the Executors panel work when a reverse
	// proxy rewrites Host so the request's own origin cannot be seen.
	ExternalURL string
	// AllowedOrigins lists additional browser Origins permitted to open an
	// agent WebSocket, on top of the request's own and ExternalURL's. Matched
	// exactly: full origins, or host[:port] meaning https (Task 20394).
	AllowedOrigins []string
	// ForwardedTrusted reports whether a request's X-Forwarded-Proto and
	// X-Forwarded-Host are believed when working out the origin it was
	// addressed to. Nil believes them from loopback only. The dashboard passes
	// its own rule (loopback, ui.trusted_proxies, cluster members), so the
	// two endpoints judge one request alike.
	ForwardedTrusted func(*http.Request) bool
	// OnOriginRefused, when set, is told of every handshake refused for its
	// Origin, so the hub can count and audit it with the dashboard's own.
	OnOriginRefused func(*http.Request)
	// Logf receives operational messages. Nil discards them.
	Logf func(format string, args ...any)
	// Now overrides the clock for tests.
	Now func() time.Time
}

type InstallHarnessPayload struct {
	// Harness is the key into the agent's table of official installers, e.g.
	// "claude". Not a URL, not a command — see the file comment.
	Harness string `json:"harness"`

	// Reason is free text for the device's log, distinguishing an install
	// triggered by a dispatch from one an operator asked for directly. It is
	// diagnostic only and never affects what is installed.
	Reason string `json:"reason,omitempty"`
}

type InventoryPayload struct {
	Capabilities AgentCapabilities `json:"capabilities"`
}

type InventoryRequestPayload struct{}

type IsolationEvidencePayload struct {
	// Evidence is what the probe read inside the sandbox; nil when Error is
	// set.
	Evidence *isolationprobe.Evidence `json:"evidence,omitempty"`
	// Host is the device's own kernel, read when the probe ran.
	Host *isolationprobe.Evidence `json:"host,omitempty"`
	// EngineKernel is the kernel release the device's container engine
	// reports for its machine.
	EngineKernel string `json:"engine_kernel,omitempty"`
	// Engine and Image are what the sandbox ran through and in.
	Engine string `json:"engine,omitempty"`
	Image  string `json:"image,omitempty"`
	// Error is why the probe could not run.
	Error string `json:"error,omitempty"`
}

type IsolationProbeRequest struct {
	// Sandbox is the executor's sandbox settings: its own for a device, a
	// virtual executor's for one of those. The agent refuses anything but
	// container mode — host mode has no runtime to verify.
	Sandbox executor.SandboxSettings `json:"sandbox"`
}

type LogAckPayload struct {
	// Offset is the highest contiguous byte offset the control plane has
	// accepted. The agent may discard everything below it.
	Offset int64 `json:"offset"`
}

type LogChunkPayload struct {
	Stream executor.StreamName `json:"stream"`
	// Offset is the byte position of Text's first byte within this handle's
	// output. Offsets, not sequence numbers, are the unit of acknowledgement:
	// after a reconnect the agent may re-chunk the same bytes differently, so
	// only a byte position identifies "where we got to" unambiguously.
	Offset int64  `json:"offset"`
	Text   string `json:"text"`
	// Time is the device's clock when the output was read.
	Time time.Time `json:"time"`
}

type MintOptions struct {
	// Name is the operator-facing label the agent will carry.
	Name string
	// TTL bounds redemption. Zero uses DefaultEnrollTTL; values above
	// MaxEnrollTTL are rejected rather than silently clamped, because an
	// operator who asked for a week should learn that the answer is no.
	TTL time.Duration
	// WorkDirRoot is the filesystem root the enrolled agent will confine
	// every workload to. Empty lets the device choose its own default.
	WorkDirRoot string
	// Labels are free-form scheduler selectors.
	Labels map[string]string
	// CreatedBy identifies the minting operator (OIDC subject, or "" local).
	CreatedBy string
	// Server is the control-plane WebSocket URL to record in the enrollment
	// bundle. Not persisted: it is what the operator carries to the device,
	// not something the control plane needs to remember.
	Server string
	// Pin is the hub's SPKI fingerprint ("sha256:<base64>") to record in the
	// bundle, so the device can tell its control plane apart from anything
	// else that answers the same hostname. Also not persisted.
	Pin string
	// Now overrides the clock for tests.
	Now func() time.Time
}

type Options struct {
	// ID is the registry key. It is the agent ID, so a project bound to an
	// agent stays bound across reconnects and control-plane restarts.
	ID string
	// Name is the operator-facing label from enrollment.
	Name string
	// Capabilities is what the device advertised at hello.
	Capabilities AgentCapabilities
	// OnStatusChange, when set, is called whenever the executor transitions
	// between online/offline/unreachable. The hub uses it to mirror status
	// into statedb without this package importing storage.
	OnStatusChange func(executorID, status string, at time.Time)
	// OnRevokeAck, when set, is called when an agent acknowledges a lease
	// revocation. It is a callback for the same reason OnStatusChange is:
	// the audit trail lives in storage and this package must not depend on
	// it. Replayed revocations report through here too, which is the only
	// way an operator learns that a queued revocation finally landed.
	OnRevokeAck func(executorID, leaseID string, ack RevokedPayload)
	// Workspace leases the credential a git workspace fetch needs, at dispatch
	// time and for the length of one start.
	//
	// It is an interface (executor.WorkspaceCredentialSource) rather than the
	// broker itself so this package stays free of the hub's secret store —
	// pkg/executor/agent imports pkg/executor/remote, and an edge binary must
	// not carry a secret database because the control plane happens to have
	// one. Nil means no credential can be leased: a workload naming a grant is
	// refused with the same typed error the broker would have raised, rather
	// than dispatched to fetch a private repository anonymously.
	Workspace executor.WorkspaceCredentialSource
	// HandleStore persists handle identity so a hub that restarts still knows
	// which workloads it dispatched to this device (Task 20191). See
	// rehydrate.go.
	//
	// Nil is the pre-Task-20191 behaviour and remains supported: the driver
	// dispatches, streams, signals and reconciles exactly as it did. What it
	// loses is the one thing only a durable row can supply — recognising a
	// reconnecting agent's resume offer after a restart. Without it every offer
	// is refused, and a refusal now stops the workload, so a storeless hub
	// trades a leaked process for a lost run.
	//
	// It is a field rather than a constructor argument because a remote
	// executor is built by the hub from an enrollment record, early and
	// synchronously, while the state database that backs the store is opened
	// later; AttachHandleStore installs it once that has happened.
	HandleStore executor.HandleStore
	// Sandbox resolves this executor's admin-configured sandbox settings —
	// whether payloads run on the device's host or in a container on it, and
	// under which engine, runtime and image (Task 20307).
	//
	// A function rather than a value, consulted on every Start rather than read
	// once here, because the whole point is that an admin can change it from the
	// UI and have the next task honour it. A value captured at construction
	// would go stale the moment the panel was used and would only refresh when
	// the device happened to reconnect.
	//
	// It returns an error rather than just a value, and the error is fatal to
	// the dispatch. That is deliberate: "I could not read whether this executor
	// is supposed to be contained" must not resolve to "run it on the host".
	// See statedb.SandboxSettingsFor, which is the implementation the hub
	// installs, for the full argument.
	//
	// Nil means no configuration source — the pre-Task-20307 behaviour, and what
	// a hub with no control-plane database gets. Payloads run as they did.
	Sandbox func() (executor.SandboxSettings, error)
	// AutoInstallHarness reports whether this hub may ask a device to install
	// a missing harness from that harness's official installer (Task 20336).
	//
	// A function for the same reason Sandbox is one: it is an admin setting
	// that must take effect on the next dispatch rather than at the next
	// reconnect.
	//
	// Nil means enabled, and that default is the feature. The behaviour it
	// replaces is a refusal telling an operator to go and install something by
	// hand on a machine the fleet exists to stop hand-administering. Sites that
	// do not want a vendor script run on a critical host turn it off here, and
	// get the Task 20332 refusal back unchanged.
	AutoInstallHarness func() bool
	// ImagePolicy reads the hub's image trust policy, for the image a project
	// names in its .cloop/sandbox.yaml (Task 20424). Consulted on every Start
	// whose sandbox runs that image, and enforced here because nothing on the
	// device enforces it: see imagepolicy.go.
	//
	// A function, re-read per dispatch, for the reason Sandbox is one: a
	// policy an operator tightens governs the next task. An error refuses
	// the dispatch — it never stands in for the zero policy, which admits
	// every image.
	//
	// Nil means no policy source, the pre-Task-20424 behaviour of an executor
	// built outside a hub. The hub always sets it.
	ImagePolicy func() (imagepolicy.Policy, error)
	// ImageResolver turns a tag into the digest its registry serves, for a
	// policy that requires signatures. Nil asks the registry
	// (imagepolicy.RegistryResolver). Tests inject their own.
	ImageResolver imagepolicy.Resolver
	// ImageVerifier checks a digest's signature. Nil runs cosign on the hub,
	// through a verifier every executor shares. Tests inject their own.
	ImageVerifier imagepolicy.Verifier
	// ResultBudget bounds the returned work — write-back bundles and project
	// state documents — this executor may have the hub hold in memory while
	// it waits to be collected (Task 20399). Nil draws on the process-wide
	// DefaultResultBudget, which is what a hub wants: the limit that keeps
	// it alive is one for the whole process. Tests inject their own.
	ResultBudget *ResultBudget
	// Now overrides the clock for tests.
	Now func() time.Time
}

type PreflightReport struct {
	ExecutorID string    `json:"executor_id"`
	Findings   []Finding `json:"findings"`
}

type ProjectResultPayload struct {
	// Data is the compressed result document pkg/executor/projectseed builds
	// and decodes. The hub parses it; this layer only bounds it.
	Data []byte `json:"data,omitempty"`
	// Err is the device's reason for sending no document — the workload
	// removed its project, the database was written by a newer cloop than the
	// agent's. Carried rather than dropped so the hub's journal can say why a
	// run came back without results instead of only that it did.
	Err string `json:"error,omitempty"`
}

type RedeemOptions struct {
	// Now overrides the clock for tests.
	Now func() time.Time
}

type RefreshResult struct {
	ExecutorID string                       `json:"executor_id"`
	Report     executor.SecretRefreshReport `json:"report"`
}

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

type ResultBudgetUsage struct {
	// Pinned is every executor's bytes together.
	Pinned int64
	// MaxPerExecutor is the most any single executor holds.
	MaxPerExecutor int64
	// Executors is how many executors hold anything at all.
	Executors int
	// PerExecutorLimit and TotalLimit are the limits in force.
	PerExecutorLimit int64
	TotalLimit       int64
}

type ResultChunkPayload struct {
	// Offset is the byte position of Data's first byte within the bundle.
	// Unlike a log chunk's offset this is not merely an acknowledgement
	// token: the hub refuses a chunk that does not start exactly where the
	// previous one ended, because a bundle assembled out of order or with a
	// hole is corrupt in a way git will report as something else entirely.
	Offset int64 `json:"offset"`
	// Data is the raw slice. A []byte marshals to base64 in JSON, so no
	// encoding decision is made here.
	Data []byte `json:"data"`
}

type ResultPayload struct {
	// Result is the metadata: mode, branch, commit, digest, or the failure.
	// It never contains bundle bytes — those arrived as chunks — for the same
	// reason executor.Status does not: this struct is logged and persisted.
	Result executor.WriteBackResult `json:"result"`
}

type ResumeAck struct {
	HandleID string `json:"handle_id"`
	// FromOffset is the first byte the control plane still needs. The agent
	// resends from here; anything below it was already delivered. Meaningless
	// when Action is ResumeTerminate.
	FromOffset int64 `json:"from_offset"`
	// Action is the verdict. Empty means ResumeContinue, which is what a v4
	// hub's acks decode to and is therefore the only backward-compatible
	// default. Added in protocol v5.
	Action ResumeAction `json:"action,omitempty"`
	// Reason is operator-facing text explaining a refusal, carried into the
	// device's log so "why did my task die" has an answer on the machine it
	// died on and not only in the control plane's.
	Reason string `json:"reason,omitempty"`
}

type ResumeAction string

type ResumeHandle struct {
	HandleID  string    `json:"handle_id"`
	StartedAt time.Time `json:"started_at"`
	// LogOffset is the total number of output bytes the agent has produced
	// for this handle so far. The control plane compares it against what it
	// received and asks for the gap.
	LogOffset int64 `json:"log_offset"`
}

type RevokeAction = executor.RevokeAction

type RevokePayload = executor.RevokeRequest

type RevokeResult = executor.RevokeOutcome

type RevokeState = executor.RevokeState

type RevokedPayload = executor.RevokeReport

type SecretFile struct {
	// LeaseID and GrantID attribute the file, so the device can tie what it
	// wrote to the binding a later revoke frame will name.
	LeaseID string `json:"lease_id,omitempty"`
	GrantID string `json:"grant_id,omitempty"`
	// Dir is the directory the workload's environment already points at. It is
	// the hub's *declaration*, not an instruction: the hub has no idea what is
	// writable on an edge device, so the agent picks a real directory of its
	// own and relocates the environment onto it (see the agent's
	// materializeSecretFiles and Spec.RelocateSecrets).
	Dir string `json:"dir"`
	// Name is a bare file name. Re-validated on receipt: a name with a
	// separator in it is an arbitrary-file-write primitive aimed at the device.
	Name string `json:"name"`
	// Mode is the permission bits, as a plain uint32 because fs.FileMode's
	// JSON form is an opaque integer whose high bits mean things a wire format
	// should not be able to assert. Zero means 0600.
	Mode uint32 `json:"mode,omitempty"`
	// Content is the plaintext, base64 in JSON. This is the credential;
	// everything else in this struct is bookkeeping.
	Content []byte `json:"content"`
}

type SecretRefreshPayload struct {
	LeaseID string `json:"lease_id"`
	// Files carry the replacements, attributed and named exactly as the start
	// frame's SecretFiles were: Dir is the directory the hub declared, which
	// the agent maps onto the one it actually created.
	Files  []SecretFile `json:"files"`
	Reason string       `json:"reason,omitempty"`
}

type SecretRefreshedPayload = executor.SecretRefreshReport

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

type SignalPayload struct {
	Signal executor.Signal `json:"signal"`
}

type StartPayload struct {
	Spec executor.Spec `json:"spec"`
	// HandleID is assigned by the control plane rather than the agent, so a
	// start whose response is lost to a disconnect is still addressable: the
	// control plane can ask about the handle it named, and the agent can
	// treat a repeated start for a known handle as a no-op instead of
	// launching the workload twice.
	HandleID string `json:"handle_id"`
	// WorkspaceCredential is the material for the single authenticated git
	// fetch Spec.Workspace needs, when it needs one. Added in protocol v3; nil
	// for a public repository or a workspace that needs no provisioning.
	//
	// It is a sibling of Spec rather than a field inside it, and that is a
	// hard rule rather than a stylistic one: pkg/executorstore persists the
	// dispatched Spec, the audit trail echoes it, and the reconcile loop
	// re-reads it after a control-plane restart. A token placed anywhere in a
	// Spec would be durable in three places within a second of being minted.
	// Here it is one field of one frame — written to a socket, never to a disk
	// — and the hub releases the lease as soon as the agent confirms the start.
	WorkspaceCredential *WorkspaceCredential `json:"workspace_credential,omitempty"`
	// SecretFiles carries the plaintext of the credential files this workload's
	// secret lease produced, for the device to write where Spec.Env already
	// says they are. Added in protocol v6; nil when the lease carries none,
	// which is every workload that leases only environment variables.
	//
	// It is a sibling of Spec for exactly the reason WorkspaceCredential is,
	// and here the rule is enforced by the type system rather than by
	// convention: executor.Spec.SecretFiles is tagged json:"-" precisely so
	// that it *cannot* travel inside a Spec. pkg/executorstore persists the
	// dispatched Spec, the audit trail echoes it, and reconcile re-reads it
	// after a control-plane restart — a credential that reached a Spec field
	// would be durable in three places within a second of being minted. Here
	// the bytes are one field of one frame, written to a socket and never to a
	// disk, and the device wipes them when the workload ends.
	//
	// This is also why the remote protocol has to carry them explicitly: a
	// driver that shares the hub's filesystem reads the files the broker
	// already wrote, and a driver on another machine has nothing to read.
	SecretFiles []SecretFile `json:"secret_files,omitempty"`
	// ProjectSeed is the hub's `.cloop/` project state — gzip-compressed JSON
	// in the shape state.Load already migrates from — for the device to place
	// into the tree it provisions. Added in protocol v10.
	//
	// A sibling of Spec like the two fields above, and for the size reason
	// rather than the secrecy one: executor.Spec.ProjectSeed is json:"-" so a
	// few hundred kilobytes of plan are not written to the handle store, echoed
	// into the audit trail and re-read by reconcile on every dispatch. Here the
	// bytes are one field of one frame.
	//
	// []byte, so encoding/json base64s it on the wire — the payload is
	// compressed binary, and it is validated on receipt before a byte of it
	// reaches a filesystem.
	ProjectSeed []byte `json:"project_seed,omitempty"`
	// Sandbox is the admin's per-executor answer to where this payload runs on
	// the device: as a host process, or in a container on that host, and under
	// which engine, runtime and image. Added in protocol v8; the zero value
	// means "unset" and leaves the device's own default alone.
	//
	// A value rather than a pointer, and sent on every start rather than
	// negotiated once at hello. Both follow from the same property: this is the
	// control plane *instructing* the device, not asking it. A pointer would
	// make "the hub said nothing" and "the hub said default" two states the
	// agent has to tell apart when they mean the same thing, and a
	// hello-time negotiation would mean an admin's change in the UI took effect
	// only after the device happened to reconnect — leaving a window in which
	// the hub believed an executor was contained and the device did not agree.
	//
	// Unlike WorkspaceCredential and SecretFiles, this belongs inside no
	// secret-free carve-out: it holds no credential, so it is safe for
	// pkg/executorstore to persist and for the audit trail to echo. That it is
	// a sibling of Spec rather than a Spec field is instead about ownership —
	// Spec describes one workload, and this describes the executor every
	// workload on that device gets.
	Sandbox executor.SandboxSettings `json:"sandbox,omitempty"`
	// Virtual is set when the workload was dispatched through a virtual
	// executor with a firewall or a device list (Task 20345, protocol v14).
	// Sandbox above then carries that executor's engine, runtime, image and
	// network rather than the device's own.
	//
	// Nil for every other dispatch, and for a virtual executor that only
	// picks an engine and a runtime: those are fully described by Sandbox,
	// which is also what keeps such a virtual executor usable on a v8 agent.
	Virtual *VirtualStart `json:"virtual,omitempty"`
	// ForwardedDevices names the device channels opened for this handle that
	// its sandbox is given (Task 20430, protocol v22). Each was opened by a
	// device_open frame ahead of this one and answered device_opened, so the
	// device is attached on the agent's host by the time this arrives; the
	// agent refuses a start naming a channel it does not hold for the handle.
	ForwardedDevices []string `json:"forwarded_devices,omitempty"`
}

type StartedPayload struct {
	HandleID  string    `json:"handle_id"`
	PID       int       `json:"pid,omitempty"`
	StartedAt time.Time `json:"started_at"`
	// Error is non-empty when the workload could not be started; the control
	// plane surfaces it verbatim so the operator sees the device's reason
	// (missing binary, workdir outside root) rather than a generic failure.
	Error string `json:"error,omitempty"`
	// DiskLimit is set beside Error when the refusal was a workspace already
	// over its disk limit (protocol v20, Task 20405), so the hub can answer it
	// as the refusal it is — journalled, and a conflict rather than a fault —
	// instead of as an opaque device error.
	DiskLimit *executor.DiskLimitBreach `json:"disk_limit,omitempty"`
}

type StatusPayload struct {
	Status executor.Status `json:"status"`
	// FinalOffset is the total output byte count when the workload reached a
	// terminal state. The control plane uses it to tell "the stream ended"
	// apart from "the connection dropped mid-stream": if it has fewer bytes
	// than FinalOffset it knows output is still outstanding.
	FinalOffset int64 `json:"final_offset,omitempty"`
}

type StatusReqPayload struct{}

type Store interface {
	// PutEnrollment persists a newly minted token record.
	PutEnrollment(rec EnrollmentRecord) error
	// GetEnrollment loads a token by its public ID. Returns ErrTokenInvalid
	// when no such row exists.
	GetEnrollment(id string) (EnrollmentRecord, error)
	// RedeemEnrollment atomically marks id redeemed by agentID. It must
	// return ErrTokenAlreadyUsed if the row is already redeemed.
	RedeemEnrollment(id, agentID string, at time.Time) error
	// RevokeEnrollment marks a token revoked; unredeemed or not.
	RevokeEnrollment(id string, at time.Time) error
	// ListEnrollments returns every token record, newest first.
	ListEnrollments() ([]EnrollmentRecord, error)

	// PutAgent persists an agent credential record.
	PutAgent(rec AgentRecord) error
	// GetAgent loads an agent by ID. Returns ErrAgentNotFound when absent.
	GetAgent(agentID string) (AgentRecord, error)
	// RevokeAgent marks an agent's credential revoked.
	RevokeAgent(agentID string, at time.Time) error
	// TouchAgent records that the agent was seen at t.
	TouchAgent(agentID string, at time.Time) error
	// ListAgents returns every enrolled agent.
	ListAgents() ([]AgentRecord, error)
}

type UpgradeOutcome struct {
	// Accepted is true when the device has begun the upgrade. It is not a
	// success report — see the file comment.
	Accepted bool
	// AlreadyCurrent marks the benign refusal: the device is already running
	// the requested build and was not asked to force it.
	AlreadyCurrent bool
	// Reason carries the device's explanation for a refusal.
	Reason string
	// FromVersion and TargetVersion are the builds the device is moving
	// between, as the device resolved them. TargetVersion is what "latest"
	// turned out to mean.
	FromVersion   string
	TargetVersion string
}

type UpgradePayload struct {
	// TargetVersion is the release tag to move to, e.g. "v0.1.4", or
	// LatestVersion to let the device resolve the newest published release.
	//
	// A tag, not a URL: the device turns this into bytes through its own
	// release channel, and verifies the result against a pinned signing
	// identity. That is the whole security model of this frame.
	TargetVersion string `json:"target_version"`

	// Force installs the target even when the device is already running it,
	// and permits moving backwards to an older release.
	//
	// Downgrade is included because the operational reason to reach for this
	// feature at all is often a bad release: the fleet is on a build that
	// misbehaves, and the fix is to put it back on the previous one before
	// diagnosing. Refusing that would leave the rollback path as "SSH to every
	// device", which is the problem this frame exists to remove.
	Force bool `json:"force,omitempty"`

	// SettleSeconds bounds how long the device waits for its restarted service
	// to come back before deciding the new binary is bad and rolling back to
	// the previous one. Zero uses the installer's default.
	SettleSeconds int `json:"settle_seconds,omitempty"`

	// Reason is free text recorded in the device's log, distinguishing an
	// operator who clicked Upgrade from the auto-update policy acting on its
	// own. It is diagnostic only and never affects what is installed.
	Reason string `json:"reason,omitempty"`
}

type UpgradeRequest struct {
	// TargetVersion is a release tag, or LatestVersion / "" for the newest
	// published release. Empty is accepted here and normalised to
	// LatestVersion before it reaches the wire — the strictness in
	// DecodeUpgrade is about frames arriving from elsewhere, and imposing it
	// on in-process callers would only produce a redundant error. Anything
	// else is refused with ErrUpgradeTarget before a frame is sent.
	//
	// A caller that can resolve LatestVersion to a tag should, and send the
	// tag: the device then installs exactly the release that was checked. An
	// unresolved LatestVersion is judged as the newest published release this
	// hub knows of (version.NewestPublishedRelease).
	TargetVersion string
	// Force reinstalls an identical build, and permits a downgrade — including
	// one that lowers the device's protocol (ErrUpgradeLowersProtocol).
	Force bool
	// TargetProtocol is the protocol an edge target's manifest says it
	// speaks, resolved by the caller through GitHub (Task 20376). It never
	// reaches the wire — the device reads the signed manifest itself — and it
	// is what lets the hub keep its promise never to lower a device's
	// protocol for a build of main, which no release table describes. Zero
	// for an edge target refuses it unless Force.
	TargetProtocol int
	// TargetProtocolIssue says why TargetProtocol is unknown, for the refusal.
	TargetProtocolIssue string
	// TargetSequence is an edge target's place on main, from the same
	// manifest as TargetProtocol, when TargetSequenceKnown (Task 20380): zero
	// then means the build carries none. Like TargetProtocol it never reaches
	// the wire — the device reads the signed manifest and its binary's stamp
	// itself — and it is what keeps the hub from asking a device for a build
	// its installer will refuse as earlier on main. A release target's
	// sequence comes from the published table instead.
	TargetSequence      int
	TargetSequenceKnown bool
	// SettleTimeout bounds the device's wait for its restarted service.
	SettleTimeout time.Duration
	// Reason is recorded in the device's log: who asked, and whether it was a
	// person or the auto-update policy.
	Reason string
}

type UpgradingPayload struct {
	// Accepted reports that the device has validated the request and is about
	// to begin. It does not report success; see the file comment.
	Accepted bool `json:"accepted"`

	// Reason explains a refusal. Always set when Accepted is false, because a
	// bare "no" leaves an operator with nothing to act on — the common
	// refusals (not installed as a service, already current, no such release)
	// have entirely different fixes.
	Reason string `json:"reason,omitempty"`

	// AlreadyCurrent distinguishes the benign refusal from the rest, so the
	// hub can report "nothing to do" rather than surfacing it as a failure.
	AlreadyCurrent bool `json:"already_current,omitempty"`

	// FromVersion is the build the device is running now, and TargetVersion
	// the one it resolved the request to — which is the newest release when
	// the hub asked for LatestVersion, and is the field that tells the
	// operator what "latest" turned out to mean.
	FromVersion   string `json:"from_version,omitempty"`
	TargetVersion string `json:"target_version,omitempty"`
}

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

type VirtualDispatch struct {
	// ID and Name identify the virtual executor.
	ID   string
	Name string
	// Spec is its configuration, already normalized.
	Spec executor.VirtualSpec
}

type VirtualSource func() (executor.VirtualSpec, error)

type VirtualStart struct {
	// ID is the virtual executor's ID. The device keys the sandbox bridge and
	// its nftables table by it, so two virtual executors on one machine get
	// two firewalls rather than whichever was installed last.
	ID string `json:"id"`
	// Name is the operator-facing label, for the device's own log.
	Name string `json:"name,omitempty"`
	// Firewall is the IP policy for the sandbox bridge. Nil means none.
	Firewall *executor.FirewallRules `json:"firewall,omitempty"`
	// Devices are resolved against the device's live USB inventory at start.
	Devices []executor.DeviceSelector `json:"devices,omitempty"`
}

type WelcomePayload struct {
	// ProtocolVersion is the version the session settled on: the lower of
	// what the two sides support. Both must encode at this version.
	ProtocolVersion int `json:"protocol_version"`
	// ExecutorID is the control plane's ID for this agent, which is also the
	// agent's own identity and the registry key projects bind to. The three
	// are deliberately one value: an operator reading a project binding, an
	// executors-table row, and an agent's log should not have to correlate
	// three different identifiers for the same device.
	ExecutorID string `json:"executor_id"`

	// Credential is the long-lived per-agent credential, sent only on the
	// connection that redeemed an enrollment token. Redemption happens
	// inline on the connect rather than as a separate HTTP call so a device
	// needs exactly one reachable URL and one round trip to enroll.
	//
	// It is the single time this secret crosses the wire; the control plane
	// keeps only its hash. An agent that fails to persist it must re-enroll.
	Credential string `json:"credential,omitempty"`
	// HeartbeatSeconds is the interval the agent must beat at. Sent rather
	// than assumed so the control plane can slow down a large fleet without
	// redeploying every device.
	HeartbeatSeconds int `json:"heartbeat_seconds"`
	// ResumeAccepted answers Hello.Resume, one entry per offer the control
	// plane has a verdict for. Since v5 the verdict is explicit: an entry may
	// say "resume from this offset" or "terminate this workload" (see
	// ResumeAck.Action). Below v5 the hub emits accepted handles only, because
	// an older agent would read a refusal's presence in this list as
	// permission to keep streaming.
	//
	// The field name is historical and no longer literal — every entry used to
	// be an acceptance. It is kept because it is a wire name, and renaming it
	// would strand every deployed agent for the sake of a better noun.
	//
	// A handle the agent offered and that is absent here still means "the
	// control plane is not tracking this". An agent that receives no entry for
	// a workload must stop it rather than merely stop reporting it: nothing
	// will ever read its output, collect its result, or be able to signal it.
	ResumeAccepted []ResumeAck `json:"resume_accepted,omitempty"`
}

type WorkspaceCredential struct {
	// Username is the HTTP basic user. Empty means the broker's GitHub
	// convention, "x-access-token", which executor.GitCredential applies.
	Username string `json:"username,omitempty"`
	// Password is the token. This is the secret; everything else in this
	// struct is bookkeeping.
	Password string `json:"password"`
	// ExpiresAt is the lease deadline, so a device can decline to begin a
	// fetch with a credential that will lapse mid-transfer rather than failing
	// halfway through with an opaque 401.
	ExpiresAt time.Time `json:"expires_at,omitempty"`
	// Host is the host the credential may be presented to (Task 20423): its
	// grant's forge host, or the git proxy's for a session token. The hub
	// chose it for exactly that host; a device scopes it there and refuses a
	// workspace on any other, as executor.GitCredentialConfig does. Not
	// secret. An older hub sends none, and an older agent ignores it.
	Host string `json:"host,omitempty"`
}