executor

type Abandoner interface {
	Abandon(ctx context.Context, handleID, reason string) error
}

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 BootstrapSource struct {
	// Edge reports that the command installs this hub's own build from the
	// edge channel: `install.sh --channel edge`.
	Edge bool
	// Commit is the full commit of the hub's published edge build: what
	// `--channel edge` installs, whether or not the command uses it. Empty when
	// there is none, and EdgeWhyNot then says why.
	Commit string
	// EdgeWhyNot says why `--channel edge` has nothing to install, for the
	// script's refusal of it. Empty when Commit is set.
	EdgeWhyNot string
	// Note is the sentence shown beside the command; empty when there is
	// nothing to add to it.
	Note string
	// Stopped reports that, as far as the hub knows, no signed build speaks
	// its protocol: the command's installer will stop at the protocol check on
	// a device without a newer cloop, and Note says what to do instead.
	Stopped bool
}

type BranchBundle struct {
	// Branch is the branch the provisioned tree is left on, attached, so the
	// harness's commits land on it. It must live under the cloop/ namespace —
	// the same rule a write-back branch obeys, and for the same reason: the
	// receiver force-creates it.
	Branch string `json:"branch"`
	// Head is the commit Branch points at in the bundle, full 40-hex. The
	// receiver verifies the checkout lands exactly here.
	Head string `json:"head"`
	// Bytes is the bundle's size. Zero means nothing was shipped: on a git
	// workspace the feature has no commits of its own yet, and Branch is
	// created at Workspace.Ref, which must then equal Head.
	Bytes int64 `json:"bytes,omitempty"`
	// SHA256 is the hex digest of the bundle, so a truncated or substituted
	// stream is refused before git reads a byte of it.
	SHA256 string `json:"sha256,omitempty"`
	// Shallow lists the commits at the bundle's lower edge whose parents were
	// deliberately left out, for a Kind bundle workspace shipped as a shallow
	// slice. The receiver records them as shallow before fetching; without
	// that git refuses the bundle as incomplete.
	Shallow []string `json:"shallow,omitempty"`
}

type BranchBundleExplainer interface {
	// ExplainBranchBundleRefusal returns a sentence completing "this executor
	// cannot receive a branch shipped from the control plane; ...", or "" when
	// the driver has nothing more specific than the generic remedy.
	ExplainBranchBundleRefusal() string
}

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"`
	// DiskEnforcement says how ResourceLimits.DiskMB is held, and is empty
	// where it is not (Task 20405). It is separate from SupportsResourceLimits
	// because a driver can enforce the other three and not this one: a remote
	// agent older than protocol v20 runs a container that bounds CPU and
	// memory and refuses a disk limit outright.
	DiskEnforcement DiskEnforcement `json:"disk_enforcement,omitempty"`
	// 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"`
	// SupportsBranchBundle reports whether this driver can receive a git
	// branch shipped beside the Spec (Workspace.Branch and
	// Spec.BranchBundleFile) and build the workload's tree from it, leaving
	// the checkout on that branch (Task 20367).
	//
	// It is what lets a feature — a branch of a repository on the hub — run
	// in a sandbox at all, and it is separate from the provisioning and
	// write-back flags because a driver can have those and still have no way
	// to carry the bytes in: the Kubernetes driver clones and pushes, but a Pod
	// has no channel from the hub to receive a bundle through. A driver that
	// ignored the field would start the harness on the base commit, without
	// any of the feature's work, which is the run-on-the-wrong-code failure
	// this whole contract exists to refuse.
	SupportsBranchBundle bool `json:"supports_branch_bundle"`
	// 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 DeviceBuild struct {
	Protocol int
	Sequence int
}

type DevicePermissions string

type DeviceSelector struct {
	// Name identifies the device in labels, audit rows and error messages.
	Name string `json:"name"`
	// USB selects a USB device by vendor, product and optionally serial or
	// port.
	USB *USBMatch `json:"usb,omitempty"`
	// Path is a device node on the executor's host.
	Path string `json:"path,omitempty"`
	// Permissions is the access granted; empty means read-write. See
	// DevicePermissions for what the container runtime can and cannot enforce.
	Permissions DevicePermissions `json:"permissions,omitempty"`
	// Group is a supplementary group the sandbox user is given so the node's
	// own permissions let it open the device — the group a udev rule assigns
	// to it, by name or number. Empty lets the device infer it from the node
	// when it can see it. Never root's.
	Group string `json:"group,omitempty"`
	// SkipInterfaceNodes passes a USB device's usbfs node alone, without the
	// tty or hidraw nodes its interfaces created. The default passes both,
	// because which of them a tool opens is the tool's business.
	SkipInterfaceNodes bool `json:"skip_interface_nodes,omitempty"`
}

type DiskEnforcement string

type DiskLimitBreach struct {
	// UsedBytes is the workspace's allocated size when it was measured: the
	// blocks its files occupy, hard links counted once, .cloop/ excluded.
	UsedBytes int64 `json:"used_bytes"`
	// LimitMB is the limit it was held to, in MiB.
	LimitMB int `json:"limit_mb"`
	// Source is DiskLimitFromSpec or DiskLimitFromCeiling.
	Source string `json:"source,omitempty"`
	// Path is the tree that was measured, on the executor's own host.
	Path string `json:"path,omitempty"`
	// MeasuredAt is when the measurement finished.
	MeasuredAt time.Time `json:"measured_at"`
}

type DiskLimitError struct {
	Breach DiskLimitBreach
	// Executor is the executor that refused.
	Executor string
}

type DiskLimitExplainer interface {
	// ExplainDiskLimitRefusal returns a sentence completing "this executor
	// cannot hold a workload to a disk limit; ...", or "" when the driver has
	// nothing more specific than the generic remedy.
	ExplainDiskLimitRefusal() string
}

type EdgeBuild struct {
	// Short is the hub's commit as its version carries it, e.g. "a0f3870".
	Short string
	// Target is "edge:<full commit>" once the commit is resolved.
	Target string
	// Published reports that CI published the build; Protocol is what its
	// manifest says it speaks, and Sequence its place on main (Task 20380) —
	// zero when the manifest names none, i.e. a build from before builds were
	// stamped with one, which a device whose build carries one refuses.
	Published bool
	Protocol  int
	Sequence  int
	// WhyNot is the sentence saying why it is not published, when it is not
	// (pkg/upgrade.EdgeBuild.Reason).
	WhyNot string
}

type EgressPosture struct {
	// DeviceID is the executor whose stored rule set is the superset for this
	// one: its own ID, or for a virtual executor its device's.
	DeviceID string
	// Config is the bound the executor's configuration file sets
	// (executors.*.egress_filter) — the level above the device's stored rules.
	// nil when the configuration does not filter.
	Config *FirewallRules
	// Own is the executor's level between the device's rules and the
	// project's: a virtual executor's firewall, or the network a device's own
	// sandboxes are given. nil when it adds no narrowing of its own; a zero
	// rule set when its sandboxes get no network.
	Own *FirewallRules
	// OwnName names Own for a sentence ("virtual executor vx-… 's firewall").
	OwnName string
	// Enforceable reports whether the executor can install a firewall built
	// from rules for one workload — a filtered bridge, a NetworkPolicy.
	Enforceable bool
	// RemovesNetwork reports whether it can start a workload with no network
	// at all, which is how a rule set that reaches nothing is honoured without
	// a packet filter.
	RemovesNetwork bool
	// Reason says why not Enforceable, for a refusal and for the panel.
	Reason string
}

type EgressPostured interface {
	EgressPosture() EgressPosture
}

type EgressProxyRoute struct {
	// Host is the host the workload's proxy variables name: a name the driver
	// pins (Gateway), or the address or name the workload dials as it is.
	Host string `json:"host"`
	// Port is the proxy's port.
	Port int `json:"port"`
	// Gateway asks the driver to resolve Host to the gateway of the network
	// the sandbox joins, and to pin that resolution inside the sandbox.
	//
	// It is how a container on the hub's own engine reaches a proxy that
	// listens on every host interface: the host is at the gateway address of
	// whichever bridge the sandbox lands on, and on an --internal bridge that
	// address is the only one off the sandbox it can route to at all.
	Gateway bool `json:"gateway,omitempty"`
}

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"`
	// Unreachable is when From was found unreachable: the transition's time.
	Unreachable time.Time `json:"unreachable_at,omitempty"`
	// To is the replacement executor, or "" when none was found or the
	// session is exhausted.
	To string `json:"to,omitempty"`
	// Exhausted reports that the claim found the session had already been
	// re-dispatched MaxAttempts times (Task 20391): nothing re-dispatches it,
	// and the store closed it as failover_exhausted.
	Exhausted bool `json:"exhausted,omitempty"`
	// MaxAttempts is the failover cap the claim was decided under.
	MaxAttempts int `json:"max_attempts"`
	// Err is set when the session is exhausted, or placement or re-dispatch
	// failed. The handler still settles the session's tasks; the work just
	// has nowhere to go.
	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 FileIdentity struct{ Dev, Ino uint64 }

type FileOwner struct{ UID, GID int }

type FirewallRules struct {
	// AllowPublicInternet opens every address outside the hard-block set.
	AllowPublicInternet bool `json:"allow_public_internet,omitempty"`
	// AllowCIDRs is the IP allowlist: ranges the sandbox may reach directly,
	// including private ones. A bare address is read as a single host.
	AllowCIDRs []string `json:"allow_cidrs,omitempty"`
	// DenyCIDRs is the IP denylist: ranges the sandbox may never reach,
	// whatever else is allowed.
	DenyCIDRs []string `json:"deny_cidrs,omitempty"`
	// AllowPorts bounds every allow above to these destination ports. Empty
	// means any port.
	AllowPorts []int `json:"allow_ports,omitempty"`
	// Resolvers are DNS servers the sandbox may query and is configured to
	// use, as address literals with an optional port (default 53).
	Resolvers []string `json:"resolvers,omitempty"`
}

type ForeignHandleLister interface {
	ListForeignHandles(executorID string) ([]HandleRecord, error)
}

type GitCA struct {
	// URLs are https base URLs, rendered the way git matches http.<url>.*:
	// scheme, host, port and a path ending in "/".
	URLs []string `json:"urls"`
	// PEM holds one or more CA certificates. Public.
	PEM []byte `json:"pem"`
}

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
	// TokenExpiresAt is when the forge stops honouring Password, for a
	// credential the hub minted — a GitHub App installation token's hour.
	// Zero for a PAT, whose expiry the hub does not know. A git proxy that
	// keeps the credential longer than that renews it through the source that
	// leased it (Task 20375). Not secret.
	TokenExpiresAt time.Time
	// SessionID names the git proxy session this credential is, when a proxy
	// minted one in the forge credential's place (pkg/executor/gitproxycreds):
	// the session's id, which is also its Username. Not secret. Empty for a
	// forge credential handed over as is.
	SessionID 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 HandleClaimer interface {
	ClaimHandle(rec HandleRecord) (bool, error)
}

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 HandleRedactor interface {
	// AddHandleRedactions extends the redaction of handleID's output with
	// values, from its next chunk on, and reports whether the handle is known.
	AddHandleRedactions(handleID string, values ...string) bool
}

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 HeldWorkspaceCredential struct {
	// LeaseID is the secret lease the credential stands on.
	LeaseID string
	// GrantID is the grant that authorised it.
	GrantID string
	// SessionID is the git proxy session it is, when one was minted.
	SessionID string
}

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 Outcome 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 ReplaceOptions struct {
	// Mode of the new file. Zero means 0600; group or world bits are refused.
	Mode fs.FileMode
	// Owner, when set, is given the new file — through its descriptor, never
	// by path. Nil leaves it owned by this process.
	Owner *FileOwner
	// Dir, when set, is the identity the lease directory must still have.
	// A directory renamed away and replaced — by anyone able to rename an
	// entry in its parent, such as the sandbox user who owns it in a sticky
	// /dev/shm — is refused rather than written into.
	Dir *FileIdentity
}

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
	// RequireDiskLimit demands a node that holds a workload to
	// ResourceLimits.DiskMB (Task 20405). Separate from RequireResourceLimits
	// because the two come apart: a remote agent below protocol v20 enforces
	// CPU and memory in its container and refuses a disk limit, so routing a
	// disk-limited spec there would be a dispatch the device turns down.
	RequireDiskLimit 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
	// RequireBranchBundle demands a node that can receive a git branch the
	// control plane ships with the Spec, which is how a feature reaches a
	// sandbox (Task 20367). Refusing is the only alternative to a harness
	// that runs on the feature's base commit with none of its work.
	RequireBranchBundle 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 workspace's disk use in megabytes (Task 20405).
	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 bounds the workspace — the tree the workload works in — in
	// megabytes. Held where Capabilities.DiskEnforcement says how (Task 20405).
	DiskMB int `json:"disk_mb,omitempty"`
	// PIDs is the maximum number of processes/threads.
	PIDs int `json:"pids,omitempty"`
}

type ResultReleaser interface {
	ReleaseResults(handleID string)
}

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"`
	// Widened explains why a revocation naming one grant took the whole lease
	// back on this executor — an agent too old to narrow it (Task 20403).
	// Empty when the executor took back what was asked. It is said rather than
	// hidden because the workload lost credentials nobody revoked, and its next
	// failure should not be a mystery.
	Widened string `json:"widened,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"`
	// Eventual reports that files were withdrawn from the object a running
	// workload reads them through rather than from the workload's own
	// filesystem, so they disappear inside it when the platform next syncs
	// that object — a Kubernetes Pod's projected Secret volume, within the
	// kubelet's sync period (about a minute) — not at the moment of this
	// report. Only the Kubernetes driver sets it (Task 20403).
	Eventual bool `json:"eventual,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 RunReaper interface {
	ReapRun(ctx context.Context, runID string) (reaped []string, err error)
}

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