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 for a bearer row: a public client authenticates with the code
	// challenge alone. A minted_pat row requires it (ErrADOMintNeedsSecret).
	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. For a minted_pat row it is
	// exactly adoscope.MintScopes: the sign-in only ever creates tokens.
	Scopes []string
	// TokenMode is the row's token mode; empty reads as bearer. own_pat has
	// no sign-in and is never a source's answer.
	TokenMode types.ADOTokenMode
	// 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
	// PATAPIOverride re-points the token lifecycle API (vssps) at another base
	// URL. TEST ONLY, and refused without AllowTestEndpoints (patClient).
	PATAPIOverride 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 ADOPATAccess struct {
	// LastToken is the newest token Wardyn created for this person on this
	// row (minted_pat only), for the card's "last token" line.
	LastToken *adoLastToken `json:"last_token,omitempty"`
	// DefaultProfile is what a run on the row gets when its policy names no
	// Azure DevOps access: the row's default_profile, or
	// adoscope.ProfileDefault when it names none.
	DefaultProfile []adoscope.Capability `json:"default_profile,omitempty"`
}

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 {
	// SweeperLease, when set, gates the sweeps that must run on one replica (the
	// run pause) to the elected leader and fences them by lease epoch. Nil means
	// this process is the only one sweeping: every pass runs and no fence applies.
	SweeperLease SweeperLease
	// SweepHealth records each background sweep's ticks in the shared sweep_ticks
	// record and reads them back for the sweep gauges and the substrate_health
	// setup row. Nil records nothing and reports no sweep.
	SweepHealth *sweephealth.Tracker
	// 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
	// AuditUnsealer opens the sealed personal fields of the audit rows the
	// audit reads serve (WARDYN_AUDIT_SEAL, internal/audit/seal.go). Nil serves
	// rows as stored.
	AuditUnsealer audit.Unsealer
	// AuditActorSubject is the actor a human caller is stored under on a row
	// written outside the recorder chain (the retention drop's chained event
	// and anchor): under WARDYN_AUDIT_SEAL=full the person's "subject:<id>".
	// Nil stores the principal as it is.
	AuditActorSubject func(ctx context.Context, principal string) (string, error)
	// SubjectKeys is the per-subject key service; person erasure destroys a
	// person's audit-seal key through it. Nil makes the audit_personal_fields
	// scope unavailable.
	SubjectKeys *subjectkey.Manager
	// 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
	// GovernAdminRuns mirrors WARDYN_GOVERN_ADMIN_RUNS: an SSO admin's or an
	// admin-role personal token's runs are governed like a member's (see
	// runUngoverned in govern_admin.go). The admin token and local mode stay
	// ungoverned either way.
	GovernAdminRuns bool
	// GovernAdminRunsExempt mirrors WARDYN_GOVERN_ADMIN_RUNS_EXEMPT: the lanes
	// left ungoverned under the switch. The only value is "recording".
	GovernAdminRunsExempt []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
	// 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
	// BedrockRegion is read by nothing: the boot Bedrock lane (WARDYN_BEDROCK_*)
	// is retired and a run's region is its provider's. ponytail: kept only so
	// the ssotoken tests that still set it compile; delete it with those lines.
	BedrockRegion 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 not 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: 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
	// 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
	// KeyDomains resolves, lists and writes the key-domain assignments behind
	// /key-domains (migration 0121). Nil answers 501.
	KeyDomains *keydomain.Service
	// KeyDomainKeys names, for each declared key domain, the key that holds it
	// ("Transit key finance", "Key Vault key https://...") for the console's
	// domains table. A domain missing here shows no key.
	KeyDomainKeys map[string]string
	// PrincipalKeys is WARDYN_PRINCIPAL_KEYS=on; /setup/status shows principal_keys.
	PrincipalKeys bool
	// 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
	// MaskManifests, when non-nil, keeps each dispatched run's masking
	// manifest in Postgres and gates the five doors that relay or persist a
	// run's output on it (mask_manifest.go): a run whose corpus it cannot prove
	// complete is refused instead of passed through. Nil keeps no manifests
	// and gates nothing, as a nil MaskRegistry masks nothing.
	MaskManifests *maskmanifest.Manifests
	// HA is WARDYN_HA: several replicas serve this database. It adds the three
	// high-availability rows to /setup/status (setup_checks_ha.go); false adds none.
	HA bool
	// MaskSync reports whether this replica's copy of the shared masking
	// registry is current (the mask_registry_shared row). Read only when HA is set.
	MaskSync MaskSyncProbe
	// LiveBus, when non-nil, carries the notices replicas send each other over Postgres NOTIFY:
	// run lifecycle events, a kill for the replica creating the run's sandbox, and the end of an
	// attach lease (live_bus.go). Nil keeps each replica to its own process, as before.
	LiveBus *livebus.Bus
	// ADORunPATs, when non-nil, keeps each `minted_pat` run's current token in Postgres so every
	// replica serves the one any replica created (ado_run_pat_cache.go). Nil keeps it in this
	// process.
	ADORunPATs *adorunpat.Store
	// ExecOutputTailOff is WARDYN_EXEC_OUTPUT_TAIL=off: no non-interactive run
	// keeps an output tail for GET /runs/{id}/output (run_output.go).
	ExecOutputTailOff bool
	// RunOutputTailBytes is WARDYN_RUN_OUTPUT_TAIL_BYTES: each run's tail size
	// and the cap on ?tail=. Zero defaults to defaultRunOutputTailBytes in New.
	RunOutputTailBytes int
	// ExecOutputTailTTL is WARDYN_EXEC_OUTPUT_TAIL_TTL: how long a run's output
	// tail is kept after its last output. Zero defaults to
	// defaultExecOutputTailTTL in New.
	ExecOutputTailTTL time.Duration
	// RunOutputPersistOff is WARDYN_RUN_OUTPUT_PERSIST=off: the final tail stays
	// in memory only and nothing reaches run_outputs (run_output_final.go). A
	// store that keeps no run outputs behaves the same.
	RunOutputPersistOff bool
	// RunOutputRetention is WARDYN_RUN_OUTPUT_RETENTION_DAYS as a duration: final
	// rows older than it are deleted by the retention sweeper. Zero keeps them
	// forever.
	RunOutputRetention time.Duration
	// 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
	// ADOEntraByRow resolves the row with this id whether or not it is enabled or
	// first, so a token created through a row an admin has since disabled can
	// still be revoked (ado_run_pat_sweep.go). Nil: the revoke uses ADOEntra.
	ADOEntraByRow func(ctx context.Context, rowID string) (ADOEntraConfig, bool, error)
	// AzureFoundryEntra resolves the Entra application an azure_foundry provider
	// row signs people in against, by the row's uid (azure_foundry_entra.go). It
	// answers found=false for a uid that is not an azure_foundry row. The
	// application is always the console's own sign-in application, so a
	// deployment without Entra console login answers an unusable configuration
	// and both legs refuse. Nil: no Azure sign-in is offered.
	AzureFoundryEntra func(ctx context.Context, rowUID string) (ADOEntraConfig, bool, error)
	// ADOLoginFacts is the console's own OIDC client, tenant and whether it holds a secret (S1; nil: none).
	ADOLoginFacts func() (clientID, tenantID string, hasSecret bool)
	// HostResolver is how the model-provider write boundary resolves an azure_foundry endpoint host for its
	// private-address advisory. Nil: the system resolver, bounded to three seconds.
	HostResolver func(host string) ([]net.IP, error)
	// 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
	// MaxConcurrentRuns caps non-terminal runs across the whole deployment, every
	// replica and every creation door (env WARDYN_MAX_CONCURRENT_RUNS); 0 or less
	// is unlimited. Past it every door answers 422 run_quota (createRun); POST /runs
	// refuses before minting and audits nothing for it, bar a create that loses
	// the race at the cap, which keeps its identity.mint row.
	MaxConcurrentRuns int
	// PreflightRatePerMin is WARDYN_PREFLIGHT_RATE_PER_MIN: the per-person
	// POST /runs/preflight rate (burst 5). 0 turns the limit off.
	PreflightRatePerMin int
	// 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
	// KEKRequired: WARDYN_KEK_REQUIRED; /setup/status shows kek_required_unmet while neither a key service nor an external store holds the credentials.
	KEKRequired bool
	// PlatformKeySeparate: the boot keys have a key of their own: WARDYN_PLATFORM_KEY_FILE in local mode only
	// (under a key service the file counts for nothing), the platform key (and identity) of the key service
	// otherwise. False shows platform_split as a warning (§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
	// SCIM, when non-nil, mounts the SCIM 2.0 Users routes under /scim/v2 (scim_users.go): the way
	// an identity provider suspends and reactivates a person. nil (default) mounts nothing.
	SCIM *SCIMConfig
	// 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
	// APITokenMaxTTL is WARDYN_API_TOKEN_MAX_TTL: the longest lifetime a newly
	// minted API token may have. Zero (the default) means no cap. A mint that
	// asks for no TTL gets this one; a mint that asks for more is clamped to it.
	// It never touches a token already minted.
	APITokenMaxTTL time.Duration
	// RoleStampTTL is WARDYN_ROLE_STAMP_TTL: the oldest an API token's role and
	// group stamp (api_tokens.identity_stamped_at) may be before apiTokenAuth
	// refuses it until its owner signs in again. Zero, the default, is off: no
	// token is refused for the age of its stamp.
	RoleStampTTL time.Duration
	// GovernanceChangeTTL is WARDYN_GOVERNANCE_CHANGE_TTL: how long a governance change held for a
	// second human (WARDYN_GOVERNANCE_SECOND_HUMAN) waits before it expires. Zero means the 72h
	// default.
	GovernanceChangeTTL 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 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 MaskSyncProbe interface {
	Synced(ctx context.Context) error
}

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 ResolvedProfile struct {
	ID       uuid.UUID
	Name     string
	Contact  *policyref.Contact // the leaf's own: never inherited from a base
	Composed bool
	// Chain is the leaf first, then each base: admin surfaces only.
	Chain   []profileLink
	Ceiling types.RunPolicySpec
	Limits  types.GovernanceLimits
	// Warnings name the LEAF only and never a base's name, id, overlay or contact: they reach a
	// member's 201 clamp_warnings.
	Warnings []string
	// AdminWarnings carry the base-level detail for GET /governance and the 409 bodies.
	AdminWarnings []string
}

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 SCIMConfig struct {
	// Token and TokenNext are the bearers the routes accept (WARDYN_SCIM_TOKEN, and the second one
	// rotation needs). TokenNext may be empty; Token may not.
	Token, TokenNext string
	// Issuer and Tenant key the identity rows a SCIM user is matched against: the OIDC issuer URL
	// sign-ins record, and the tenant id derived from it.
	Issuer, Tenant string
	// PurgeAfter is how long after a suspension the purge sweeper purges the person
	// (WARDYN_SCIM_PURGE_AFTER); zero disables the automatic purge, and DELETE still purges.
	PurgeAfter time.Duration
	// KeepWorkspaces leaves a purged person's workspaces with them (WARDYN_SCIM_LEAVER_WORKSPACES
	// set to keep); false hands them to the operator.
	KeepWorkspaces bool
}

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

	// The fields below are set on a row where each person adds their own token
	// (token_mode own_pat, or an Azure DevOps Server row) and on no other.
	//
	// TokenMode is "own_pat" on both.
	TokenMode string `json:"token_mode,omitempty"`
	// ExpiresOn is the date (YYYY-MM-DD) the person said their token expires —
	// the deadline `expiring` and `expired_signin` name. Absent with no token.
	ExpiresOn string `json:"expires_on,omitempty"`
	// MaxDays is the furthest expiry, in days from today, the row's
	// administrator allows (pat_max_days).
	MaxDays int `json:"max_days,omitempty"`
	// TokenScopes is what to tick on Azure DevOps' own token page, in its own
	// wording ("Code (Read & write)"), derived from the row's ceiling.
	TokenScopes []string `json:"token_scopes,omitempty"`
	// GitOnly is set on an Azure DevOps Server row: its token carries git and
	// nothing else (ado_own_pat_server.go).
	GitOnly bool `json:"git_only,omitempty"`
	// RefusedAt (RFC 3339) is when Azure DevOps first refused the token before
	// the expiry the person entered (a 401 answers a revoked token, an expired
	// one and a missing scope alike). Informational: State is unchanged and
	// the token is still used until ExpiresOn. A new token clears it.
	RefusedAt string `json:"refused_at,omitempty"`

	// ADOPATAccess adds the token console's facts (ado_pat_console.go).
	ADOPATAccess
}

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"`
	// GovernAdminRuns is WARDYN_GOVERN_ADMIN_RUNS and GovernAdminRunsExempt the
	// lanes WARDYN_GOVERN_ADMIN_RUNS_EXEMPT leaves ungoverned. Neither is a
	// secret, and redactSetupStatusForUser leaves Auth alone, so every signed-in
	// person can read the posture their own runs are under.
	GovernAdminRuns       bool     `json:"govern_admin_runs"`
	GovernAdminRunsExempt []string `json:"govern_admin_runs_exempt,omitempty"`
}

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. sso_rbac sets it ("default_role", #491:
	// #484's original no-role-map-and-no-admin-list warn leaves it empty), and so
	// does substrate_health ("runner_unreachable", "runner_auth", "sweep_stale").
	Cause string `json:"cause,omitempty"`
}

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 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"`
	// ProvidersUngranted (#1052) is true when at least one enabled model
	// provider serves this harness but none of the ENABLED providers in this
	// caller's own granted set (setupModelProviderState's capVisible-narrowed
	// model_providers) serve it — canon.md's R5b, "no provider serves this
	// person for this harness at all". Enabled rows only on both sides: a
	// provider the caller is granted but an admin turned off serves nobody, so
	// it does not answer a different enabled provider they are not granted. 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 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"`
}

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 and Kubernetes 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"`
	// Kubernetes is the ONE substrate bit a member may read: the runner is the
	// Kubernetes driver. Driver itself stays operator-only, so without this a
	// member's console cannot tell a Kubernetes install apart and would hand
	// them the Docker host's /dev/kvm remedy for Vault. A boolean, deliberately
	// not the driver name or anything a substrate reports about itself.
	Kubernetes bool `json:"kubernetes,omitempty"`
	// SandboxStart is the Kubernetes sandbox start deadlines (WARDYN_SANDBOX_START_TIMEOUT,
	// WARDYN_SANDBOX_CAPACITY_WAIT), kept in a member's redacted body because the run page's
	// "taking longer than expected" bound follows them. Absent off Kubernetes.
	SandboxStart *SetupSandboxStart `json:"sandbox_start,omitempty"`
	// contains filtered or unexported fields
}

type SetupSandboxStart struct {
	StartTimeoutSeconds int `json:"start_timeout_seconds"`
	CapacityWaitSeconds int `json:"capacity_wait_seconds"`
}

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"`
	// 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. 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): at least one enabled model provider serves an
	// agent (llmPathExists). A DEPLOYMENT fact — whether THIS person can use one
	// is ProviderAccess. It exists because a MEMBER'S redacted response
	// (redactSetupStatusForUser) drops the checks 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. 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"`
	// SCMAccess is THIS PRINCIPAL's Azure DevOps access state — scmaccess.go's
	// computeSCMAccess, ProviderAccess'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. Getting started and the
	// setup checklist read this, 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 SweeperLease interface {
	Join() (ctx context.Context, epoch int64, end func(), ok bool)
	Current(ctx context.Context, epoch int64) (bool, error)
}

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
}