api

type ADOEntraAccess struct {
	AccessToken string
	Scopes      []string
	ExpiresAt   time.Time
}

type ADOEntraConfig struct {
	// RowID identifies the provider row this capture belongs to. It is part of
	// the stored secret's name, so a deployment offering two Azure DevOps
	// organisations keeps two credentials that cannot overwrite each other.
	RowID string
	// TenantID / ClientID / ClientSecret are the app registration. ClientSecret
	// is optional: a public client authenticates with the code challenge alone,
	// which is the posture a browser-delivered redirect wants.
	TenantID     string
	ClientID     string
	ClientSecret string
	// RedirectURL is the absolute callback URL registered on the application.
	// It must be the control plane's own callback route.
	RedirectURL string
	// Scopes is the row's CEILING: the vso.* scopes this deployment may ever
	// ask for. A sign-in requests these (plus offline access and openid); a
	// later redemption may ask for any subset.
	Scopes []string
	// LoginClientID / LoginTenantID are the application and tenant THIS CONSOLE
	// signs people in with. They are the other half of the 0.7.10 boundary: the
	// subject comparison is only sound when the two tokens come from one app
	// registration, so a row naming anything else is refused by name. Empty
	// values refuse every capture, which is the fail-closed direction.
	LoginClientID string
	LoginTenantID string
	// AuthorityOverride re-points every Entra endpoint at another base URL. It
	// is TEST ONLY and honoured only under AllowTestEndpoints — see
	// ValidateEntraAuthorityOverride.
	AuthorityOverride string
	// AllowTestEndpoints is WARDYN_ALLOW_TEST_ENDPOINTS, the repo's existing
	// acknowledgement that this deployment is a test deployment. Without it an
	// AuthorityOverride is refused rather than ignored.
	AllowTestEndpoints bool
}

type ADOEntraFailure string

type ADOEntraSource func(ctx context.Context) (ADOEntraConfig, bool, error)

type ApprovalService interface {
	Request(ctx context.Context, req types.ApprovalRequest) (types.ApprovalRequest, error)
	// Decide transitions an approval to decision.State (APPROVED or DENIED —
	// the caller picks; there is no separate approve bool, since
	// types.ApprovalDecision.State already says which). decidedByType is kept
	// as its own parameter rather than folded into ApprovalDecision: it is
	// audit attribution (who/what decided), not a property of the decision
	// itself.
	Decide(ctx context.Context, id uuid.UUID, decidedByType types.ActorType, decision types.ApprovalDecision) (types.ApprovalRequest, error)
	Get(ctx context.Context, id uuid.UUID) (types.ApprovalRequest, error)
	List(ctx context.Context, state types.ApprovalState) ([]types.ApprovalRequest, error)
	// CancelForRun moves every still-PENDING approval of a run that has just
	// reached a terminal state to CANCELLED, returning how many moved per kind. It is
	// part of the terminal cascade, beside identity/broker revocation: an
	// approval whose run has ended is a control that cannot function, and a row
	// left PENDING renders live Approve/Deny buttons in the console. reason names
	// the transition ("run_killed", "run_completed", ...). Idempotent by
	// construction — a second call finds nothing PENDING and emits nothing.
	CancelForRun(ctx context.Context, runID uuid.UUID, reason string) (map[string]int, error)
	// ExpireOne moves one still-PENDING approval to EXPIRED (a no-op once decided):
	// wardyn-toolgate's give-up signal (#811). actor is the withdrawing agent.
	ExpireOne(ctx context.Context, id uuid.UUID, actor, reason string) error
	// CountForRun returns how many approvals a run has raised, in ANY state —
	// the per-run cap handleInternalRequestApproval enforces. A sandbox chooses
	// the hosts it asks about, so without that cap the number of rows one run can
	// create is bounded by nothing.
	CountForRun(ctx context.Context, runID uuid.UUID) (int, error)
}

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

type CapState string

type Capability struct {
	ID        string   `json:"id"`
	State     CapState `json:"state"`
	Reason    string   `json:"reason,omitempty"`
	Residency string   `json:"residency,omitempty"`
}

type ComponentInfo struct {
	Selected string `json:"selected"`
	// Available lists every implementation self-registered in this build's seam
	// registry (so /healthz truthfully shows what THIS binary can run — e.g. a
	// tagless build advertises sandbox.available=[]). Empty for seams without a
	// registry (policy_engine today).
	Available []string `json:"available,omitempty"`
	Source    string   `json:"source,omitempty"`
}

type Config struct {
	// Store is the abstract persistence seam (run/policy/grant/approval/audit
	// CRUD + reads). The control plane talks to this instead of *pgxpool.Pool
	// directly, so a future pure-Go backend can be swapped in. Defaults to a
	// store.NewPG(Pool) adapter when wired from wardynd.
	Store store.Store
	// Identity mints/verifies/revokes per-run identities (embedded by default).
	Identity identity.Provider
	// Approvals is the approval FSM service.
	Approvals ApprovalService
	// ApprovalExpiryAfter mirrors WARDYN_APPROVAL_EXPIRY_AFTER, the deployment's
	// ceiling on how long any request waits for a decision. A run's captured
	// wait (captureRunLimits) never exceeds it. 0 means unknown here. Dispatch
	// also mirrors it onto a hold-mode run's sandbox (approval_expiry.go, RL-1).
	ApprovalExpiryAfter time.Duration
	RunLeaseConfig      // the run lease's settings (run_lease_server.go)
	// Broker mints credentials inside the approval-gated transaction.
	Broker MintBroker
	// GitHubRulesets, when set, lets the setup checklist ask GitHub whether the
	// App is ref-confined on a granted repo. Nil omits that row entirely — which
	// is also what happens when no GitHub App is configured, so the vast majority
	// of deployments never make the call.
	GitHubRulesets RefRulesetVerifier
	// Audit records control-plane-originated audit events. The recorder handed in
	// is the shared masking → spooling → store/fanout chain (see cmd/wardynd), so a
	// failed durable write is masked, logged loudly, and spooled to the local
	// append-only fallback for EVERY writer — the API layer no longer spools itself.
	Audit audit.Recorder
	// AuditSpool is the SAME durable fallback spool the recorder chain appends to on
	// a failed store write (see cmd/wardynd buildAuditChain). When set together with
	// AuditDrainRecorder, New starts a background loop that replays spooled events
	// back into the durable store once it recovers and empties the file, so the
	// queryable audit trail heals automatically. Nil disables the drain.
	AuditSpool *AuditSpool
	// AuditDrainRecorder is the RAW durable recorder (store.Recorder — NOT the
	// spooling chain) the spool drain replays into. It must bypass the spool to
	// avoid a re-spool loop / lock re-entry; a nil recorder disables the drain.
	AuditDrainRecorder audit.Recorder
	// AuditSinkDrops, when set, reports per-sink audit-delivery drop counts for
	// the wardyn_audit_sink_drops_total metric (cmd/wardynd wires it to the audit
	// Fanout's DropsByName). Nil omits the metric — a deployment with no SIEM
	// sinks configured has nothing to report.
	AuditSinkDrops func() map[string]int64
	// Runner launches sandboxes. Nil => headless API-only mode.
	Runner runner.Runner
	// AdminToken gates the public API (constant-time bearer compare). Empty
	// disables the public API entirely (fail closed) except /healthz.
	AdminToken string
	// LocalMode enables local host mode: the public-API auth (humanOrAdminAuth)
	// is bypassed entirely and every admin-gated action is attributed to
	// LocalOperator. This is the single-developer localhost path — no SSO, no
	// token, no Dex. It NEVER affects internalAuth (sidecar/run-token
	// verification), so the sidecar callback path is unchanged. The daemon
	// (cmd/wardynd) refuses LocalMode when bound to an EXPLICIT public IP, but
	// only WARNS (does not refuse) on an unspecified bind (0.0.0.0, the
	// WARDYN_LISTEN default) — operators must bind/publish loopback-only for a
	// real guarantee (the Compose default already publishes 127.0.0.1).
	LocalMode bool
	// LocalOperator is the principal stamped on runs/approvals/audit in
	// LocalMode (e.g. "local:<os-user>"). Ignored unless LocalMode is true.
	LocalOperator string
	// MemberMode mirrors WARDYN_USER_DESKTOP (cmd/wardynd's validateMemberModePosture
	// already enforces its precondition at boot). internal/api did not carry this
	// bit before #378/#379: it exists here so handleHealthz can compute
	// token_login — a member-mode desktop's admin token is a PROCESS credential
	// (deploy/desktop/wardyn.env.m-prime.example), never a human sign-in path, so
	// the console must not offer it as one.
	MemberMode bool
	// SSOOnly mirrors WARDYN_SSO_ONLY: the operator's declaration that SSO is the
	// ONLY way into this console. cmd/wardynd's validateSSOOnlyPosture refuses
	// boot unless that is actually true (OIDC configured, admin token/local
	// mode/member mode/no-operator-list override all absent) before this field
	// is ever set, so handleHealthz's sso_only bit — which the sign-in screen
	// reads to drop the admin-token form and the role-derivation caveat — can
	// never overclaim.
	SSOOnly bool
	// SubscriptionPostureOK reports whether this deployment may resolve a SHARED
	// subscription credential (one operator's live Anthropic OAuth token) into an
	// agent run. Decided once at boot by subscriptionInjectPosture (cmd/wardynd) —
	// false on the k8s runner, false when an OIDC issuer is configured, and false
	// off local mode unless WARDYN_ALLOW_SHARED_SUBSCRIPTION waives that one clause.
	//
	// This is a COMPLIANCE boundary, not only a security one: the harness vendor's
	// terms require each end user to authenticate with their own credential, so a
	// multi-user deployment sharing one subscription puts the OPERATOR in breach.
	// It is enforced at three depths — providers are not constructed at boot,
	// dispatch does not author a sentinel grant, and the injection sink refuses to
	// resolve one. The sink is the load-bearing layer: four other code paths can
	// put a sentinel grant on a run without consulting dispatch (a stored policy
	// naming it, an integration_id, a recorded profile, the managed fallback).
	SubscriptionPostureOK bool
	// SubscriptionPostureReason says WHY injection is unavailable, so the setup and
	// integrations surfaces can explain it instead of rendering identically to
	// "the operator never logged in". Empty when SubscriptionPostureOK is true.
	SubscriptionPostureReason string
	// TrustDomain is surfaced in /healthz and used for run SPIFFE ids.
	TrustDomain string
	// DefaultPolicy is applied to runs created without an explicit policy_id.
	DefaultPolicy types.RunPolicySpec
	// TrustedCAPEM is WARDYN_TRUSTED_CA_FILE's content (cmd/wardynd's
	// loadTrustedCA), read once at boot: a PEM bundle of additional roots a
	// corporate TLS-inspecting middlebox signs with. "" (the default) means the
	// knob is unset. Forwarded verbatim to two other trust boundaries dispatch
	// composes per run — the proxy sidecar (runner.ProxyConfig.TrustedCAPEM,
	// which rides WARDYN_PROXY_CONFIG_JSON) and the sandbox's own CA trust
	// (installSandboxTrustedCA, appended to WARDYN_MITM_CA_PEM) — wardynd's OWN
	// outbound TLS trusts it separately, via installTrustedCA mutating
	// http.DefaultTransport at boot. Control-plane-authored only: never a
	// SiteConfig field, never agent-reachable.
	TrustedCAPEM string
	// LLMGateways maps a public model-provider host ("api.anthropic.com" /
	// "api.openai.com") to an operator-configured internal gateway base URL
	// (WARDYN_ANTHROPIC_BASE_URL / WARDYN_OPENAI_BASE_URL, validated by
	// ValidateLLMGateways). Control-plane-authored, same trust boundary as
	// TrustedCAPEM above — the sandbox cannot set this. nil/empty (the
	// default) => every lane dials the public host, byte-identical to today.
	// Consulted by (*Server).llmProviderFor (the api-key lane's host
	// substitution) and, for Anthropic specifically, by
	// (*Server).anthropicBaseURL/anthropicGatewayHost/anthropicGatewayHostPort
	// (the subscription and Wardyn-managed lanes, runs_dispatch_llm.go) and the
	// subscription-injection host allowlist (injection.go). The harness-login
	// (`claude setup-token`) lane never consults it and always stays on the
	// public host — that flow mints the OAuth token itself.
	LLMGateways map[string]string
	// LLMGatewayAuth maps the same public model-provider host key as
	// LLMGateways to an operator-configured injection header/format override
	// (WARDYN_<VENDOR>_GATEWAY_HEADER / _GATEWAY_FORMAT, validated by
	// ValidateLLMGateways) — independent of whether that provider also has an
	// LLMGateways entry. nil/empty (the default) => every provider keeps the
	// harness catalog's compile-time convention (harness.go's Gateway field),
	// byte-identical to today. Consulted by (*Server).llmProviderFor, which
	// applies Header/Format field-by-field onto the InjectionRule it builds —
	// never onto the mint path directly, so a stored/proposed grant always
	// reflects the resolved convention at proposal time.
	LLMGatewayAuth map[string]LLMGatewayAuth
	// RunnerTarget records which target a run is dispatched to ("docker"|"k8s"),
	// or "none" for a headless control plane (-runner none: runs stay PENDING).
	// Defaults to "docker".
	RunnerTarget string
	// UIDir, when set, serves a SPA from this directory at "/".
	UIDir string
	// ControlPlaneURL is the externally-reachable base URL handed to sidecars
	// (proxy config) so they can call the internal endpoints.
	ControlPlaneURL string
	// ControlPlaneCAPEM is wardynd's internal CA certificate (internal/hoptls),
	// handed to every proxy as the only root it trusts for ControlPlaneURL.
	// Empty only when ControlPlaneURL is loopback http (a local install).
	ControlPlaneCAPEM string
	// ProxyURL, when set, overrides the WARDYN_PROXY_URL injected into sandbox
	// env. Defaults to "http://wardyn-proxy:3128" (the per-run proxy sidecar
	// hostname set by the docker driver). Non-secret: it is a network address,
	// not a credential.
	ProxyURL string
	// RecordingStore, when set, serves PTY session replays under
	// GET /api/v1/runs/{id}/recording/{id} (admin-gated) and accepts uploads
	// via PUT /api/v1/runs/{id}/recording (run-token auth).
	RecordingStore recording.Store
	// OIDC, when set, enables human SSO: it mounts /auth/login,/auth/callback
	// and composes oidc.Middleware in front of the admin-gated API
	// so a valid session cookie OR the admin bearer token authenticates a caller.
	// The admin token still works for the CLI when OIDC is configured.
	OIDC *oidc.Authenticator
	// Directory, when set, backs GET /access/directory/search — the
	// console's autocomplete over the identity provider for every "who" field (a
	// governance assignment's subject, the People-step mapping value), so an
	// admin picks a DisplayName and Wardyn stores the ClaimValue instead of
	// hand-typing a group's object GUID.
	//
	// nil is the ABSENT MODE, not a broken one, and it is the default: the
	// handler answers a distinct 503 (directoryUnconfiguredCode) the console
	// reads as "degrade the combobox to a plain text input". Wired only when
	// WARDYN_DIRECTORY_PROVIDER is set (cmd/wardynd's resolveDirectoryConfig,
	// which REFUSES boot rather than handing over a connector that cannot
	// authenticate). Set, it means this daemon can read the WHOLE directory —
	// stated plainly in docs/OPERATIONS.md, because it is a real expansion of
	// the minimal-reach posture rather than a convenience toggle.
	Directory directory.Directory
	// SessionRevocations is the write side of the revoke-a-human-now
	// lever: handleRevokeSessions calls RevokeSub/RevokeAll on it.
	// oidc.Middleware holds the matching READ side (Config.Revocations, wired
	// by the same cmd/wardynd adapter) — this field is nil exactly when OIDC
	// is unconfigured, and the revoke-sessions route only mounts when it is
	// set (see routes.go).
	SessionRevocations oidc.SessionRevocations
	// OperatorEmails is WARDYN_OIDC_OPERATOR_EMAILS, the legacy admin allowlist.
	// internal/api no longer reads this field directly: requireOperator/isOperator
	// (http.go) gate on the session's derived Role instead. The list still
	// matters — cmd/wardynd feeds the SAME value into oidc.Config.LegacyAdminEmails,
	// so an email on it is still an additional RoleAdmin match at OIDC-login role
	// derivation time (see internal/auth/oidc's deriveRole) — it just flows through
	// Session.Role now instead of being re-checked a second time here. Kept on
	// Config (not deleted) so that wiring keeps compiling; read it here only if you
	// need the raw configured list for display (e.g. an admin-facing settings page),
	// never to gate a request.
	OperatorEmails []string
	// AllowEmailMappings is WARDYN_OIDC_ALLOW_EMAIL_MAPPINGS (Q7 adjudication,
	// docs/design/people-access-prompt.md): the console People-step opt-in
	// gate for an email-shaped (contains "@") role-mapping VALUE on
	// POST /access/mappings. Default false refuses one with EMAIL_KEY_REFUSED
	// (access.go) — an SSO/Entra deployment's default posture steers an admin
	// to an App Role or group key instead. Belongs on api.Config, not
	// oidc.Config: it gates a CONSOLE WRITE, not a boot-time role-derivation
	// input, and env WARDYN_OIDC_ROLE_MAP's own email-keyed entries are
	// UNAFFECTED either way (legacy, still boot-warned separately — see
	// buildOptionalFeatures).
	AllowEmailMappings bool
	// UserMounts is the operator/MDM-set posture for MEMBER-authored local_dir
	// binds (WARDYN_USER_WORKSPACE_ROOTS + _MAP + WARDYN_USER_WRITABLE_ROOTS
	// + _DENY, parsed at boot by runner.ParseUserMountPolicy). The ZERO VALUE
	// — the default — means a member may not onboard a host directory at all
	// (repos and operator-owned workspaces are unaffected), which is the
	// fail-closed posture the section-(c) threat model requires. It bounds ONLY
	// mounts on a member-OWNED workspace; an operator's mounts are never
	// narrowed by it. See internal/runner/member_mount.go.
	UserMounts runner.UserMountPolicy
	// UserDriveHostRoots is the operator/MDM-set ceiling over admin-authored
	// host_path USER DRIVES (WARDYN_USER_DRIVE_HOST_ROOTS, parsed at boot by
	// runner.ParseUserDriveHostRoots). The ZERO VALUE — the default — means NO
	// host_path drive may be authored at all, the same fail-closed posture
	// UserMounts takes above and for the same reason: a drive's host root is
	// authored in the database and bound into OTHER PEOPLE's sandboxes, so its
	// ceiling has to live where a console compromise cannot reach it.
	//
	// A []string rather than the types.UserDriveHostRootCheck closure because
	// GET /drives has to report whether a ceiling is CONFIGURED (so the console
	// can disable the host_path option with the reason rather than offering a
	// save that 422s), which a func value cannot answer. The closure is built
	// from it at the write boundary — see Server.userDriveHostRootCheck.
	UserDriveHostRoots []string
	// ImageBuilder, when set, builds a per-run sandbox image from the
	// devcontainer_repo in a create-run request. Nil disables devcontainer
	// builds (the request degrades to the convention image).
	ImageBuilder ImageBuilder
	// AgentImages, when set, is an agent-name -> OCI image-ref map that
	// overrides the ghcr convention image for named agents. Agents not present
	// in the map fall back to the convention. Validated at server construction
	// (must parse if set); nil disables the override and the convention is used
	// for every agent.
	AgentImages map[string]string
	// AgentAnthropicModel, when set, pins the ANTHROPIC_MODEL env inside a
	// claude-code sandbox (e.g. "opus") so the agent uses a specific model rather
	// than the account/CLI default (which a promo can push to a cheaper model like
	// Fable). Empty = unset; the CLI's own default is used. Applies in both
	// subscription and api-key auth modes.
	AgentAnthropicModel string
	// BedrockRegion / BedrockModel, when BOTH set, opt a claude-code run into the
	// Amazon Bedrock Anthropic transport (CLAUDE_CODE_USE_BEDROCK) instead of the
	// default api-key/proxy-inject path — an enterprise path with no direct
	// Anthropic egress, billed via AWS. BedrockModel is a Bedrock model id (a
	// cross-region inference-profile id like "us.anthropic.claude-..." is what
	// claude-code actually expects, not a bare foundation-model id). Boot-time
	// config only (mirrors AgentAnthropicModel — no live admin write path); the
	// AWS credentials themselves come from the secret store (aws-access-key-id /
	// aws-secret-access-key / optional aws-session-token), read directly at
	// dispatch time because Bedrock's AWS SigV4 request signing can't be
	// proxy-injected the way a static x-api-key header can (see runs.go
	// resolveBedrockAuth). Empty BedrockRegion or BedrockModel disables Bedrock
	// entirely; a subscription-mode run always takes priority over Bedrock.
	BedrockRegion string
	BedrockModel  string
	// BedrockBaseURL re-points the Bedrock DATA plane (bedrock-runtime) at a
	// private VPC/PrivateLink endpoint — the default posture for a regulated
	// estate, where inference traffic must never traverse the public internet.
	// Normalized https base URL (WARDYN_BEDROCK_BASE_URL, validated by
	// ValidateBedrockBaseURL at boot). Empty (the default) => every Bedrock
	// lane dials the regional public host, byte-identical to today.
	//
	// A boot flag, never a SiteConfig field: in bearer mode this value
	// IS the TLS-MITM target and the Authorization-injection scope, so a
	// runtime-writable field would let an admin re-point the operator's Bedrock
	// credential at a host of their choosing with no restart and no boot log —
	// the trust class THREAT-MODEL.md pins as boot-time-only. It is deliberately
	// NOT folded into LLMGateways either: that map carries brokered
	// reverse-proxy semantics (a run's api_key grant targets it and the
	// proxy serves the host over /wardyn/llm/*), while Bedrock is a CONNECT
	// tunnel with SigV4, or MITM + bearer.
	//
	// Ceiling: ONE data-plane host per deployment — the override wins
	// for every region, including a workspace's own region override, so a
	// multi-region estate must not set it. The CONTROL plane
	// (bedrock.<region>.amazonaws.com) is deliberately NOT overridden; an
	// inference-profile ARN is the answer there.
	BedrockBaseURL string
	// AWSSSOEndpointOverride re-points the two AWS IAM Identity Center services
	// (sso-oidc and the sso portal) at ONE server of the operator's choosing —
	// a TEST hatch, and nothing else. It exists so "a member signs in on
	// Kubernetes and their Bedrock run gets per-user credentials" is provable
	// without a real AWS tenant, by pointing the login sandbox, the dispatch
	// egress list and the dispatch-time token renewal at test/awsssofake running
	// on the cluster. See awssso_endpoint.go for the five derivations it moves
	// and why it is neither BedrockBaseURL nor the global AWS_ENDPOINT_URL.
	//
	// Normalized by ValidateAWSSSOEndpointOverride at boot, which REFUSES a
	// non-empty value unless WARDYN_ALLOW_TEST_ENDPOINTS=true; wardynd also
	// WARNs on every boot that carries it. Empty (the default, and every real
	// deployment) => every SSO derivation is byte-identical to a build that
	// never had this field. A BOOT flag, never a SiteConfig field, for the same
	// reason as BedrockBaseURL: a runtime-writable spelling would let an
	// admin re-point a credential exchange with no restart and no boot log.
	AWSSSOEndpointOverride string
	// AllowTestEndpoints is WARDYN_ALLOW_TEST_ENDPOINTS: the only thing that lets
	// a model provider's bedrock.base_url be plain http:// (validateProviderBedrock).
	AllowTestEndpoints bool

	HarnessLoginCPUMillis int // WARDYN_HARNESS_LOGIN_CPU_MILLIS; see harnessLoginResources (harnesscred.go)
	HarnessLoginMemoryMiB int // WARDYN_HARNESS_LOGIN_MEMORY_MIB; ditto — still governance-ceiling capped

	// AWSSSOProxyInject is the kill switch for proxy-side SSO token injection
	// (WARDYN_AWS_SSO_PROXY_INJECT,
	// resolved by ResolveAWSSSOProxyInject at boot): when true a captured-AWS-SSO
	// Bedrock dispatch stages an inert placeholder in the sandbox's token cache
	// and authors a proxy-side injection of the real token onto that run's own
	// portal.sso host, so the session is never resident; when false NEW
	// dispatches stage the real token in the sandbox's own cache instead (a run
	// already dispatched keeps its authored lane until it ends).
	//
	// It is the rollback for an SDK or corporate-MITM surprise without a
	// downgrade. See runs_dispatch_sso_inject.go for the default and docs/ENV.md
	// for the operator-facing contract.
	AWSSSOProxyInject bool
	// BedrockAWSConfigDir, when set, bind-mounts a host AWS config directory
	// (a `~/.aws`) READ-ONLY into the sandbox at /home/agent/.aws, so the AWS
	// SDK inside the run resolves credentials itself — including short-lived AWS
	// SSO / IAM Identity Center sessions, which it refreshes on demand. This is
	// the HOST-MODE alternative to pasting static aws-access-key-id/-secret
	// secrets (which expire under SSO and must be re-pasted): with the mount,
	// `aws sso login` on the host is enough and nothing is stored in Wardyn.
	// It is OFF by default. Host-mode setup.sh auto-detects ~/.aws; the compose
	// stack supports it too via the WARDYN_BEDROCK_AWS_DIR bind (same
	// host==container path, :ro — see deploy/compose/docker-compose.yaml), an
	// opt-in the operator sets explicitly. Because it mounts the operator's
	// ambient cloud credentials into runs, it is a single-user / self-hosted
	// choice, not for a shared multi-tenant service (invariant 1) — the deliberate
	// residency tradeoff already accepted for the ~/.claude subscription mount.
	// Empty = disabled. Takes precedence over the resident static-key path but not
	// over a bedrock-api-key bearer.
	BedrockAWSConfigDir string
	// BedrockAWSProfile, when set, is passed as AWS_PROFILE into the sandbox so
	// the SDK selects a named profile from the mounted config (common with SSO:
	// `aws sso login --profile X`). Only meaningful with BedrockAWSConfigDir.
	BedrockAWSProfile string
	// BedrockAWSSSORegion is the AWS region whose SSO endpoints (oidc.<r>,
	// portal.sso.<r>) the sandbox is allowed to reach so the SDK can exchange an
	// SSO token for role credentials. It often differs from BedrockRegion.
	// Empty defaults to BedrockRegion. Used by the BedrockAWSConfigDir mount path
	// AND by the containerized `aws sso login` (harnessLogin.loginEgress), which
	// has no other way to know which regional SSO endpoints to allow.
	BedrockAWSSSORegion string
	// Secrets is the at-rest secret store. It backs the admin secret-management
	// endpoints (PUT/DELETE/list — values are NEVER readable via the API) and
	// the internal injection-resolve endpoint the proxy calls at startup. Nil
	// disables both surfaces.
	Secrets secretstore.Store
	// MaskRegistry, when non-nil, is used to mask verbatim secret values from
	// PTY capture / asciicast uploads before they reach the RecordingStore.
	// A nil registry disables masking (existing tests stay green).
	MaskRegistry *secretmask.Registry
	// ADOEntra resolves the Azure DevOps Entra app registration the per-user
	// sign-in runs against (see ado_entra.go). Nil — the default — means this
	// deployment offers no Azure DevOps sign-in and both of its routes refuse.
	// A function rather than a value so the provider row stays the single
	// source of truth and the sign-in never acts on a cached copy of it.
	ADOEntra ADOEntraSource
	// SubscriptionToken, when non-nil, yields the operator's LIVE Anthropic
	// subscription OAuth access token from the resident ~/.claude credentials.
	// The internal injection-resolve endpoint uses it to inject a fresh token
	// per request for subscription runs (secret name subscriptionOAuthSecret),
	// so the sandbox holds only an inert sentinel instead of a copy that goes
	// stale. Nil disables the subscription-injection path (falls back to the
	// resident-copy behavior).
	SubscriptionToken subscription.Provider
	// ManagedToken, when non-nil, yields the Wardyn-MANAGED Anthropic subscription
	// token — a long-lived `claude setup-token` the operator captured via the
	// container-login flow, stored age-encrypted. The injection sink resolves the
	// types.ManagedOAuthSecret sentinel through it, exactly like SubscriptionToken
	// resolves the resident-host sentinel. This is what credentials a subscription
	// run in a COMPOSE deployment whose distroless wardynd has no host ~/.claude.
	// Nil disables the managed-injection path.
	ManagedToken subscription.Provider
	// DisableSubscriptionInject is the operator ESCAPE HATCH: when true (env
	// WARDYN_SUBSCRIPTION_INJECT=off), subscription runs keep the legacy
	// resident-copy behavior (the mounted credential, which can go stale) instead
	// of auto-enabling TLS-MITM + injecting the live host token. Default false =
	// the safe proxy-side default whenever a SubscriptionToken provider is wired.
	DisableSubscriptionInject bool
	// AuditCoalesceWindow folds IDENTICAL consecutive auth.fail audit rows —
	// same boundary, reason, path and peer — into the first row plus one summary
	// row carrying count/first_seen/last_seen (env WARDYN_AUDIT_COALESCE_WINDOW,
	// default 5m at the boot flag; 0 or unset = off, one row per refusal exactly
	// as before). It is a maximum GAP between two consecutive identical rows, not
	// a cap on a streak's duration: the flood this exists for was one row a
	// minute forever from a single retrying sidecar, which the 1/sec rate limiter
	// never trips and which still evicted every real security event out of the
	// console's 1000-row window in minutes. See coalesceAuthFailed (http.go) for
	// the bounds that keep a burst from collapsing into one row. The same
	// window folds the device routes' failure rows (device_audit_bounds.go).
	AuditCoalesceWindow time.Duration
	HostCapacityConfig
	// Now is overridable in tests; defaults to time.Now.
	Now func() time.Time
	// OrgFederation is the hybrid audit forwarder's status (cmd/wardynd's
	// bootHybrid), nil when WARDYN_ORG_URL is unset. It feeds /healthz's
	// org_federation block, the wardyn_org_federation_lag gauge and the
	// create-run refusal once the organisation has revoked this device.
	OrgFederation func() federation.Status
	// BaseCtx is the process-lifetime base context used for detached background
	// work that MUST outlive the request that started it — specifically the
	// completion watcher dispatch starts after Exec. The request/dispatch ctx is
	// cancelled when the HTTP handler returns, which would kill a watcher
	// immediately; BaseCtx (threaded from main.go's rootCtx) keeps it alive for
	// the lifetime of the daemon and is cancelled on shutdown. Defaults to
	// context.Background() when unset (the watcher then only stops on process
	// exit).
	BaseCtx context.Context
	// Components advertises, per pluggable seam (identity, secret_store,
	// recording, policy_engine, sandbox, ...), the SELECTED running implementation
	// and the recommended production default, for honest /healthz visibility. Nil
	// => the components object is omitted.
	Components map[string]ComponentInfo
	// AgeKeyDurable: the age key was SUPPLIED (WARDYN_AGE_KEY), not generated at boot, or no local key holds anything (store
	// mode, a key service). False, stored secrets are unreadable after a restart: /setup/status warns. Computed in cmd/wardynd.
	AgeKeyDurable bool
	// SecretStoreExternal names the store every credential is written to in store mode ("Vault at
	// vault.example:8200"), "" in local mode; set, /setup/status shows store_external, not the age-key row.
	SecretStoreExternal string
	// SecretKeyService: the key service wrapping every stored data key ("Vault Transit at host"), or "" for the local key; set, /setup/status shows kek_service.
	SecretKeyService string
	// PlatformKeySeparate: WARDYN_PLATFORM_KEY_FILE gives the boot keys their own local key; false in local mode, /setup/status shows platform_shared (§2.13 c).
	PlatformKeySeparate bool
	// LocalLoopback reports whether the HTTP listen address binds only loopback.
	// It feeds SetupAuth.LocalLoopback so the wizard can explain the local-mode
	// posture. Computed at boot in cmd/wardynd (listenIsLoopback).
	LocalLoopback bool
	// LocalTrustForwarder, when true, tells the LocalMode no-auth bypass to accept a
	// NON-loopback request peer (r.RemoteAddr). It exists for the compose/team
	// deployment ONLY: there wardynd binds 0.0.0.0 inside a container but the host
	// publishes the port loopback-only (127.0.0.1:PORT), so a host UI/CLI request
	// arrives at wardynd from the docker bridge gateway, not loopback. The LAN
	// protection in that topology is the loopback PUBLISH (a LAN peer cannot reach a
	// 127.0.0.1-bound host port at all), not the peer check — so the peer gate is a
	// false positive there. The DNS-rebinding Host gate still applies. NEVER set this
	// for a directly-bound host-mode wardynd on 0.0.0.0: that would re-open the LAN
	// no-auth exposure the peer gate closes. Default false; set by compose only.
	LocalTrustForwarder bool
	// RequireOperatorSetEgress (WARDYN_REQUIRE_OPERATOR_SET_EGRESS, DEFAULT
	// TRUE) makes applyWorkspaceRequirements apply the same provenance gate
	// to a scan_seeded EGRESS requirement that the SECRET side has always applied
	// unconditionally (runs_create.go): only an operator_set requirement is
	// auto-added at launch, and a scan_seeded one — the workspace scanner reading
	// UNTRUSTED repo content — is skipped.
	//
	// Defaulting it TRUE narrows egress for existing workspaces on upgrade, and
	// that cost is deliberate: the secret side calls this exact boundary
	// "security-critical — do not relax", for a reason that applies verbatim to
	// egress — a hostile or simply never-reviewed repo could widen a run's
	// allowlist just by naming a host in a committed file, with no operator ever
	// acting.
	//
	// The upgrade cost is real and bounded: a workspace whose egress
	// requirements are scan_seeded stops having them auto-added, and the run's
	// warnings say which were skipped. The fix is an operator declaring the host
	// (making it operator_set), which is the action the gate exists to require.
	// Set false to auto-add scan_seeded egress requirements again.
	RequireOperatorSetEgress bool
	// DisableGitPATBroker (WARDYN_GIT_PAT_BROKER=off) is the operator escape
	// hatch for the never-resident git_pat lane.
	//
	// With the broker on (the default), a git_pat for a non-GitHub forge is
	// minted PROXY-SIDE and injected on the outbound leg, so the PAT never enters
	// the sandbox — the same posture github_token has always had. Turning it off
	// restores the in-sandbox lane, where the grant id rides the sandbox env and
	// the in-sandbox credential helper mints the PAT into the agent's process.
	//
	// It exists because the broker changes the git TRANSPORT for those hosts (an
	// insteadOf rewrite to a plain-HTTP broker path), and a forge that behaves
	// unexpectedly under that rewrite must not leave a fleet unable to clone.
	// Reverting is a flag flip and a restart, not a redeploy.
	DisableGitPATBroker bool
	// OIDCRoleMapConfigured reports whether WARDYN_OIDC_ROLE_MAP is non-empty —
	// the sso_rbac /setup/status check's gate. Only the presence, never the
	// mapping itself: the API layer has no use for individual entries, only
	// whether the operator has opted into role derivation at all (see
	// internal/auth/oidc's deriveRole). Computed at boot in cmd/wardynd.
	OIDCRoleMapConfigured bool
	// OIDCRedirectURL echoes WARDYN_OIDC_REDIRECT_URL (a URL, not a credential)
	// for the tls_cookie_posture /setup/status check, which flags an https
	// redirect issued while OIDCSecureCookies is still false — the classic
	// behind-an-ingress misconfiguration where WARDYN_TLS_TERMINATED was never
	// set. Computed at boot in cmd/wardynd.
	OIDCRedirectURL string
	// OIDCSecureCookies is the boot-computed secureCookies posture
	// (validateConfig, cmd/wardynd/main.go): true iff wardynd knows the
	// connection is TLS-protected end to end (built-in TLS or
	// WARDYN_TLS_TERMINATED) — the same value threaded into
	// oidc.Config.SecureCookies. Feeds tls_cookie_posture alongside
	// OIDCRedirectURL. Computed at boot in cmd/wardynd.
	OIDCSecureCookies bool
	// BasePath is WARDYN_BASE_PATH ("" = the host root): the prefix Handler
	// mounts every console route under (base_path.go).
	BasePath string
	// ScanAIAdvisor, when non-nil, enables the ADVISORY AI workspace-scan fallback
	// (internal/workspacescan/ai.go): after the deterministic DeriveProfile, when
	// the profile is low-confidence or left unrecognized samples (ShouldAdvise),
	// this gap-fills EMPTY fields only and can only RAISE NeedsReview — it never
	// overrides a deterministic fact and FAILS OPEN (any error keeps the
	// deterministic profile unchanged and the upload still succeeds). Nil (default)
	// = feature OFF, byte-identical to the deterministic-only behavior. Production
	// wires it (from WARDYN_SCAN_AI_ADVISOR) to a workspacescan.AdviseProfile
	// closure; it doubles as the test seam so tests inject a fake instead of
	// shelling out to a real coding-agent CLI.
	ScanAIAdvisor func(context.Context, workspacescan.ScanFacts, workspacescan.WorkspaceProfile) workspacescan.WorkspaceProfile
	// SSHListenAddr is WARDYN_SSH_LISTEN: the address the SSH gateway binds
	// (e.g. ":2222"). Empty = off = no listener, no new surface — ServeSSHGateway
	// no-ops when this is empty, so a caller may invoke it unconditionally.
	SSHListenAddr string
	// SSHAdvertiseAddr is WARDYN_SSH_ADVERTISE: the externally-reachable
	// host[:port] surfaced on /healthz and shown in the run-detail "Connect via
	// SSH" pane's `ssh` command — NOT what wardynd binds to (that's
	// SSHListenAddr), since a container/NAT deployment's bind and reachable
	// address routinely differ. Purely advisory copy; the gateway itself never
	// reads it.
	SSHAdvertiseAddr string
	// SSHHostKey is the gateway's persisted ed25519 host key (loadOrCreateSecret
	// pattern, cmd/wardynd), used to derive the ssh.Signer AddHostKey wants and
	// the fingerprint /healthz discloses ("verify on first connect" — public by
	// design, it identifies the server, it authenticates no one). Empty when the
	// gateway is disabled (cmd/wardynd only loads/generates it when
	// SSHListenAddr is set, so a deployment with SSH off never even mints this
	// secret).
	SSHHostKey ed25519.PrivateKey
	// SSHRoleTTL is WARDYN_SSH_ROLE_TTL: how stale a key's role_checked_at
	// (migration 0046) may be before sshAuth's admin-override path refuses it
	// — the bound on the OIDC-login re-check, since SSH itself has no live
	// session to read a current role from. Zero defaults to a sensible 24h in
	// New (matching the flag's own default), so a Config built without going
	// through cmd/wardynd's flags — every test harness, notably — gets the
	// same posture production does rather than an accidental zero-tolerance
	// TTL that fails every override.
	SSHRoleTTL time.Duration
	// UIListenAddr is WARDYN_UI_SANDBOX_LISTEN: the address the UI-sandbox
	// gateway binds (e.g. ":8081"). Empty = off = no listener, no new surface,
	// mirroring SSHListenAddr. It MUST NOT equal the console's -listen: relayed
	// content is sandbox-authored, and the second listener IS the origin
	// separation that keeps it away from the console's storage (boot refuses —
	// cmd/wardynd's validateUISandboxConfig).
	UIListenAddr string
	// UIAdvertiseURL is WARDYN_UI_SANDBOX_ADVERTISE: the externally-reachable
	// base URL of that listener (e.g. "https://wardyn-ui.example.com"), used to
	// build the enter-URL template /healthz publishes. Advisory copy, like
	// SSHAdvertiseAddr — the gateway binds UIListenAddr, never this.
	UIAdvertiseURL string
	// UIOriginTemplate is WARDYN_UI_SANDBOX_ORIGIN_TEMPLATE: an optional PER-RUN
	// origin (e.g. "https://run-{run}.ui.example.com") for deployments with
	// wildcard DNS. Set, it gives every run its own browser origin — closing the
	// shared-origin residual path mode leaves — and the gateway then REFUSES an
	// enter served on any other host. Empty = shared path-mode origin, where one
	// run's page is separated from another's only by the path-scoped cookie.
	UIOriginTemplate string
	// UISessionTTL is WARDYN_UI_SANDBOX_SESSION_TTL: how long a minted relay
	// session stays usable, and — because the cookie carries its own issued-at
	// — how stale an ALREADY-minted one may be. The UI relay's sibling of
	// SSHRoleTTL: the SSH gateway bounds a stale admin-override stamp, this
	// bounds a stale relay session, and both exist because neither lane has a
	// live console session to re-read a current role from. Zero defaults to
	// defaultUISessionTTL in New (matching the flag's default), so a Config
	// built without going through cmd/wardynd's flags gets the shipped posture
	// rather than a zero TTL that would refuse every session.
	UISessionTTL time.Duration
	// UICookiePolicy is WARDYN_UI_SANDBOX_STRIP_COOKIES: which inbound cookies,
	// beyond the always-stripped wardyn_* namespace, the relay forwards to a
	// sandbox app. The zero value forwards every other cookie.
	UICookiePolicy UICookiePolicy
	// UISessionKey signs the wardyn_ui_sess relay cookie (HMAC-SHA256, >= 32
	// bytes, the loadOrCreateSecret pattern). Nil/short = gateway disabled: a
	// cookie that cannot be signed must never be issued.
	UISessionKey []byte
	// RunConfigKey seals each run's stored proxy config (32 bytes, the
	// wardyn-run-config-key boot key; run_proxy_config.go). Nil: none is kept.
	RunConfigKey []byte
	// DemoVideoBaseURL is WARDYN_DEMO_VIDEO_BASE_URL, validated at boot by
	// ValidateDemoVideoBaseURL (same seven-rule shape as an internal model
	// gateway: https://, no userinfo, no query/fragment). It re-points the
	// Getting Started demo episodes at an operator-run mirror for an
	// air-gapped deployment, where github.com is unreachable — both the
	// download URL episodeUrl's /healthz-reading caller builds and the CSP's
	// media-src this base's host is echoed into (cspMediaSrc,
	// security_headers.go). Empty (the default) = the two hardcoded GitHub
	// hosts, byte-identical to today. Control-plane-authored only, same trust
	// boundary as TrustedCAPEM/LLMGateways above — never a SiteConfig field,
	// never agent-reachable.
	DemoVideoBaseURL string
}

type HostCapacityConfig struct {
	// HostCapacity refuses every run launch while the host is over its memory
	// or load limits (WARDYN_HOST_*); nil admits everything.
	HostCapacity *hostcapacity.Guard
}

type ImageBuildSweeper interface {
	SweepOrphanedBuilds(ctx context.Context) error
}

type ImageBuilder interface {
	// BuildDevcontainer builds the devcontainer for repoURL@ref and returns the
	// local image reference to run. outputTag is the deterministic per-run tag
	// the result is committed under. logSink, when non-nil, receives build
	// output lines as they happen (e.g. the wizard Build step's in-memory log);
	// nil preserves the implementation's own default (wardynd's slog).
	BuildDevcontainer(ctx context.Context, repoURL, ref, outputTag string, logSink io.Writer) (imageRef string, err error)
	// BuildFromDevcontainerFiles builds an image from IN-MEMORY generated
	// devcontainer files (relative path -> content, e.g.
	// ".devcontainer/devcontainer.json") rather than a repo checkout, returning
	// the local image reference. It drives the SAME hardened envbuilder path as
	// BuildDevcontainer. Used for an onboarded workspace WITHOUT a wired
	// devcontainer, where internal/workspacescan generates a minimal one from the
	// detected profile. outputTag is the deterministic profile-hash-keyed tag
	// the result is committed under. logSink: see BuildDevcontainer.
	BuildFromDevcontainerFiles(ctx context.Context, files map[string]string, outputTag string, logSink io.Writer) (imageRef string, err error)
	// FinalizeBase wraps an arbitrary USER-supplied base image (Bring Your Own
	// Image) with Wardyn's runner tools + a cleared ENTRYPOINT, returning the
	// runnable local image reference. No untrusted build, no registry push — just
	// the trusted FROM+COPY finalize stage; the base is pulled only if absent, so
	// a host-pre-pulled private image works. outputTag is the per-run tag.
	// logSink: see BuildDevcontainer.
	FinalizeBase(ctx context.Context, baseRef, outputTag string, logSink io.Writer) (imageRef string, err error)
}

type LLMGatewayAuth struct {
	Header string
	Format string
}

type LLMGatewayRaw struct {
	BaseURL string
	Header  string
	Format  string
}

type MintBroker interface {
	MintForGrant(ctx context.Context, caller *identity.Claims, grantID uuid.UUID) (broker.Minted, error)
	RevokeRun(ctx context.Context, runID uuid.UUID) error
}

type RecordTaskResult struct {
	RunID uuid.UUID `json:"run_id"`
	// Label is the operator-chosen session name (e.g. "build & test"). Persisted
	// because sessions are user-named, not derived — the session key is a slug of
	// this, so the label carries the original display text.
	Label string `json:"label,omitempty"`
	Mode  string `json:"mode"` // auto | interactive
	// Confined distinguishes a VERIFY session (default-deny egress, limited to the
	// workspace's approved set + baseline) from a learning session (open egress).
	// Same interactive attach machinery; the flag flips AllowAllEgress and lets the
	// UI list learning sessions on the Record step and verify sessions on Verify.
	Confined bool `json:"confined,omitempty"`
	// LLMMode + Model record the auth the session actually ran with (the operator's
	// configured provider): subscription | api-key | none, plus the pinned model.
	// Saved with the session so it's visible and a verify replays the SAME auth as
	// the recording (the operator's setup, not a re-derived guess).
	LLMMode    string     `json:"llm_mode,omitempty"`
	Model      string     `json:"model,omitempty"`
	Status     string     `json:"status"` // recording | recorded | record_failed
	StartedAt  time.Time  `json:"started_at"`
	FinishedAt *time.Time `json:"finished_at,omitempty"`
	// Observations is the deterministic recordmode.Capture aggregate of what the
	// run ACTUALLY used, computed server-side from its audit events at
	// termination — never from a sandbox upload.
	Observations *recordmode.Observations `json:"observations,omitempty"`
	// Clean is the server-side recordmode.CleanReplay verdict, stamped ONLY for
	// a CONFINED entry (nil for an open recording — the verdict only means
	// something under confinement). Absent (nil) also covers old rows written
	// before this field existed: unknown, not "not clean" — render neutral,
	// never red. Clean means clean for what was replayed: reconcile finalizes
	// on any terminal state, so a replay the operator ends early earns the
	// same verdict as a full one.
	Clean *bool `json:"clean,omitempty"`
	// Caught is the number of observed domains with DenyCount>0 or
	// PendingCount>0, stamped alongside Clean — CONFINED entries only (0/unset
	// for an open recording).
	Caught int `json:"caught,omitempty"`
	// SecretNamesMinted resolves Observations.MintedGrantIDs to the secret /
	// grant names actually exercised, for the "proven used" checklist render.
	SecretNamesMinted []string `json:"secret_names_minted,omitempty"`
	// EgressPromoted marks that at least one of this task's observed hosts was
	// merged into the workspace's `egress:` requirement rows (operator action,
	// never automatic; possibly a subset — the flag is a boolean, not a count).
	EgressPromoted bool `json:"egress_promoted,omitempty"`
	// KernelSensorBlind: the run executed under CC3/Kata where the host eBPF
	// sensor cannot see — proxy decisions were the sole egress signal.
	KernelSensorBlind bool `json:"kernel_sensor_blind,omitempty"`
	// FailureHint explains a record_failed in operator terms (e.g. the sandbox
	// couldn't reach the control plane, so no evidence landed).
	FailureHint string   `json:"failure_hint,omitempty"`
	Caveats     []string `json:"caveats,omitempty"`
}

type RefRulesetVerifier interface {
	VerifyRefRuleset(ctx context.Context, repo string) (confined bool, detail string, err error)
}

type RunLeaseConfig struct {
	// EndedRunGrace mirrors WARDYN_ENDED_RUN_GRACE: how long a run its lease
	// ended keeps its files (stopped, no network) before it is torn down. 0
	// tears a run down at its end.
	EndedRunGrace time.Duration
}

type SCMAccess struct {
	// State is one of the six modelaccess.go values.
	State string `json:"state"`
	// Source is "org" or "separate" — set for a per-user connection that is
	// live or expired_signin (which door to go back through).
	Source string `json:"source,omitempty"`
	// Cause narrows `expired_signin` (scmAccessCauseEnded,
	// scmAccessCauseConsentNeeded).
	Cause string `json:"cause,omitempty"`
	// Org is the Azure DevOps address this row clones from (the row's first
	// base URL) — the {org} the connect and launch dialogs name.
	//
	// NO ROW ID. workspace_admission.go's disclosure rule ("the kind, never
	// the row id") applies here as it does to admitSSHHostLevel's 201 warning;
	// Org is the one deliberate exception the frozen copy needs
	// (LAUNCH_DIALOG_BODY, CONNECT_DIALOG_BODY, PANEL_ORG interpolate {org}
	// verbatim). Org + Kind is the stable key over the /me/scm-access array.
	Org string `json:"org,omitempty"`
	// Kind is the provider kind this row is ("azure_devops", always, today —
	// scmaccess.go grades Azure DevOps rows only) — paired with Org as the
	// stable key a list of these needs, in place of a row id.
	Kind string `json:"kind,omitempty"`
	// CapabilityCeiling is the row's capability_ceiling: the most any run on it
	// may hold. The policy editor locks every capability outside it, since a
	// policy naming one is refused at launch. Read-only here.
	CapabilityCeiling []adoscope.Capability `json:"capability_ceiling,omitempty"`
}

type SandboxOrphanSweeper interface {
	SweepOrphanedSandboxes(ctx context.Context, minAge time.Duration, isOrphan func(runID uuid.UUID) bool) (int, error)
}

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

type SetupAgeKey struct {
	Durable bool `json:"durable"`
}

type SetupAuth struct {
	Mode          string `json:"mode"`
	LocalLoopback bool   `json:"local_loopback"`
	// SharedSubscriptionAllowed reports whether this deployment may inject ONE
	// operator's Anthropic subscription into runs (single-user desktop only; see
	// subscriptionInjectPosture in cmd/wardynd). The console reads it to decide
	// whether to offer the "Connect Claude subscription" affordance at all —
	// rendering a sign-in that cannot work is worse than not offering it.
	SharedSubscriptionAllowed bool `json:"shared_subscription_allowed"`
	// SharedSubscriptionReason says WHY it is unavailable, so the UI can explain
	// rather than looking identical to "the operator never logged in". Empty when
	// allowed.
	SharedSubscriptionReason string `json:"shared_subscription_reason,omitempty"`
}

type SetupBedrock struct {
	Region string `json:"region,omitempty"`
	Model  string `json:"model,omitempty"`
	// The four credential SOURCES resolveBedrockAuth accepts, in its precedence
	// order (bearer > captured AWS SSO session > ~/.aws mount > resident SigV4).
	// ANY one is sufficient — a mount-, bearer- or SSO-credentialed host has NO
	// aws-access-key-id/-secret secrets yet is fully ready, so gating readiness on
	// CredsPresent alone wrongly reads "needs setup".
	CredsPresent  bool `json:"creds_present"`  // resident aws-access-key-id + aws-secret-access-key secrets
	AWSMount      bool `json:"aws_mount"`      // host-mode read-only ~/.aws bind-mount (SSO auto-refreshes)
	BearerPresent bool `json:"bearer_present"` // bedrock-api-key bearer token secret (never resident)
	// SSOPresent: a captured container-login AWS SSO session that a run would
	// actually authenticate with — live, OR expired-but-renewable (dispatch
	// renews it). Only a session nothing can heal (no refresh token, or a lapsed
	// client registration) reads false.
	SSOPresent bool `json:"sso_present"`
	// SSOExpired: a session IS captured and nothing can heal it (no refresh
	// token, or a lapsed registration). NOT on the wire, deliberately: it exists
	// so the capability matrix can say "the credential expired" instead of "no
	// credential is configured" — two different things an operator fixes two
	// different ways — and nothing on the console reads a second copy of a fact
	// SetupStatus.ModelAccess already carries per principal.
	SSOExpired bool `json:"-"`
	// SSOAccountID/SSORoleName are the AWS account and IAM role the CALLER's own
	// captured session names. IN-PROCESS only (json:"-"), for the same reason
	// SSOExpired is: nothing on the console renders a second copy of an identity
	// SetupStatus.ModelAccess already speaks for per principal. They exist so
	// bedrockProviderCheck can say, on the ADMIN's own Bedrock row, that a
	// stored capture disagrees with the roster pin — the posture that is
	// otherwise audible only as somebody else's refused run.
	SSOAccountID, SSORoleName string `json:"-"`
	// PerUser/Mechanism: the CALLER's own awsSSOScope, echoed in-process (never
	// on the wire — bedrockProviderCheck's callsite already has bedrock in
	// hand, so no second SetupStatus consumer needs to re-derive it) so
	// bedrockProviderCheck/llmProviderCheck can tell "a real person's own
	// credential is missing" from "the shared admin token was asked a
	// per-person question" without re-resolving scope themselves.
	PerUser bool `json:"-"`
	// Mechanism: this caller IS the shared admin bearer token under a per_user
	// row — see awsSSOScopeIsMechanism. Always false when PerUser is false.
	Mechanism bool `json:"-"`
	// PerUserBearer: the roster row's own MECHANISM (types.AgentMechanism) is
	// bedrock_bearer rather than bedrock_sso, under a per_user row. Meaningless
	// (always false) when PerUser is false. IN-PROCESS only (json:"-"), for the
	// same reason PerUser/Mechanism are: it exists so bedrockProviderRow can
	// tell an SSO caller from a bearer caller and pick the sentence that names
	// the ACTUAL remedy — signing in to AWS is not it for a bearer row; storing
	// a bedrock-api-key of their own is (#153, #320).
	PerUserBearer bool `json:"-"`
	// Ready is the server-computed readiness (region+model+any credential source),
	// echoed so the UI doesn't re-derive — and drift from — this gate.
	Ready bool `json:"ready"`
}

type SetupCheck struct {
	ID       string `json:"id"`
	Label    string `json:"label"`
	Status   string `json:"status"`
	Platform string `json:"platform,omitempty"`
	Detail   string `json:"detail,omitempty"`
	Fix      string `json:"fix,omitempty"`
	Blocking bool   `json:"blocking,omitempty"`
	// Cause narrows a row that can warn for more than one reason, the same
	// shape as SCMAccess.cause on the wire (ui/src/app/lib/types/setup.ts) — a
	// machine key, never prose, so a console reader can pick per-cause copy
	// without string-matching Detail. Only sso_rbac sets it today ("default_role",
	// #491): #484's original no-role-map-and-no-admin-list warn leaves it empty.
	Cause string `json:"cause,omitempty"`
}

type SetupDeployment struct {
	HostLike bool `json:"host_like"`
}

type SetupFix struct {
	Action      string `json:"action"` // "add_secret" | "scan_workspace" | "none"
	SecretName  string `json:"secret_name,omitempty"`
	WorkspaceID string `json:"workspace_id,omitempty"` // ID, not source — api.scanWorkspace takes an id
}

type SetupHarness struct {
	Provider    string `json:"provider"`              // "anthropic" | "aws"
	Captured    bool   `json:"captured"`              // a token blob is stored
	CapturedAt  string `json:"captured_at,omitempty"` // RFC3339, when pasted
	Aging       bool   `json:"aging,omitempty"`       // captured longer ago than harnessTokenAging
	SourceRunID string `json:"source_run_id,omitempty"`
	// ExpiresAt/Expired carry a REAL, machine-readable expiry and are populated
	// only for providers whose credential exposes one (AWS SSO does; an Anthropic
	// setup-token does not, which is the whole reason Aging exists as a
	// conservative age heuristic). Empty here means "this provider can't tell you"
	// — never "it doesn't expire".
	ExpiresAt string `json:"expires_at,omitempty"`
	Expired   bool   `json:"expired,omitempty"`
	// Renewable: the stored credential can be renewed without a fresh
	// interactive login — it carries a refresh token AND its OIDC client
	// registration has not lapsed. The SAME predicate resolveBedrockAuth and
	// setupBedrock apply (awsSSOBlob.renewable), deliberately: a row that read
	// "renewable" off the refresh token alone would render "nothing to do" for a
	// credential whose registration is gone, which dispatch gives up on. Legacy
	// sso_start_url profiles carry no refresh token and must be re-logged-in.
	Renewable bool `json:"renewable,omitempty"`
}

type SetupHarnessTool struct {
	ID            string `json:"id"`
	Display       string `json:"display"`
	HasGateway    bool   `json:"has_gateway"`
	HasLogin      bool   `json:"has_login"`
	NoManagedAuth bool   `json:"no_managed_auth,omitempty"`
	// Enabled is the ADMIN'S answer for this row: may a run name this agent?
	// True for every row when no AgentProviders block exists (legacy open mode),
	// otherwise the row's own state — and false for a catalog agent the block
	// does not mention at all.
	//
	// NOT omitempty, and that is the whole point: false is the value that has to
	// reach the console, which renders a disabled row disabled with a reason
	// rather than hiding it. A roster that silently drops agents is how "Claude
	// Code is just gone" becomes a support ticket.
	Enabled bool `json:"enabled"`
	// Mechanism and CredentialSource are the row's declared model-access lane and
	// whose credential it uses, empty when no block exists or no row names this
	// agent. They are the MEMBER-SAFE half of the agent policy: a lane name and
	// "shared"/"per_user" carry no host, no secret name and never the AWS access
	// portal URL, which is why redactSetupStatusForUser keeps them — a member
	// deciding whether to sign in has to be able to see that their org captures
	// credentials per person.
	Mechanism        string `json:"mechanism,omitempty"`
	CredentialSource string `json:"credential_source,omitempty"`
	// CredentialResidency is published for exactly ONE row shape: an enabled
	// `per_user` + `bedrock_sso` row, which is "sandbox". EMPTY for every other
	// row, and that is the whole design.
	//
	// A roster cannot say where a credential lands — the RESOLVED lane decides
	// that, and resolving one here would mean dry-running a body New Run never
	// sends (it sends a policy_id or a minimal inline_policy, and create folds the
	// run/workspace/default integration first), so the answer could be confidently
	// wrong in either direction. The per-user Bedrock SSO row is the one case the
	// row settles by itself: it admits no other lane (resolveBedrockAuth stops at
	// the per-user branch, mechanismSatisfied accepts only bedrock_sso), and that
	// lane writes the captured session into the sandbox and mints resident SigV4
	// credentials from it whatever policy, workspace or integration the run
	// carries. It is also the field report's own estate, and the one state where
	// the precise answer is unavailable: Preflight 422s a member who has not
	// signed in.
	//
	// Every other row reads "Resolved at launch." in the console until the caller
	// presses Preflight, which answers for the exact run. Member-safe for the same
	// reason the two fields above are.
	CredentialResidency string `json:"credential_residency,omitempty"`
	// ProvidersUngranted (#1052) is true when at least one enabled model
	// provider serves this harness but this caller's own granted set
	// (setupModelProviderState's capVisible-narrowed model_providers) serves
	// none of them — canon.md's R5b, "no provider serves this person for this
	// harness at all". Distinct from R9 (nothing serves the harness at all,
	// which leaves this false): /setup/status's model_providers list is
	// already narrowed to granted providers before the wire, so without this
	// fact the two states were indistinguishable to the console.
	ProvidersUngranted bool `json:"providers_ungranted,omitempty"`
}

type SetupIntegration struct {
	Capabilities []Capability `json:"capabilities"`
	// contains filtered or unexported fields
}

type SetupItem struct {
	Kind       string    `json:"kind"` // "llm_access" | "secret" | "workspace" | "workspace_secret" | "repo_credential" | "egress" | "backend"
	ID         string    `json:"id"`   // stable "<kind>:<key>", e.g. "secret:anthropic-api-key"
	Label      string    `json:"label"`
	RequiredBy string    `json:"required_by"`
	Status     string    `json:"status"` // "satisfied" | "missing" | "unverified"
	Detail     string    `json:"detail,omitempty"`
	Fix        *SetupFix `json:"fix,omitempty"`
	// Residency names WHERE the credential this item concerns actually lives at
	// run time, derived from the FINAL spec's own delivery mechanism (never
	// guessed): "proxy_injected" (an api_key grant — the value never leaves the
	// wardyn-proxy sidecar, injection.go), "resident_mount" (a host credential
	// bind-mounted into the sandbox, e.g. the Claude subscription mount), or
	// "brokered_mint" (a github_token/git_pat grant — the broker mints/resolves
	// a value and hands it directly to the in-sandbox git-credential helper at
	// task time, internal.go handleInternalMint). Empty when not applicable
	// (workspace/egress/backend rows carry no single credential).
	Residency string `json:"residency,omitempty"`
}

type SetupModelAccess struct {
	State     string `json:"state"`
	Mechanism string `json:"mechanism,omitempty"`
	// Action is the one thing to do, already composed by the server ("" when
	// there is nothing).
	Action string `json:"action,omitempty"`
	// Deadline is the instant Action names — the registration's lapse, or the
	// access token's expiry for a blob that cannot be renewed. It serves the
	// admin's checklist row, which prints the same one the member's action line
	// does, and it is on the wire.
	//
	// Localisation is why: `expiring`
	// rides a strip on every screen for the whole 24-hour window, and the
	// sentence carries an RFC3339 UTC stamp, which a reader in another timezone
	// misreads every time they see it. The console re-composes that ONE line
	// through the same frozen template (AGENTS.MODEL_ACCESS_EXPIRING_ACTION) on
	// the reader's own clock, and relativeTime in the strip; it needs the
	// instant to do either.
	//
	// Safe for a member only because userModelAccess builds a FRESH struct
	// that drops it — the leak that function exists to close was this same
	// instant republished one field over. Pinned:
	// TestModelAccessDeadline_OnTheWireForItsOWNER_NeverForASharedMember.
	Deadline string `json:"deadline,omitempty"`
	// PinMismatch says this answer's `expired_signin` is a CONTRADICTED identity
	// rather than a lapsed session. IN-PROCESS only (json:"-"): the console
	// renders Action verbatim and needs no second copy of what it says — this
	// exists so the admin-facing checklist row (awsSSOCredentialRow) does not
	// tell an operator their live session "expired at <ts> and cannot be
	// renewed", which of this one credential is simply false.
	PinMismatch bool `json:"-"`
	// PerUser says whether this answer is about a credential this principal
	// owns. IN-PROCESS only (json:"-"): it is not a fact the console renders, it
	// is what userModelAccess needs to decide whether a member may be told a
	// deadline or offered a sign-in at all. False is `shared` AND legacy open
	// mode — in both, the graded blob is the OPERATOR's.
	PerUser bool `json:"-"`
	// Cause is WHICH fact put this answer into `expiring` — "" for every other
	// state. IN-PROCESS only (json:"-"): the six WIRE states are the vocabulary
	// the console renders and stay unchanged; Cause exists only so grading and
	// the admin checklist row (awsSSOCredentialRow) can tell apart two different
	// facts that happen to want the same door — a refresh token AWS has already
	// retired (causeRenewalSpent) is not the same story as a registration or an
	// unrenewable access token approaching ITS OWN lapse on schedule.
	Cause string `json:"-"`
}

type SetupModelProvider struct {
	ID   string `json:"id"`
	Name string `json:"name,omitempty"`
	Kind string `json:"kind"`
	// Disabled is published, never hidden: a turned-off default is why this
	// person's runs are refused, and they need to see it.
	Disabled bool `json:"disabled,omitempty"`
	// Harnesses are the ones this provider serves that this person may launch.
	Harnesses []string `json:"harnesses"`
	// DefaultFor are the harnesses whose roster default this provider is.
	DefaultFor []string `json:"default_for,omitempty"`
	Host       string   `json:"host"`
}

type SetupPlatform struct {
	OS  string `json:"os"`
	WSL bool   `json:"wsl"`
	// KVM: the host exposes /dev/kvm — lets the UI split Vault's "incompatible
	// with this hardware" from a fixable "needs setup" (additive; old UIs ignore).
	KVM bool `json:"kvm"`
}

type SetupProvider struct {
	Tool             string `json:"tool"`
	Installed        bool   `json:"installed"`
	LoggedIn         bool   `json:"logged_in"`
	LoginDetectedVia string `json:"login_detected_via,omitempty"`
	// AuthMode is how the CLI authenticates, when detectable: "subscription" (a
	// resident Claude OAuth token is present — fresh OR expired; freshness lives in
	// the llm_provider check Detail, not here) or "" (unknown; never guessed). The
	// "api_key" value is reserved in the contract but not inferred for a CLI (no
	// cheap honest signal); codex stays "" (no auth-file parse).
	AuthMode string `json:"auth_mode,omitempty"`
}

type SetupProviderAccess struct {
	Provider    string     `json:"provider"`
	State       string     `json:"state"`
	Action      string     `json:"action,omitempty"`
	Deadline    string     `json:"deadline,omitempty"`
	SourceRunID string     `json:"source_run_id,omitempty"`
	AddedAt     *time.Time `json:"added_at,omitempty"`
	LastUsedAt  *time.Time `json:"last_used_at,omitempty"`
}

type SetupRunner struct {
	Driver                string            `json:"driver"`
	ConfinementClasses    []string          `json:"confinement_classes"`
	ConfinementSubstrates map[string]string `json:"confinement_substrates,omitempty"`
	// EphemeralDiskEnforcement is what actually binds a run's disk_mib on this
	// deployment — `filesystem`, `eviction` or `none`; absent reads as `none`
	// (runner.Capabilities.EphemeralDiskEnforcement, weakest across substrates).
	// The Workspace Providers screen renders it beside default_disk_mib so an
	// admin setting a number can see whether anything will hold it.
	//
	// Operator-only: redactSetupStatusForUser rebuilds this struct with
	// ConfinementClasses alone, so the word never reaches a member. It is
	// deliberately absent from the ANONYMOUS /healthz, which composes its own body
	// field by field.
	EphemeralDiskEnforcement types.StorageEnforcement `json:"ephemeral_disk_enforcement,omitempty"`
}

type SetupSecrets struct {
	Present   []string `json:"present"`
	GitHubApp bool     `json:"github_app"`
}

type SetupStatus struct {
	// Ready is server-computed and CONSERVATIVE (false when the runner is nil),
	// so the wizard opens rather than hiding a half-configured bootstrap.
	Ready bool `json:"ready"`
	// Checks is the single list of environment/readiness rows the UI renders.
	Checks []SetupCheck `json:"checks"`
	// Auth is the active public-API auth posture.
	Auth SetupAuth `json:"auth"`
	// Runner is the sandbox runner + the confinement classes actually live on
	// this host (from Runner.Capabilities, same source as /healthz).
	Runner SetupRunner `json:"runner"`
	// Providers reports resident coding-agent CLIs detected on the wardynd host.
	Providers []SetupProvider `json:"providers"`
	// Secrets reports which known secrets are present (NAMES only, reserved
	// names excluded) — never any value.
	Secrets SetupSecrets `json:"secrets"`
	// AgeKey reports whether the at-rest secret store survives a restart.
	AgeKey SetupAgeKey `json:"age_key"`
	// CredentialStorage names the KIND of store credentials live in — never a
	// host, path or vault name (design F-3): local/key_service/vault/key_vault.
	// Unlike Checks (the same fact as admin-only detail), this is KEPT through
	// redactSetupStatusForUser — every person reads it, not just an admin.
	CredentialStorage string `json:"credential_storage,omitempty"`
	// HasRuns drives the wizard's "launch your first run" done state.
	HasRuns bool `json:"has_runs"`
	// OnboardingComplete reports whether an operator has finished (or
	// deliberately left) the Getting Started funnel on this install —
	// SiteConfig.OnboardingCompletedAt, flattened to the only bit the console
	// needs. It is a fact about the install, not about the browser: browser
	// localStorage would outlive wiped databases and disagree with itself
	// between 127.0.0.1 and localhost (different origins, different storage).
	// The first-run landing, the welcome hero and the setup gate all read THIS.
	OnboardingComplete bool `json:"onboarding_complete"`
	// Platform is the OS + WSL posture the environment-step copy keys off.
	Platform SetupPlatform `json:"platform"`
	// HostProxy is the host-side proxy detection (env/shell/git/tool-config/OS)
	// the Host Proxy Getting-Started step renders. Read-only detection; it
	// never configures anything (the upstream-proxy plumbing is separate).
	HostProxy setup.HostProxyDetection `json:"host_proxy"`
	// SCM is the presence-only git-credential posture (gh CLI login, helper,
	// plaintext stores) the ScmProviderStep's ladder recommendations key off.
	SCM setup.SCMPosture `json:"scm"`
	// Bedrock is the AWS Bedrock Anthropic-transport readiness the "Connect a
	// model" step renders alongside the API-key/subscription rows. Region/Model
	// are boot-time operator config (non-secret, safe to echo); the AWS
	// credentials themselves are never echoed — CredsPresent is a bool derived
	// from secret-name presence, same as every other secret in this contract.
	Bedrock SetupBedrock `json:"bedrock"`
	// Deployment reports whether wardynd itself sees a resident Claude login
	// (host mode) or is blind to it (compose/container).
	Deployment SetupDeployment `json:"deployment"`
	// Harness reports per-provider Wardyn-managed subscription credentials
	// captured via container login (setup-token), so the wizard can show a
	// "connected / expiring / reconnect" row that works in compose mode where
	// there is no resident host login. Empty when no managed credential exists.
	Harness []SetupHarness `json:"harness,omitempty"`
	// Integrations is the effective integration set (stored ∪ legacy-derived,
	// see effectiveIntegrations in integrations.go) with each row's live
	// capability matrix — the same shape GET /api/v1/integrations returns,
	// folded in here so the wizard needs one fewer round trip. ADDITIVE field;
	// omitted when empty.
	Integrations []SetupIntegration `json:"integrations,omitempty"`
	// Harnesses is the STATIC coding-agent harness catalog (harnessCatalog,
	// harness.go) — which tools Wardyn knows how to run and whether it can
	// wire each one a managed model credential or a container-login
	// subscription. Distinct from Harness above (a CAPTURED credential's live
	// readiness). ADDITIVE field; omitted when empty.
	Harnesses []SetupHarnessTool `json:"harnesses,omitempty"`
	// LLMReady is the server-computed "does SOME run's LLM access path exist"
	// verdict (HIGH-4 review fix) — the same winning-signal logic that already
	// decides llmProvenance's detail (resident CLI login, a secret-name
	// heuristic, Bedrock, a managed harness token) OR'd with an AI-provider
	// Integration being configured. It exists
	// because a MEMBER'S redacted response (redactSetupStatusForUser) drops
	// the checks/providers/secret-name detail that would otherwise let the
	// console derive this itself — LLMReady is computed BEFORE redaction and
	// deliberately left untouched BY it, so the console's readiness chip / new-run
	// banner / demo gating keep working for a member without any of that detail
	// leaking. Kept in exact sync with ui/src/app/lib/types.ts's SetupStatus.
	LLMReady bool `json:"llm_ready"`
	// ChecksRedacted marks a body whose Checks/Providers/Secrets detail was
	// stripped for this caller's tier — an empty list here is withheld, not a fact.
	ChecksRedacted bool `json:"checks_redacted,omitempty"`
	// ModelAccess is THIS PRINCIPAL's model-access state — the per-person answer
	// LLMReady above structurally cannot give (it is a DEPLOYMENT fact, which is
	// why a member whose own AWS session had lapsed read a green chip off it).
	// Redaction-safe by construction and KEPT for a member: see SetupModelAccess.
	ModelAccess SetupModelAccess `json:"model_access,omitzero"`
	// SCMAccess is THIS PRINCIPAL's Azure DevOps access state — scmaccess.go's
	// computeSCMAccess, ModelAccess's sibling for #386. Zero value (state "")
	// when no Azure DevOps row is configured; safe for a member by
	// construction (their own state, computed from their own OIDC subject).
	SCMAccess SCMAccess `json:"scm_access,omitzero"`
	// TrustedCACerts is the number of additional roots WARDYN_TRUSTED_CA_FILE
	// loaded at boot (0 = unset). Derived from Config.TrustedCAPEM, never a
	// second boot-time field — see handleSetupStatus. Go + test only: no
	// console reader exists yet (the ui/src/app/lib/types.ts mirror is
	// hand-maintained, added when the Network step renders it) and
	// redactSetupStatusForUser does not zero it — a bare count carries no
	// PEM content, host name, or other detail members are barred from.
	TrustedCACerts int `json:"trusted_ca_certs,omitempty"`
	// ModelProviders is the model providers THIS PRINCIPAL may use, in the
	// member-safe shape (SetupModelProvider) — the same for every tier, so the
	// member redaction has nothing to strip. `omitzero`, not `omitempty`:
	// setupModelProviders returns nil when there is no provider block at all
	// (the field is then absent, exactly as before), and a non-nil, possibly
	// empty slice whenever a block exists — including one this caller is
	// granted nothing from, or one capVisible's own filter-error path
	// answered with rows[:0:0] — so the field is then present as `[]`. A
	// console reading this field can tell "no block" from "granted none"
	// only because of that distinction; `omitempty` could not make it (it
	// drops both nil and an empty-but-present slice alike).
	ModelProviders []SetupModelProvider `json:"model_providers,omitzero"`
	// ProviderAccess is THIS PRINCIPAL's connection state for every provider in
	// ModelProviders (MP-12) — one row per provider, generalising the single
	// AWS-SSO-only answer ModelAccess gives. Getting started and the setup
	// checklist read this instead of grading one hardcoded lane, so a person
	// granted several providers sees all of them. Kept for members: a state
	// name, an already-composed action sentence, and a deadline instant — no
	// secret names, no start URL. The pin-mismatch action is the one place the
	// pinned account and role appear (SetupProviderAccess's doc). Absent with
	// no provider block.
	ProviderAccess []SetupProviderAccess `json:"provider_access,omitempty"`
}

type UICookiePolicy struct {
	// Allow true forwards ONLY the cookies Names matches; false strips them.
	Allow bool
	// Names are exact cookie names, or prefixes when they end in "*".
	// Matching is case-sensitive, as browsers treat cookie names.
	Names []string
}