runner

type AttachOptions struct {
	Cols uint16
	Rows uint16
}

type Capabilities struct {
	Driver string `json:"driver"` // e.g. "docker"
	// ConfinementClasses available on this host/cluster, strongest last.
	ConfinementClasses []types.ConfinementClass `json:"confinement_classes"`
	// Resolved maps each available ConfinementClass to the concrete substrate
	// label that enforces it (e.g. "oci/runc", "oci/runsc", "oci/kata-qemu"), so
	// /healthz can advertise WHICH runtime backs each class — the seam that makes
	// CC3 substrate-pluggability visible to operators. Nil when a driver does not
	// report substrate detail.
	Resolved map[types.ConfinementClass]string `json:"confinement_substrates,omitempty"`
	// StructuralEgress reports L0 support: sandbox has no default route and
	// its only egress path is the wardyn-proxy sidecar.
	StructuralEgress bool `json:"structural_egress"`
	// NetworkPolicy reports L1 support (nftables / NetworkPolicy default-deny).
	NetworkPolicy bool `json:"network_policy"`
	// NetworkPolicyAcknowledged (B1): an operator has accepted an
	// ambient-default-deny-shaped canary failure as expected rather than
	// proven — see substrate.ClassSupport.NetworkPolicyAcknowledged's doc.
	// omitempty: absent on every driver that predates B1 reads the same as
	// false.
	NetworkPolicyAcknowledged bool `json:"network_policy_acknowledged,omitempty"`
	// SessionRecording reports wardyn-rec sidecar support.
	SessionRecording bool `json:"session_recording"`
	// UserDrives reports whether this driver can BIND a member's user drive
	// (migration 0054) into the sandbox — SandboxSpec.Drive.
	//
	// FALSE IS THE FAIL-CLOSED DEFAULT AND IT IS LOAD-BEARING. A driver that
	// says nothing declares no drive support, so the control plane refuses a
	// drive-carrying request rather than admitting one this substrate would
	// reject at CreateSandbox — the same rule ConfinementClasses states one
	// field up: never claim a control that is not structurally enforced, and
	// never schedule a run demanding more than the driver declares.
	//
	// omitempty: absent on a driver that predates the field reads the same as
	// false, which is the safe half.
	UserDrives bool `json:"user_drives,omitempty"`
	// EphemeralDiskEnforcement names WHAT ACTUALLY BINDS a run's Resources.DiskMiB
	// on this deployment: `filesystem` (docker, on a storage driver that can
	// enforce a per-container size quota), `eviction` (kubernetes — the kubelet
	// measures periodically and kills the pod over the limit; it never refuses the
	// write) or `none` (nothing binds it at all).
	//
	// EMPTY READS AS `none`, the same fail-closed direction UserDrives takes: a
	// driver that says nothing claims no enforcement. The orchestrator aggregates
	// it as the WEAKEST across substrates, not the strongest — a deployment must
	// not promise an enforcement one of its substrates cannot deliver.
	//
	// Surfaced on the admin setup status (internal/api's SetupRunner), so an admin
	// setting a disk number can see whether anything will hold it. NOT on the
	// anonymous /healthz.
	EphemeralDiskEnforcement types.StorageEnforcement `json:"ephemeral_disk_enforcement,omitempty"`
}

type ExecSession struct {
	// Stdin writes to the exec's standard input. Close HALF-closes the write
	// side only (the exec observes EOF on stdin) — implementations MUST NOT
	// tear down Stdout/Stderr when Stdin.Close is called; those streams may
	// still be flowing.
	Stdin io.WriteCloser
	// Stdout carries standard output. With ExecSpec.TTY=true it ALSO carries
	// stderr (PTY semantics merge the two onto one stream); with TTY=false it
	// carries ONLY stdout — see Stderr.
	Stdout io.Reader
	// Stderr carries standard error as a SEPARATE stream when ExecSpec.TTY is
	// false. When TTY is true there is no separate stderr channel to read
	// (PTY semantics already merged it onto Stdout), so Stderr reads io.EOF
	// immediately.
	//
	// STREAMING CONTRACT (TTY=false): Stdout and Stderr are UNBUFFERED
	// io.Pipes fed by a single background demux goroutine off ONE underlying
	// connection: a single undrained stderr byte blocks the demux goroutine,
	// Stdout, AND Wait (which observes the same exec). Callers MUST start
	// draining Stderr BEFORE (or concurrently with) the first Stdout read.
	// This mirrors how every demultiplexed docker/moby attach stream must be
	// consumed; it is not implementation-specific.
	Stderr io.Reader
	// Resize changes the PTY window size. A no-op returning nil when the exec
	// has no TTY.
	Resize func(cols, rows uint16) error
	// Wait blocks until the exec exits and returns its exit code.
	Wait func() (int, error)
	// Close tears down ONLY this exec stream — never the sandbox, the agent
	// process, or any sidecar.
	Close func() error
}

type ExecSpec struct {
	Argv []string
	// Env is additional exec-scoped environment (on top of the sandbox's own).
	Env []string
	// TTY requests a pseudo-terminal. PTY semantics MERGE stdout and stderr
	// onto ExecSession.Stdout (ExecSession.Stderr then reads io.EOF
	// immediately — there is no separate channel to read). Without a TTY,
	// stdout and stderr are delivered as SEPARATE streams: a binary protocol
	// riding stdout (SFTP, socat) would be corrupted by interleaved stderr
	// bytes, so a merged stream is only acceptable under PTY semantics.
	TTY bool
	// Cols, Rows seed the initial PTY window size (TTY only); zero lets the
	// implementation pick a default.
	Cols, Rows uint16
}

type ImageChecker interface {
	// ImagePresent reports whether ref is present in the substrate's local
	// image store right now.
	ImagePresent(ctx context.Context, ref string) (bool, error)
}

type ImageRemover interface {
	// ImageRemove deletes ref from the substrate's local image store. A ref
	// already absent (raced by a manual prune, a prior partial cleanup) is
	// NOT an error — same idempotent-teardown contract as StopSandbox.
	ImageRemove(ctx context.Context, ref string) error
}

type InjectionGrant struct {
	GrantID uuid.UUID            `json:"grant_id"`
	Rule    egress.InjectionRule `json:"rule"`
}

type MemberMountPolicy struct {
	// Roots is the shared allowlist (WARDYN_MEMBER_WORKSPACE_ROOTS): absolute,
	// cleaned host prefixes any member's local_dir source must resolve into.
	Roots []string
	// RootsByPrincipal (WARDYN_MEMBER_WORKSPACE_ROOTS_MAP) is the per-member
	// override. A principal with an entry uses ONLY that entry — per-member
	// REPLACES shared, because per-member exists to be the more restrictive
	// control, and a union would make adding a row widen rather than narrow.
	// Keys are lowercased principals (OIDC sub or email, the same dual-key
	// identity a capability_grants `user` subject carries).
	RootsByPrincipal map[string][]string
	// WritableRoots (WARDYN_MEMBER_WRITABLE_ROOTS) is where a member may mark
	// their own mount writable. Empty = nowhere.
	WritableRoots []string
	// WritableDeny (WARDYN_MEMBER_WRITABLE_DENY) carves holes in WritableRoots.
	// Deny WINS over allow, and is checked first.
	WritableDeny []string
}

type Mount struct {
	Source   string `json:"source"`
	Target   string `json:"target"`
	ReadOnly bool   `json:"read_only"`
	// MemberAuthored marks a bind whose SOURCE a MEMBER chose — a member-owned
	// workspace's local_dir. ONLY these are re-checked against
	// SandboxSpec.MemberMountRoots at bind time, because the roots bound what a
	// MEMBER may name and nothing else: the same spec also carries binds WARDYN
	// ITSELF authored (the subscription ~/.claude credential staging, the Bedrock
	// ~/.aws dir) and an operator-owned workspace's dirs, none of which live
	// under any member root. Checking those too refused the credential mounts
	// EVERY model run needs, so no member-owned workspace could run at all on a
	// subscription or Bedrock deployment.
	//
	// Set by internal/api dispatch from the run's member-owned workspaces
	// (memberMountPosture); false — the operator default — everywhere else.
	MemberAuthored bool `json:"member_authored,omitempty"`
	// DriveAuthored marks the ONE bind a driver synthesizes from
	// SandboxSpec.Drive: the host_path user drive's per-person subdirectory.
	//
	// IT IS A LABEL, NEVER A GATE — unlike MemberAuthored, which selects which
	// of a mixed slice of binds the member roots apply to. A drive arrives on
	// its OWN field (SandboxSpec.Drive), so the driver already knows it is
	// looking at a drive; the deployment's WARDYN_USER_DRIVE_HOST_ROOTS ceiling
	// (UserDriveHostRootCheck) therefore runs on EVERY host_path drive
	// unconditionally, and no check anywhere may be written as `if
	// m.DriveAuthored`. One was, and it was fail-OPEN by shape: the flag's only
	// false state is a refactor that stops stamping it, so the check would
	// vanish exactly when the code around it changed.
	//
	// IT NEVER LEAVES THE DRIVER, and never reaches a wire. SandboxSpec.Drive is
	// a types.DriveMount rather than a Mount precisely so the composer clamp, the
	// workspace-source allow-list and the k8s blanket host-bind refusal never see
	// a drive — which also means dispatch puts no Mount carrying this flag into
	// spec.Mounts, and nothing that serializes a SandboxSpec ever observes it.
	// The Docker driver builds a local Mount from the DriveMount so the bind
	// passes through the same value shape every other bind does, stamps this on
	// it, and converts it to the runtime's own mount type in the next statement.
	// The json tag is the struct's shape, not a claim that this field is
	// transmitted; `omitempty` plus "never set outside the driver" means it is
	// absent from every spec that is.
	//
	// So it is DOCUMENTATION IN THE TYPE, kept deliberately (user-drives DESIGN
	// §3.1(5) and §11 Q3, owner default: a bool, converted to a Kind enum at the
	// third authoring class). `git grep -n DriveAuthored` is the whole audit: the
	// declaration, the one assignment, and prose. If a gate ever reads it, that
	// grep is where the fail-open shows up.
	//
	// TWO FLAGS, NOT A Kind ENUM, and this comment is the trigger to change
	// that: N=2 is below the consolidation threshold and MemberAuthored is
	// security-critical code, so a THIRD authoring class — anything that adds a
	// `*Authored bool` beside these two — is the point at which both become one
	// `Kind` field with a closed set of values, rather than three booleans whose
	// illegal combinations are only prevented by everyone remembering.
	DriveAuthored bool `json:"drive_authored,omitempty"`
}

type ProxyConfig struct {
	// RunToken authenticates the sidecars to the control plane (identity
	// provider verifies; it is NOT a secret usable outside the platform).
	RunToken string
	// ControlPlaneURL is where sidecars stream decisions/recordings.
	ControlPlaneURL string
	// ControlPlaneCAPEM is wardynd's internal CA (internal/hoptls): the only
	// root the sidecar trusts for ControlPlaneURL. Public; empty with a
	// loopback http URL only.
	ControlPlaneCAPEM string
	// Policy is the run's egress policy, handed verbatim to the wardyn-proxy
	// sidecar (default-deny domain allowlist, method rules, first-use flag).
	// Drivers MUST deliver it to the sidecar at launch: a proxy without a
	// policy fails closed and the sandbox has no working egress at all.
	Policy types.RunPolicySpec
	// Injection lists the run's auto-mintable api_key grants the proxy
	// resolves at startup (secret values live only in proxy memory — never in
	// the sandbox). Approval-gated api_key grants are NOT included: they would
	// block proxy startup, which fails closed if any injection mint fails.
	Injection []InjectionGrant
	// MITMCACertPEM / MITMCAKeyPEM are the OPTIONAL per-run TLS-MITM CA (PEM)
	// delivered to the proxy sidecar when the policy opts into intercept_tls. The
	// CA private key reaches ONLY the proxy (never the sandbox); the sandbox
	// trusts the public cert (delivered separately via the agent env). Empty =>
	// opaque CONNECT passthrough (no MITM).
	MITMCACertPEM string
	MITMCAKeyPEM  string
	// MITMHosts are OPERATOR-CONFIGURED corp artifact hosts the proxy may TLS-MITM
	// in addition to the built-in LLM hosts, so a corporate registry token can be
	// injected on the wire (the sandbox never holds it). A tight per-host operator
	// allowlist sourced from site-config's artifact overrides — NEVER a blanket and
	// NEVER attacker-controlled (dispatch populates it, the sandbox cannot).
	MITMHosts []string
	// MITMLLM reports whether TLS-MITM of the built-in LLM hosts (Anthropic/OpenAI)
	// is intended for this run (subscription injection or intercept_tls) — as opposed
	// to a CA minted only for artifact-token injection. See proxy.Config.MITMLLM.
	MITMLLM bool
	// GitGrants is the git-broker per-repo allowlist ("<org>/<repo>" -> github_token
	// grant id) delivered to the proxy sidecar's /wardyn/gh/ route so the sandbox
	// reaches only its granted repos (never all of github.com) and the token stays
	// proxy-side. Populated at dispatch from the run's github grants; empty => no
	// repo brokered. See proxy.Config.GitGrants.
	GitGrants map[string]uuid.UUID
	// PATGrants is the git_pat broker's per-HOST allowlist ("host" -> the grant
	// to mint from), backing the proxy's /wardyn/git/ route so a non-GitHub
	// forge's PAT is minted proxy-side and never enters the sandbox. Empty => no
	// host brokered. See proxy.Config.PATGrants.
	PATGrants map[string]proxy.PATGrant
	// ADOGrants is the run's per-person Azure DevOps grant for the proxy's REST
	// gate. See proxy.Config.ADOGrants.
	ADOGrants []proxy.ADOGrantConfig
	// UpstreamProxyURL is the OPTIONAL corporate parent proxy the sidecar chains
	// egress through (http://[user:pass@]host[:port] — https-to-proxy is rejected
	// by the sidecar's own config validation, parseUpstreamProxy). Threaded
	// verbatim to the proxy sidecar; control-plane calls bypass it. Empty =>
	// direct dial.
	//
	// Sourced operator-wide at dispatch (internal/api/runs.go dispatchWithVerify)
	// from the persisted site-config's UpstreamProxySecretRef, resolved to the
	// secret's value. Any resolution failure (unset ref, missing secret, non-http
	// URL) leaves this "" rather than failing the run — see
	// resolveUpstreamProxyURL and its audit event run.upstream_proxy.resolve.
	UpstreamProxyURL string
	// TrustedCAPEM is the operator's corporate CA bundle (WARDYN_TRUSTED_CA_FILE,
	// api.Config.TrustedCAPEM), forwarded verbatim so the sidecar's egress TLS
	// additionally trusts it (never its control-plane calls). Threaded to the proxy via proxy.Config's
	// identically-named field (WARDYN_PROXY_CONFIG_JSON, BuildProxyConfig below).
	// Control-plane-authored, same trust boundary as MITMCACertPEM/MITMCAKeyPEM
	// above; empty => system roots only, byte-identical to today.
	TrustedCAPEM string
	// InternalHosts are the operator-declared internal hostnames
	// (SiteConfig.InternalHosts, forwarded verbatim) eligible for the proxy's
	// private-IP-guard lift. Control-plane-authored (the sandbox cannot set
	// this); empty => no lift, byte-identical to today. Threaded to the proxy
	// via proxy.Config's identically-named field (BuildProxyConfig below).
	InternalHosts []types.InternalHost
	// UpstreamProxyNoProxy is SiteConfig.UpstreamProxyNoProxy, forwarded
	// verbatim: the hosts, .domain suffixes and CIDRs whose dials skip the
	// corporate upstream proxy and are made directly. It is a ROUTING decision
	// only — a bypassed dial still faces the private-IP guard and the run's
	// policy, which is why reaching a private endpoint also needs an
	// InternalHosts declaration.
	UpstreamProxyNoProxy []string
	// LLMUpstreams maps a public vendor host to an operator-configured internal
	// model gateway base URL (api.Config.LLMGateways, forwarded verbatim;
	// WARDYN_ANTHROPIC_BASE_URL/WARDYN_OPENAI_BASE_URL). Control-plane-authored
	// (the sandbox cannot set this); empty => every brokered LLM route dials
	// the vendor host, byte-identical to today. Threaded to the proxy via
	// proxy.Config's identically-named field (BuildProxyConfig below).
	LLMUpstreams map[string]string
	// LLMUnavailableDetail is the control-plane-composed reason the proxy's
	// brokered-LLM 404 gives when this run has no LLM credential behind that
	// route (internal/api's llmUnavailableDetail). Empty => the route's own
	// generic detail. Threaded to the proxy via proxy.Config's identically-named
	// field (BuildProxyConfig below).
	LLMUnavailableDetail string
}

type Resources struct {
	CPUMillis int64
	MemoryMiB int64
	// PidsLimit caps the number of processes/threads in the sandbox — the
	// fork-bomb guard for the host PID space. Zero => driver default.
	PidsLimit int64
	// DiskMiB caps writable storage. Best-effort, and WHAT BINDS IT DIFFERS BY
	// SUBSTRATE — Capabilities.EphemeralDiskEnforcement names which: the docker
	// driver applies it as a storage-driver quota only when the daemon supports a
	// per-container one (overlay2 on xfs+pquota, or btrfs/zfs), otherwise it warns
	// and runs uncapped rather than hard-failing the run; the k8s substrate sets
	// the agent container's resources.limits[ephemeral-storage], where the kubelet
	// enforces it by EVICTING the pod (periodically measured; the write is never
	// refused).
	DiskMiB int64
	// DiskMiBFilled says DiskMiB was FILLED IN for this run from the org's
	// storage.ephemeral.default_disk_mib rather than authored on its policy —
	// the one bit that tells a driver whose host cannot enforce a cap whether
	// refusing the run is the honest answer or the destructive one.
	//
	// An org default arrives by MDM (site-config on every desktop boot), and the
	// desktop tier is overlay2 over ext4, where the docker driver's disk quota
	// FAILS THE CREATE CLOSED. Failing closed is right for a cap a policy asked
	// for and this host cannot keep; applied to a fleet-wide default it would
	// brick every request-less run on every laptop the moment an admin typed a
	// number for the Kubernetes half of the estate. So a FILLED value degrades
	// to uncapped-with-a-warning there (enforcement `none`), while a
	// POLICY-AUTHORED DiskMiB keeps today's fail-closed arm exactly.
	//
	// The k8s substrate ignores the bit on purpose: an ephemeral-storage limit
	// is set and the kubelet evicts either way, so there is no unenforceable
	// case for it to degrade.
	DiskMiBFilled bool
}

type Runner interface {
	Name() string
	Capabilities(ctx context.Context) (Capabilities, error)
	// CreateSandbox provisions the sandbox AND its sidecars (proxy, recorder)
	// with L0 confinement: no default route, egress only via the proxy.
	CreateSandbox(ctx context.Context, spec SandboxSpec) (Sandbox, error)
	// Exec starts the agent process inside the sandbox (PTY attached when
	// recording). Returns when the process has been started, not finished. The
	// returned agentExecID identifies the started process for exec-based substrates
	// (the docker idle-container + `docker exec` path); it is "" for exec-less /
	// main-process substrates (krun), where the container IS the agent. Persist it
	// so the crash reconciler can observe agent liveness across a wardynd restart
	// via AgentStatus.
	Exec(ctx context.Context, ref string, argv []string) (agentExecID string, err error)
	// Wait blocks until the agent process started by Exec for this sandbox ref
	// has exited, returning its exit code. It is ONLY valid after a successful
	// Exec on the same ref (it observes the agent exec Exec created). Wait
	// honours ctx cancellation/deadline and returns an error if no agent exec
	// is tracked for ref (e.g. Exec was never called, or the ref is unknown).
	Wait(ctx context.Context, ref string) (exitCode int, err error)
	// Attach opens a NEW interactive exec (an interactive shell) inside the
	// already-RUNNING sandbox ref and returns a live PTY Session. This is the
	// foundation of interactive session mode: a human attaches to a live PTY in
	// a running sandbox. The exec is SEPARATE from the agent process Wait tracks
	// — it is a fresh shell, so attaching/detaching never affects the agent.
	//
	// Session.Close tears down ONLY the exec stream, NOT the sandbox: detaching
	// leaves the run and its sidecars exactly as they were. The interactive
	// shell is bounded by the SAME L0 egress + confinement envelope as the agent
	// (it runs inside the existing sandbox); Attach opens no new network path
	// (invariant 3). Callers MUST record the human principal for attribution
	// (invariant 4) at the call site (the runner is identity-agnostic).
	Attach(ctx context.Context, ref string, opts AttachOptions) (Session, error)
	// ExecStream launches spec.Argv inside the already-RUNNING sandbox ref as a
	// fresh, streamable exec, distinct from both the agent process Exec starts
	// (Wait/AgentStatus observe THAT one, not this) and from Attach's
	// interactive shell (no PTY tmux session, no shell wrapping — argv runs
	// directly). See ExecSpec/ExecSession for the streaming and TTY-merge
	// contract.
	//
	// UNLIKE Exec, ExecStream MUST be repeatable against the SAME ref: a
	// long-lived consumer (an SSH/SFTP bridge, a multiplexed shell) opens ONE
	// ExecStream per channel against ONE long-lived sandbox ref for the life
	// of the connection, so a substrate that errored or no-op'd on a second
	// call would break that consumer outright. A k8s substrate implements
	// ExecStream on the streaming exec subresource (pods/<name>/exec —
	// repeatable, leaves no pod-spec residue), NOT an ephemeral container
	// (add-only; that add-only limit is what makes Exec one-shot, not
	// ExecStream — see Substrate.Exec's doc).
	//
	// SECURITY: ExecStream opens no new network path (invariant 3). Callers
	// MUST record the human principal for attribution (invariant 4) at the
	// call site (the runner is identity-agnostic) — a raw argv makes this the
	// MORE dangerous of the two streaming primitives, not less.
	ExecStream(ctx context.Context, ref string, spec ExecSpec) (*ExecSession, error)
	Status(ctx context.Context, ref string) (Status, error)
	// AgentStatus reports the AGENT's observed state in a restart-safe way, given
	// the agentExecID Exec returned (persisted on the run row). For exec-based
	// substrates it inspects that exec, so a run whose agent has exited reports a
	// terminal State + ExitCode even while the idle container is still up — the
	// distinction container-level Status cannot make after a restart lost the
	// in-memory exec map. When agentExecID is "" (exec-less/main-process, or Exec
	// never ran) it falls back to Status, where the container IS the agent.
	AgentStatus(ctx context.Context, ref, agentExecID string) (Status, error)
	// StopSandbox is the graceful path (lifecycle auto-stop).
	StopSandbox(ctx context.Context, ref string) error
	// KillSandbox is the kill-switch path: immediate teardown. The control
	// plane cascades identity + credential revocation around this call.
	KillSandbox(ctx context.Context, ref string) error
}

type Sandbox struct {
	Ref    string // container ID / pod name
	Driver string
	// EnforcedClass is what the driver actually applied (>= requested or error).
	EnforcedClass types.ConfinementClass
}

type SandboxSpec struct {
	RunID            uuid.UUID
	Image            string // resolved agent/workspace OCI image
	ConfinementClass types.ConfinementClass
	// Env is non-secret environment: every value here is safe to read straight
	// off the substrate's own object model (a docker container config, a k8s
	// Pod spec — which any principal with pods/get can read). Credential
	// material NEVER passes through here; it rides SecretEnv.
	Env map[string]string
	// SecretEnv is CREDENTIAL-BEARING environment — the same name=value shape as
	// Env, delivered to the agent under the same names — split out because a
	// substrate must be able to deliver it WITHOUT writing the value anywhere an
	// ordinary reader of that substrate can see it. Two dispatch lanes populate
	// it (internal/api's resolveEnvSecretGrants, for env_secret grant VALUES,
	// and applyBedrockTransport, for the resident AWS SigV4 keys / the captured
	// AWS SSO blob); every other variable a run gets is platform configuration
	// and stays in Env.
	//
	// DISJOINT from Env by construction — dispatch's splitSecretEnv MOVES a key
	// from one map to the other, never copies — so a driver may concatenate the
	// two without deduplicating, and no value is ever delivered twice.
	//
	// Driver obligations differ because the exposure differs. The k8s driver
	// MUST route these through the per-run Secret via ValueFrom.SecretKeyRef:
	// an inline EnvVar.Value is readable by anyone holding pods/get in the runs
	// namespace, which is the entire reason this field exists (the same reason
	// the proxy config already travels as a Secret rather than inline). The
	// docker driver passes them as ordinary container env: a container's config
	// is readable only through the daemon socket, i.e. by a principal already
	// root-equivalent on that host — the trust boundary docker's proxyEnv
	// already documents for the run token.
	SecretEnv map[string]string
	// ProxyConfig wires the L0 path: the sandbox's only egress is the
	// wardyn-proxy sidecar identified here.
	ProxyConfig ProxyConfig
	// Resources are hard caps (cgroups / ResourceQuota).
	Resources Resources
	// Labels are attached to the sandbox for attestation selectors and audit.
	Labels map[string]string
	// Mounts are operator/policy-controlled host bind mounts into the sandbox
	// (e.g. a host repo at ~/work for the WSL-migration substrate / a persistent
	// workspace). SECURITY: these are POLICY-controlled, NEVER attacker-controlled.
	// The ONLY population path is internal/api dispatch copying a policy's
	// RunPolicySpec.WorkspaceMounts here; the create-run HTTP request body has no
	// mounts field, so a prompt-injected agent or a malicious run requester can
	// never choose a host mount. Drivers apply these as bind mounts AND enforce a
	// deny-list defense-in-depth (see runner/docker/driver.go) even though the
	// values came from policy. Default ReadOnly.
	Mounts []Mount
	// MemberMountRoots, when non-nil, marks this run as one whose mounts were
	// authored by a MEMBER (a member-owned workspace's local_dir) and carries
	// the operator/MDM-set roots those mounts must resolve inside. Resolved at
	// create-run from the owning member's principal (MemberMountPolicy.RootsFor)
	// and re-checked by the driver at BIND time — the last moment this process
	// can resolve the real path — via ValidateMemberMountSource.
	//
	// NIL for every operator/non-member run, and nil means the driver does
	// EXACTLY what it does today: the member gate is purely additive and can
	// never narrow an operator mount. See member_mount.go for the threat model.
	MemberMountRoots []string
	// Drive is the acting principal's USER DRIVE (migration 0054), already
	// resolved, folded and narrowed by the control plane — nil for every run
	// that did not ask for one. It is NOT a Mount: it never rides
	// RunPolicySpec.WorkspaceMounts, the composer clamp never sees it, and the
	// request that produced it carried a flag rather than a path (the operator-
	// controlled-only mounts guardrail). Drivers mount ObjectName at Target
	// (DriveTarget) with the given mode; the Docker driver still converts it to
	// a Mount internally so the deny matrix runs on the host path.
	Drive *types.DriveMount
	// OnWaiting, when non-nil, reports WHY this sandbox is not up yet, in the
	// substrate's own `<component>: <Reason>[: <message>]` words ("agent:
	// ImagePullBackOff: …", "pod: Unschedulable: …", "image: Pulling: <ref>"),
	// each time that reason CHANGES. It exists because the whole STARTING window
	// is spent INSIDE CreateSandbox — there is no sandbox ref yet, so nothing
	// outside the driver can ask a substrate what it is waiting on — and the
	// answer is already in the driver's hand, read and discarded once per poll.
	//
	// CONTRACT, and the driver relies on every clause of it: called
	// SYNCHRONOUSLY on CreateSandbox's own goroutine, so an implementation must
	// not block (wardynd's does one scoped UPDATE under a 500ms deadline and
	// drops an overdue one); called only while CreateSandbox is still running,
	// never after it returns; only on a CHANGE, so a 200ms poll costs one call
	// per distinct reason rather than five a second; DIAGNOSTIC, so a driver
	// never fails a create because a report could not be delivered. Nil for every
	// driver-level caller (the conformance suite, cmd/wardyn-runner), which is
	// why NotifyWaiting rather than the field is what drivers call.
	OnWaiting func(detail string) `json:"-"`
	// Interactive marks a run that comes up idle for `wardyn attach` (no task is
	// exec'd). Drivers use it to prepare the workspace on the idle main process —
	// e.g. clone the repo into ~/work — so the attach shell isn't empty. A non-
	// interactive run ignores it (its task exec does the preparation).
	Interactive bool
}

type Session interface {
	// Read copies terminal output (PTY bytes) into p. It returns io.EOF when the
	// shell exits or the stream is closed.
	Read(p []byte) (int, error)
	// Write sends keystrokes (PTY bytes) into the shell.
	Write(p []byte) (int, error)
	// Resize informs the PTY of a new window size (e.g. on a browser resize).
	Resize(ctx context.Context, cols, rows uint16) error
	// Close tears down ONLY the interactive exec stream. It does NOT stop the
	// sandbox, the agent process, or any sidecar — detaching a human leaves the
	// run exactly as it was.
	Close() error
}

type Status struct {
	State    types.RunState
	ExitCode *int
	Message  string
}