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"`
	// MaxConcurrent is the agent's ceiling on simultaneous workloads.
	MaxConcurrent int `json:"max_concurrent,omitempty"`
	// Labels are free-form selectors (region, site, gpu) set by the operator.
	Labels map[string]string `json:"labels,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 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 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 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 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
	// ExternalURL is what this deployment calls itself, e.g.
	// https://cloop.example.com. Its host is always an accepted WebSocket
	// Origin, which is what makes the Executors panel work when a reverse
	// proxy rewrites Host so the same-origin check cannot fire.
	ExternalURL string
	// AllowedOrigins lists additional browser Origins permitted to open an
	// agent WebSocket, on top of loopback, same-origin, and ExternalURL.
	// Entries may be full origins, host:port, or bare hosts.
	AllowedOrigins []string
	// Logf receives operational messages. Nil discards them.
	Logf func(format string, args ...any)
	// Now overrides the clock for tests.
	Now func() time.Time
}

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
	// Now overrides the clock for tests.
	Now func() time.Time
}

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

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

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

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