executor

type AttachConn interface {
	io.ReadWriteCloser

	// Resize reports new terminal geometry. It is a no-op — not an error —
	// for a session without a TTY, so a caller that always sends the window
	// size does not need to know which kind it opened.
	Resize(rows, cols uint16) error
}

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

type AttachRequest struct {
	// HandleID identifies the running workload, as returned by Start.
	HandleID string

	// Command is the argv to run inside the sandbox. Empty means the driver's
	// default interactive shell.
	Command []string

	// TTY requests a pseudo-terminal. Without one the session is a pipe: fine
	// for `tail -f`, useless for anything that draws.
	TTY bool

	// Stdin reports that the caller holds write authority and that the driver
	// should wire an input channel.
	//
	// It is a field of the request rather than a property of the returned
	// session because it must reach the sandbox: `docker exec` without -i and
	// a Kubernetes exec without stdin=true give the remote process no input fd
	// at all. A read-only session is therefore read-only *in the sandbox*, not
	// merely at the hub — there is no open channel to smuggle bytes down.
	Stdin bool

	// Rows and Cols are the initial terminal geometry; ignored when !TTY.
	Rows, Cols uint16

	// Env carries extra environment for the exec'd command (TERM, mainly).
	// Entries are "K=V"; a driver that cannot set environment ignores them.
	Env []string
}

type AttachSessionInfo struct {
	SessionID  string `json:"session_id"`
	ExecutorID string `json:"executor_id"`
	HandleID   string `json:"handle_id"`
	Actor      string `json:"actor"`
	Command    string `json:"command"`
	Writable   bool   `json:"writable"`
}

type Attacher interface {
	Attach(ctx context.Context, req AttachRequest) (AttachConn, error)
}

type BuildReporter interface {
	Executor
	// AgentVersion returns the cloop build the connected device advertised,
	// or "" when there is no live session to ask.
	AgentVersion() string
}

type BundleEntry struct {
	// Path is the repository-relative path, slash-separated.
	Path string
	// Mode is the resulting file mode, one of the Mode* constants. ModeAbsent
	// means the path was deleted.
	Mode string
	// LinkTarget is the symlink destination, for Mode ModeSymlink. The caller
	// reads it out of the blob; this package decides whether it is allowed.
	LinkTarget string
}

type Candidate struct {
	// Executor is the driver instance. Select returns the Candidate, so the
	// caller gets this back to Start on.
	Executor Executor
	// Health is the supervisor's current view. A zero value normalizes to
	// ready, so a caller with no health store still gets sane placement.
	Health Health
	// Labels are operator-assigned scheduler selectors (region, tier, owner).
	Labels map[string]string
	// Harnesses are the agent CLIs available on the node, as detected by
	// pkg/executor/agent.Detect ("claude", "codex", "cloop", ...).
	Harnesses []string
	// ContainerRuntimes are the container runtimes the node can drive.
	ContainerRuntimes []string
	// MemoryMB is total system memory on the node; 0 means unknown, which is
	// never treated as "too small".
	MemoryMB int
	// InFlight is the number of sessions currently running on the node, and
	// InFlightKnown says whether that number is real. A driver that cannot
	// enumerate reports InFlightKnown=false, and capacity is then not
	// enforced — refusing to schedule because load is unknown would make
	// every non-enumerating driver unusable.
	InFlight      int
	InFlightKnown bool
}

type Capabilities struct {
	// Isolation is the strength of the boundary between workload and host.
	Isolation Isolation `json:"isolation"`
	// Virtualized reports whether the workload runs behind a hypervisor — a
	// VM or microVM with a kernel of its own — rather than sharing the
	// executing machine's kernel.
	//
	// It is a separate field rather than a reading of Isolation because the
	// two answer different questions and a driver can need both. A Kata pod
	// on a remote cluster is IsolationRemote (the machine is not ours) *and*
	// virtualized (the kernel is not the node's); collapsing that into one
	// enum value would force every such driver to drop one of the two facts,
	// and Isolation is explicitly not a total order (see placement.go).
	//
	// It stays false unless the driver is certain. A requirement to run
	// virtualized is checked against this field, so a false positive places a
	// workload that must be behind a hypervisor onto one that is not.
	Virtualized bool `json:"virtualized,omitempty"`
	// KernelIsolated reports whether the workload's system calls are served
	// by something other than the executing machine's kernel — a guest
	// kernel in a VM, or gVisor's Sentry.
	//
	// Every virtualized executor is also kernel-isolated; the reverse does
	// not hold, and the gap between them is exactly gVisor. Before this
	// field existed a gVisor sandbox advertised the same capabilities as a
	// runc one, so the stronger boundary an operator had paid for was
	// invisible to placement and a project could not ask for it without
	// demanding a hypervisor it did not need.
	//
	// Like Virtualized it stays false unless the driver is certain, and for
	// the same reason: RequireKernelIsolation is checked against it, so a
	// false positive runs a workload on the host kernel it was told to stay
	// off.
	KernelIsolated bool `json:"kernel_isolated,omitempty"`
	// SupportsStream reports whether Stream returns live output. Drivers
	// that only persist output post-hoc set this false.
	SupportsStream bool `json:"supports_stream"`
	// SupportsSignal reports whether Signal can deliver signals to a
	// running handle.
	SupportsSignal bool `json:"supports_signal"`
	// SupportsResourceLimits reports whether Spec.ResourceLimits is
	// enforced. When false, limits in a Spec are ignored, not an error.
	SupportsResourceLimits bool `json:"supports_resource_limits"`
	// SharesHostFilesystem reports whether Spec.WorkDir refers to a path on
	// the control-plane host. False for remote and for containers with a
	// copied (rather than bind-mounted) workspace.
	SharesHostFilesystem bool `json:"shares_host_filesystem"`
	// NetworkEgress reports whether workloads can reach the network.
	NetworkEgress bool `json:"network_egress"`
	// FilteredEgress reports whether that reach is bounded at the IP layer
	// by a policy cloop installs — an nftables ruleset on the sandbox
	// bridge, an --internal runtime network, or a Kubernetes NetworkPolicy.
	//
	// It is separate from NetworkEgress because the two answer different
	// questions, and conflating them loses both. NetworkEgress says whether
	// the workload has an interface at all, which is what placement needs;
	// this says whether what it reaches through that interface is
	// constrained, which is what an operator auditing the fleet needs.
	//
	// False does not mean "nothing filters this" — a cluster may run its own
	// NetworkPolicy, an operator may firewall the host — it means cloop is
	// not the thing doing it and will not claim credit for it.
	FilteredEgress bool `json:"filtered_egress"`
	// SupportsImageOverride reports whether Spec.Image is honoured. It is
	// false for drivers with no image concept at all (localprocess) and for
	// drivers whose image is fixed by the operator, and it is what lets a
	// project carrying a .cloop/sandbox.yaml be refused *before* it runs
	// with the wrong toolchain rather than after.
	SupportsImageOverride bool `json:"supports_image_override"`
	// SupportsSandboxBuild reports whether Spec.SetupCommands can be baked
	// into a derived image. Building needs a builder on the executor, which
	// a driver that only schedules pre-built images does not have.
	SupportsSandboxBuild bool `json:"supports_sandbox_build"`
	// SupportsWorkspaceProvisioning reports whether this driver can
	// materialise a source tree itself (Spec.Workspace.Kind == "git").
	//
	// It is what makes a non-local executor honest. A driver that ignored the
	// field would start the harness in an empty directory, and the run would
	// look like a working run producing inexplicable output — which is the
	// exact failure this capability exists to turn into a refusal at
	// placement time. Drivers that share the host filesystem report false and
	// are given Kind "bind" instead, because their tree is already there.
	SupportsWorkspaceProvisioning bool `json:"supports_workspace_provisioning"`
	// SupportsProjectSeed reports whether this driver places Spec.ProjectSeed
	// into the workspace before the harness starts.
	//
	// Separate from SupportsWorkspaceProvisioning, which it always accompanies,
	// because the two failures look nothing alike. A driver that cannot
	// provision leaves an empty directory, and the harness says so loudly. A
	// driver that provisions but drops the seed produces a tree that is
	// entirely correct and a `cloop run` that exits on its first line with
	// "no cloop project found" — pointing at the project, which is fine, rather
	// than at the dispatch, which is not. A capability makes that a refusal at
	// placement time instead.
	SupportsProjectSeed bool `json:"supports_project_seed"`
	// ReturnsProjectState reports whether this driver brings a seeded run's
	// changes back — the tasks it finished or created, the steps, events and
	// cost rows it recorded — for the hub to merge into its own copy of the
	// project (Task 20339). See ProjectResultFetcher.
	//
	// It is SupportsProjectSeed's other half, and separate from it because a
	// driver can have one without the other: a v10–v12 remote agent places the
	// seed and returns nothing, which is exactly the gap that let a run finish
	// its task on a device while the dashboard kept showing it pending. The
	// hub reads this to tell "the run came back with no changes" from "this
	// executor cannot report any", and to say which in the project's journal.
	ReturnsProjectState bool `json:"returns_project_state"`
	// SupportsWriteBack reports whether this driver can return the files a
	// workload changed (Spec.WriteBack).
	//
	// Separate from SupportsWorkspaceProvisioning even though the same drivers
	// implement both, because they are two different halves of the run and a
	// driver can genuinely have one without the other — an executor that
	// shares the host filesystem needs neither, and one whose transport cannot
	// carry bytes back can fetch but not return. Every field a driver can
	// quietly drop needs a flag that says so, and this is the one whose
	// omission costs work rather than confusion.
	SupportsWriteBack bool `json:"supports_write_back"`
	// SupportsSandboxMounts reports whether Spec.Mounts is honoured.
	//
	// It is tracked separately from SupportsImageOverride even though the same
	// two drivers implement both, because the failure mode of getting it wrong
	// is silent: a driver that ignores Mounts produces a sandbox that starts,
	// runs, and cannot find the cache directory the project told it to expect.
	// Every field a driver can quietly drop needs a flag that says so.
	SupportsSandboxMounts bool `json:"supports_sandbox_mounts"`
	// SupportsHostMounts reports whether Spec.HostMounts is honoured — i.e.
	// whether this driver can bind a path from the control-plane host into
	// the sandbox.
	//
	// It is not implied by SharesHostFilesystem, and the two are genuinely
	// different answers. localprocess shares the filesystem and cannot bind
	// anything: a granted repository is simply already visible at its own
	// path there. A remote agent can bind, but not paths from *this* host,
	// which it has never seen. Only a driver that both runs here and has a
	// mount namespace to bind into can honour the field, and a driver that
	// ignored it would start a harness whose /repos is empty.
	SupportsHostMounts bool `json:"supports_host_mounts"`
	// SupportsDevices reports whether Spec.Devices is honoured — i.e.
	// whether this driver can expose a host device node inside the sandbox.
	//
	// Distinct from SupportsHostMounts because a device is not a file the
	// driver can bind and be done with. A container runtime needs a cgroup
	// rule permitting the major:minor pair as well as the node itself, and
	// the Kubernetes driver needs the node to advertise the device at all.
	// A driver that quietly dropped the field would produce a sandbox whose
	// /dev is missing exactly the hardware the task exists to talk to, so
	// the honest outcome is a placement refusal naming the executor.
	SupportsDevices bool `json:"supports_devices"`
	// SupportsInterfaces reports whether Spec.Interfaces is honoured — i.e.
	// whether this driver can move a host network interface into the
	// sandbox's network namespace.
	//
	// Separate from SupportsDevices because a netdev is not a node under
	// /dev: there is nothing to bind and no cgroup rule to write, and the
	// runtimes have no flag for it. The operation is a namespace move, which
	// needs the driver to be co-resident with the interface, privileged
	// enough to perform it, and — decisively — to be handing the workload a
	// kernel that will observe the new device. A Kata guest and a gVisor
	// Sentry both build their view of the network when the sandbox starts
	// and never see an interface that arrives afterwards, so on those
	// runtimes this is false even though the move itself would succeed.
	//
	// That last case is why a driver must not treat the field as
	// best-effort. The move appears to work, the host loses the interface,
	// and the workload sees no new link at all: a bench with no wire in it,
	// reported as a success. The honest outcome is a placement refusal
	// naming the executor.
	SupportsInterfaces bool `json:"supports_interfaces"`
	// SupportsEgressScope reports whether Spec.EgressScope is honoured —
	// whether this driver can confine one workload's IP-layer egress
	// independently of the other workloads on the same executor.
	//
	// Its absence is the reason the field cannot simply be best-effort. An
	// executor that ignored a project's request to be cut off from private
	// address space would hand a harness the reach into the operator's
	// internal network that the project had explicitly renounced, and would
	// report success doing it.
	SupportsEgressScope bool `json:"supports_egress_scope"`
	// SupportsSecretFiles reports whether the credential *files* a secret
	// lease produces actually reach the workload.
	//
	// It is the flag whose absence was silent, and expensively so. A lease's
	// environment travelled everywhere; its files were written into the hub's
	// own /dev/shm and named in Spec.Env, which is a delivery only for a
	// workload running on the hub's filesystem. Every isolating driver
	// forwarded the variable and dropped the file. A repo-scoped github_pat
	// delivers its *whole enforcement* as files — a credential helper, a token
	// file, a gitconfig exported through GIT_CONFIG_GLOBAL — and deliberately
	// exports no bare token unless the grant is unrestricted, so what arrived
	// in the sandbox was a path that did not exist and no credential at all.
	//
	// False here refuses such a workload at placement time (see
	// Requirements.RequireSecretFiles) instead of starting a sandbox whose git
	// authentication will fail for a reason nothing names.
	SupportsSecretFiles bool `json:"supports_secret_files"`
	// SecretFilesFromHostPath reports whether the workload reads those files
	// straight off the control-plane host's filesystem, at the path the hub
	// wrote them to.
	//
	// It decides *who materialises*, which is a different question from
	// whether files are supported at all, and the two cannot be collapsed.
	// localprocess reads hub paths, so the hub writes the plaintext and the
	// process opens it. A container also runs on the hub — SharesHostFilesystem
	// is true for it — and still cannot read that directory: it has a mount
	// namespace of its own, and the lease directory is 0700 owned by the hub
	// user while the sandbox runs as an unprivileged UID. So the container
	// driver takes the bytes and stages its own copy, and the hub writes no
	// plaintext at all. Kubernetes and remote are further out again.
	//
	// The rule this field encodes: the hub materialises a credential only for
	// a backend that will genuinely read it from there. Anywhere else, writing
	// it would create a plaintext file on the control plane that nothing ever
	// opens.
	SecretFilesFromHostPath bool `json:"secret_files_from_host_path,omitempty"`
	// MaxConcurrent is the advertised ceiling on simultaneously running
	// handles; 0 means unbounded/unknown.
	MaxConcurrent int `json:"max_concurrent,omitempty"`
	// Platform and Arch describe the execution target (GOOS/GOARCH style).
	Platform string `json:"platform,omitempty"`
	Arch     string `json:"arch,omitempty"`
}

type Clamp struct {
	// Resource is the human name of the field: "cpu", "memory", "disk", "pids".
	Resource string `json:"resource"`
	// Requested is what the run asked for; 0 means it asked for no limit.
	Requested int `json:"requested"`
	// Effective is what it was given.
	Effective int `json:"effective"`
	// Source names the ceiling that bound it — one of the CeilingSource
	// constants.
	Source string `json:"source"`
}

type Clock interface {
	// Now returns the current time.
	Now() time.Time
	// After returns a channel that fires once after d.
	After(d time.Duration) <-chan time.Time
}

type Constraint string

type DevicePermissions string

type EgressScope string

type EgressScopeExplainer interface {
	// ExplainEgressScopeRefusal returns a sentence completing "this executor
	// cannot confine one project's egress independently of its neighbours; ...".
	ExplainEgressScopeRefusal() string
}

type EventSink interface {
	// ExecutorTransition is called once per state change.
	ExecutorTransition(t Transition)
	// ExecutorFailover is called once per session moved off a dead node,
	// including when no replacement could be found (ev.Err is then set).
	ExecutorFailover(ev FailoverEvent)
}

type Executor interface {
	// ID returns the stable, unique identifier of this executor instance.
	ID() string
	// Kind returns the driver implementation name (one of the Kind* consts).
	Kind() string
	// Capabilities describes what this executor supports.
	Capabilities() Capabilities
	// Start launches a workload and returns its handle. The workload
	// outlives ctx.
	Start(ctx context.Context, spec Spec) (Handle, error)
	// Signal delivers sig to a running handle. Signalling an
	// already-finished handle returns nil (the desired end state already
	// holds); an unknown handle returns ErrHandleNotFound.
	Signal(ctx context.Context, handleID string, sig Signal) error
	// Status reports the current state of a handle.
	Status(ctx context.Context, handleID string) (Status, error)
	// Stream returns a channel of output chunks for a handle. The channel
	// is closed when the workload finishes and all output has been
	// delivered. Output produced between Start and Stream is replayed
	// (bounded) so callers do not race the workload's first writes.
	// Cancelling ctx unsubscribes the caller without affecting the
	// workload or other subscribers.
	Stream(ctx context.Context, handleID string) (<-chan LogLine, error)
	// HealthCheck reports whether this executor is able to accept work.
	HealthCheck(ctx context.Context) error
}

type FailoverEvent struct {
	// Session is the claimed session, carrying its *new* claim token.
	Session Session `json:"session"`
	// From is the executor that went unreachable.
	From string `json:"from"`
	// To is the replacement executor, or "" when none was found.
	To string `json:"to,omitempty"`
	// Err is set when placement or re-dispatch failed. The task is still
	// marked failed-with-retry; it just has nowhere to go right now.
	Err error `json:"-"`
	// Reason renders Err for the event payload.
	Reason string    `json:"reason,omitempty"`
	At     time.Time `json:"at"`
}

type FailoverHandler func(ctx context.Context, ev FailoverEvent) error

type GitCredential struct {
	// Username and Password are HTTP basic credentials. For a GitHub PAT the
	// broker's convention is username "x-access-token" and the token as the
	// password.
	Username string
	Password string
	// LeaseID, GrantID and SecretName are bookkeeping for the audit trail and
	// for releasing the lease afterwards. None of them is secret.
	LeaseID    string
	GrantID    string
	SecretName string
	// ExpiresAt is the lease deadline, so a driver can refuse to start a
	// provisioning step whose credential will expire mid-fetch.
	ExpiresAt time.Time
	// Branches is the authorising grant's branch allowlist, when it has one:
	// branch-name globs every push made with this credential must match
	// (Task 20340). Not secret, and not enforceable by anything that holds
	// the credential — a git proxy between the holder and the forge is what
	// applies it (see pkg/executor/gitproxycreds).
	Branches []string
}

type GitStep struct {
	// Name identifies the step for logs and audit records.
	Name string
	// Argv is the command. Argv[0] is always "git" and no element is ever
	// passed through a shell.
	Argv []string
	// Authenticated marks the single step that contacts the remote and so
	// receives the credential in its environment. Exactly one step in a plan
	// has it set, which is what lets a driver deliver the token to one child
	// process instead of to the whole provisioning sequence.
	Authenticated bool
}

type Handle struct {
	// ID is unique within the executor that produced it.
	ID string `json:"id"`
	// ExecutorID is the ID of the executor that owns this handle, so a
	// caller holding only a Handle can find its way back to the driver.
	ExecutorID string `json:"executor_id"`
	// PID is the operating-system process ID *on the executor*. It is 0
	// for drivers where a PID is meaningless or not reported. Host-local
	// tooling (the /proc scan in pkg/multiui that powers the Stop button)
	// relies on this being the real PID for KindLocalProcess.
	PID int `json:"pid,omitempty"`
	// StartedAt is when the workload began, in the control plane's clock.
	StartedAt time.Time `json:"started_at"`
	// Image is the fully-resolved image reference the workload actually ran
	// from — digest-pinned where the driver could resolve one, so the run
	// stays reproducible after the tag moves. Empty for drivers with no image.
	//
	// It is reported here rather than echoed from Spec.Image because the two
	// differ in exactly the case that matters: the spec asks for `python:3.12`
	// and the handle records `python@sha256:…`, which is the only one of the
	// two that will still mean the same thing next month.
	Image string `json:"image,omitempty"`
}

type HandleRecord struct {
	// HandleID is the driver-side handle, unique within ExecutorID. It is the
	// key callers hold, so it is the primary key here too.
	HandleID string `json:"handle_id"`
	// ExecutorID is the executor instance that owns the workload. Rehydration
	// is scoped by it: a driver adopts only its own rows, so two container
	// executors configured against the same runtime never steal each other's
	// containers.
	ExecutorID string `json:"executor_id"`
	// Driver is the Kind* constant of the owning driver, recorded so a sweep
	// can reason about rows whose executor is no longer registered (a
	// container executor removed from config still left containers behind).
	Driver string `json:"driver"`
	// ExternalID is the name the *runtime* knows the workload by, and is the
	// whole point of the record. Its shape is driver-specific:
	//
	//   localprocess  the OS process ID, rendered as decimal
	//   container     the container name
	//   kubernetes    "namespace/podname"
	//   remote        the agent-side handle ID (same as HandleID; the agent
	//                 offers it back on reconnect)
	//
	// It is a string rather than a typed union because nothing outside the
	// owning driver interprets it — the sweep only needs to know a row exists.
	ExternalID string `json:"external_id"`
	// ProjectPath and TaskID identify the work, so an operator reading the
	// table can tell what an orphan was doing and a sweep can scope itself to
	// one project.
	ProjectPath string `json:"project_path,omitempty"`
	TaskID      int    `json:"task_id,omitempty"`
	// PID is the OS process ID where one is meaningful (localprocess), 0
	// elsewhere. Duplicated from ExternalID for localprocess because a
	// typed field is what the liveness check wants.
	PID int `json:"pid,omitempty"`
	// Image is the resolved image reference, for drivers that have one.
	Image string `json:"image,omitempty"`
	// StartedAt is when the workload began, in the control plane's clock. The
	// orphan sweep compares it against a grace period, so it must be the
	// dispatch time and not the time the row was written.
	StartedAt time.Time `json:"started_at"`
	// Deadline is when Spec.TimeoutMinutes expires, or the zero time for an
	// unbounded workload.
	//
	// It is stored as an absolute instant rather than as the original
	// duration because the two disagree in exactly the case it exists for: a
	// hub down for twenty minutes must resume a one-hour timeout with forty
	// minutes left, not restart the hour. A duration would silently extend
	// every timeout by the length of the outage.
	//
	// Drivers whose backend enforces the deadline itself leave this zero and
	// say so — the Kubernetes driver hands the API server
	// activeDeadlineSeconds, which already survives a control-plane restart
	// and is the reason a client-side timer was the wrong mechanism there in
	// the first place. It is the drivers holding a time.AfterFunc in this
	// process (container, localprocess) that lose their timer on a restart
	// and need this to re-arm.
	Deadline time.Time `json:"deadline,omitempty"`
	// Meta carries driver-specific extras that do not deserve a column —
	// a Kubernetes NetworkPolicy name, a container's runtime. Never secrets:
	// this map is persisted verbatim.
	Meta map[string]string `json:"meta,omitempty"`
	// Secrets are the lease bindings the workload was started with, so a
	// revocation arriving after a control-plane restart can still find it.
	//
	// This is the one field that is *material-adjacent* and still safe to
	// persist, and the reason is a property of the type rather than of this
	// call site: SecretBinding carries lease ids, variable names and paths
	// and no values — which is what already lets it be written to
	// executor_sessions and into audit rows. The Spec next to it is not safe
	// and is deliberately absent; see the file header.
	//
	// Without it the driver's lease→handle index was in-memory only, so a
	// rehydrated workload answered HoldsLease with false and a revocation
	// aimed at it reported nothing-to-revoke — a *success* for a credential
	// that was still in use.
	Secrets []SecretBinding `json:"secrets,omitempty"`
	// SecretsRecorded reports whether Secrets is an authoritative answer.
	//
	// It exists because nil is ambiguous in the one direction that matters:
	// "this workload held no leases" and "nobody wrote down which leases this
	// workload held" are the same empty slice, and reading the second as the
	// first is how a revocation silently misses a holder. A row written
	// before bindings were persisted at all decodes with this false, and its
	// driver marks the adopted handle unresolved rather than unbound — see
	// LeaseIndex.Adopt.
	//
	// False is therefore the safe zero value: a writer that forgets to set it
	// produces an over-cautious revocation report, never an over-confident
	// one.
	SecretsRecorded bool `json:"secrets_recorded,omitempty"`
}

type HandleStore interface {
	// PutHandle inserts or replaces the row for rec.HandleID.
	PutHandle(rec HandleRecord) error
	// ListHandles returns the rows owned by executorID, oldest first.
	// Passing "" returns every row, which is what a cross-driver sweep wants.
	ListHandles(executorID string) ([]HandleRecord, error)
	// DeleteHandle forgets one row. Deleting a row that is not there is not
	// an error: a terminal transition can be recorded twice (once by the log
	// pump, once by an explicit reap) and neither call should fail.
	DeleteHandle(handleID string) error
}

type Health struct {
	// ExecutorID is the registry key this health record describes.
	ExecutorID string `json:"executor_id"`
	// State is the current scheduling state.
	State NodeState `json:"state"`
	// Reason is a short human-readable explanation of the current state:
	// the probe error for unreachable, the operator's note for cordoned.
	Reason string `json:"reason,omitempty"`
	// ConsecutiveFailures counts probe failures since the last success. It
	// keeps counting while a node is cordoned so that uncordoning restores
	// the state the probes actually justify rather than optimistically
	// assuming ready.
	ConsecutiveFailures int `json:"consecutive_failures"`
	// LastSeen is the most recent time a probe succeeded. Zero means the
	// node has never been observed healthy by this control plane.
	LastSeen time.Time `json:"last_seen,omitempty"`
	// LastProbe is the most recent time a probe ran, successful or not. The
	// gap between LastProbe and LastSeen is how long a node has been failing.
	LastProbe time.Time `json:"last_probe,omitempty"`
	// StateChangedAt is when State last took a different value, which is what
	// "cordoned 20m ago" in the UI is computed from.
	StateChangedAt time.Time `json:"state_changed_at,omitempty"`
}

type HealthPolicy struct {
	// DegradeAfter is the consecutive-failure count at which a ready node
	// becomes degraded. Must be >= 1.
	DegradeAfter int
	// UnreachableAfter is the consecutive-failure count at which a node is
	// declared unreachable and its work is failed over. Must be >=
	// DegradeAfter.
	UnreachableAfter int
}

type HealthStore interface {
	// LoadHealth returns the persisted health for an executor. An unknown
	// executor yields the zero Health and a nil error — "never probed" is a
	// normal state, not a lookup failure.
	LoadHealth(executorID string) (Health, error)
	// SaveHealth persists a health record, creating it if absent.
	SaveHealth(h Health) error
	// ListHealth returns every persisted health record.
	ListHealth() ([]Health, error)
}

type HostDevice struct {
	// Name identifies the device within its grant, for diagnostics and for
	// the `devices:` selector in a sandbox spec.
	Name string `json:"name"`
	// Source is the absolute path of the device node on the executor's host.
	Source string `json:"source"`
	// Target is the absolute path it appears at inside the sandbox. Empty
	// means the same path as Source, which is what a workload looking for
	// well-known hardware expects.
	Target string `json:"target,omitempty"`
	// Permissions is the access granted. Empty means DeviceReadWrite, which
	// is what a device is useful with and is still short of mknod.
	Permissions DevicePermissions `json:"permissions,omitempty"`
	// LeaseID is the secret lease that authorised this device, so revocation
	// can find it and the audit trail can say who opened it. Empty is
	// permitted only for a device the operator configured directly on the
	// executor, which is not a path any project-scoped grant takes.
	LeaseID string `json:"lease_id,omitempty"`
	// KubernetesResource optionally names the extended resource a Kubernetes
	// node advertises for this hardware ("nvidia.com/gpu", "squat.ai/fuse").
	//
	// It exists because Kubernetes does not take device paths. A device
	// plugin owns the node and hands the container the right one in response
	// to a resource request, so on that driver the path is not the thing
	// asked for — the resource name is. A grant that omits it is honestly
	// undeliverable on Kubernetes rather than silently ignored there; see
	// Capabilities.SupportsDevices.
	KubernetesResource string `json:"kubernetes_resource,omitempty"`
}

type HostExecutionDeniedError struct {
	// ExecutorID is the un-isolated executor that was resolved.
	ExecutorID string
	// ProjectPath is the project whose workload was refused; may be empty
	// for workloads not tied to a project.
	ProjectPath string
	// Alternatives are the IDs of registered executors that *do* isolate,
	// ordered for stable output. Empty means none are configured, which is a
	// materially different (and much more urgent) situation.
	Alternatives []string
}

type HostInterface struct {
	// Name identifies the interface within its grant, for diagnostics and for
	// the `interfaces:` selector in a sandbox spec. It is not an interface
	// name: it is a handle, and may be longer and more descriptive than the
	// kernel would allow a netdev to be.
	Name string `json:"name"`
	// Source is the interface's name on the executor's host.
	Source string `json:"source"`
	// Target is the name it takes inside the sandbox. Empty means keep
	// Source's name.
	//
	// Renaming is worth supporting because the host's name is frequently
	// unusable as a contract: a veth end is named for the pair that created
	// it, and a predictable-network-name NIC is named for its PCI path.
	Target string `json:"target,omitempty"`
	// Address is an optional CIDR to configure on the interface inside the
	// sandbox ("172.31.99.200/24", "fd00::10/64").
	//
	// Optional because the two sensible regimes are both real: a bench with a
	// DHCP server on it wants the sandbox to ask, and a bench without one
	// wants the operator to have decided. Empty means the interface arrives
	// up and unaddressed, which is also what a workload doing raw L2 wants.
	Address string `json:"address,omitempty"`
	// Gateway is an optional default route to install inside the sandbox via
	// this interface. Meaningless without Address and refused without it.
	//
	// Note what this does: it makes the sandbox's default route point at the
	// bench rather than at the runtime's own network. That is usually the
	// intent for an isolated segment and never the intent for a workload that
	// also needs the Internet, so it is opt-in per interface.
	Gateway string `json:"gateway,omitempty"`
	// MTU optionally overrides the interface's MTU inside the sandbox. Zero
	// means leave the kernel's value alone. Jumbo frames on a capture segment
	// are the common reason to set it.
	MTU int `json:"mtu,omitempty"`
	// LeaseID is the secret lease that authorised this interface, so
	// revocation can find it and the audit trail can say who opened it. Empty
	// is permitted only for an interface an operator configured directly on
	// the executor, which is not a path any project-scoped grant takes.
	LeaseID string `json:"lease_id,omitempty"`
}

type HostMount struct {
	// Name is the granted repository's handle, for diagnostics and audit.
	Name string `json:"name,omitempty"`
	// Source is the absolute path on the executor's host.
	Source string `json:"source"`
	// Target is the absolute path it appears at inside the sandbox.
	Target string `json:"target"`
	// ReadOnly binds the source read-only. The zero value is read-write, so
	// callers building one of these by hand get the same default as the
	// runtime flag they render into — the safe default lives in the grant
	// (secretbroker.Constraints.Writable), which is where an operator sets it.
	ReadOnly bool `json:"read_only,omitempty"`
}

type Isolation string

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

type Lister interface {
	// HandleStatuses returns a status snapshot per handle the driver
	// retains, including recently-finished ones. Ordering is unspecified.
	//
	// It is not called Handles because the drivers already expose a
	// diagnostic Handles() []string, and one method name meaning two
	// different things across the same types is how a caller ends up
	// counting strings and believing it counted running workloads.
	HandleStatuses(ctx context.Context) ([]Status, error)
}

type LogLine struct {
	HandleID string     `json:"handle_id"`
	Stream   StreamName `json:"stream"`
	Text     string     `json:"text"`
	Time     time.Time  `json:"time"`
	// Seq numbers chunks per handle starting at 1. Because drivers must
	// never block a workload's writes waiting for a slow consumer, a
	// subscriber that falls too far behind has chunks dropped. A gap in
	// Seq is how a consumer detects that; see Run, which reports it.
	Seq uint64 `json:"seq"`
}

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

type NodeState string

type PlacementError struct {
	// Constraint is the headline reason — the requirement that eliminated
	// the most candidates, which is nearly always the one to fix.
	Constraint Constraint
	// Rejections is the per-candidate detail, ordered by executor ID.
	Rejections []Rejection
	// Considered is how many candidates were offered.
	Considered int
}

type ProjectResult struct {
	// Data is the compressed result document. Empty when Err is set.
	Data []byte
	// Err is the executor's own account of why it could not read the run back
	// — the workload removed its project, the database was written by a newer
	// cloop than the device's. Operator-facing.
	Err string
	// Redact removes the credentials the hub leased to the workload from a
	// string. The hub applies it to everything it takes from Data rather than
	// trusting the device to have scrubbed: a result is written by the party a
	// redaction exists to protect against. Never nil.
	Redact func(string) string
}

type ProjectResultFetcher interface {
	// ProjectResult returns what the device sent back for handleID, once: the
	// result is released to the caller and forgotten, because merging the same
	// run twice would count its spend twice. It returns
	// ErrProjectResultUnavailable when nothing arrived.
	//
	// Call it after the handle's output stream has closed. A device sends the
	// result before the terminal status, and the terminal status is what
	// closes the stream, so by then everything that is coming has come.
	ProjectResult(handleID string) (ProjectResult, error)
}

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

type Rejection struct {
	ExecutorID string     `json:"executor_id"`
	Constraint Constraint `json:"constraint"`
	Detail     string     `json:"detail"`
}

type Requirements struct {
	// ExecutorID pins placement to one node. It is still checked for health
	// and policy: a pin is a statement about *where*, not a license to run on
	// a dead or forbidden node.
	ExecutorID string
	// Labels is a selector; every key must be present on the candidate with
	// the same value.
	Labels map[string]string
	// Harnesses lists agent CLIs the task will invoke. A candidate must
	// advertise all of them, unless it advertises none at all (see
	// hasHarness).
	Harnesses []string
	// Platform and Arch constrain the execution target (GOOS/GOARCH style).
	Platform string
	Arch     string
	// MinMemoryMB rejects nodes that report less memory than this. Nodes
	// reporting 0 (unknown) are not rejected.
	MinMemoryMB int
	// RequireIsolation rejects any node that shares the control-plane host.
	RequireIsolation bool
	// AllowedIsolations, when non-empty, restricts placement to these
	// isolation kinds. Isolation is not a total order (a container and a
	// remote device are differently, not more or less, isolated), so this is
	// a set rather than a minimum.
	AllowedIsolations []Isolation
	// RequireVirtualization demands a node whose workloads run behind a
	// hypervisor — a Kata sandbox, locally or on a remote cluster.
	//
	// Separate from AllowedIsolations because it cuts across it: both a local
	// Kata container (IsolationVM) and a Kata Pod on a remote cluster
	// (IsolationRemote) satisfy it, and no set of Isolation values selects
	// exactly those two without also admitting the non-Kata remote executors
	// that share their isolation value.
	RequireVirtualization bool
	// RequireKernelIsolation demands a node on which the workload's system
	// calls are not served by the executing machine's kernel — either a
	// hypervisor-backed sandbox (Kata) or a userspace kernel (gVisor).
	//
	// Weaker than RequireVirtualization and separate from it because the two
	// are different asks, and conflating them costs real placements. A project
	// whose actual requirement is "a kernel bug in my task must not be a
	// kernel bug on the host" is satisfied by gVisor; making it say
	// `virtualized: true` to express that would refuse every gVisor executor
	// in the fleet, so an operator who had deliberately standardised on gVisor
	// would watch their nodes rejected for a property they had in fact
	// provided.
	RequireKernelIsolation bool
	// RequireContainerRuntime demands a node that can drive containers.
	RequireContainerRuntime bool
	// RequireNetworkEgress demands a node whose workloads can reach the
	// network.
	RequireNetworkEgress bool
	// RequireDevices demands a node that honours Spec.Devices — one that can
	// expose a host device node inside the sandbox.
	//
	// The refusal it produces is the point. A granted /dev/ttyUSB0 is a
	// statement about one machine's hardware, so a project holding that grant
	// and bound to a Kubernetes or remote executor has asked for something no
	// amount of retrying will produce. Saying so at placement time names both
	// facts; the alternative is a harness that opens the path, gets ENOENT,
	// and reports that the device is broken.
	RequireDevices bool
	// RequireInterfaces demands a node that honours Spec.Interfaces — one
	// that can move a host network interface into the sandbox.
	//
	// Narrower than RequireDevices, and the extra narrowness is the point. A
	// device grant needs an executor on the machine with the hardware; an
	// interface grant needs that *and* a runtime whose kernel will notice a
	// link that appears after the sandbox has started, which rules out Kata
	// and gVisor on the very machine that has the wire. Placement is the only
	// layer that can say so before the host has already given the interface
	// away.
	RequireInterfaces bool
	// RequireEgressScope demands a node that can confine one workload's
	// IP-layer egress independently of its neighbours (Spec.EgressScope).
	RequireEgressScope bool
	// RequireResourceLimits demands a node that actually enforces
	// Spec.ResourceLimits rather than ignoring them.
	RequireResourceLimits bool
	// RequireImageOverride demands a node that honours Spec.Image, i.e. that
	// a per-project sandbox can choose its own toolchain there.
	//
	// This is the constraint that makes per-project sandboxes honest. Without
	// it a project pinning `image: rust:1.79` placed on the host driver would
	// run against whatever toolchain the control plane happens to have, get a
	// plausible-looking build failure, and send its author hunting through
	// their own code. Refusing placement and naming the reason is the only
	// outcome that points at the deployment instead.
	RequireImageOverride bool
	// RequireSandboxBuild demands a node that can bake Spec.SetupCommands
	// into a derived image.
	RequireSandboxBuild bool
	// RequireSandboxMounts demands a node that honours Spec.Mounts.
	RequireSandboxMounts bool
	// RequireHostMounts demands a node that honours Spec.HostMounts — a
	// driver that can bind a path from the control-plane host into the
	// sandbox, which is what a local_repo grant needs.
	//
	// This is the constraint that makes "local repositories" and "remote
	// sandbox" an honest either/or rather than a silent failure. A project
	// granted three checkouts on the hub and bound to a Kubernetes or remote
	// executor is refused here, naming both facts, instead of running against
	// an empty /repos on a machine that has never seen those files.
	RequireHostMounts bool
	// RequireWorkspaceProvisioning demands a node that can materialise the
	// source tree itself, because this workload's tree is not already there.
	//
	// Without this constraint the failure mode is the worst kind: the harness
	// starts, finds an empty directory, and reports back on a repository it
	// never saw. Refusing placement converts that into a message naming the
	// executor that cannot fetch.
	RequireWorkspaceProvisioning bool
	// RequireHostFilesystemWorkspace demands a node whose WorkDir really is a
	// path on the control-plane host, because the workload was dispatched with
	// Workspace.Kind "bind" — i.e. with the tree assumed to be there already.
	RequireHostFilesystemWorkspace bool
	// RequireWriteBack demands a node that can return the files the workload
	// changes, because this one's tree does not survive the run.
	//
	// It is the workspace constraint's mirror image, and its failure is the
	// worse of the two. An executor that cannot fetch produces a harness that
	// reports on a repository it never saw; one that cannot write back produces
	// a harness that reports, accurately, on work that is then discarded with
	// the sandbox. The first is confusing on arrival, the second is invisible
	// until someone goes looking for the commit.
	RequireWriteBack bool
	// RequireProjectSeed demands a node that places the hub's `.cloop/` into
	// the workspace it fetched, because a cloned tree carries a source
	// repository and not a cloop project.
	//
	// Its failure is loud but misdirected, which is its own hazard: the harness
	// exits on its first line with "no cloop project found (run 'cloop init'
	// first)", so the operator goes looking at the project — which is intact —
	// instead of at the executor that dropped its state.
	RequireProjectSeed bool
	// RequireSecretFiles demands a node that delivers a secret lease's
	// credential *files* to the workload, not only its environment.
	//
	// The failure it prevents is the quietest one in this list. A node that
	// drops the files still starts, still runs, and still receives the
	// environment variables naming them — so the workload holds
	// GIT_CONFIG_GLOBAL pointing at a directory that does not exist, gets no
	// token (a narrow github_pat deliberately exports none), and fails to
	// authenticate with nothing in the transcript connecting that to the
	// grant. Refusing placement is what turns it into a sentence.
	RequireSecretFiles bool
	// RequireRevocation demands a node that can take a secret lease's material
	// back from a workload that is already running.
	//
	// It is the constraint that makes "revoking a lease takes the credential
	// away" a property of the system rather than of which backend a project
	// happens to be bound to. A driver that cannot honour a revocation still
	// starts the workload and still receives the credential — it simply has no
	// way to give it back, so the TTL and the push revocation become advice.
	// Refusing placement is the only point at which that is visible.
	RequireRevocation bool
	// RequireStream and RequireSignal demand live output and the ability to
	// stop a workload — the two capabilities the Web UI's run panel needs.
	RequireStream bool
	RequireSignal bool
	// AllowDegraded permits placement on a degraded node. Default true via
	// the zero value being "not forbidden"; set ForbidDegraded to tighten.
	ForbidDegraded bool
	// IgnoreCapacity skips the MaxConcurrent check.
	IgnoreCapacity bool
}

type ResourceCeiling struct {
	// CPUMillis caps the CPU allowance in thousandths of a core.
	CPUMillis int `json:"cpu_millis,omitempty"`
	// MemoryMB caps resident memory in megabytes.
	MemoryMB int `json:"memory_mb,omitempty"`
	// DiskMB caps the writable-layer / scratch ceiling in megabytes.
	DiskMB int `json:"disk_mb,omitempty"`
	// PIDs caps the number of processes/threads.
	PIDs int `json:"pids,omitempty"`
}

type ResourceLimits struct {
	// CPUMillis is the CPU allowance in thousandths of a core (1000 = 1 CPU).
	CPUMillis int `json:"cpu_millis,omitempty"`
	// MemoryMB is the resident memory ceiling in megabytes.
	MemoryMB int `json:"memory_mb,omitempty"`
	// DiskMB is the writable-layer / scratch-space ceiling in megabytes.
	DiskMB int `json:"disk_mb,omitempty"`
	// PIDs is the maximum number of processes/threads.
	PIDs int `json:"pids,omitempty"`
}

type RevocationDeniedError struct {
	// ExecutorID and Kind name the driver that was refused.
	ExecutorID string
	Kind       string
	// Bindings are the revocable bindings that made the spec ineligible.
	Bindings []SecretBinding
	// Detail is the driver's own reason, when it implements Revoker but
	// cannot honour a revocation at this moment (an offline agent, a
	// protocol too old). Empty when the driver does not implement Revoker
	// at all.
	Detail string
}

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

type RevokeAction string

type RevokeOutcome struct {
	LeaseID    string      `json:"lease_id"`
	GrantID    string      `json:"grant_id,omitempty"`
	ExecutorID string      `json:"executor_id"`
	State      RevokeState `json:"state"`
	// Action is what was asked for, echoed so a caller reading only the
	// outcome knows whether a kill was requested.
	Action RevokeAction `json:"action,omitempty"`
	Reason string       `json:"reason,omitempty"`
	// SentAt / AckedAt bound how long the material was still live after the
	// operator pressed the button. Operators ask this after an incident.
	SentAt  time.Time `json:"sent_at"`
	AckedAt time.Time `json:"acked_at,omitempty"`
	// Ack is the driver's report, present once State is RevokeStateRevoked.
	Ack *RevokeReport `json:"ack,omitempty"`
	// Error explains a failed or unreachable outcome.
	Error string `json:"error,omitempty"`
}

type RevokeReport struct {
	LeaseID string       `json:"lease_id"`
	GrantID string       `json:"grant_id,omitempty"`
	Action  RevokeAction `json:"action,omitempty"`
	// Known reports whether the driver was holding this lease at all. False
	// is a success, not a failure: the material is not here, which is the
	// end state the revocation asked for.
	Known bool `json:"known"`
	// EnvScrubbed names the variables whose values were dropped. Names only
	// — echoing a revoked credential back to the control plane would be a
	// fine way to write it into a log.
	//
	// A name here means the *control plane's* copy is gone. It does not mean
	// a process that already forked with that variable has lost it; see
	// Killed for the material that needed stronger treatment.
	EnvScrubbed []string `json:"env_scrubbed,omitempty"`
	// FilesRemoved counts credential files wiped.
	FilesRemoved int `json:"files_removed,omitempty"`
	// EgressDropped reports that the lease's network allowlist entry is gone
	// *on this executor*.
	//
	// Only the remote driver sets it, and that is correct rather than an
	// omission. A remote agent keeps an allowlist of its own on the device, so
	// it has something local to drop. The hub's own drivers do not: the
	// allowlist lives in the egress broker's proxy session, which the hub tears
	// down with the lease itself before any driver is asked — reported as
	// WipedLocally, not here. A container or Kubernetes driver claiming to have
	// dropped it would be taking credit for another component's work, and would
	// read as a second, independent guarantee where there is one.
	EgressDropped bool `json:"egress_dropped,omitempty"`
	// Killed lists the handles terminated — for RevokeKill, and for a
	// RevokeScrub the driver could not honour without terminating.
	Killed []string `json:"killed,omitempty"`
	// Error is non-empty when part of the revocation failed. The report is
	// still returned: "I tried and this is what went wrong" is far more
	// actionable than silence, which a hub can only read as unreachable.
	Error string `json:"error,omitempty"`
}

type RevokeRequest struct {
	// LeaseID is the lease being revoked. Required.
	LeaseID string `json:"lease_id"`
	// GrantID narrows the revocation to one grant within the lease. Empty
	// revokes everything the lease delivered.
	GrantID string `json:"grant_id,omitempty"`
	// Reason is operator-facing text carried into the driver's log and the
	// audit trail, so "why did my run lose its token" has an answer on both
	// sides of the link.
	Reason string `json:"reason,omitempty"`
	// Action is scrub or kill. An empty or unknown action is treated as
	// scrub: the conservative reading of a request from a possibly-newer
	// control plane is the one that does not destroy work.
	Action RevokeAction `json:"action,omitempty"`
}

type RevokeState string

type Revoker interface {
	Executor

	// SupportsRevocation reports whether a revocation issued *right now*
	// would be honoured.
	//
	// It is separate from implementing the interface because the two answer
	// different questions. Implementing Revoker is a property of the driver
	// and is known at compile time; this is a property of the moment — a
	// remote agent that is offline, or one speaking a protocol too old for
	// the frame, cannot honour anything even though its driver can.
	SupportsRevocation() bool

	// HoldsLease reports whether any workload this executor tracks was
	// started with material from leaseID.
	HoldsLease(leaseID string) bool

	// Leases lists the lease IDs this executor is currently holding material
	// for, sorted.
	Leases() []string

	// RevokeLease takes one lease's material back.
	//
	// It returns an outcome rather than an error because the caller's next
	// move depends on *which* failure: an error alone cannot say whether the
	// material is gone, in doubt, or definitely still out there. A driver
	// that was not holding the lease returns RevokeStateRevoked with
	// Ack.Known false — "not here" is the end state a revocation wants.
	RevokeLease(ctx context.Context, req RevokeRequest) RevokeOutcome

	// Revocations reports this executor's revocation log, newest first, so
	// the Secrets panel can show what landed and what is still owed.
	Revocations() []RevokeOutcome
}

type RunResult struct {
	Handle Handle
	Status Status
	// Output is the workload's combined stdout+stderr.
	Output []byte
	// Dropped is true when the consumer fell behind and chunks were
	// discarded, so Output is incomplete. Detected via LogLine.Seq gaps.
	Dropped bool
	// WriteBack is what the driver recovered of the workload's file changes,
	// copied from the terminal Status. Nil when the Spec asked for none.
	WriteBack *WriteBackResult
	// Bundle is the git bundle the driver received, for a bundle-mode
	// write-back. Empty for every other mode — a push leaves the objects at
	// the origin, so there is nothing for the hub to carry.
	Bundle []byte
}

type SandboxMode string

type SandboxSettings struct {
	// Mode is where payloads run: on the executor's host, or in a container
	// on it.
	Mode SandboxMode `json:"mode,omitempty"`
	// Engine is the container CLI to drive ("docker", "podman", "nerdctl").
	// Empty lets the executor detect one. Ignored unless Mode is container.
	Engine string `json:"engine,omitempty"`
	// Runtime is the OCI runtime the engine hands each container to — the
	// `--runtime` value. Empty means the engine's default, which is runc or
	// crun. This is the field that decides whether the payload sits behind a
	// hypervisor (kata) or a userspace kernel (runsc); see IsVirtualized.
	Runtime string `json:"runtime,omitempty"`
	// Image is the container image payloads run in. Empty means the
	// executor's own configured default. Ignored unless Mode is container.
	Image string `json:"image,omitempty"`
	// Network is the container network payloads are attached to: "none"
	// (the default), "bridge", or a network the operator created on the
	// device. Ignored unless Mode is container.
	//
	// It exists because "none" is both the right default and unusable for the
	// flow this product is built around. A sandbox reaches its repositories
	// through the hub's git interception proxy, its cluster through the
	// Kubernetes access monitor and its Internet through the egress broker —
	// and all three are *network services*, addressed by URL. Without a
	// network the payload cannot resolve or connect to any of them, so a
	// container-mode remote executor could be granted credentials it had no
	// way to use, and the failure surfaced inside the sandbox as a DNS error
	// rather than at the hub as a refusal.
	//
	// Its own field rather than a derived one, because the answer is a
	// property of the device: which network exists, and whether it reaches
	// the hub, is something the admin who enrolled it knows and the hub does
	// not. Deriving it from "does this dispatch need the proxy" would also
	// silently widen a payload's reach every time a grant was added.
	Network string `json:"network,omitempty"`
}

type SecretBinding struct {
	// LeaseID is the broker lease this material was issued under.
	LeaseID string `json:"lease_id"`
	// GrantID is the specific grant within the lease, when the binding
	// describes one grant rather than every material in the lease.
	GrantID string `json:"grant_id,omitempty"`
	// SecretName is the operator-facing name, for diagnostics.
	SecretName string `json:"secret_name,omitempty"`
	// Kind is the credential kind ("github_pat", "kubeconfig", "egress", …).
	Kind string `json:"kind,omitempty"`
	// EnvKeys names the environment variables this lease contributed. Keys
	// only, never "K=V" — a value here would defeat the whole point.
	EnvKeys []string `json:"env_keys,omitempty"`
	// Files are the credential file paths as the *executor* sees them.
	Files []string `json:"files,omitempty"`
	// Dir is the lease directory holding Files.
	Dir string `json:"dir,omitempty"`
	// Egress marks a binding that also opened a network path (an egress
	// proxy session), so revoking it must drop the allowlist entry and not
	// only the credential.
	Egress bool `json:"egress,omitempty"`
	// ExpiresAt is the lease TTL, so a driver can expire material locally
	// even while it cannot reach the control plane.
	ExpiresAt time.Time `json:"expires_at,omitempty"`
}

type SecretFile struct {
	// LeaseID and GrantID attribute the file, so a driver can tie what it
	// wrote back to the binding that must later scrub it.
	LeaseID string
	GrantID string
	// Dir is the absolute directory the workload expects the file in.
	Dir string
	// Name is a bare file name: no separators, no "." or "..".
	Name string
	// Mode is the permission bits to create it with. Zero means 0600.
	Mode fs.FileMode
	// Content is the plaintext. This is the credential; everything else in
	// this struct is bookkeeping.
	Content []byte
}

type Session struct {
	// ID is unique across the control plane.
	ID string `json:"id"`
	// ExecutorID is the node the session was dispatched to.
	ExecutorID string `json:"executor_id"`
	// HandleID is the driver-side handle, when one was obtained.
	HandleID string `json:"handle_id,omitempty"`
	// ProjectPath and TaskID identify the work, so failover can mark the
	// task failed-with-retry and re-dispatch it.
	ProjectPath string `json:"project_path,omitempty"`
	TaskID      int    `json:"task_id,omitempty"`
	// ClaimToken is the exactly-once guard. Requeueing a session requires
	// presenting the token the session currently carries; the store rotates
	// it atomically, so a second requeue attempt — from a concurrent
	// supervisor, or from this one after a restart — finds a token that no
	// longer matches and is refused with ErrSessionClaimLost.
	ClaimToken string `json:"claim_token"`
	// Attempt counts dispatches, starting at 1.
	Attempt   int       `json:"attempt"`
	StartedAt time.Time `json:"started_at"`
	// Spec is the workload the session was dispatched with, so a failover
	// can re-dispatch it verbatim. It is persisted rather than held in
	// memory precisely because the control plane that requeues a session is
	// often not the one that started it.
	Spec Spec `json:"spec"`
}

type SessionStore interface {
	// RunningSessions returns the sessions currently in flight on an
	// executor. Passing "" returns every running session.
	RunningSessions(executorID string) ([]Session, error)
	// ClaimRequeue atomically transfers ownership of a session away from its
	// current claim token, returning the session with its new token.
	//
	// It must be a single conditional write ("UPDATE ... WHERE id = ? AND
	// claim_token = ?"): that is the entire double-execution guard. It
	// returns ErrSessionClaimLost when the token no longer matches.
	ClaimRequeue(sessionID, claimToken string, at time.Time) (Session, error)
	// CountRunning returns the number of in-flight sessions on an executor,
	// which drain waits on and the UI displays.
	CountRunning(executorID string) (int, error)
}

type Signal string

type Spec struct {
	// WorkDir is the directory the workload runs in. For host-local drivers
	// this is a real path; for remote drivers it is the path *on the
	// executor*, which the driver is responsible for provisioning.
	WorkDir string `json:"work_dir"`
	// Argv is the command and its arguments. Argv[0] is the program. It is
	// never passed through a shell — no quoting or injection surface.
	Argv []string `json:"argv"`
	// Env is the environment in "K=V" form. A nil Env means "inherit the
	// control plane's environment", matching os/exec semantics; an empty
	// non-nil slice means "start with an empty environment".
	Env []string `json:"env,omitempty"`
	// Labels carry routing and bookkeeping metadata (project path, task ID,
	// requesting user). Drivers may surface them for observability; they
	// never affect execution. See LabelRunID for the one a driver reads.
	Labels map[string]string `json:"labels,omitempty"`
	// ResourceLimits bounds the workload where the driver supports it.
	ResourceLimits ResourceLimits `json:"resource_limits,omitempty"`
	// TimeoutMinutes kills the workload after this long. 0 means no
	// timeout — cloop runs are long-lived by design (Task 20148 removed the
	// implicit task timeout), so this must stay opt-in.
	TimeoutMinutes int `json:"timeout_minutes,omitempty"`
	// Harness names the agent CLI this workload will invoke once it is running
	// — "claude" for the claudecode provider, and empty for a provider that
	// talks to an HTTP API and so needs no binary on the machine.
	//
	// Argv does not carry it: argv is `cloop run`, and which harness that
	// process goes on to exec is a property of the *project's* configuration,
	// resolved inside the workload long after placement is over. So the one
	// thing an executor must have for the run to get anywhere is the one thing
	// nothing downstream could see, and a device that advertised no `claude`
	// was dispatched to anyway — failing on the far side with
	//
	//	exec: "claude": executable file not found in $PATH
	//
	// after the hub had leased a credential, delivered it to the device and
	// provisioned a workspace. Every input to that refusal was on the hub
	// before any of it happened.
	//
	// It is a requirement, not an instruction: no driver execs this. It exists
	// so SandboxRequirements can state it and placement can refuse on it, which
	// is why an unset value is not "no harness" but "no opinion" — a caller
	// with no basis for the claim (`cloop executor test`, a smoke run) must not
	// be forced to invent one.
	Harness string `json:"harness,omitempty"`

	// Image overrides the executor's configured sandbox image for this run.
	// Empty means "use the executor's image". A driver that does not
	// advertise SupportsImageOverride must reject a non-empty value rather
	// than run the wrong toolchain silently.
	Image string `json:"image,omitempty"`
	// SetupCommands are shell commands baked into a derived image once per
	// unique (base image, command list) pair — not re-run per workload.
	// Requires SupportsSandboxBuild.
	SetupCommands []string `json:"setup_commands,omitempty"`
	// Mounts re-expose sub-paths of WorkDir elsewhere in the sandbox. See
	// SpecMount: sources are workspace-relative and cannot escape it.
	Mounts []SpecMount `json:"mounts,omitempty"`
	// HostMounts bind absolute paths on the executor's host into the
	// sandbox. Unlike Mounts they may point anywhere, which is why nothing
	// that parses a repo-committed file is allowed to set them: the only
	// writer is a secret lease (secretbroker.KindLocalRepo), where a human
	// named the path and the broker recorded who. See HostMount.
	HostMounts []HostMount `json:"host_mounts,omitempty"`
	// Devices expose host device nodes inside the sandbox. Like HostMounts
	// and for the same reason, nothing that parses a repo-committed file may
	// set them: the only writer is a secret lease
	// (secretbroker.KindHostDevice), where a human named the device and the
	// broker recorded who. A sandbox spec may select among what the project
	// was granted, never add to it. See HostDevice.
	Devices []HostDevice `json:"devices,omitempty"`
	// Interfaces move host network interfaces into the sandbox's network
	// namespace, giving the workload a seat on the segment they are attached
	// to rather than a route through the host.
	//
	// Same authority rule as Devices, and nothing that parses a
	// repo-committed file may set them: the only writer is a secret lease
	// (secretbroker.KindHostInterface). A sandbox spec may select among what
	// the project was granted, never add to it. See HostInterface.
	//
	// Unlike every other field here, honouring this one takes something away
	// from the host: an interface belongs to exactly one network namespace,
	// so for the life of the workload the executor cannot use it.
	Interfaces []HostInterface `json:"interfaces,omitempty"`
	// EgressScope confines this workload's IP-layer network reach
	// independently of the other workloads on the same executor.
	//
	// One-directional like DisableNetwork: a scope can only take reach away.
	// A project that needs to reach private address space says so with an
	// egress grant, which an operator issues; see egressscope.go.
	EgressScope EgressScope `json:"egress_scope,omitempty"`
	// DisableNetwork forces this workload off the network regardless of how
	// the executor is configured.
	//
	// It is deliberately one-directional. A sandbox spec is repo-committed
	// input, so it may *narrow* what the operator granted and may never widen
	// it; there is no corresponding EnableNetwork field, and a spec that wants
	// egress gets it only by the executor already having it (see
	// Requirements.RequireNetworkEgress, which refuses placement instead of
	// quietly turning the network on).
	DisableNetwork bool `json:"disable_network,omitempty"`
	// SandboxHash identifies the sandbox spec this workload was built from,
	// for the audit trail. Drivers surface it as a label; it never affects
	// execution.
	SandboxHash string `json:"sandbox_hash,omitempty"`

	// Secrets attributes parts of Env and the filesystem to the secret
	// leases that produced them, so a driver can take an individual
	// credential back mid-run. See SecretBinding.
	Secrets []SecretBinding `json:"secrets,omitempty"`

	// SecretFiles carries the *contents* of those credential files, for a
	// driver that has to place them itself because the workload cannot read
	// the control plane's filesystem. Empty when the hub materialised them
	// (see Capabilities.SecretFilesFromHostPath) — then Secrets[].Files
	// already names paths the workload can open.
	//
	// json:"-" is a hard rule, not a default. This is the one field of a Spec
	// that holds plaintext, and a Spec is persisted by pkg/executorstore,
	// echoed into the audit trail, and re-read by reconcile after a restart.
	// A wire format that legitimately needs the bytes opts in with a type of
	// its own; see remote.StartPayload.SecretFiles.
	SecretFiles []SecretFile `json:"-"`

	// ProjectSeed carries the hub's `.cloop/` project state — goal,
	// instructions, provider selection and plan — for a workload whose
	// workspace had to be fetched rather than shared. Empty for a bind
	// workspace, where the real `.cloop/` is already at WorkDir.
	//
	// json:"-" for size rather than for secrecy; see seed.go.
	ProjectSeed []byte `json:"-"`

	// Workspace says how the source tree gets into WorkDir. It carries no
	// credential — only the name of a grant — for the reasons set out in
	// workspace.go. The zero value is "unspecified", which leaves a driver's
	// pre-existing behaviour alone.
	Workspace Workspace `json:"workspace,omitempty"`

	// WriteBack says how the file changes the workload produces get back to
	// the hub. It carries no credential either — a push reuses the grant
	// Workspace named — for the reasons set out in writeback.go. The zero
	// value means nothing is returned, which is correct for a driver that
	// shares the hub's filesystem and wrong for every other one; the caller
	// that builds the Spec is responsible for saying so.
	WriteBack WriteBack `json:"write_back,omitempty"`
}

type SpecMount struct {
	// Source is a slash-separated path relative to Spec.WorkDir. It may not
	// be absolute and may not contain a ".." element.
	Source string `json:"source"`
	// Target is the absolute path the source appears at inside the sandbox.
	Target string `json:"target"`
	// ReadOnly maps the source read-only.
	ReadOnly bool `json:"read_only,omitempty"`
}

type State string

type Status struct {
	HandleID   string    `json:"handle_id"`
	ExecutorID string    `json:"executor_id"`
	State      State     `json:"state"`
	PID        int       `json:"pid,omitempty"`
	ExitCode   int       `json:"exit_code"`
	StartedAt  time.Time `json:"started_at"`
	FinishedAt time.Time `json:"finished_at,omitempty"`
	// Error carries the driver-side failure detail for StateFailed. It is
	// a string rather than an error so Status stays serializable across
	// the remote-executor boundary.
	Error string `json:"error,omitempty"`
	// WriteBack reports what the driver recovered of the workload's file
	// changes, once the workload is terminal. Nil means the driver returned
	// nothing — either the Spec asked for no write-back, or the workload is
	// still running. It is metadata only; the bundle bytes, when there are
	// any, are collected through WriteBackFetcher.
	WriteBack *WriteBackResult `json:"write_back,omitempty"`
}

type StreamName string

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

type SupervisorConfig struct {
	// Interval is the probe period for a healthy node.
	Interval time.Duration
	// ProbeTimeout bounds one HealthCheck call. It must be well under
	// Interval so a hung probe cannot stack up rounds.
	ProbeTimeout time.Duration
	// BackoffBase is the first retry delay after a failure; each subsequent
	// consecutive failure doubles it up to BackoffMax.
	BackoffBase time.Duration
	BackoffMax  time.Duration
	// JitterFraction is the proportional jitter applied to every delay
	// (0.2 = ±20%). Clamped to [0, 0.9].
	JitterFraction float64
	// MaxConcurrentProbes bounds how many nodes are probed at once.
	MaxConcurrentProbes int
	// Policy sets the degrade/unreachable thresholds.
	Policy HealthPolicy
	// Rand returns a value in [0,1) for jitter. Nil uses a package-level
	// source; tests inject a deterministic one.
	Rand func() float64
}

type SupervisorOption func(*Supervisor)

type Transition struct {
	ExecutorID string    `json:"executor_id"`
	From       NodeState `json:"from"`
	To         NodeState `json:"to"`
	Reason     string    `json:"reason,omitempty"`
	At         time.Time `json:"at"`
}

type Workspace struct {
	// Kind selects the strategy.
	Kind WorkspaceKind `json:"kind,omitempty"`
	// Repo is the clone URL for Kind git. https only: a token delivered over
	// cleartext http is not a short-lived credential, it is a published one.
	Repo string `json:"repo,omitempty"`
	// Ref is the branch, tag or commit to check out. Empty means the remote's
	// default branch.
	Ref string `json:"ref,omitempty"`
	// Depth is the shallow-fetch depth; 0 fetches full history.
	Depth int `json:"depth,omitempty"`
	// CredentialGrant names the secret grant whose material authenticates the
	// fetch — never the material itself. Empty means an unauthenticated
	// fetch, which only works for a public repository.
	CredentialGrant string `json:"credential_grant,omitempty"`
	// SizeLimitMB bounds the provisioned tree, from the project's
	// .cloop/sandbox.yaml resources.disk. 0 means the executor's own default.
	SizeLimitMB int `json:"size_limit_mb,omitempty"`
}

type WorkspaceAccess struct {
	// Credential authenticates the git commands. It may be empty, for the
	// unauthenticated fetch of a public repository.
	Credential GitCredential
	// Repo, when non-empty, replaces Workspace.Repo for every git command the
	// executor runs against this workspace — the fetch that provisions it and
	// the push that writes back. Empty means no redirection.
	Repo string
}

type WorkspaceCredentialSource interface {
	// ForWorkspace leases material authorising a fetch of w on behalf of
	// projectID. A workspace that needs no credential yields the zero
	// WorkspaceAccess, a no-op release, and a nil error.
	//
	// When no grant authorises the fetch the error is a
	// *WorkspaceGrantError, which names the missing grant. Drivers surface it
	// unchanged rather than starting a workload against an empty tree.
	ForWorkspace(ctx context.Context, projectID string, w Workspace) (WorkspaceAccess, func(), error)
}

type WorkspaceEvent struct {
	Phase        WorkspaceEventPhase
	ExecutorID   string
	ExecutorKind string
	HandleID     string
	ProjectPath  string
	Workspace    Workspace
	GrantID      string
	LeaseID      string
	// DurationMS is set on the end event only.
	DurationMS int64
	// Err is the failure, already redacted, or "" on success.
	Err string
}

type WorkspaceEventPhase string

type WorkspaceGrantError struct {
	// Repo is the clone URL that could not be authenticated.
	Repo string
	// RepoPath is the owner/name form, when the URL had one.
	RepoPath string
	// Grant is the grant the spec named, or "" when none was named and none
	// could be inferred.
	Grant string
	// ExecutorID is the executor the workload was bound to.
	ExecutorID string
	// ProjectPath is the project whose run was refused.
	ProjectPath string
	// Reason distinguishes "no grant exists" from "a grant exists but excludes
	// this repository" — different fixes, so they must not read alike.
	Reason string
}

type WorkspaceKind string

type WriteBack struct {
	// Mode selects the strategy.
	Mode WriteBackMode `json:"mode,omitempty"`
	// Branch is the per-task branch the sandbox commits to, e.g.
	// "cloop/task-42-add-retry". It must not already carry a refs/ prefix.
	Branch string `json:"branch,omitempty"`
	// Message is the commit subject. Empty gets a generated one.
	Message string `json:"message,omitempty"`
	// MaxBundleBytes caps the bundle for Mode bundle. 0 means
	// DefaultWriteBackBundleBytes; values above MaxWriteBackBundleBytes are a
	// validation error rather than being silently clamped, because a project
	// that asked for 1 GiB and got 128 MiB would fail later, further away.
	MaxBundleBytes int64 `json:"max_bundle_bytes,omitempty"`
}

type WriteBackFetcher interface {
	// WriteBackBundle returns the bundle received for handleID. It returns
	// ErrHandleNotFound for an unknown handle and ErrWriteBackUnavailable when
	// the handle produced no bundle.
	WriteBackBundle(handleID string) ([]byte, error)
}

type WriteBackMode string

type WriteBackReason string

type WriteBackRejection struct {
	// Path is the offending repository-relative path.
	Path string
	// Mode is the file mode that was refused, when the mode is the problem.
	Mode string
	// Target is the symlink destination, when that is the problem.
	Target string
	// Reason is the human-readable refusal.
	Reason string
	// Code classifies the refusal into a closed set, for metrics and for
	// alerting.
	//
	// It exists because Reason cannot serve that purpose and must not be
	// made to: it interpolates branch names, commit SHAs and paths, all of
	// which come from the sandbox. Counting rejections by Reason would let
	// a sandbox mint an unbounded number of Prometheus series by varying
	// the branch it pushes — an out-of-memory the isolated workload gets to
	// trigger from inside the box. Code is chosen by the hub from
	// WriteBackReason*, so a sandbox can influence which bucket it lands in
	// but never how many buckets exist.
	//
	// The zero value is WriteBackReasonUnspecified rather than a panic: a
	// rejection with no code is still a valid rejection, and losing the
	// refusal because its classification was forgotten would be strictly
	// worse than losing the classification.
	Code WriteBackReason
	// Branch and CommitSHA locate the refusal in the sandbox's output.
	Branch    string
	CommitSHA string
}

type WriteBackResult struct {
	// Mode is the mode that actually ran, which may be None when the spec
	// asked for one and the tree turned out to be clean.
	Mode WriteBackMode `json:"mode,omitempty"`
	// Branch is the branch the sandbox committed to.
	Branch string `json:"branch,omitempty"`
	// CommitSHA is the tip the sandbox produced. Full 40-hex.
	CommitSHA string `json:"commit_sha,omitempty"`
	// BaseSHA is the commit the sandbox started from — the tip the workspace
	// was provisioned at. The hub verifies the range base..commit rather than
	// the whole branch, so a bundle cannot smuggle history that predates the
	// checkout past the inspection.
	BaseSHA string `json:"base_sha,omitempty"`
	// Pushed reports whether the branch reached the origin.
	Pushed bool `json:"pushed,omitempty"`
	// BundleBytes and BundleSHA256 describe the bundle, for mode bundle. The
	// digest is what lets the hub detect a truncated or altered stream before
	// handing the file to git.
	BundleBytes  int64  `json:"bundle_bytes,omitempty"`
	BundleSHA256 string `json:"bundle_sha256,omitempty"`
	// Commits and FilesChanged are for the operator reading a task record.
	Commits      int `json:"commits,omitempty"`
	FilesChanged int `json:"files_changed,omitempty"`
	// Skipped reports that there was nothing to write back: the harness ran and
	// changed no tracked file. It is distinct from a failure, and distinct from
	// a write-back that never ran, because "the agent produced no edits" is a
	// real and reportable outcome.
	Skipped bool `json:"skipped,omitempty"`
	// SkipReason explains Skipped in one phrase.
	SkipReason string `json:"skip_reason,omitempty"`
	// Err is the failure, already redacted, or "" on success.
	Err string `json:"error,omitempty"`
}