Program.cs

using Microsoft.Extensions.DependencyInjection.Extensions;
using Microsoft.Extensions.Logging.Abstractions;
using Microsoft.Extensions.Options;
using OpenTelemetry.Exporter;
using OpenTelemetry.Logs;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
using CodeyBox.Agents;
using CodeyBox.Agents.Aider;
using CodeyBox.Agents.Antigravity;
using CodeyBox.Agents.Autohand;
using CodeyBox.Agents.CavemanCode;
using CodeyBox.Agents.Cline;
using CodeyBox.Agents.Crock;
using CodeyBox.Agents.Claude;
using CodeyBox.Agents.Cmd;
using CodeyBox.Agents.Codex;
using CodeyBox.Agents.Copilot;
using CodeyBox.Agents.Cursor;
using CodeyBox.Agents.Devin;
using CodeyBox.Agents.Gemini;
using CodeyBox.Agents.Goose;
using CodeyBox.Agents.Kilo;
using CodeyBox.Agents.Omp;
using CodeyBox.Agents.Continue;
using CodeyBox.Agents.Crush;
using CodeyBox.Agents.Opencode;
using CodeyBox.Agents.Pi;
using CodeyBox.Agents.Prime;
using CodeyBox.Agents.Qwen;
using CodeyBox.Agents.Vibe;
using CodeyBox.Agents.DotNetOpencode;
using CodeyBox.Agents.Unreal;
using CodeyBox.AdminSeed;
using CodeyBox.Api;
using CodeyBox.Api.Hubs;
using CodeyBox.Api.Majordomo;
using CodeyBox.Audit;
using CodeyBox.Audit.Llm;
using CodeyBox.Audit.Llm.PlanAudit;
using CodeyBox.Audit.Presets;
using CodeyBox.Audit.Shell;
using CodeyBox.Build.GitHubActions;
using CodeyBox.Build.MSBuild;
using CodeyBox.DotnetTestRunnerPlugin;
using CodeyBox.Core;
using CodeyBox.Deployment;
using CodeyBox.Git;
using CodeyBox.Orchestrator;
using CodeyBox.Projects;
using CodeyBox.Sandbox;
using CodeyBox.Sandbox.ArtifactProvenance;
using CodeyBox.Sandbox.Bubblewrap;
using CodeyBox.Sandbox.Incus;
using CodeyBox.Sandbox.Multipass;
using CodeyBox.Sandbox.MultipassRemote;
using CodeyBox.Sandbox.Process;
using CodeyBox.Sandbox.Sprites;
using CodeyBox.HostProcess;
using CodeyBox.Webhooks;
using CodeyBox.Upstream.GitHub;
using CodeyBox.Notifications;
using Serilog;
using Serilog.Events;
using Serilog.Extensions.Logging;
using Serilog.Filters;
using Serilog.Formatting.Compact;
// Disambiguate: both Serilog and MEL expose an ILogger interface.
// Program.cs only uses Serilog.Log (the static class) and MEL's ILogger<T>;
// declaring the alias keeps local function signatures unambiguous.
using ILogger = Microsoft.Extensions.Logging.ILogger;

// Converts a missing-required-setting startup failure into a clean
// diagnostic (message on stderr, conventional non-zero exit, no stack trace,
// no core dump). Scoped to RequiredConfigurationException only — every other
// unhandled exception keeps the runtime's existing crash behaviour.
RequiredConfigurationValidator.RegisterUnhandledExceptionHandler();

var builder = WebApplication.CreateBuilder(args);

// Optional extra-config file pointed at by CODEYBOX_EXTRA_CONFIG. Lets
// operator-side configuration (e.g. dev/test setups in a gitignored
// local/ directory) layer on top of the committed appsettings.json
// without copying files into the API project. Loaded LAST so it wins.
// reloadOnChange:true so an operator can edit this file without restarting
// CodeyBox — IOptionsMonitor<T> consumers will observe the new values within
// the framework's debounce window (~1 s).
{
    var extra = Environment.GetEnvironmentVariable("CODEYBOX_EXTRA_CONFIG");
    if (!string.IsNullOrEmpty(extra))
        builder.Configuration.AddJsonFile(extra, optional: false, reloadOnChange: true);
}

// Default to loopback-only. Operators putting a TLS-terminating reverse
// proxy in front should override via ASPNETCORE_URLS or appsettings.
// Anything beyond localhost MUST be intentional, since the API can spawn
// sandboxes and trigger merges.
if (string.IsNullOrEmpty(Environment.GetEnvironmentVariable("ASPNETCORE_URLS"))
    && builder.Configuration["urls"] is null
    && builder.Configuration["Kestrel:Endpoints:Default:Url"] is null)
{
    builder.WebHost.UseUrls("http://127.0.0.1:5000");
}

// ── Serilog bootstrap ─────────────────────────────────────────────────────
// Configured from CodeyBox:AuditLog section before the host builds so the
// logger is available from startup. UseSerilog() replaces the default MEL
// providers, so all ILogger<T> call sites continue to work unchanged.
{
    var cbConf = builder.Configuration.GetSection("CodeyBox").Get<CodeyBoxOptions>()
        ?? new CodeyBoxOptions();
    var auditOpts = cbConf.AuditLog;
    var agentStreamOpts = cbConf.AgentStreams;

    AuditLogStartup.ValidateAndPrepare(auditOpts);

    using var bootstrapLoggerFactory = LoggerFactory.Create(static b => b.AddSerilog(dispose: false));
    AgentStreamsOptions.ValidateAtStartup(
        agentStreamOpts,
        bootstrapLoggerFactory.CreateLogger("CodeyBox.AgentStreams"));

    // When OTel export is enabled we forward Serilog events to the MEL provider
    // pipeline (the OpenTelemetry logging provider added in the OTel section).
    // UseSerilog(providers:) bridges every registered ILoggerProvider into this
    // collection and the WriteTo.Providers sink fans events out to them, so the
    // existing ILogger call sites flow to OTel with trace correlation while the
    // console / file sinks stay owned by this single logger. Null (OTel off)
    // keeps the original Serilog-only path with zero added overhead.
    var otelLogForwarding = cbConf.Otel.Enabled ? new LoggerProviderCollection() : null;

    var serilogConfig = new LoggerConfiguration()
        .MinimumLevel.Information()
        .MinimumLevel.Override("Microsoft", LogEventLevel.Warning)
        .MinimumLevel.Override("Microsoft.Hosting.Lifetime", LogEventLevel.Information)
        .Enrich.FromLogContext()
        .Enrich.WithMachineName()
        .Enrich.WithThreadId()
        .Enrich.WithProperty("Application", "CodeyBox")
        .Enrich.With<SensitiveDataRedactionEnricher>()
        .WriteTo.Console();

    // Rolling plain-text mirror of the console stream. Replaces the
    // historical `>>` shell-redirect of stdout to codeybox-orchestrator.run.log,
    // which grew without bound (22 M+ lines / multi-GB by 2026-06) and made
    // operator tail/grep return weeks-old lines. RunLogSink bounds it by size
    // (RetainedFileCountLimit x MaxFileSizeBytes peak) and stamps every line
    // with a full-date UTC timestamp. Both rotation knobs are re-read live
    // (see ReadRunLogOptions), so they hot-reload without a restart; only the
    // path stays pinned to its startup value. Disable via
    // CodeyBox:AuditLog:ConsoleLog:Enabled=false if the operator manages
    // run-log capture out of process.
    // builder.Configuration reloads appsettings / CODEYBOX_EXTRA_CONFIG in
    // place, so re-binding just the small ConsoleLog section here (at most
    // once per second) is what makes the knobs hot-reloadable this early in
    // bootstrap, before the DI container (and IOptionsMonitor) exists.
    var runLogGate = new object();
    var runLogCached = auditOpts.ConsoleLog;
    var runLogCachedAt = DateTimeOffset.UtcNow;
    ConsoleLogOptions ReadRunLogOptions()
    {
        lock (runLogGate)
        {
            if (DateTimeOffset.UtcNow - runLogCachedAt > TimeSpan.FromSeconds(1))
            {
                runLogCached = builder.Configuration
                    .GetSection("CodeyBox:AuditLog:ConsoleLog")
                    .Get<ConsoleLogOptions>() ?? new ConsoleLogOptions();
                runLogCachedAt = DateTimeOffset.UtcNow;
            }

            return runLogCached;
        }
    }

    if (auditOpts.ConsoleLog.Enabled)
    {
        serilogConfig = serilogConfig.WriteTo.Sink(
            new RunLogSink(auditOpts.ConsoleLog.Path, ReadRunLogOptions));
    }

    serilogConfig = serilogConfig
        .WriteTo.File(
            formatter: new CompactJsonFormatter(),
            path: auditOpts.Path,
            rollingInterval: RollingInterval.Day,
            retainedFileCountLimit: auditOpts.RetainedDays,
            fileSizeLimitBytes: auditOpts.MaxFileSizeBytes,
            rollOnFileSizeLimit: true,
            shared: false)
        .WriteTo.Logger(lc => lc
            .Filter.ByIncludingOnly(Matching.WithProperty<bool>("Audit", v => v))
            .WriteTo.File(
                formatter: new CompactJsonFormatter(),
                path: auditOpts.AuditPath,
                rollingInterval: RollingInterval.Day,
                retainedFileCountLimit: auditOpts.RetainedDays,
                fileSizeLimitBytes: auditOpts.MaxFileSizeBytes,
                rollOnFileSizeLimit: true,
                shared: false));

    if (otelLogForwarding is not null)
        serilogConfig = serilogConfig.WriteTo.Providers(otelLogForwarding);

    Log.Logger = serilogConfig.CreateLogger();

    builder.Host.UseSerilog(Log.Logger, dispose: false, providers: otelLogForwarding);
}

// ── OpenTelemetry ─────────────────────────────────────────────────────────
// Off by default (OtelOptions.Enabled = false). Operators opt in by setting
// CodeyBox:Otel:Enabled=true and CodeyBox:Otel:OtlpEndpoint. When disabled,
// no OTel types are registered — zero overhead in the default configuration.
//
// The Prometheus scrape exporter (CodeyBox:Otel:Prometheus:Enabled) is a
// peer of the OTLP push exporter: enabling either one (or both) registers
// the metric provider, observable gauges, and CodeyBox meters. The
// tracing / logging providers and the OTLP push pipeline activate only
// when CodeyBox:Otel:Enabled=true; Prometheus alone keeps tracing and logs
// on the existing Serilog-only path.
{
    var cbConf = builder.Configuration.GetSection("CodeyBox").Get<CodeyBoxOptions>()
        ?? new CodeyBoxOptions();
    var otelOpts = cbConf.Otel;
    OtelOptions.Validate(otelOpts);

    var prometheusEnabled = otelOpts.Prometheus.Enabled;
    var metricsEnabled = otelOpts.Enabled || prometheusEnabled;

    if (metricsEnabled)
    {
        // service.version defaults to the API assembly version when the operator
        // hasn't pinned a git SHA / release tag.
        var serviceVersion = otelOpts.ServiceVersion
            ?? typeof(Program).Assembly.GetName().Version?.ToString();

        // service.name honours the standard OTEL_SERVICE_NAME env var, falling
        // back to the CodeyBox:Otel appsettings value — env wins so the standard
        // OTel bootstrap can retarget identity without editing appsettings.
        var serviceName = Environment.GetEnvironmentVariable("OTEL_SERVICE_NAME") is { Length: > 0 } envServiceName
            ? envServiceName
            : otelOpts.ServiceName;

        // Resource attributes shared by traces, metrics, and logs so the three
        // signals correlate on identical service identity. service.instance.id
        // and deployment.environment are added automatically; appsettings
        // ResourceAttributes are applied, then any OTEL_RESOURCE_ATTRIBUTES env
        // pairs last so the standard env contract overrides appsettings on key
        // collision.
        var instanceId = $"{Environment.MachineName}:{Environment.ProcessId}";
        var deploymentEnv = builder.Environment.EnvironmentName;
        void ConfigureResource(ResourceBuilder r)
        {
            r.AddService(serviceName, serviceVersion: serviceVersion, serviceInstanceId: instanceId);
            if (!string.IsNullOrWhiteSpace(deploymentEnv))
                r.AddAttributes(new[] { new KeyValuePair<string, object>("deployment.environment", deploymentEnv) });
            if (otelOpts.ResourceAttributes.Count > 0)
                r.AddAttributes(otelOpts.ResourceAttributes.Select(
                    kv => new KeyValuePair<string, object>(kv.Key, kv.Value)));
            var envAttrs = OtelOptions.ParseResourceAttributesEnv(
                Environment.GetEnvironmentVariable("OTEL_RESOURCE_ATTRIBUTES"));
            if (envAttrs.Count > 0)
                r.AddAttributes(envAttrs);
        }

        var otelBuilder = builder.Services.AddOpenTelemetry()
            .ConfigureResource(ConfigureResource);

        if (otelOpts.Enabled)
        {
            otelBuilder.WithTracing(t => t
                .AddSource("CodeyBox.Pipeline")
                .AddSource("CodeyBox.Sandbox")
                .AddSource("CodeyBox.Upstream")
                .AddSource("CodeyBox.Audit")
                .AddAspNetCoreInstrumentation()
                .AddHttpClientInstrumentation()
                .AddOtlpExporter(o => ConfigureOtlp(o, otelOpts)));
        }

        otelBuilder.WithMetrics(m =>
        {
            m.AddMeter("CodeyBox.Pipeline")
             .AddMeter("CodeyBox.Sandbox")
             .AddMeter("CodeyBox.Audit")
             .AddMeter("CodeyBox.Upstream")
             .AddMeter("CodeyBox.Coordinator")
             .AddRuntimeInstrumentation();
            if (otelOpts.Enabled)
                m.AddOtlpExporter(o => ConfigureOtlp(o, otelOpts));
            if (prometheusEnabled)
                m.AddPrometheusExporter();
        });

        if (otelOpts.Enabled)
        {
            // Route the existing ILogger output through the OpenTelemetry logging
            // provider. Serilog forwards events here via the LoggerProviderCollection
            // wired above (writeToProviders); LogRecords are stamped with the active
            // Activity's TraceId/SpanId for log↔trace correlation.
            builder.Logging.AddOpenTelemetry(o =>
            {
                o.IncludeScopes = true;
                o.IncludeFormattedMessage = true;
                o.ParseStateValues = true;
                var rb = ResourceBuilder.CreateDefault();
                ConfigureResource(rb);
                o.SetResourceBuilder(rb);
                o.AddOtlpExporter(e => ConfigureOtlp(e, otelOpts));
            });
        }

        // Observable gauges (work items by state, worker pool occupancy, active
        // sandboxes, quota headroom) are registered only when at least one
        // metric exporter is active to preserve the zero-overhead disabled path.
        builder.Services.AddHostedService<CodeyBoxObservableMetrics>();
    }
}

// AddOptions + PostConfigure instead of plain Configure so the AgentClasses
// override resolver runs after the binder. The default ConfigurationBinder
// merges arrays positionally — for AgentClasses that's a silent footgun
// (a shorter operator override exposes the base array's trailing element).
// The post-configure step REPLACES AgentClasses with the highest-precedence
// provider's view, and re-runs on every IOptionsMonitor reload.
// SandboxClasses gets the same treatment: it is the same shape of data
// (classes each holding a member array) with the same footgun.
builder.Services.AddOptions<CodeyBoxOptions>()
    .Bind(builder.Configuration.GetSection("CodeyBox"))
    .PostConfigure(opts => AgentClassesOverrideResolver.ApplyTo(opts, builder.Configuration))
    .PostConfigure(opts => AgentClassesOverrideResolver.ApplySandboxClassesTo(opts, builder.Configuration));
// Artifact provenance: operator-owned, opt-in trust policy for plugin
// bundles and externally staged tool executables. Disabled by default; when
// enabled, admission is verified before load/provisioning. Validation fails
// fast at host start; the options remain hot-reloadable and the admission
// service keys cached verdicts by the live policy digest. The admission
// singleton is always registered (it is inert while the policy is disabled)
// so enabling the policy at runtime takes effect without a restart.
builder.Services.AddSingleton<IValidateOptions<ArtifactTrustOptions>, ArtifactTrustOptionsValidator>();
builder.Services.AddOptions<ArtifactTrustOptions>()
    .Bind(builder.Configuration.GetSection(ArtifactTrustOptions.SectionName))
    .ValidateOnStart();
builder.Services.AddSingleton(new ArtifactAdmissionService());
// Majordomo MCP surface: hot-reloadable policy (autonomy mode, per-turn
// blast-radius cap, identity name, turn window) mirroring the vocabulary's
// MajordomoOptions. Validation fails fast at host start rather than silently
// weakening the gate on a config typo, and reports the specific rule that
// failed via the IValidateOptions implementation.
builder.Services.AddSingleton<IValidateOptions<MajordomoServerOptions>, MajordomoServerOptionsValidator>();
builder.Services.AddOptions<MajordomoServerOptions>()
    .Bind(builder.Configuration.GetSection(MajordomoServerOptions.SectionName))
    .ValidateOnStart();
builder.Services.AddMajordomoMcp();
// Majordomo sandbox: long-lived, reusable-across-turns sandbox for the
// operator's assistant. Hot-reloadable options (network profile, idle bound,
// model backend) mirroring MajordomoSandboxOptions. Validation fails fast at
// host start rather than silently weakening the egress or credential posture.
builder.Services.AddSingleton<IValidateOptions<MajordomoSandboxOptions>, MajordomoSandboxOptionsValidator>();
builder.Services.AddOptions<MajordomoSandboxOptions>()
    .Bind(builder.Configuration.GetSection(MajordomoSandboxOptions.SectionName))
    .ValidateOnStart();
// Long-lived majordomo sandbox: one reusable sandbox for the operator's
// assistant, created on demand and torn down after the configured idle bound
// by MajordomoSandboxIdleService. It never touches the work-item dispatch
// path (no concurrency-gate permit, no worker-pool mutation), so the fleet's
// accounting is unchanged while it is alive. Both accessors re-read live
// options, so network-profile and idle-bound edits apply without a restart.
builder.Services.AddSingleton(sp => new MajordomoSandboxSession(
    sp.GetRequiredService<ISandboxProvider>(),
    () => sp.GetRequiredService<IOptionsMonitor<MajordomoSandboxOptions>>().CurrentValue,
    () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.SandboxNetworkProfiles.Keys.ToArray(),
    TimeProvider.System,
    sp.GetRequiredService<ILoggerFactory>().CreateLogger<MajordomoSandboxSession>()));
builder.Services.AddHostedService(sp => new MajordomoSandboxIdleService(
    sp.GetRequiredService<MajordomoSandboxSession>(),
    () => sp.GetRequiredService<IOptionsMonitor<MajordomoSandboxOptions>>().CurrentValue,
    TimeProvider.System,
    sp.GetRequiredService<ILoggerFactory>().CreateLogger<MajordomoSandboxIdleService>()));

builder.Services.AddSingleton(sp => new SqliteDatabaseWriteGateFactory(
    () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.SqliteWriteGate,
    sp.GetRequiredService<ILoggerFactory>(),
    TimeProvider.System));
// A BackgroundService fault stops the host via StopHost, which the host
// reports as a graceful shutdown (exit code 0) — indistinguishable from an
// intentional stop, so Restart=on-failure supervisors never restart after an
// orchestrator crash (e.g. a sustained SQLite write-gate outage escalated by
// the dispatch loop). Stated explicitly here (rather than relying on the
// framework default) because the exit-code contract below depends on it:
// faults are recorded on the tracker and mapped to a non-zero exit.
builder.Services.Configure<HostOptions>(static o =>
    o.BackgroundServiceExceptionBehavior = BackgroundServiceExceptionBehavior.StopHost);
builder.Services.AddSingleton<BackgroundServiceFailureTracker>();
builder.Services.AddHostedService(sp => new SqliteDatabaseMaintenanceService(
    sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value.StateDatabasePath,
    () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.SqliteMaintenance,
    sp.GetRequiredService<SqliteDatabaseWriteGateFactory>(),
    sp.GetRequiredService<ILogger<SqliteDatabaseMaintenanceService>>(),
    TimeProvider.System));
builder.Services.Configure<BuildScriptAuditorOptions>(builder.Configuration.GetSection("CodeyBox:BuildScriptAudit"));
// Regression-test-selection mode (Audit:TestSelection:Mode). Bound through
// AddOptions so IOptionsMonitor<TestSelectionOptions> hot-reloads the mode
// without a restart, with a fail-fast validator rejecting an unrecognised value
// at load rather than silently narrowing at audit time. Default 'all' keeps the
// emitted dotnet-test command byte-identical to today.
builder.Services.AddOptions<TestSelectionOptions>()
    .Bind(builder.Configuration.GetSection(TestSelectionOptions.SectionName))
    .Validate(
        static opts => TestSelectionModeParser.TryParse(opts.Mode, out _),
        $"{TestSelectionOptions.SectionName}:Mode must be one of: all, coverage-shadow, project-graph, coverage");
// Coverage-guided selection knobs (Audit:TestSelection:Coverage). Bound through
// AddOptions so IOptionsMonitor<CoverageTestSelectionOptions> hot-reloads the
// baseline location, age/size caps, and global targets without a restart, with
// a fail-fast validator rejecting a malformed section at load. Every consumer
// treats invalid/absent values as "no baseline" and falls back to the full
// suite — the validator only fails fast on structurally invalid config.
builder.Services.AddOptions<CoverageTestSelectionOptions>()
    .Bind(builder.Configuration.GetSection(CoverageTestSelectionOptions.SectionName))
    .Validate(
        static opts => CoverageTestSelectionOptions.IsValid(opts),
        $"{CoverageTestSelectionOptions.SectionName} is invalid");
// Soundness-report knobs (Audit:TestSelection:Soundness). Bound through
// AddOptions so IOptionsMonitor<TestSelectionSoundnessOptions> hot-reloads
// the calibration window and the report limit bound without a restart.
builder.Services.AddOptions<TestSelectionSoundnessOptions>()
    .Bind(builder.Configuration.GetSection(TestSelectionSoundnessOptions.SectionName))
    .Validate(
        static opts => TestSelectionSoundnessOptions.IsValid(opts),
        $"{TestSelectionSoundnessOptions.SectionName} is invalid");
// Standalone audit-run knobs (CodeyBox:AuditRuns). Disabled by default:
// queue implementation only until the operator enables a supported
// sandbox provider with real installed tools.
builder.Services.AddOptions<AuditRunOptions>()
    .Bind(builder.Configuration.GetSection(AuditRunOptions.SectionName))
    .Validate(
        static opts => AuditRunOptions.IsValid(opts),
        $"{AuditRunOptions.SectionName} is invalid");
// MSBuild structured build-diagnostics adapter (CodeyBox:MSBuildDiagnostics).
// Disabled by default: registers the hot-reloadable options plus the
// capability-based producer, but captures/parses nothing until the operator
// opts in. See docs/concepts/msbuild-diagnostics.md.
builder.Services.AddMSBuildBuildDiagnostics(builder.Configuration);
// GitHub Actions execution/evidence adapter (CodeyBox:GitHubActionsBuilds).
// Disabled by default: registers the hot-reloadable options plus the
// binding store only. The HTTP transport and provider need the credentialed
// overload with an explicit IGitHubTokenProvider; nothing dispatches, polls,
// or reads artifacts until the operator opts in AND pins an approved
// workflow. See docs/concepts/github-actions-builds.md.
builder.Services.AddGitHubActionsExternalBuilds(builder.Configuration);
// Post-merge baseline-production knobs
// (Audit:TestSelection:BaselineProduction). Bound through AddOptions so
// IOptionsMonitor<TestSelectionBaselineProductionOptions> hot-reloads the
// kill-switch, the sandboxed-job timeout, retention, and the guest producer
// binary without a restart.
builder.Services.AddOptions<TestSelectionBaselineProductionOptions>()
    .Bind(builder.Configuration.GetSection(TestSelectionBaselineProductionOptions.SectionName))
    .Validate(
        static opts => TestSelectionBaselineProductionOptions.IsValid(opts),
        $"{TestSelectionBaselineProductionOptions.SectionName} is invalid");
builder.Services.Configure<NotificationsOptions>(builder.Configuration.GetSection("CodeyBox:Notifications"));
builder.Services.Configure<AuditProgressApiOptions>(builder.Configuration.GetSection("CodeyBox:AuditProgressApi"));
// E2eExecutionOptions binds as a standalone section so the pool / dispatcher can
// take IOptionsMonitor<E2eExecutionOptions> directly without dragging the whole
// CodeyBoxOptions graph. The same section is also a property on CodeyBoxOptions
// (for the unbound-key validator's walk and operator visibility); the standalone
// binding is what gets hot-reloaded into the pool's MaxConcurrent.
builder.Services.AddOptions<E2eExecutionOptions>()
    .Bind(builder.Configuration.GetSection("CodeyBox:E2eExecution"))
    .Validate(static opts => IsValidE2eExecutionOptions(opts), "CodeyBox:E2eExecution is invalid")
    .Validate(opts => IsValidE2eExecutionOptionsForConfig(opts, builder.Configuration), "CodeyBox:E2eExecution remote pool prerequisites are invalid");
// Post-implementation e2e-replay authoring/verification gate config. Bound
// through AddOptions so IOptionsMonitor<E2eReplayAuthoringOptions> hot-reloads
// the Enabled switch and thresholds without restart. Disabled by default; the
// gate is a no-op until a deployment opts in AND wires a cheap-model authoring
// driver (IE2eReplayAuthoringDriver).
builder.Services.AddOptions<E2eReplayAuthoringOptions>()
    .Bind(builder.Configuration.GetSection("CodeyBox:E2eReplayAuthoring"))
    .Validate(
        static opts => opts.MaxReauthorAttempts >= E2eReplayAuthoringOptions.MinReauthorAttempts
            && opts.MaxReauthorAttempts <= E2eReplayAuthoringOptions.MaxAllowedReauthorAttempts,
        "CodeyBox:E2eReplayAuthoring:MaxReauthorAttempts is out of range")
    .Validate(
        static opts => opts.VerificationTimeout > TimeSpan.Zero && opts.VerificationPollInterval > TimeSpan.Zero,
        "CodeyBox:E2eReplayAuthoring verification timeout/poll interval must be positive")
    .Validate(
        static opts => !string.IsNullOrWhiteSpace(opts.AuthorModelId),
        "CodeyBox:E2eReplayAuthoring:AuthorModelId is required");
// Register ProjectsOptions through AddOptions so IOptionsMonitor<ProjectsOptions>
// is wired into the framework's reload pipeline. PostConfigure layers our custom
// map-shaped binding (audit-type / language overrides / profile inheritance) on
// top of the framework's section.Bind() — these dictionaries don't bind from the
// standard Bind() path because their keys are dynamic JSON property names. On
// reload, both run again automatically.
builder.Services.AddOptions<ProjectsOptions>()
    .Bind(builder.Configuration.GetSection("CodeyBox"))
    .PostConfigure(opts => ProjectsOptionsBinder.ApplyCustomMaps(opts, builder.Configuration.GetSection("CodeyBox")));

// Immutable-field guard for CodeyBoxOptions. The startup snapshot is bound from
// IConfiguration when the service provider resolves it, after test/host
// ConfigureAppConfiguration hooks have had a chance to add their final sources.
// The retaining monitor cache is deliberate: stock IOptionsMonitor drops its
// prior cached value before validating a reload candidate, so a rejected edit
// would make CurrentValue throw until the next successful reload.
//
// AgentClassesOverrideResolver runs here AS WELL AS in the IOptions PostConfigure
// pipeline: this snapshot pre-seeds the RetainingOptionsMonitorCache below, and
// stock IOptionsMonitor returns that cached value without running the options
// factory, so without this call IOptionsMonitor<CodeyBoxOptions>.CurrentValue
// would observe the raw positional-merge AgentClasses until the first reload.
builder.Services.AddSingleton(sp =>
{
    var config = sp.GetRequiredService<IConfiguration>();
    var snapshot = config.GetSection("CodeyBox").Get<CodeyBoxOptions>() ?? new CodeyBoxOptions();
    AgentClassesOverrideResolver.ApplyTo(snapshot, config);
    AgentClassesOverrideResolver.ApplySandboxClassesTo(snapshot, config);
    AgentFailureClassifier.SetAdditionalTransientNetworkPatterns(snapshot.TransientNetworkFailurePatterns);
    ProviderTransientSignatureBinder.SyncStore(snapshot);
    return new CodeyBoxOptionsStartupSnapshot(snapshot);
});
builder.Services.AddSingleton<IOptionsMonitorCache<CodeyBoxOptions>>(
    sp => new RetainingOptionsMonitorCache<CodeyBoxOptions>(
        sp.GetRequiredService<CodeyBoxOptionsStartupSnapshot>().Value,
        opts =>
        {
            AgentFailureClassifier.SetAdditionalTransientNetworkPatterns(opts.TransientNetworkFailurePatterns);
            if (!ProviderTransientSignatureBinder.TrySyncStore(opts, out var transientError))
            {
                sp.GetRequiredService<ILoggerFactory>().CreateLogger("CodeyBoxOptions")
                    .LogWarning("Hot-reload of CodeyBox:ProviderTransientSignatures rejected; keeping prior signatures: {Error}", transientError);
            }
        }));
builder.Services.TryAddSingleton<IProcessRunner, DefaultProcessRunner>();
builder.Services.TryAddSingleton<IOpenSshConfigResolver, OpenSshConfigResolver>();
builder.Services.TryAddSingleton<E2eRemoteHostValidation>();
builder.Services.TryAddSingleton<E2eRemotePoolConfigValidation>();
builder.Services.AddSingleton<IValidateOptions<CodeyBoxOptions>>(
    sp => new ImmutableCodeyBoxOptionsValidator(
        sp.GetRequiredService<CodeyBoxOptionsStartupSnapshot>().Value));
builder.Services.AddSingleton<IValidateOptions<CodeyBoxOptions>>(
    sp => new CodeyBoxOptionsValidator(
        sp.GetRequiredService<E2eRemotePoolConfigValidation>(),
        sp.GetRequiredService<PluginSandboxProviderCatalog>().Kinds));

// Deploy-consistency probe. Refreshes the built-vs-checkout comparison at
// startup and warns while the service is still healthy when the working tree
// has moved ahead of bin/. Registered before UnboundConfigKeyHostedValidator
// so the unbound-key failure can name a stale build as its cause. Never
// throws; unknown revisions report unknown, not diverged.
builder.Services.AddSingleton<DeployConsistencyService>();
builder.Services.AddHostedService(sp => sp.GetRequiredService<DeployConsistencyService>());

// Unbound-key startup check. Walks the CodeyBox:* configuration sub-tree
// and surfaces any key that does not bind to a property on the typed
// options graph (the .NET binder silently drops these, which makes a
// misspelled or renamed key a no-op the operator never notices). Default
// behaviour is fail-fast at host start; switch to warn-only via
// CodeyBox:ConfigValidation:UnboundKeys:Mode="warn".
builder.Services.AddHostedService<UnboundConfigKeyHostedValidator>();

// Audit-budget ordering startup check. Rejects auditor-idle >= per-iteration,
// per-iteration >= item-stale, and item-stale >= sandbox wall clock with the
// offending config paths named, so a misordered budget fails startup instead
// of silently killing healthy long runs at audit time.
builder.Services.AddHostedService<AuditBudgetOrderingStartupValidator>();

// Rejects ProjectsOptions reloads that remove a project still holding
// non-terminal work items. Adding new projects passes cleanly.
builder.Services.AddSingleton<IValidateOptions<ProjectsOptions>, ProjectsOptionsRemovalValidator>();

// Sized from the resolved sandbox provider's capability, not the provider config
// name. SandboxTeardownMode is intentionally hot-reloadable at shutdown time, but
// HostOptions is captured at startup, so suspend-capable providers keep the
// RAM-snapshot ceiling even when startup config says Stop/Dispose. It is only a
// ceiling: shutdown still returns promptly when no suspend work is running.
// Using the DI-resolved provider keeps the deployment knowledge (name → provider)
// in the composition root and out of the Core policy. See ComputeHostShutdownTimeout.
builder.Services.AddOptions<HostOptions>()
    .Configure<IOptions<CodeyBoxOptions>, ISandboxProvider, ILoggerFactory>(
        (o, cbOptsAccessor, sandboxProvider, loggerFactory) =>
        {
            var providerSupportsSuspend = sandboxProvider is ISuspendingSandboxProvider;
            o.ShutdownTimeout = Program.ComputeHostShutdownTimeout(
                cbOptsAccessor.Value,
                providerSupportsSuspend,
                loggerFactory.CreateLogger("CodeyBox.HostShutdown"));
        });

ApiKeyAuth.Configure(builder);

// --- Sandbox provider --------------------------------------------------------
// Selected by CodeyBox:SandboxProvider in config. Each option has a different
// security/setup trade-off — see docs/concepts/sandboxes.md.
//
//   process     — UNSAFE. No isolation. Dev only; refuses to load outside
//                 Development env unless DangerouslyAllowProcessSandbox=true.
//   bubblewrap  — Namespace + seccomp isolation, no daemon. Single package
//                 install. Shares the host kernel.
//   multipass   — Real Ubuntu VMs via Canonical's snap. Separate guest
//                 kernel. Single 'snap install multipass' on Ubuntu, no
//                 podman / OCI runtime / /etc edits. ~10-30s VM launch.
//   incus       — Real VMs backed by a snapshot-capable Incus storage pool.
//                 Baseline clones are copy-on-write and host directories are
//                 shared through explicitly selected virtiofs devices.
//   sprites     — Fly.io hosted Firecracker microVMs via sprites.dev. Requires
//                 SPRITES_TOKEN (or configured token env var).
builder.Services.AddSingleton<ISandboxProvider>(SelectSandboxProvider);

// Colocated executor: the in-process executor host giving single-host
// deployments working local phase execution with no configuration. Every
// knob carries a safe default and validation fails fast at host start, so an
// operator who configures nothing still gets the executor path. The phase
// handler is optional here (none is composed yet): without one the host
// reports no runner and any dispatch to it fails loudly instead of silently
// running elsewhere.
builder.Services.AddSingleton<IValidateOptions<ColocatedExecutorOptions>, ColocatedExecutorOptionsValidator>();
builder.Services.AddOptions<ColocatedExecutorOptions>()
    .Bind(builder.Configuration.GetSection(ColocatedExecutorOptions.SectionName))
    .ValidateOnStart();
builder.Services.AddSingleton(sp => new ColocatedExecutorHost(
    sp.GetRequiredService<ISandboxProvider>(),
    () => sp.GetRequiredService<IOptionsMonitor<ColocatedExecutorOptions>>().CurrentValue,
    () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.ExecutorPhaseDispatch,
    sp.GetService<IExecutorPhaseHandler>(),
    tracker: new ExecutorSandboxTracker(),
    loggerFactory: sp.GetRequiredService<ILoggerFactory>(),
    repositoriesRootAccessor: () => sp.GetRequiredService<IGitHost>().RepositoriesRootDirectory));
builder.Services.AddSingleton<IExecutorPhaseTransportFactory>(sp =>
    new ColocatedExecutorTransportFactory(sp.GetRequiredService<ColocatedExecutorHost>()));

// Remote phase-dispatch rendezvous: the poll-driven protocol's
// orchestrator-side state (pending queues, in-flight dispatches, chunk
// relay) plus the stage-out upload registry backing the two-call complete
// protocol. Both live as long as the process; the broker fails pending
// dispatches and deletes temp archives on shutdown. Reached only through the
// executor-initiated phase endpoints below — the orchestrator never dials
// an executor.
builder.Services.AddSingleton(sp => new ExecutorPhaseBroker(
    () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.ExecutorPhaseDispatch,
    log: sp.GetRequiredService<ILoggerFactory>().CreateLogger<ExecutorPhaseBroker>()));
builder.Services.AddSingleton<ExecutorPhaseStageOutUploads>();
builder.Services.AddSingleton<TimeProvider>(TimeProvider.System);
builder.Services.AddSingleton<Func<ExecutorPhaseDispatchOptions>>(sp =>
    () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.ExecutorPhaseDispatch);

// Member-keyed provider registry for sandbox placement. Each provider kind
// named by a SandboxClass member is constructed once here (via the same
// BuildSandboxProviderInner the singleton uses, or via the plugin catalog for
// plugin-contributed kinds) and shared across the members
// naming it; lookup is by normalised kind so registration order never affects
// resolution. Each instance carries an admission wrapper whose gate is
// DERIVED from the member catalog (see ISandboxProviderRegistry
// .SyncKindCapacities): the gate target is the sum of member capacities
// naming the kind, so the kind gate always fits the member gates beneath it
// and never clamps them — real admission happens once, at the member gate
// inside SandboxPlacementAcquirer, while the kind wrapper keeps owning
// lifecycle tracking, metrics, and capability preservation. No provider kind
// is named anywhere outside this factory: core and pipeline code resolve
// through the registry.
builder.Services.AddSingleton<ISandboxProviderRegistry>(sp => new SandboxProviderRegistry(
    kind => BuildRegistrySandboxProvider(sp, kind),
    sp.GetRequiredService<ILoggerFactory>().CreateLogger<SandboxProviderRegistry>(),
    sp.GetRequiredService<PluginSandboxProviderCatalog>().Kinds));

// B1: register baseline-image capabilities as derived views of the selected
// provider. Providers without baseline support (process / bubblewrap) receive
// null-object implementations, so consumers can depend on the capability
// without knowing which concrete provider is active.
builder.Services.AddSingleton(sp =>
    sp.GetRequiredService<ISandboxProvider>() as IBaselineImageResolver
        ?? NullBaselineImageResolver.Instance);
builder.Services.AddSingleton(sp =>
    sp.GetRequiredService<ISandboxProvider>() as IBaselineImageProvisioner
        ?? NullBaselineImageProvisioner.Instance);

static void ConfigureOtlp(OtlpExporterOptions o, OtelOptions opts)
{
    // Honour the standard OTel env contract: when OTEL_EXPORTER_OTLP_ENDPOINT /
    // OTEL_EXPORTER_OTLP_HEADERS are set we leave the exporter's SDK defaults in
    // place (the SDK reads those vars itself, including the http path-append
    // semantics), so env overrides appsettings. We only assign from
    // CodeyBox:Otel when the corresponding env var is absent.
    var envEndpoint = Environment.GetEnvironmentVariable("OTEL_EXPORTER_OTLP_ENDPOINT");
    if (string.IsNullOrWhiteSpace(envEndpoint) && !string.IsNullOrWhiteSpace(opts.OtlpEndpoint))
        o.Endpoint = new Uri(opts.OtlpEndpoint);

    // OTEL_EXPORTER_OTLP_PROTOCOL is part of the same env contract: when it is
    // set the SDK reads it itself, so forcing the appsettings protocol here would
    // silently override an env-only deployment (e.g. http/protobuf on :4318 while
    // appsettings still defaults to grpc). Only assign from CodeyBox:Otel when the
    // env var is absent.
    var envProtocol = Environment.GetEnvironmentVariable("OTEL_EXPORTER_OTLP_PROTOCOL");
    if (string.IsNullOrWhiteSpace(envProtocol))
        o.Protocol = opts.ExportProtocol == "httpprotobuf"
            ? OtlpExportProtocol.HttpProtobuf
            : OtlpExportProtocol.Grpc;

    var envHeaders = Environment.GetEnvironmentVariable("OTEL_EXPORTER_OTLP_HEADERS");
    if (string.IsNullOrWhiteSpace(envHeaders) && !string.IsNullOrEmpty(opts.OtlpHeaders))
        o.Headers = opts.OtlpHeaders;
}

static ISandboxProvider SelectSandboxProvider(IServiceProvider sp)
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    var loggerFactory = sp.GetRequiredService<ILoggerFactory>();
    var startupLog = loggerFactory.CreateLogger("CodeyBox.Sandbox");

    var environment = sp.GetRequiredService<IHostEnvironment>();
    var kind = SandboxProviderSelection.ResolveConfiguredKind(
        opts.SandboxProvider,
        sp.GetRequiredService<IConfiguration>(),
        environment,
        startupLog);

    var hostPlatformEarly = CodeyBox.Core.HostPlatformSupport.HostOperatingSystem.Current;
    var pluginKindsEarly = sp.GetRequiredService<PluginSandboxProviderCatalog>().Kinds;
    if (!CodeyBox.Core.HostPlatformSupport.IsProviderSupportedOnHost(kind, hostPlatformEarly, pluginKindsEarly))
    {
        throw new InvalidOperationException(
            $"CodeyBox:SandboxProvider '{kind}' is not supported on {hostPlatformEarly.Name}: " +
            CodeyBox.Core.HostPlatformSupport.GetUnsupportedReason(kind, hostPlatformEarly, pluginKindsEarly));
    }

    // Plain (non-reloadable) kinds are owned by the member-keyed registry:
    // the singleton and any member naming the kind share the exact same
    // admission-wrapped instance, so lifecycle inventory is never split
    // across two instances of one backend. Reloadable kinds keep their
    // dedicated cutover router below.
    if (!SandboxProviderKinds.SupportsHotReload(kind))
    {
        return sp.GetRequiredService<ISandboxProviderRegistry>().EnsureKind(kind);
    }

    ISandboxProvider inner = BuildReloadableSandboxProvider(sp, loggerFactory);
    var hostPlatform = hostPlatformEarly;
    LogSandboxEgressClassification(kind, hostPlatform, startupLog);
    SandboxProviderSelection.ValidateWorkloadTrust(
        inner,
        opts,
        sp.GetRequiredService<IConfiguration>(),
        environment);
    var orchestratorOptions = sp.GetRequiredService<OrchestratorOptions>();
    startupLog.LogInformation(
        "Sandbox admission control: provider={Provider}, MaxConcurrentSandboxes={MaxConcurrentSandboxes}",
        inner.Name,
        orchestratorOptions.MaxConcurrentSandboxes);
    if (inner is ISandboxHostPoolSnapshot hostPool)
        RemoteHostPoolCapacityLogger.Log(hostPool, startupLog);
    LogSandboxProviderCapabilities(inner, startupLog);
    var pipelineTuning = sp.GetRequiredService<PipelineTuningSnapshot>();
    return SandboxAdmissionControlledProvider.Wrap(
        inner,
        orchestratorOptions.MaxConcurrentSandboxes,
        loggerFactory.CreateLogger<SandboxAdmissionControlledProvider>(),
        waitWarningThresholdProvider: () => pipelineTuning.Current.SandboxPermitWaitWarningThreshold);
}

static ISandboxProvider BuildRegistrySandboxProvider(IServiceProvider sp, string kind)
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    var loggerFactory = sp.GetRequiredService<ILoggerFactory>();
    var startupLog = loggerFactory.CreateLogger("CodeyBox.Sandbox.Registry");
    var environment = sp.GetRequiredService<IHostEnvironment>();
    var pluginCatalog = sp.GetRequiredService<PluginSandboxProviderCatalog>();
    var isPluginKind = pluginCatalog.IsPluginKind(kind);
    if (!SandboxProviderKinds.IsRegistered(kind) && !isPluginKind)
    {
        throw new InvalidOperationException(
            $"Unregistered sandbox provider kind '{kind}'. Registered providers: " +
            $"{CodeyBox.Core.HostPlatformSupport.FormatKnownProviders(pluginCatalog.Kinds)}. " +
            "The kind is NOT silently falling back to another provider.");
    }
    var hostPlatform = CodeyBox.Core.HostPlatformSupport.HostOperatingSystem.Current;
    if (!CodeyBox.Core.HostPlatformSupport.IsProviderSupportedOnHost(kind, hostPlatform, pluginCatalog.Kinds))
    {
        throw new InvalidOperationException(
            $"Sandbox provider kind '{kind}' is not supported on {hostPlatform.Name}: " +
            CodeyBox.Core.HostPlatformSupport.GetUnsupportedReason(kind, hostPlatform, pluginCatalog.Kinds));
    }
    ISandboxProvider inner;
    if (isPluginKind && pluginCatalog.TryGetProvider(kind, out var pluginProvider))
    {
        inner = pluginProvider;
        startupLog.LogInformation(
            "Sandbox provider registry: kind '{Kind}' is plugin-contributed by '{PluginId}' (provider={Provider}); " +
            "platform support and workload-trust gates apply exactly as for built-in kinds.",
            kind.Trim().ToLowerInvariant(),
            pluginCatalog.PluginIdFor(kind),
            inner.Name);
    }
    else
    {
        inner = BuildSandboxProviderInner(sp, opts, environment, startupLog, loggerFactory, kind);
    }
    SandboxProviderSelection.ValidateWorkloadTrust(
        inner,
        opts,
        sp.GetRequiredService<IConfiguration>(),
        environment);
    LogSandboxEgressClassification(kind, hostPlatform, startupLog);
    var orchestratorOptions = sp.GetRequiredService<OrchestratorOptions>();
    var pipelineTuning = sp.GetRequiredService<PipelineTuningSnapshot>();
    startupLog.LogInformation(
        "Sandbox admission control: provider={Provider}, MaxConcurrentSandboxes={MaxConcurrentSandboxes}",
        inner.Name,
        orchestratorOptions.MaxConcurrentSandboxes);
    if (inner is ISandboxHostPoolSnapshot hostPool)
        RemoteHostPoolCapacityLogger.Log(hostPool, startupLog);
    LogSandboxProviderCapabilities(inner, startupLog);
    startupLog.LogInformation(
        "Sandbox provider registry: constructed kind '{Kind}' (provider={Provider}, MaxConcurrentSandboxes={MaxConcurrentSandboxes})",
        kind,
        inner.Name,
        orchestratorOptions.MaxConcurrentSandboxes);
    return SandboxAdmissionControlledProvider.Wrap(
        inner,
        orchestratorOptions.MaxConcurrentSandboxes,
        loggerFactory.CreateLogger<SandboxAdmissionControlledProvider>(),
        waitWarningThresholdProvider: () => pipelineTuning.Current.SandboxPermitWaitWarningThreshold);
}

/// <summary>
/// Logs the host-owned egress-enforcement classification for one constructed provider
/// kind, so an operator can see which of their providers actually contain network
/// egress and which do not. <c>NotEnforced</c> (every plugin kind, plus bubblewrap
/// and process) is logged as a warning stating where such a provider may be used.
/// A kind opted into <c>CodeyBox:EgressVerification</c> stays <c>NotEnforced</c>
/// here — verification is granted per sandbox by placement, never statically.
/// </summary>
static void LogSandboxEgressClassification(
    string kind,
    CodeyBox.Core.HostPlatformSupport.HostOperatingSystem hostPlatform,
    ILogger startupLog)
{
    var enforcement = CodeyBox.Core.HostPlatformSupport.GetEgressEnforcement(kind);
    if (enforcement == CodeyBox.Core.EgressEnforcementLocation.EnforcedOnRemoteExecutorHost)
    {
        startupLog.LogInformation(
            "Sandbox egress enforcement for provider '{Provider}' lives on the remote Linux executor host; " +
            "the {Host} orchestrator host needs no packet filter, but the executor must have " +
            "scripts/setup-host-networks.sh applied (see docs/concepts/host-platforms.md).",
            kind,
            hostPlatform.Name);
        return;
    }
    if (enforcement == CodeyBox.Core.EgressEnforcementLocation.EnforcedOnOrchestratorHost)
    {
        startupLog.LogInformation(
            "Sandbox egress enforcement for provider '{Provider}' lives on the {Host} orchestrator host " +
            "(Linux nftables bridges; see scripts/setup-host-networks.sh).",
            kind,
            hostPlatform.Name);
        return;
    }
    if (enforcement == CodeyBox.Core.EgressEnforcementLocation.EnforcedOnProviderHostVerified)
    {
        // Defensive: the static switch never returns the verified value (it is
        // per-sandbox, via SandboxEgressPolicy.EffectiveEnforcement). Logged
        // without the NotEnforced warning so a future static source of this
        // value stays explicit — and still never above orchestrator-host
        // enforcement.
        startupLog.LogInformation(
            "Sandbox egress enforcement for provider '{Provider}': {Classification}.",
            kind,
            CodeyBox.Core.SandboxEgressPolicy.DescribeEgressEnforcement(kind));
        return;
    }
    startupLog.LogWarning(
        "Sandbox provider '{Provider}': {Classification}. " +
        "It may only serve sandboxes with no named network profile and must never be described as isolation.",
        kind,
        CodeyBox.Core.SandboxEgressPolicy.DescribeEgressEnforcement(kind));
}

static void LogSandboxProviderCapabilities(ISandboxProvider provider, ILogger startupLog)
{
    IReadOnlyList<ISandboxProvider> registered = provider is ReloadableSandboxProvider reloadable
        ? reloadable.RegisteredProviders
        : [provider];

    var matrix = SandboxCapabilities.FormatMatrix(registered);
    startupLog.LogInformation(
        "Registered sandbox provider capabilities: {CapabilitiesMatrix}",
        matrix);
}

static ISandboxProvider BuildSandboxProviderInner(
    IServiceProvider sp,
    CodeyBoxOptions opts,
    IHostEnvironment environment,
    ILogger startupLog,
    ILoggerFactory loggerFactory,
    string kind)
{
    // Provider construction lives in the shared factory
    // (SharedSandboxProviderFactory) so the orchestrator and the executor
    // host cannot drift apart: adding a kind means editing the factory, and
    // the arms below only attach orchestrator-side option shaping (plugins,
    // disk guard, banners, transports). Kinds with no arm fall through to
    // the factory with default options, so a new factory kind needs no edit
    // here unless it needs orchestrator-side tuning.
    return kind switch
    {
        SandboxProviderKinds.Process => BuildProcess(sp, opts, environment, startupLog, loggerFactory),
        SandboxProviderKinds.Bubblewrap => SharedSandboxProviderFactory.Build(
            SandboxProviderKinds.Bubblewrap,
            new SandboxProviderBuildArgs
            {
                Loggers = loggerFactory,
                BubblewrapOptions = () => new BubblewrapSandboxOptions(),
                Timings = sp.GetService<ITimingStore>(),
            }),
        SandboxProviderKinds.Multipass => BuildMultipass(
            opts,
            sp,
            loggerFactory,
            startupLog,
            sp.GetService<ITimingStore>(),
            sp.GetService<ISandboxResourceUsageStore>()),
        SandboxProviderKinds.Incus => BuildIncus(
            sp,
            loggerFactory,
            sp.GetService<ITimingStore>(),
            sp.GetService<ISandboxResourceUsageStore>()),
        SandboxProviderKinds.MultipassRemote => BuildMultipassRemote(sp, loggerFactory),
        SandboxProviderKinds.Sprites => BuildSprites(sp, loggerFactory, startupLog),
        _ => SharedSandboxProviderFactory.Build(
            kind,
            new SandboxProviderBuildArgs
            {
                Loggers = loggerFactory,
                ProcessRunner = sp.GetService<IProcessRunner>(),
                Timings = sp.GetService<ITimingStore>(),
                ResourceUsage = sp.GetService<ISandboxResourceUsageStore>(),
            }),
    };
}

static IE2eExecutionPool BuildE2eExecutionPool(IServiceProvider sp)
{
    var loggerFactory = sp.GetRequiredService<ILoggerFactory>();
    var e2eOptions = sp.GetRequiredService<IOptionsMonitor<E2eExecutionOptions>>();
    var poolKind = (e2eOptions.CurrentValue.PoolKind ?? "remote-ssh").Trim().ToLowerInvariant();
    var environment = sp.GetRequiredService<IHostEnvironment>();
    var startupOptions = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue;
    if (poolKind == "local" && !environment.IsDevelopment())
    {
        throw RequiredConfigurationValidator.CreateAggregateException(
            sp.GetRequiredService<IConfiguration>(),
            environment,
            RequiredConfigurationValidator.E2eLocalPoolMessage);
    }

    if (poolKind == "remote-ssh" && e2eOptions.CurrentValue.Enabled)
    {
        ValidateEnabledRemoteE2eConfig(
            e2eOptions.CurrentValue,
            startupOptions,
            sp.GetRequiredService<E2eRemotePoolConfigValidation>());
    }

    if (poolKind == "remote-ssh")
    {
        return BuildRemoteE2eExecutionPool(sp, loggerFactory, e2eOptions);
    }

    ISandboxProvider provider = poolKind switch
    {
        "local" => BuildE2eLocalSandboxProvider(sp, loggerFactory),
        _ => throw new InvalidOperationException(
            $"Unknown CodeyBox:E2eExecution:PoolKind '{e2eOptions.CurrentValue.PoolKind}'. Valid: local, remote-ssh"),
    };

    return new LocalE2eExecutionPool(
        provider,
        e2eOptions,
        loggerFactory.CreateLogger<LocalE2eExecutionPool>(),
        fallbackImageReference: () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.SandboxImageReference,
        name: poolKind);
}

static IE2eExecutionPool BuildRemoteE2eExecutionPool(
    IServiceProvider sp,
    ILoggerFactory loggerFactory,
    IOptionsMonitor<E2eExecutionOptions> e2eOptions)
{
    var currentOptions = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue;
    var hostConfigs = GetE2eRemoteHostConfigs(currentOptions);
    if (hostConfigs.Count == 0)
    {
        var provider = BuildE2eMultipassRemote(sp, loggerFactory, hostIndex: 0);
        return new LocalE2eExecutionPool(
            provider,
            e2eOptions,
            loggerFactory.CreateLogger<LocalE2eExecutionPool>(),
            fallbackImageReference: () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.SandboxImageReference,
            name: "remote-ssh");
    }

    var hosts = hostConfigs
        .Select((cfg, index) => new E2eExecutionHost(
            string.IsNullOrWhiteSpace(cfg.RemoteSandbox.SshTarget) ? $"remote-ssh:{index}" : cfg.RemoteSandbox.SshTarget!,
            BuildE2eMultipassRemote(sp, loggerFactory, index),
            cfg.MaxConcurrent ?? 1))
        .ToArray();

    return new MultiHostE2eExecutionPool(
        hosts,
        e2eOptions,
        loggerFactory.CreateLogger<MultiHostE2eExecutionPool>(),
        fallbackImageReference: () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.SandboxImageReference);
}

static bool IsValidE2eExecutionOptions(E2eExecutionOptions opts)
{
    if (opts.MaxConcurrent is < E2eExecutionOptions.MinimumMaxConcurrent or > E2eExecutionOptions.MaximumMaxConcurrent)
        return false;
    if (opts.PollInterval < TimeSpan.Zero || opts.PerRunTimeout <= TimeSpan.Zero)
        return false;
    if (!string.Equals(opts.PoolKind, "local", StringComparison.OrdinalIgnoreCase)
        && !string.Equals(opts.PoolKind, "remote-ssh", StringComparison.OrdinalIgnoreCase))
        return false;
    if (opts.AllowedReadinessOrigins.Count == 0)
        return false;
    foreach (var origin in opts.AllowedReadinessOrigins)
    {
        if (string.IsNullOrWhiteSpace(origin)
            || !Uri.TryCreate(origin, UriKind.Absolute, out var uri)
            || (uri.Scheme != Uri.UriSchemeHttp && uri.Scheme != Uri.UriSchemeHttps)
            || !string.IsNullOrEmpty(uri.AbsolutePath.Trim('/'))
            || !string.IsNullOrEmpty(uri.Query)
            || !string.IsNullOrEmpty(uri.Fragment)
            || !string.IsNullOrEmpty(uri.UserInfo))
            return false;
    }

    return true;
}

static bool IsValidE2eExecutionOptionsForConfig(E2eExecutionOptions opts, IConfiguration config)
{
    if (!opts.Enabled || !string.Equals(opts.PoolKind, "remote-ssh", StringComparison.OrdinalIgnoreCase))
        return true;

    var cb = config.GetSection("CodeyBox").Get<CodeyBoxOptions>() ?? new CodeyBoxOptions();
    return TryValidateEnabledRemoteE2eConfig(opts, cb, out _);
}

static void ValidateEnabledRemoteE2eConfig(
    E2eExecutionOptions e2e,
    CodeyBoxOptions options,
    E2eRemotePoolConfigValidation? validator = null)
{
    if (!TryValidateEnabledRemoteE2eConfig(e2e, options, out var message, validator))
        throw new InvalidOperationException(message);
}

static bool TryValidateEnabledRemoteE2eConfig(
    E2eExecutionOptions e2e,
    CodeyBoxOptions options,
    out string message,
    E2eRemotePoolConfigValidation? validator = null)
{
    var failures = (validator ?? E2eRemotePoolConfigValidation.Default).ValidateEnabledRemoteE2eConfig(e2e, options);
    if (failures.Count > 0)
    {
        message = string.Join("; ", failures);
        return false;
    }
    message = string.Empty;
    return true;
}

static IReadOnlyList<E2eMultipassRemoteHostConfig> GetE2eRemoteHostConfigs(CodeyBoxOptions options)
{
    if (options.E2eMultipassRemoteSandboxes is { Count: > 0 } hosts)
        return hosts;
    return options.E2eMultipassRemoteSandbox is null
        ? []
        : [options.E2eMultipassRemoteSandbox];
}

static ISandboxProvider BuildE2eLocalSandboxProvider(IServiceProvider sp, ILoggerFactory loggerFactory)
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    var environment = sp.GetRequiredService<IHostEnvironment>();
    var startupLog = loggerFactory.CreateLogger("CodeyBox.E2eSandbox");
    if (!environment.IsDevelopment())
    {
        throw new InvalidOperationException(
            "CodeyBox:E2eExecution:PoolKind=local is only available in Development.");
    }

    var kind = ReloadableSandboxProvider.NormalizeConfiguredProviderId(opts.SandboxProvider);
    if (string.IsNullOrEmpty(kind))
    {
        if (environment.IsDevelopment())
        {
            startupLog.LogWarning(
                "CodeyBox:E2eExecution:PoolKind=local with CodeyBox:SandboxProvider unset; defaulting E2E provider to 'process' because environment is Development.");
            kind = "process";
        }
        else
        {
            throw new InvalidOperationException(
                "CodeyBox:SandboxProvider must be set when CodeyBox:E2eExecution:PoolKind=local in non-Development environments.");
        }
    }

    return BuildSandboxProviderInner(sp, opts, environment, startupLog, loggerFactory, kind);
}

static ISandboxProvider BuildProcess(IServiceProvider sp, CodeyBoxOptions opts, IHostEnvironment env, ILogger startupLog, ILoggerFactory loggerFactory)
{
    if (!env.IsDevelopment() && !opts.DangerouslyAllowProcessSandbox)
    {
        throw RequiredConfigurationValidator.CreateAggregateException(
            sp.GetRequiredService<IConfiguration>(),
            env,
            RequiredConfigurationValidator.ProcessSandboxUnsafeMessage);
    }
    startupLog.LogWarning("Using Process sandbox provider — NO ISOLATION. Dev only.");
    // Construction lives in the shared factory; only the dev-gate policy stays here.
    return SharedSandboxProviderFactory.Build(
        SandboxProviderKinds.Process,
        new SandboxProviderBuildArgs { Loggers = loggerFactory });
}

static ISandboxProvider BuildIncus(
    IServiceProvider sp,
    ILoggerFactory loggerFactory,
    ITimingStore? timings,
    ISandboxResourceUsageStore? resourceUsageStore)
{
    var configLog = loggerFactory.CreateLogger("CodeyBox.Incus.Config");
    Func<IncusSandboxOptions> optionsAccessor =
        // The reloadable selector may route future work to another registered
        // provider, while each Incus operation resolves the latest allowed
        // settings. A live sandbox keeps the immutable IncusSandboxOptions
        // snapshot captured when it was created, so a reload cannot change its
        // project, pool, or device map halfway through teardown.
        () =>
        {
            var live = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue;
            var projects = sp.GetRequiredService<IOptionsMonitor<ProjectsOptions>>().CurrentValue;
            var incus = live.Incus ?? new IncusSandboxConfig();
            var baselineVerificationCommands = incus.UseBaselineImages
                ? BaselineVerificationProbeBuilder.Build(
                    live,
                    projects,
                    sp.GetServices<IInVmSmokeProbe>(),
                    sp.GetService<InVmSmokeOptions>())
                : Array.Empty<BaselineVerificationCommand>();
            var baseline = IncusSandboxConfigMapper.Build(
                live,
                configLog,
                baselineVerificationCommands);
            return ApplyPluginBaselineContributions(
                sp, configLog, baseline, baselineVerificationCommands.Count, providerKind: "incus");
        };
    // Construction lives in the shared factory; option shaping (plugins,
    // baselines, hot-reload delegate) stays here.
    var provider = SharedSandboxProviderFactory.Build(
        SandboxProviderKinds.Incus,
        new SandboxProviderBuildArgs
        {
            Loggers = loggerFactory,
            IncusOptions = optionsAccessor,
            Timings = timings,
            ResourceUsage = resourceUsageStore,
            ArtifactTrust = () => sp.GetRequiredService<IOptionsMonitor<ArtifactTrustOptions>>().CurrentValue,
            ArtifactAdmission = sp.GetService<ArtifactAdmissionService>(),
            BaselineBlockedTracker = sp.GetRequiredService<BaselineProvisioningBlockedTracker>(),
        });

    if (provider is IDiskGuardedSandboxProvider guarded)
        LogDiskGuardBanner(guarded, configLog);
    return provider;
}

/// <summary>
/// Merges enabled plugins' external-tool requirements into an Incus options
/// snapshot. Install steps go after operator <c>ExtraRuncmd</c> (so operator
/// repository setup runs first); verification steps go after the agent-CLI
/// probes. Both lists join the baseline-identity hash, so enabling or
/// disabling a plugin rebakes the baseline via the normal orphan/grace path.
/// </summary>
static IncusSandboxOptions ApplyPluginBaselineContributions(
    IServiceProvider sp,
    ILogger log,
    IncusSandboxOptions baseline,
    int existingVerificationCount,
    string providerKind)
{
    var contributions = ResolvePluginBaselineContributions(sp, log, existingVerificationCount, providerKind);
    if (contributions.VerificationCommands.Count == 0 && contributions.InstallCommands.Count == 0)
        return baseline;
    return baseline with
    {
        ExtraRuncmd = [.. baseline.ExtraRuncmd, .. contributions.InstallCommands],
        BaselineVerificationCommands = [.. baseline.BaselineVerificationCommands, .. contributions.VerificationCommands],
    };
}

static IReadOnlyList<string> AppendPluginInstallCommands(
    IReadOnlyList<string> extraRuncmd,
    PluginBaselineContributions contributions) =>
    contributions.InstallCommands.Count == 0
        ? extraRuncmd
        : [.. extraRuncmd, .. contributions.InstallCommands];

static IReadOnlyList<BaselineVerificationCommand> AppendPluginVerificationCommands(
    IReadOnlyList<BaselineVerificationCommand> existing,
    PluginBaselineContributions contributions) =>
    contributions.VerificationCommands.Count == 0
        ? existing
        : [.. existing, .. contributions.VerificationCommands];

/// <summary>
/// Resolves the validated tool requirements of loaded (enabled + allowlisted)
/// plugins and builds their host-owned baseline contributions. Never throws:
/// a resolution failure degrades to no plugin contributions (logged) rather
/// than breaking sandbox creation.
/// </summary>
static PluginBaselineContributions ResolvePluginBaselineContributions(
    IServiceProvider sp,
    ILogger log,
    int existingVerificationCount,
    string providerKind)
{
    IReadOnlyList<PluginToolRequirement> tools;
    try
    {
        tools = sp.GetService<IPluginLoader>()?.GetEnabledPluginTools() ?? [];
    }
    catch (Exception ex)
    {
        log.LogWarning(
            ex,
            "Plugin baseline provisioning for {Provider} unavailable: cannot resolve enabled plugin tools; continuing without them",
            providerKind);
        return new PluginBaselineContributions([], [], []);
    }
    if (tools.Count == 0)
        return new PluginBaselineContributions([], [], []);
    var contributions = PluginBaselineProvisioning.BuildContributions(tools, existingVerificationCount);
    foreach (var dropped in contributions.DroppedTools)
    {
        log.LogDebug(
            "Plugin baseline provisioning for {Provider}: dropped tool {PluginId}:{Binary} (provider verification headroom exhausted)",
            providerKind, dropped.PluginId, dropped.Binary);
    }
    log.LogInformation(
        "Plugin baseline provisioning for {Provider}: {Verifications} verification steps and {Installs} install steps from {Tools} enabled plugin tools",
        providerKind,
        contributions.VerificationCommands.Count,
        contributions.InstallCommands.Count,
        tools.Count);
    return contributions;
}

static ISandboxProvider BuildMultipass(
    CodeyBoxOptions opts,
    IServiceProvider sp,
    ILoggerFactory loggerFactory,
    ILogger startupLog,
    ITimingStore? timings,
    ISandboxResourceUsageStore? resourceUsageStore)
{
    // DiskGuard is resolved once at startup: it captures the state-database
    // directory (built from opts) which is itself immutable for the process
    // lifetime. The cloud-init / runcmd / network-profile fields below are
    // resolved live via IOptionsMonitor on every VM launch.
    var diskGuard = MultipassDiskGuardConfig.Build(opts, startupLog);
    Func<MultipassSandboxOptions> optionsAccessor =
        // Resolve through IOptionsMonitor so cloud-init / runcmd edits land
        // on the next VM launch without restart. Sandboxes already running
        // keep the snapshot they were constructed with.
        () =>
        {
            var live = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue;
            var projects = sp.GetRequiredService<IOptionsMonitor<ProjectsOptions>>().CurrentValue;
            var multipassSandbox = live.MultipassSandbox ?? new MultipassSandboxConfig();
            // Post-bake binary verification is only meaningful on the baseline-
            // clone path. When baseline images are disabled the per-launch
            // cloud-init flow exists no baseline to verify, so skip the build
            // entirely — both to avoid unnecessary work and to keep ordinary
            // Multipass provisioning insulated from any future bake-only fault
            // in the builder.
            //
            // Smoke options are intentionally NOT passed here: the bake gate
            // verifies durable image integrity and must run regardless of the
            // runtime smoke toggles (CodeyBox:Smoke:Enabled,
            // CodeyBox:Smoke:InVm:Enabled), which only govern dispatch-time
            // routing. The exempt-list flows through InVmSmokeOptions because
            // that is its existing configuration home; the builder reads only
            // ExemptAgentsWithoutProbe from it.
            var baselineVerificationCommands = live.MultipassUseBaselineImages
                ? BaselineVerificationProbeBuilder.Build(
                    live,
                    projects,
                    sp.GetServices<IInVmSmokeProbe>(),
                    sp.GetService<InVmSmokeOptions>())
                : Array.Empty<BaselineVerificationCommand>();
            var pluginContributions = ResolvePluginBaselineContributions(
                sp, startupLog, baselineVerificationCommands.Count, providerKind: "multipass");
            return new MultipassSandboxOptions
            {
                ExtraCloudInit = live.MultipassExtraCloudInit,
                ExtraRuncmd = AppendPluginInstallCommands(live.MultipassExtraRuncmd, pluginContributions),
                BaselineVerificationCommands = AppendPluginVerificationCommands(
                    baselineVerificationCommands, pluginContributions),
                NetworkProfiles = live.SandboxNetworkProfiles,
                UseBaselineImages = live.MultipassUseBaselineImages,
                CloudInitReadyRetryAttempts = multipassSandbox.CloudInitReadyRetryAttempts,
                VmStartTimeout = multipassSandbox.VmStartTimeout,
                VmStopTimeout = multipassSandbox.VmStopTimeout,
                MaxConcurrentBoots = multipassSandbox.MaxConcurrentBoots,
                BootLaunchDelay = TimeSpan.FromMilliseconds(multipassSandbox.BootLaunchDelayMs),
                DisableAgentOutputHttpIngest = multipassSandbox.DisableAgentOutputHttpIngest,
                CaptureResourceMetrics = multipassSandbox.CaptureResourceMetrics,
                ResourceMetricsCaptureTimeout = multipassSandbox.ResourceMetricsCaptureTimeoutSeconds > 0
                    ? TimeSpan.FromSeconds(multipassSandbox.ResourceMetricsCaptureTimeoutSeconds)
                    : MultipassSandboxOptions.DefaultResourceMetricsCaptureTimeout,
                DiskGuard = diskGuard,
                PackageCacheSeeds = BaselineProvisioningConfigSnapshot.SnapshotPackageCacheSeeds(
                    live.MultipassPackageCacheSeeds,
                    "CodeyBox:MultipassPackageCacheSeeds"),
                ExecutableProvisions = BaselineProvisioningConfigSnapshot.SnapshotExecutableProvisions(
                    live.MultipassExecutableProvisions,
                    "CodeyBox:MultipassExecutableProvisions"),
            };
        };
    // Construction lives in the shared factory; option shaping (disk guard,
    // plugins, hot-reload delegate) stays here.
    var provider = SharedSandboxProviderFactory.Build(
        SandboxProviderKinds.Multipass,
        new SandboxProviderBuildArgs
        {
            Loggers = loggerFactory,
            MultipassOptions = optionsAccessor,
            Timings = timings,
            ResourceUsage = resourceUsageStore,
            ArtifactTrust = () => sp.GetRequiredService<IOptionsMonitor<ArtifactTrustOptions>>().CurrentValue,
            ArtifactAdmission = sp.GetService<ArtifactAdmissionService>(),
        });

    // Startup banner: log free disk for each guarded path so the operator
    // can see at a glance whether the host is close to the threshold. Mirrors
    // the existing baseline-image banner pattern. Speaks to the capability
    // interface so this code does not depend on the concrete provider type.
    if (diskGuard is not null && provider is IDiskGuardedSandboxProvider guarded)
    {
        LogDiskGuardBanner(guarded, startupLog);
    }

    return provider;
}

static ISandboxProvider BuildMultipassRemote(IServiceProvider sp, ILoggerFactory loggerFactory)
    => BuildMultipassRemoteFromConfig(
        sp,
        loggerFactory,
        live => live.MultipassRemoteSandbox);

static ISandboxProvider BuildE2eMultipassRemote(IServiceProvider sp, ILoggerFactory loggerFactory, int hostIndex)
    => BuildMultipassRemoteFromConfig(
        sp,
        loggerFactory,
        live =>
        {
            var hosts = GetE2eRemoteHostConfigs(live);
            return hostIndex >= 0 && hostIndex < hosts.Count ? hosts[hostIndex].RemoteSandbox : null;
        });

static ISandboxProvider BuildMultipassRemoteFromConfig(
    IServiceProvider sp,
    ILoggerFactory loggerFactory,
    Func<CodeyBoxOptions, MultipassRemoteSandboxConfig?> configSelector)
{
    // All options resolved through IOptionsMonitor so SSH endpoint, key path,
    // staging dir, host-pool membership, and timeouts hot-reload on the next
    // CreateAsync without an orchestrator restart. Construction lives in the
    // shared factory; the transport wiring stays here.
    return SharedSandboxProviderFactory.Build(
        SandboxProviderKinds.MultipassRemote,
        new SandboxProviderBuildArgs
        {
            Loggers = loggerFactory,
            MultipassRemoteOptions = () => ReadRemoteOpts(sp, configSelector),
            ProcessRunner = sp.GetService<IProcessRunner>(),
        });

    static MultipassRemoteSandboxOptions ReadRemoteOpts(
        IServiceProvider sp,
        Func<CodeyBoxOptions, MultipassRemoteSandboxConfig?> configSelector)
    {
        var live = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue;
        return MultipassRemoteOptionsMapper.Map(configSelector(live), live.SandboxNetworkProfiles);
    }
}

static ISandboxProvider BuildSprites(IServiceProvider sp, ILoggerFactory loggerFactory, ILogger startupLog)
{
    startupLog.LogInformation(
        "Using sprites.dev sandbox provider; host mounts are staged through the Sprites API.");
    Func<SpritesSandboxOptions> optionsAccessor =
        () =>
        {
            var live = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue;
            var cfg = live.Sprites ?? new SpritesSandboxConfig();
            var defaults = new SpritesSandboxOptions();
            return new SpritesSandboxOptions
            {
                ApiBaseUrl = !string.IsNullOrWhiteSpace(cfg.ApiBaseUrl) ? cfg.ApiBaseUrl : defaults.ApiBaseUrl,
                TokenEnvironmentVariable = !string.IsNullOrWhiteSpace(cfg.TokenEnvironmentVariable)
                    ? cfg.TokenEnvironmentVariable
                    : defaults.TokenEnvironmentVariable,
                NamePrefix = !string.IsNullOrWhiteSpace(cfg.NamePrefix) ? cfg.NamePrefix : defaults.NamePrefix,
                WaitForCapacity = cfg.WaitForCapacity,
                UrlAuth = !string.IsNullOrWhiteSpace(cfg.UrlAuth) ? cfg.UrlAuth : defaults.UrlAuth,
                MaxListPages = cfg.MaxListPages > 0 ? cfg.MaxListPages : defaults.MaxListPages,
                AllowUnsafeHttp = cfg.AllowUnsafeHttp,
                AllowPersistentTmpfsDowngrade = cfg.AllowPersistentTmpfsDowngrade,
                SetupCommands = cfg.SetupCommands ?? defaults.SetupCommands,
                NetworkProfiles = CopySpritesNetworkProfiles(cfg.NetworkProfiles),
                MaxSyncArchiveBase64Bytes = cfg.MaxSyncArchiveBase64Bytes > 0
                    ? cfg.MaxSyncArchiveBase64Bytes
                    : defaults.MaxSyncArchiveBase64Bytes,
                MaxSyncArchiveBytes = cfg.MaxSyncArchiveBytes > 0
                    ? cfg.MaxSyncArchiveBytes
                    : defaults.MaxSyncArchiveBytes,
                MaxSyncArchiveExpandedBytes = cfg.MaxSyncArchiveExpandedBytes > 0
                    ? cfg.MaxSyncArchiveExpandedBytes
                    : defaults.MaxSyncArchiveExpandedBytes,
                MaxSyncArchiveEntries = cfg.MaxSyncArchiveEntries > 0
                    ? cfg.MaxSyncArchiveEntries
                    : defaults.MaxSyncArchiveEntries,
                MaxFileSyncBase64Bytes = cfg.MaxFileSyncBase64Bytes > 0
                    ? cfg.MaxFileSyncBase64Bytes
                    : defaults.MaxFileSyncBase64Bytes,
                MaxFileSyncBytes = cfg.MaxFileSyncBytes > 0
                    ? cfg.MaxFileSyncBytes
                    : defaults.MaxFileSyncBytes,
                DefaultCpuCount = cfg.DefaultCpuCount,
                DefaultMemoryBytes = cfg.DefaultMemoryBytes,
                Region = cfg.Region,
            };
        };
    // Construction lives in the shared factory; option shaping stays here.
    return SharedSandboxProviderFactory.Build(
        SandboxProviderKinds.Sprites,
        new SandboxProviderBuildArgs
        {
            Loggers = loggerFactory,
            SpritesOptions = optionsAccessor,
        });

    static Dictionary<string, List<string>> CopySpritesNetworkProfiles(Dictionary<string, List<string>>? source)
    {
        var result = new Dictionary<string, List<string>>(StringComparer.OrdinalIgnoreCase);
        if (source is null)
            return result;

        foreach (var (name, hosts) in source)
            result[name] = hosts?.ToList() ?? [];
        return result;
    }
}

static void LogDiskGuardBanner(IDiskGuardedSandboxProvider provider, ILogger startupLog)
{
    foreach (var sample in provider.SampleDiskGuardState())
    {
        var freeRendered = sample.FreeBytes is long b ? FormatBytes(b) : "(unknown)";
        startupLog.LogInformation(
            "Disk-guard: {Path} free={FreeBytes} threshold={Threshold}",
            sample.Path, freeRendered, FormatBytes(sample.ThresholdBytes));
    }
}

static string FormatBytes(long bytes)
{
    const double gib = 1024d * 1024 * 1024;
    const double mib = 1024d * 1024;
    if (bytes >= gib) return $"{bytes / gib:F2} GiB";
    if (bytes >= mib) return $"{bytes / mib:F2} MiB";
    return $"{bytes:N0} B";
}

// --- Git host ----------------------------------------------------------------
builder.Services.AddSingleton<LocalGitHost>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new LocalGitHost(
        new LocalGitHostOptions
        {
            RootDirectory = opts.GitRootDirectory,
            GitCommandMaxOutputBytes = opts.GitCommandMaxOutputBytes,
            EnableSharedUpstreamMirror = opts.EnableSharedUpstreamMirror,
            SharedUpstreamMirrorDirectory = opts.SharedUpstreamMirrorDirectory
        },
        sp.GetRequiredService<ILogger<LocalGitHost>>());
});
builder.Services.AddSingleton<IGitHost>(sp => sp.GetRequiredService<LocalGitHost>());

// --- Pre-merge CI gate verifier -----------------------------------------------
// LocalGitPreMergeVerifier materialises the orchestrator's merge result into
// a worktree on the host bare repo and runs the operator-configured
// PreMergeVerifyArgv against it before the forge auto-merge API call. The
// gate stays opt-in: the orchestrator skips the verifier when the project's
// PreMergeVerifyArgv is empty, so projects that have not configured the gate
// see no behaviour change. Test argv runs Audit:Flake:AdmissionReruns times
// (default 3) so flaky tests block the merge; the count is read live from
// IOptionsMonitor on every verification (hot-reload, no restart).
builder.Services.AddSingleton<IPreMergeVerifier>(sp =>
{
    var flakeMonitor = sp.GetRequiredService<IOptionsMonitor<AuditSectionOptions>>();
    return new LocalGitPreMergeVerifier(
        sp.GetRequiredService<IGitHost>(),
        sp.GetRequiredService<ILogger<LocalGitPreMergeVerifier>>(),
        admissionRerunsProvider: () => flakeMonitor.CurrentValue.Flake.AdmissionReruns);
});
builder.Services.AddSingleton<IRequiredBuildVerifier>(sp => new SandboxRequiredBuildVerifier(
    sp.GetRequiredService<ISandboxProvider>(),
    sp.GetRequiredService<IGitHost>(),
    sp.GetRequiredService<PipelineOptions>(),
    sp.GetRequiredService<ILogger<SandboxRequiredBuildVerifier>>(),
    () => sp.GetRequiredService<IOptionsMonitor<MSBuildDiagnosticsOptions>>().CurrentValue,
    sp.GetServices<IBuildDiagnosticsProducer>().FirstOrDefault(static p => p.ProviderId == MSBuildDiagnosticsOptions.ProviderId)));

// --- Pull request service (in-memory by default) -----------------------------
builder.Services.AddSingleton<IPullRequestService, InMemoryPullRequestService>();

// Plugin discovery result captured before builder.Build() so the shared
// agent-execution composition below can reference the list lazily without any
// async blocking. Populated by AddCodeyBoxPlugins (called in the
// plugin-foundation section near the end of service registration).
IReadOnlyList<LoadedPlugin>? preDiscoveredPlugins = null;

// --- Agent execution ---------------------------------------------------------
// Runners, registry, credentials and stream capture compose once in
// CodeyBox.Orchestrator.AgentExecutionComposition.AddAgentExecution — the single
// catalog both the API host and the executor host call. Adding an agent edits
// that catalog, never this file. Credential plugins resolve lazily through the
// list AddCodeyBoxPlugins populates below before Build.
builder.Services.AddAgentExecution(
    builder.Configuration,
    composition => composition.PluginsProvider = () => preDiscoveredPlugins ?? []);

// Seeded fake-agent run mode for the admin E2E/demo instance (see
// docs/concepts/admin-e2e.md). Opt-in via CodeyBox:SeededFakeAgents:Enabled;
// when disabled nothing here registers and production routing is untouched.
builder.Services.AddOptions<SeededFakeAgentOptions>()
    .Bind(builder.Configuration.GetSection(SeededFakeServiceExtensions.ConfigSectionPath));
if (builder.Configuration.GetValue<bool>(
    $"{SeededFakeServiceExtensions.ConfigSectionPath}:Enabled"))
{
    builder.Services.AddSeededFakeAgents();
}
builder.Services.AddOptions<AgentPromptPreprocessingOptions>()
    .Bind(builder.Configuration.GetSection("CodeyBox:PromptPreprocessing"));
builder.Services.AddSingleton<IAgentPromptPreprocessor, ProjectRulesPromptPreprocessor>();
// Attachment delivery: for the configured delivery phases (default work /
// rework / audit) the preprocessor stages a work item's attachment blobs into
// the sandbox and injects an ATTACHMENTS manifest so the agent knows they exist
// and where to read them. The source maps stored metadata to collision-free
// in-VM paths; the blob store supplies the host-side bytes. Both are optional so
// the preprocessor stays a no-op when attachments are not wired.
builder.Services.AddSingleton<IWorkItemAttachmentSource, StoreWorkItemAttachmentSource>();
builder.Services.AddSingleton<IAgentPromptPreprocessor>(sp =>
    new AttachmentManifestPromptPreprocessor(
        sp.GetRequiredService<ILogger<AttachmentManifestPromptPreprocessor>>(),
        sp.GetService<IWorkItemAttachmentSource>(),
        sp.GetService<IWorkItemAttachmentBlobStore>(),
        () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.Attachments));
// Cross-agent handoff brief injection: fires only when the involvement store
// shows a prior phase ran under a different AgentKind. Gated end-to-end by
// CodeyBox:PipelineTuning:EnableHandoffSeeding (default off) — the builder
builder.Services.AddSingleton<ICrossAgentHandoffBriefBuilder, AgentStreamBriefBuilder>();
builder.Services.AddSingleton<IAgentPromptPreprocessor, CrossAgentHandoffPromptPreprocessor>();
builder.Services.AddSingleton<ConvergenceBriefComposer>(sp =>
    new ConvergenceBriefComposer(
        sp.GetRequiredService<IWorkItemStore>(),
        sp.GetRequiredService<IAuditProgressStore>(),
        sp.GetRequiredService<IAuditReportStore>(),
        sp.GetRequiredService<IFailureEventStore>(),
        sp.GetRequiredService<IAgentInvolvementStore>(),
        sp.GetRequiredService<IAgentFallbackHistoryStore>(),
        sp.GetRequiredService<IAgentStreamSummaryStore>(),
        sp.GetService<IAgentStreamStore>(),
        () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.ConvergenceBrief,
        sp.GetService<ILogger<ConvergenceBriefComposer>>()));

// --- Knob framework ----------------------------------------------------------
// Add a new tuning knob by registering its IKnob implementation here — the
// registry exposes it to the API for set/validate and the work-prompt
// preprocessor picks up its fragment without further edits.
builder.Services.AddSingleton<IKnob, CodeyBox.Orchestrator.Knobs.ChangeScopeKnob>();
builder.Services.AddSingleton<IKnob, CodeyBox.Orchestrator.Knobs.PlanKnob>();
builder.Services.AddSingleton<IKnobRegistry, KnobRegistry>();
builder.Services.AddSingleton<IMergeScopeResolver, CodeyBox.Orchestrator.Knobs.ChangeScopeMergeScopeResolver>();
builder.Services.AddSingleton<IAgentPromptPreprocessor, CodeyBox.Orchestrator.Knobs.KnobWorkPromptPreprocessor>();

builder.Services.AddSingleton<AgentPromptPreprocessorChain>();

// ClaudeSessionWorker — resumable Claude runner. Registered alongside (NOT
// instead of) the one-shot ClaudeAgentRunner so the default dispatch path is
// unchanged; config-gated opt-in callers resolve the concrete type to drive
// multi-turn sessions across a stop/resume-able VM. The options snapshot is a
// singleton so a hot reload can flip Enabled mid-process without restart.
// Mutable singleton so the IOptionsMonitor.OnChange handler below can flip
// Transport / Enabled / EmitTurnMetrics in place; the worker reads the live
// value on every turn so the flip applies to the NEXT dispatch.
builder.Services.AddSingleton<CodeyBox.Agents.Claude.ClaudeSessionWorkerOptions>(sp =>
{
    var monitor = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>();
    var live = new CodeyBox.Agents.Claude.ClaudeSessionWorkerOptions();
    ClaudeSessionOptionsBinder.Apply(live, monitor.CurrentValue.ClaudeSession);
    monitor.OnChange(opts => ClaudeSessionOptionsBinder.Apply(live, opts.ClaudeSession));
    return live;
});
// Orchestration-side dispatch gate. PipelineRunner takes a provider-agnostic
// AgentSessionDispatchOptions so the orchestration boundary doesn't depend on
// any per-provider options shape; the composition root maps the per-provider
// Enabled flag into the orchestrator-owned options and forwards hot-reload
// changes through the same OnChange handler that drives the worker options.
builder.Services.AddSingleton<CodeyBox.Orchestrator.AgentSessionDispatchOptions>(sp =>
{
    var monitor = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>();
    var dispatch = new CodeyBox.Orchestrator.AgentSessionDispatchOptions();
    AgentSessionDispatchOptionsBinder.Apply(dispatch, monitor.CurrentValue.ClaudeSession);
    monitor.OnChange(opts => AgentSessionDispatchOptionsBinder.Apply(dispatch, opts.ClaudeSession));
    return dispatch;
});
// Default metrics sink is the no-op; operators wire a logging/metrics-backed
// sink by registering their own IClaudeSessionMetricsSink before this line.
builder.Services.TryAddSingleton<CodeyBox.Agents.Claude.IClaudeSessionMetricsSink>(
    CodeyBox.Agents.Claude.NullClaudeSessionMetricsSink.Instance);
// ACP transport. Always registered so the operator can flip
// CodeyBox:ClaudeSession:Transport=acp at runtime; the worker only opens an
// ACP transport when the resolved config asks for it.
builder.Services.AddSingleton<CodeyBox.Agents.Claude.AcpClaudeTransport>(sp =>
    new CodeyBox.Agents.Claude.AcpClaudeTransport(
        sp.GetRequiredService<CodeyBox.Core.AgentNetworkToleranceSnapshot>()));
builder.Services.AddSingleton<CodeyBox.Agents.Claude.ClaudeSessionWorker>(sp =>
{
    var runner = sp.GetServices<IAgentRunner>()
        .OfType<ClaudeAgentRunner>()
        .First();

    // Provider identity is persisted with the sandbox reference so a live
    // selector change cannot redirect an existing session to another backend.
    var provider = sp.GetService<ISandboxProvider>();
    Func<AgentSessionSandboxRef, CancellationToken, Task>? resumeHook = null;
    if (provider is ISuspendingSandboxProvider suspending)
    {
        resumeHook = (sandboxRef, ct) => AgentSessionSandboxRouting.ResumeAsync(
            suspending,
            // Provider-less durable references predate the Incus provider and
            // were written when Multipass was the only resumable backend.
            AgentSessionSandboxRouting.AddProviderScopeIfMissing(
                sandboxRef,
                SandboxProviderKinds.Multipass),
            ct);
    }

    return new CodeyBox.Agents.Claude.ClaudeSessionWorker(
        runner,
        sandboxReattacher: null,
        sandboxResumeHook: resumeHook,
        credentialProvider: sp.GetService<ICredentialProvider>(),
        sandboxRefFactory: AgentSessionSandboxRouting.CreateReference,
        metricsSink: sp.GetRequiredService<CodeyBox.Agents.Claude.IClaudeSessionMetricsSink>(),
        options: sp.GetRequiredService<CodeyBox.Agents.Claude.ClaudeSessionWorkerOptions>(),
        acpTransport: sp.GetRequiredService<CodeyBox.Agents.Claude.AcpClaudeTransport>(),
        printTransport: null,
        onTransportDegraded: (sessionId, reason) =>
            AuditLog.ClaudeAcpTransportDegraded(sessionId, reason));
});


// --- HTTP clients ------------------------------------------------------------
// Named client for GitHub upstream. GitHub requires a User-Agent header.
// Authorization is added per-request in GitHubUpstreamRemote (per-project PAT).
builder.Services.AddHttpClient("github-upstream", client =>
{
    client.DefaultRequestHeaders.UserAgent.ParseAdd("codeybox");
    // Shorter timeout than the 100 s .NET default: bounds the stall window per
    // attempt given the orchestrator retries up to UpstreamPushMaxAttempts times.
    client.Timeout = TimeSpan.FromSeconds(30);
});

// Named client for quota probes. Short timeout — quota probes are on the hot
// path and must not stall the worker pickup loop. Authorization is added per-
// request; headers are never logged (see SensitiveDataRedactionEnricher).
builder.Services.AddHttpClient("agent-quota", client =>
{
    client.Timeout = TimeSpan.FromSeconds(10);
}).ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler { AllowAutoRedirect = false });

builder.Services.AddHttpClient("check-completion", client =>
{
    client.Timeout = TimeSpan.FromSeconds(60);
}).ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler { AllowAutoRedirect = false });

// Named client for credential smoke probes. Authorization is added per-request
// from the credential bundle; the header is never logged. Timeout is generous
// (15 s) since the probe runs at most once per credential fingerprint per TTL.
builder.Services.AddHttpClient("agent-smoke", client =>
{
    client.Timeout = TimeSpan.FromSeconds(15);
}).ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler { AllowAutoRedirect = false });

// Named client for the startup model-list probes used by AgentClassConfigValidator.
// Authorization is added per-request; headers are never logged. Per-call timeout is
// shorter than the validator's overall 10 s deadline so a slow provider can't soak
// the entire budget on a single probe.
builder.Services.AddHttpClient("agent-modellist", client =>
{
    client.Timeout = TimeSpan.FromSeconds(5);
}).ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler { AllowAutoRedirect = false });

// --- Quota probes ------------------------------------------------------------
// Registered as IEnumerable<IAgentQuotaProbe>; the router resolves by Kind.
// OAuth files are reread by the provider delegate on each probe pickup because
// local agent CLIs refresh those files in place. Probe results are still cached
// per token by the probe implementations.
builder.Services.AddSingleton<QuotaRouterOptions>(sp =>
{
    var cbOpts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return QuotaRouterConfigMapper.ToOptions(cbOpts.QuotaRouter);
});
builder.Services.AddSingleton<QuotaGatePolicy>(sp =>
    new QuotaGatePolicy(sp.GetRequiredService<QuotaRouterOptions>()));
builder.Services.AddSingleton<IAgentQuotaGate>(sp => new QuotaGateAvailability(
    sp.GetRequiredService<QuotaGatePolicy>(),
    sp.GetService<IQuotaFailureStore>(),
    sp.GetRequiredService<QuotaRouterOptions>().ObservedFailureWindow,
    sp.GetService<IAgentBurnEstimator>(),
    sp.GetRequiredService<ILogger<QuotaGateAvailability>>()));
builder.Services.AddSingleton<IQuotaFailureStore>(sp =>
{
    var cbOpts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteQuotaFailureStore(
        cbOpts.StateDatabasePath,
        sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
builder.Services.AddSingleton<AgentQuotaAvailabilityBroadcaster>();
builder.Services.AddSingleton<IAgentQuotaAvailabilityPublisher>(sp =>
    sp.GetRequiredService<AgentQuotaAvailabilityBroadcaster>());
builder.Services.AddSingleton<IAgentQuotaAvailabilityObservationSource>(sp =>
    sp.GetRequiredService<AgentQuotaAvailabilityBroadcaster>());
builder.Services.AddSingleton<IAgentFallbackHistoryStore>(sp =>
{
    var cbOpts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteAgentFallbackHistoryStore(
        cbOpts.StateDatabasePath,
        sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
builder.Services.AddSingleton<IAgentInvolvementStore>(sp =>
{
    var cbOpts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteAgentInvolvementStore(
        cbOpts.StateDatabasePath,
        sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
// OAuth-refreshing quota-token sources. These wrap the raw credential file
// sources with provider-specific refresh logic so an expired access_token is
// re-minted via the provider's OAuth refresh endpoint before the probe sends
// it. Without this, an expired token would 401, the snapshot would become
// AvailablePct=-1, and dispatch would risk landing on an agent that
// immediately 429s (refused outright while a reserve floor is in force, or
// admitted by the router's default UnknownPolicy=UseObservedFailures when no
// floor applies). See
// CodeyBox.Agents/OauthCredentialFileRefresher.cs for the provider-neutral
// refresh contracts; each concrete refresher lives in its own
// CodeyBox.Agents.* project.
builder.Services.AddSingleton<IClaudeQuotaTokenSource>(sp => new ClaudeOauthCredentialFileRefresher(
    sp.GetRequiredService<ClaudeCredentialFileSource>(),
    sp.GetRequiredService<IHttpClientFactory>(),
    sp.GetRequiredService<ILoggerFactory>().CreateLogger<ClaudeOauthCredentialFileRefresher>()));
builder.Services.AddSingleton<ICodexQuotaTokenSource>(sp => new CodexOauthCredentialFileRefresher(
    sp.GetRequiredService<CodexCredentialFileSource>(),
    sp.GetRequiredService<IHttpClientFactory>(),
    sp.GetRequiredService<ILoggerFactory>().CreateLogger<CodexOauthCredentialFileRefresher>()));
builder.Services.AddSingleton<IGeminiQuotaTokenSource>(sp =>
{
    var config = sp.GetRequiredService<IConfiguration>();
    return new GeminiOauthCredentialFileRefresher(
        sp.GetRequiredService<GeminiOAuthCredentialFileSource>(),
        sp.GetRequiredService<IHttpClientFactory>(),
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<GeminiOauthCredentialFileRefresher>(),
        geminiOauthClientId: Environment.GetEnvironmentVariable("CODEYBOX_GEMINI_OAUTH_CLIENT_ID")
            ?? config["CodeyBox:GeminiOauthClientId"],
        geminiOauthClientSecret: Environment.GetEnvironmentVariable("CODEYBOX_GEMINI_OAUTH_CLIENT_SECRET")
            ?? config["CodeyBox:GeminiOauthClientSecret"],
        cliTokenRefresher: GeminiOauthCredentialFileRefresher.TryCreateCliRefreshHandler());
});
builder.Services.AddSingleton<IAntigravityQuotaTokenSource>(sp =>
{
    var loggerFactory = sp.GetRequiredService<ILoggerFactory>();
    // Platform-guarded keyring access: the Secret Service reader only exists
    // on Linux. Anywhere else the refresher keeps the last on-disk token and
    // the startup warning below says so explicitly instead of degrading
    // silently. Runs once (singleton) and is forced at startup — see the
    // eager resolution after app.Build().
    var keyringReader = SecretServiceKeyringReader.TryCreate(
        log: loggerFactory.CreateLogger<SecretServiceKeyringReader>());
    AntigravityKeyringStartup.LogKeyringStatus(
        loggerFactory.CreateLogger("CodeyBox.Antigravity"),
        keyringReader);
    return new AntigravityOauthCredentialFileRefresher(
        sp.GetRequiredService<AntigravityCredentialFileSource>(),
        sp.GetRequiredService<IHttpClientFactory>(),
        loggerFactory.CreateLogger<AntigravityOauthCredentialFileRefresher>(),
        cliRunner: AntigravityOauthCredentialFileRefresher.TryCreateCliRefreshHandler(),
        keyringReader: keyringReader is null ? null : AntigravityKeyring.ToRefreshDelegate(keyringReader));
});

// Every quota probe is wrapped so paused members use a longer polling cadence,
// then transient blips serve the most recent real reading (bounded by the
// active or paused staleness ceiling plus the reading's own reset). Discard-on-
// Permanent/NoCredential is driven by the probe's QuotaUnknownReason.
static IAgentQuotaProbe WrapQuotaProbe(IAgentQuotaProbe inner, IServiceProvider sp)
{
    var monitor = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>();
    var lf = sp.GetRequiredService<ILoggerFactory>();
    var routerOptions = sp.GetRequiredService<QuotaRouterOptions>();
    var pauses = sp.GetRequiredService<IAgentPauseController>();
    var timeProvider = sp.GetService<TimeProvider>();
    var paused = new PausedAgentQuotaProbe(
        inner,
        pauses,
        () => new PausedAgentQuotaProbeOptions
        {
            CacheTtl = routerOptions.PausedQuotaCacheTtl,
            MaxCacheEntries = routerOptions.PausedQuotaMaxCacheEntries,
        },
        lf.CreateLogger<PausedAgentQuotaProbe>(),
        timeProvider);
    return new LastKnownGoodQuotaProbe(
        paused,
        (member, ct) => BuildLastKnownGoodQuotaOptionsAsync(member, ct, pauses, monitor, routerOptions),
        lf.CreateLogger<LastKnownGoodQuotaProbe>(),
        timeProvider);
}

static async ValueTask<LastKnownGoodQuotaOptions> BuildLastKnownGoodQuotaOptionsAsync(
    AgentMembership member,
    CancellationToken ct,
    IAgentPauseController pauses,
    IOptionsMonitor<CodeyBoxOptions> monitor,
    QuotaRouterOptions routerOptions)
{
    var pause = await pauses.GetAgentStateAsync(member.Agent, ct, member.InstanceId)
        .ConfigureAwait(false);
    var maxStaleness = pause is null
        ? TimeSpan.FromSeconds(monitor.CurrentValue.QuotaRouter.ProbeMaxStalenessSeconds)
        : routerOptions.PausedProbeMaxStaleness;
    return new LastKnownGoodQuotaOptions { MaxStaleness = maxStaleness };
}

static ClaudeQuotaProbeResilienceOptions BuildClaudeQuotaProbeResilienceOptions(
    IOptionsMonitor<CodeyBoxOptions> optionsMonitor)
{
    var qr = optionsMonitor.CurrentValue.QuotaRouter;
    return new ClaudeQuotaProbeResilienceOptions
    {
        MaxRetries = qr.ProbeMaxRetries,
        RetryInitialDelay = TimeSpan.FromMilliseconds(qr.ProbeRetryInitialDelayMs),
        MaxRetryDelay = TimeSpan.FromSeconds(qr.ProbeRetryMaxDelaySeconds),
        MaxConsecutiveFailures = qr.ProbeMaxConsecutiveFailures,
        MaxStaleness = TimeSpan.FromSeconds(qr.ProbeMaxStalenessSeconds),
    };
}

// A credential-source token update invalidates the credential-scoped quota
// state (retained last-known-good + provider response cache) so a rotated
// token is never gated by the prior credential's learned quota.
static IAgentQuotaProbe WireQuotaProbeTokenInvalidation(
    IAgentQuotaProbe probe,
    CredentialFileSource source)
{
    if (probe is IAgentQuotaCacheInvalidator invalidator)
        source.TokenUpdated += invalidator.InvalidateCredentialState;
    return probe;
}

builder.Services.AddSingleton<IAgentQuotaProbe>(sp =>
{
    var loggerFactory = sp.GetRequiredService<ILoggerFactory>();
    var source = sp.GetRequiredService<ClaudeCredentialFileSource>();
    var tokenSource = sp.GetRequiredService<IClaudeQuotaTokenSource>();
    var optionsMonitor = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>();
    var probe = new ClaudeQuotaProbe(
        sp.GetRequiredService<IHttpClientFactory>(),
        // Sync-over-async is intentional and safe here: ASP.NET Core has no
        // SynchronizationContext (no deadlock potential), the cache hit-path
        // is fully synchronous, and only a stale-token miss blocks the thread
        // on the OAuth refresh round-trip (bounded by the agent-quota client's
        // 10s timeout).
        member => AgentInstanceCredentialResolver.ResolveQuotaCredentials(
            member,
            () => new AgentQuotaCredentials(
                tokenSource.GetAccessTokenAsync(CancellationToken.None).ConfigureAwait(false).GetAwaiter().GetResult()
                    ?? Environment.GetEnvironmentVariable("CODEYBOX_CLAUDE_API_KEY")))
            ?? new AgentQuotaCredentials(null),
        sp.GetRequiredService<QuotaRouterOptions>().QuotaCacheTtl,
        loggerFactory.CreateLogger<ClaudeQuotaProbe>(),
        // Resilience knobs are read on every probe call so values bound from
        // CodeyBox:QuotaRouter hot-reload through IOptionsMonitor without
        // restarting the process.
        resilienceProvider: () => BuildClaudeQuotaProbeResilienceOptions(optionsMonitor),
        timeProvider: sp.GetService<TimeProvider>());
    return WireQuotaProbeTokenInvalidation(WrapQuotaProbe(probe, sp), source);
});
builder.Services.AddSingleton<IAgentQuotaProbe>(sp =>
{
    var loggerFactory = sp.GetRequiredService<ILoggerFactory>();
    var source = sp.GetRequiredService<CodexCredentialFileSource>();
    var tokenSource = sp.GetRequiredService<ICodexQuotaTokenSource>();
    var probe = new CodexQuotaProbe(
        sp.GetRequiredService<IHttpClientFactory>(),
        member => AgentInstanceCredentialResolver.ResolveQuotaCredentials(
            member,
            () =>
        {
            var codexAuth = tokenSource.GetTokensAsync(CancellationToken.None).ConfigureAwait(false).GetAwaiter().GetResult();
            return new AgentQuotaCredentials(
                codexAuth.AccessToken ?? Environment.GetEnvironmentVariable("CODEYBOX_CODEX_API_KEY"),
                codexAuth.AccountId ?? Environment.GetEnvironmentVariable("CODEYBOX_CODEX_ACCOUNT_ID"));
        }) ?? new AgentQuotaCredentials(null),
        sp.GetRequiredService<QuotaRouterOptions>().QuotaCacheTtl,
        loggerFactory.CreateLogger<CodexQuotaProbe>(),
        // Config-sourced routed-default model: lets the subscription-bucket alias
        // target follow CodeyBox:AgentDefaults[codex] instead of a source literal.
        sp.GetRequiredService<AgentDefaultsSnapshot>());
    return WireQuotaProbeTokenInvalidation(WrapQuotaProbe(probe, sp), source);
});
// Gemini OAuth-subscription path (Code Assist Individual / AI Pro / AI Ultra).
// API-key (PayPerApi) and Vertex paths have no analogous endpoint and stay
// PayPerApi members in the agent class config — for those the router treats
// a missing probe result as unlimited.
builder.Services.AddSingleton<IAgentQuotaProbe>(sp =>
{
    var loggerFactory = sp.GetRequiredService<ILoggerFactory>();
    var source = sp.GetRequiredService<GeminiOAuthCredentialFileSource>();
    var tokenSource = sp.GetRequiredService<IGeminiQuotaTokenSource>();
    var probe = new GeminiQuotaProbe(
        sp.GetRequiredService<IHttpClientFactory>(),
        member => AgentInstanceCredentialResolver.ResolveQuotaCredentials(
            member,
            () => new AgentQuotaCredentials(
                tokenSource.GetAccessTokenAsync(CancellationToken.None).ConfigureAwait(false).GetAwaiter().GetResult()
                    ?? Environment.GetEnvironmentVariable("CODEYBOX_GEMINI_OAUTH_TOKEN")))
            ?? new AgentQuotaCredentials(null),
        sp.GetRequiredService<QuotaRouterOptions>().QuotaCacheTtl,
        loggerFactory.CreateLogger<GeminiQuotaProbe>());
    return WireQuotaProbeTokenInvalidation(WrapQuotaProbe(probe, sp), source);
});
builder.Services.AddSingleton<IAgentQuotaProbe>(sp =>
{
    var loggerFactory = sp.GetRequiredService<ILoggerFactory>();
    var source = sp.GetRequiredService<CursorCredentialFileSource>();
    var probe = new CursorQuotaProbe(
        sp.GetRequiredService<IHttpClientFactory>(),
        member => AgentInstanceCredentialResolver.ResolveQuotaCredentials(
            member,
            () => new AgentQuotaCredentials(
                CredentialFileTokenExtractor.ExtractCursorAccessToken(source.GetRaw())
                    ?? CredentialFileTokenExtractor.ExtractCursorAccessToken(
                        Environment.GetEnvironmentVariable("CODEYBOX_CURSOR_AUTH_JSON"))))
            ?? new AgentQuotaCredentials(null),
        sp.GetRequiredService<QuotaRouterOptions>().QuotaCacheTtl,
        loggerFactory.CreateLogger<CursorQuotaProbe>());
    return WireQuotaProbeTokenInvalidation(WrapQuotaProbe(probe, sp), source);
});
builder.Services.AddSingleton<IAgentQuotaProbe>(sp =>
{
    var loggerFactory = sp.GetRequiredService<ILoggerFactory>();
    var source = sp.GetRequiredService<DevinCredentialFileSource>();
    var probe = new DevinQuotaProbe(
        sp.GetRequiredService<IHttpClientFactory>(),
        member => AgentInstanceCredentialResolver.ResolveQuotaCredentials(
            member,
            () =>
            {
                var (apiKey, apiServerUrl) = CredentialFileTokenExtractor.ExtractDevinCredentials(
                    source.GetRaw()
                        ?? Environment.GetEnvironmentVariable("CODEYBOX_DEVIN_AUTH_TOML"));
                return new AgentQuotaCredentials(apiKey, EndpointBaseUrl: apiServerUrl);
            })
            ?? new AgentQuotaCredentials(null),
        sp.GetRequiredService<QuotaRouterOptions>().QuotaCacheTtl,
        loggerFactory.CreateLogger<DevinQuotaProbe>());
    return WireQuotaProbeTokenInvalidation(WrapQuotaProbe(probe, sp), source);
});

// opencode: metered out-of-tree by the codeybox.opencode-go-quota plugin,
// which claims opencode-go members (and zen-backed copilot members) through
// IAgentQuotaProbe.Handles. No in-tree probe is registered here so two probes
// can never claim the same member; without the plugin loaded, opencode
// members fall through to the NullQuotaProbe unknown path exactly as before.
// Crock: pay-per-token Anthropic API key (with ~50% batch discount applied at
// billing time). Anthropic exposes no per-key remaining-credit endpoint, so the
// probe hits the token-free `GET /v1/models` to validate the key and surfaces
// 100% / 0% / Unknown based on the HTTP shape. Spend gating lives in the
// configured AgentBudgetProvider; the router takes MIN(probe, budget).
//
// IMPORTANT: this path uses the configured CrockCode API key only. There is no
// fallback to a subscription OAuth token — calling api.anthropic.com with a
// subscription token would (a) charge against the wrong account and (b)
// surface a different quota meter than the one the dispatch actually rides.
builder.Services.AddSingleton<IAgentQuotaProbe>(sp =>
{
    var loggerFactory = sp.GetRequiredService<ILoggerFactory>();
    var probe = new CrockQuotaProbe(
        sp.GetRequiredService<IHttpClientFactory>(),
        member => AgentInstanceCredentialResolver.ResolveQuotaCredentials(
            member,
            () => new AgentQuotaCredentials(
                CrockQuotaProbe.TryExtractApiKey(
                    Environment.GetEnvironmentVariable("CODEYBOX_CROCK_CONFIG_JSON"))))
            ?? new AgentQuotaCredentials(null),
        sp.GetRequiredService<QuotaRouterOptions>().QuotaCacheTtl,
        loggerFactory.CreateLogger<CrockQuotaProbe>());
    return WrapQuotaProbe(probe, sp);
});
// Antigravity: the agy gateway exposes NO readable per-model quota meter
// (daily-cloudcode-pa :retrieveUserQuota* return 403), so the probe uses
// :loadCodeAssist as a free authorization/tier liveness read (200 ⇒ available)
// and learns per-model exhaustion reactively from runtime 429s. It does NOT
// burn a live :generateContent ping for routine probing. Token sources fall
// back to the Gemini OAuth file since both CLIs use Sign-in-with-Google;
// operators with distinct credentials can override via
// CODEYBOX_ANTIGRAVITY_OAUTH_TOKEN or per-instance CredentialReference.
builder.Services.AddSingleton<IAgentQuotaProbe>(sp =>
{
    var loggerFactory = sp.GetRequiredService<ILoggerFactory>();
    var source = sp.GetRequiredService<GeminiOAuthCredentialFileSource>();
    var antigravitySource = sp.GetRequiredService<AntigravityCredentialFileSource>();
    var tokenSource = sp.GetRequiredService<IAntigravityQuotaTokenSource>();
    var probe = new AntigravityQuotaProbe(
        sp.GetRequiredService<IHttpClientFactory>(),
        member => AgentInstanceCredentialResolver.ResolveQuotaCredentials(
            member,
            () => new AgentQuotaCredentials(
                tokenSource.GetAccessTokenAsync(CancellationToken.None).ConfigureAwait(false).GetAwaiter().GetResult()
                    ?? ReadAntigravityTokenFile(antigravitySource.FilePath)
                    ?? ReadAntigravityTokenFile(
                        sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>()
                            .CurrentValue.Antigravity.OAuthTokenFile)
                    ?? CredentialFileTokenExtractor.ExtractGeminiAccessToken(source.GetRaw())
                    // The agy bundle nests its token ({"token":{"access_token":…}}), so the gemini
                    // extractor — which only reads a flat top-level access_token — always returned
                    // null here. The probe then reported "no token configured", the router treated
                    // that as UNKNOWN, and agy dispatched with no quota gate at all.
                    ?? CredentialFileTokenExtractor.ExtractAntigravityAccessToken(
                        Environment.GetEnvironmentVariable(AntigravityConstants.OAuthCredsEnvVar))
                    ?? Environment.GetEnvironmentVariable("CODEYBOX_ANTIGRAVITY_OAUTH_TOKEN")
                    ?? Environment.GetEnvironmentVariable("CODEYBOX_GEMINI_OAUTH_TOKEN")))
            ?? new AgentQuotaCredentials(null),
        sp.GetRequiredService<QuotaRouterOptions>().QuotaCacheTtl,
        loggerFactory.CreateLogger<AntigravityQuotaProbe>(),
        timeProvider: null,
        quotaUserAgent: sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>()
            .CurrentValue.Antigravity.QuotaUserAgent);
    var wrapped = WrapQuotaProbe(probe, sp);
    source.TokenUpdated += ((IAgentQuotaCacheInvalidator)wrapped).InvalidateCredentialState;
    antigravitySource.TokenUpdated += ((IAgentQuotaCacheInvalidator)wrapped).InvalidateCredentialState;
    return wrapped;
});

// Reads the agy OAuth bundle from disk for the quota probe. Bounded and failure-tolerant: an
// absent, unreadable, oversized or malformed file simply yields null so the caller falls through to
// its other credential sources rather than throwing inside a probe.
static string? ReadAntigravityTokenFile(string? path)
{
    const int MaxTokenFileBytes = 64 * 1024;
    if (string.IsNullOrWhiteSpace(path))
        return null;

    try
    {
        var info = new FileInfo(path);
        if (!info.Exists || info.Length > MaxTokenFileBytes)
            return null;

        return CredentialFileTokenExtractor.ExtractAntigravityAccessToken(File.ReadAllText(path));
    }
    catch (Exception ex) when (ex is IOException or UnauthorizedAccessException or NotSupportedException)
    {
        return null;
    }
}

// --- Agent class router ------------------------------------------------------
builder.Services.AddSingleton<QuotaReservationLedger>(sp =>
    new QuotaReservationLedger(
        sp.GetRequiredService<QuotaRouterOptions>(),
        TimeProvider.System));
builder.Services.AddSingleton<ExecutorQuotaReportStore>(sp =>
    new ExecutorQuotaReportStore(
        sp.GetRequiredService<QuotaRouterOptions>(),
        TimeProvider.System));
builder.Services.AddSingleton<AgentClassRouter>(sp =>
{
    var cbOpts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    var startupLog = sp.GetRequiredService<ILoggerFactory>().CreateLogger("CodeyBox.AgentClasses");

    // Build and validate the catalog. Shared with AgentConfigHotReload so a
    // reload of CodeyBox:AgentClasses runs the same validation rules.
    var catalog = AgentClassesConfigBuilder.Build(cbOpts.AgentClasses, cbOpts.AgentInstances, startupLog, cbOpts.Copilot.Providers);
    var subscriptionMembers = catalog.Sum(c => c.Members.Count(m => m.Billing == AgentBilling.Subscription));
    startupLog.LogInformation("Quota gate enabled for {Count} subscription members", subscriptionMembers);

    // Build and validate time-of-day score modifiers.
    var todModifiers = AgentClassesConfigBuilder.BuildTodModifiers(cbOpts.AgentScoreModifiers, startupLog);
    var inVmSmokeOptions = sp.GetService<InVmSmokeOptions>();
    InVmSmokeSandboxTarget? configuredSmokeTarget =
        string.IsNullOrWhiteSpace(inVmSmokeOptions?.NetworkProfile)
            ? null
            : new InVmSmokeSandboxTarget(inVmSmokeOptions.NetworkProfile, SandboxProfileFlavor.Headless);

    return new AgentClassRouter(
        catalog,
        sp.GetServices<IAgentQuotaProbe>(),
        sp.GetRequiredService<QuotaRouterOptions>(),
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<AgentClassRouter>(),
        TimeProvider.System,
        todModifiers,
        sp.GetService<IQuotaFailureStore>(),
        sp.GetService<IAgentBurnEstimator>(),
        sp.GetService<IAgentRunningCounters>(),
        sp.GetService<IAgentBudgetProvider>(),
        sp.GetService<AgentConcurrencySnapshot>(),
        configuredSmokeTarget,
        sp.GetService<IAgentDispatchAvailability>(),
        sp.GetRequiredService<IAgentQuotaAvailabilityPublisher>(),
        sp.GetService<AgentCircuitBreaker>(),
        sp.GetRequiredService<QuotaReservationLedger>(),
        sp.GetRequiredService<ExecutorQuotaReportStore>());
});

// SandboxClassesSnapshot — validated sandbox class catalog. Built once here
// so a bad CodeyBox:SandboxClasses edit fails the host fast at startup;
// AgentConfigHotReload rebuilds through the same builder on every reload and
// keeps the prior catalog when the new one is rejected. The work-phase
// sandbox acquisition routes through this catalog, and each member's capacity
// owns a per-member admission gate inside SandboxPlacementAcquirer (the
// process-wide ceiling is the derived sum of member capacities).
builder.Services.AddSingleton<SandboxClassesSnapshot>(sp =>
{
    var cbOpts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    var startupLog = sp.GetRequiredService<ILoggerFactory>().CreateLogger("CodeyBox.SandboxClasses");
    var (maxWorkers, maxSandboxes) = OrchestratorOptionsFactory.ResolveSandboxCounts(
        cbOpts.Concurrency, cbOpts.WorkerPool, startupLog);
    var registry = sp.GetRequiredService<ISandboxProviderRegistry>();
    IReadOnlyList<SandboxClass> catalog;
    if (cbOpts.SandboxClasses.Count == 0)
    {
        // No SandboxClasses configured: synthesize the default single-member
        // class from CodeyBox:SandboxProvider so placement has a member to
        // select without requiring new configuration. Single-member behaviour
        // matches the legacy single-provider path: the member's capacity is
        // the resolved WorkerPool:MaxConcurrentSandboxes ceiling, so its
        // admission gate behaves identically to the former process-wide gate.
        // The member carries the provider's own declared capabilities.
        var kind = SandboxProviderSelection.ResolveConfiguredKind(
            cbOpts.SandboxProvider,
            sp.GetRequiredService<IConfiguration>(),
            sp.GetRequiredService<IHostEnvironment>(),
            startupLog);
        var provider = registry.EnsureKind(kind);
        catalog = SandboxClassesDefaultCatalog.Synthesize(kind, provider.DeclaredCapabilities, startupLog, maxSandboxes);
    }
    else
    {
        catalog = SandboxClassesConfigBuilder.Build(
            cbOpts.SandboxClasses, maxWorkers, registry.KnownKinds, startupLog);
    }
    // Warm every configured kind now so a bad provider fails the host fast
    // at startup instead of the first placement.
    foreach (var memberKind in catalog
                 .SelectMany(static c => c.Members)
                 .Select(static m => m.ProviderKind)
                 .Distinct(StringComparer.OrdinalIgnoreCase))
        registry.EnsureKind(memberKind);
    // Derive the constructed kind gates from the catalog: each kind gate
    // becomes the sum of member capacities naming it, so kind gates fit the
    // member gates beneath them instead of clamping them.
    registry.SyncKindCapacities(catalog);
    startupLog.LogInformation("SandboxClasses loaded: {Count} class(es)", catalog.Count);
    return new SandboxClassesSnapshot(catalog);
});

// Placement-driven sandbox acquisition for the pipeline work phase: builds
// requirements from the work item plus the phase's network profile and
// credential, asks the placement decider for a member, and creates the
// sandbox on that member's registry provider. Falls back to the legacy
// single provider only when no class is configured at all (minimal
// embeddings); production always synthesizes the default single-member class
// above. The dispatch knobs resolve through the live IOptionsMonitor so a
// PlacementRecheckIn edit lands on the next deferred placement without
// restart. Egress-verification reads the same way: opt-in, canary endpoints
// and cool-down land on the next acquisition, while the shared gate keeps
// per-kind demotions process-wide across acquisitions.
builder.Services.AddSingleton<CodeyBox.Core.EgressVerificationGate>(sp => new CodeyBox.Core.EgressVerificationGate(
    () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.EgressVerification,
    sp.GetRequiredService<TimeProvider>()));
builder.Services.AddSingleton<CodeyBox.Core.IEgressVerificationEventSink>(sp =>
    new CodeyBox.Core.LoggerEgressVerificationEventSink(
        sp.GetRequiredService<ILoggerFactory>().CreateLogger("CodeyBox.EgressVerification")));
builder.Services.AddSingleton<SandboxPlacementAcquirer>(sp => new SandboxPlacementAcquirer(
    sp.GetRequiredService<SandboxClassesSnapshot>(),
    sp.GetRequiredService<ISandboxProviderRegistry>(),
    fallbackProvider: sp.GetRequiredService<ISandboxProvider>(),
    optionsAccessor: () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.ExecutorPhaseDispatch,
    log: sp.GetRequiredService<ILoggerFactory>().CreateLogger<SandboxPlacementAcquirer>(),
    verificationOptionsAccessor: () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.EgressVerification,
    verificationGate: sp.GetRequiredService<CodeyBox.Core.EgressVerificationGate>(),
    verificationSink: sp.GetRequiredService<CodeyBox.Core.IEgressVerificationEventSink>(),
    clock: sp.GetRequiredService<TimeProvider>()));

// --- Per-agent concurrency / rate-aware dispatch -----------------------------
builder.Services.AddSingleton<AgentConcurrencyOptions>(sp =>
    sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value.AgentConcurrency);
// AgentConcurrencySnapshot is the shared swappable holder: OrchestratorService
// (dispatch gate) and PipelineRunner (pickup-time rebase-resolver cap-aware
// routing) both read through this single instance. The hot-reload coordinator
// updates it via OrchestratorService.ApplyAgentConcurrencyReload, and both
// consumers' next read picks up the new caps — without the shared holder,
// PipelineRunner would keep gating against the pre-reload caps until restart.
builder.Services.AddSingleton<AgentConcurrencySnapshot>(sp =>
    new AgentConcurrencySnapshot(sp.GetRequiredService<AgentConcurrencyOptions>()));

// AgentCircuitBreakerSnapshot — shared swappable holder for the per-agent
// dispatch failure breaker tuning. The router's dispatch gate and PipelineRunner's
// outcome feed both read the single AgentCircuitBreaker built over this snapshot;
// AgentConfigHotReload publishes new tuning via Replace so an edit to
// CodeyBox:AgentCircuitBreaker takes effect on the next gate/outcome read without
// a process restart. Same pattern as AgentConcurrencySnapshot.
builder.Services.AddSingleton<AgentCircuitBreakerSnapshot>(sp =>
    new AgentCircuitBreakerSnapshot(
        sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value.AgentCircuitBreaker));
builder.Services.AddSingleton<AgentCircuitBreaker>(sp =>
    new AgentCircuitBreaker(
        sp.GetRequiredService<AgentCircuitBreakerSnapshot>(),
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<AgentCircuitBreaker>()));

// IncrementalRebaseSnapshot — hot-reloadable feature flag for the
// between-iteration incremental rebase. Same swappable-singleton pattern as
// AgentConcurrencySnapshot: PipelineRunner reads through it, and the
// hot-reload coordinator publishes new values on Replace so an edit to
// CodeyBox:IncrementalRebase takes effect on the next audit iteration
// without a process restart.
builder.Services.AddSingleton<IncrementalRebaseSnapshot>(sp =>
    new IncrementalRebaseSnapshot(
        sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value.IncrementalRebase));

// PipelineTuningSnapshot — hot-reloadable quota-fallback and merge-staging
// retry tuning knobs consumed by PipelineRunner. Same swappable-singleton
// pattern as AgentConcurrencySnapshot.
builder.Services.AddSingleton<PipelineTuningSnapshot>(sp =>
    new PipelineTuningSnapshot(
        sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value.PipelineTuning));

// Provider-transient host correlation — one process-wide tracker shared by
// the PipelineRunner (which observes signature hits) and the
// OrchestratorService dispatch loop (which holds new spawns while a tripped
// pause is active). Settings read live from PipelineTuningSnapshot so
// operator edits to the correlation window / threshold / pause take effect
// without a restart.
builder.Services.AddSingleton<ProviderTransientCorrelationTracker>(sp =>
{
    var tuning = sp.GetRequiredService<PipelineTuningSnapshot>();
    return new ProviderTransientCorrelationTracker(() => ProviderTransientCorrelationSettings.Create(
        tuning.Current.ProviderTransientCorrelationWindow,
        tuning.Current.ProviderTransientCorrelationThreshold,
        tuning.Current.ProviderTransientDispatchPause));
});

// NonDeterministicTestEscalationSnapshot — hot-reloadable thresholds for the
// NotDiffAttributable flake-escalation path (spawn-or-reuse a base-branch
// fix item and park the parent on dependsOn). Same swappable-singleton
// pattern: PipelineRunner reads through it, and the hot-reload coordinator
// publishes new values on Replace so an edit to
// CodeyBox:NonDeterministicTestEscalation takes effect on the next audit
// iteration without a process restart.
builder.Services.AddSingleton<NonDeterministicTestEscalationSnapshot>(sp =>
    new NonDeterministicTestEscalationSnapshot(
        sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value.NonDeterministicTestEscalation));

// BudgetDeferralRecheckSnapshot — hot-reloadable budget-cap deferral recheck
// intervals consumed by OrchestratorService. Edits to
// CodeyBox:BudgetDeferralRecheck take effect on the next pickup attempt
// without a process restart.
builder.Services.AddSingleton<BudgetDeferralRecheckSnapshot>(sp =>
    new BudgetDeferralRecheckSnapshot(
        sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value.BudgetDeferralRecheck));

// AgentDefaultsSnapshot, AgentNetworkToleranceSnapshot and
// ClaudeThinkingBlockSanitizerConfig register in the shared agent-execution
// composition both hosts call; hot-reload still flows through Replace on
// those same singletons.

// ToolchainFaultSnapshot — keyed toolchain-fault signatures over gate
// subprocess results, swappable by the hot-reload coordinator. Every gate
// reads through this same instance so an operator edit to
// CodeyBox:ToolchainFaults takes effect on the next gate run without a
// process restart. A new signature for an unseen language is a config-only
// addition.
builder.Services.AddSingleton<CodeyBox.Core.ToolchainFaultSnapshot>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new CodeyBox.Core.ToolchainFaultSnapshot(opts.ToolchainFaults);
});
builder.Services.AddSingleton<CodeyBox.Core.IToolchainFaultClassifier>(sp =>
    new CodeyBox.Core.ToolchainFaultClassifier(
        sp.GetRequiredService<CodeyBox.Core.ToolchainFaultSnapshot>()));
builder.Services.AddSingleton<CodeyBox.Core.IToolchainFaultRecordStore, CodeyBox.Core.InMemoryToolchainFaultRecordStore>();

builder.Services.AddSingleton<AgentBurnEstimatorOptions>(sp =>
    sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value.AgentBurnEstimator);
builder.Services.AddSingleton<AgentBurnEstimator>(sp => new AgentBurnEstimator(
    // Deferred resolution: the cost store backs onto a SQLite file that may
    // not yet be initialised when the router is constructed (e.g. in unit
    // tests that only build the router DI subgraph). Resolving lazily on the
    // first GetEstimateAsync keeps router construction allocation-only.
    () => sp.GetRequiredService<IWorkItemCostStore>(),
    sp.GetRequiredService<AgentBurnEstimatorOptions>(),
    sp.GetRequiredService<ILoggerFactory>().CreateLogger<AgentBurnEstimator>(),
    TimeProvider.System));
// Concrete and interface share the same singleton — AgentConfigHotReload needs
// the concrete type to call ApplyConfigReload, the router takes the interface.
builder.Services.AddSingleton<IAgentBurnEstimator>(sp =>
    sp.GetRequiredService<AgentBurnEstimator>());

// Per-agent/per-model spend budgets → synthetic quota for the router.
builder.Services.AddSingleton<AgentBudgetCalculator>(sp => new AgentBudgetCalculator(
    // Deferred resolution mirrors the burn estimator: the usage store backs onto
    // a SQLite file that may not be initialised when the router subgraph is built.
    () => sp.GetRequiredService<IAgentUsageStore>(),
    // Bind the initial options from configuration. There is intentionally no
    // AgentBudgetOptions DI singleton: it would be a stale snapshot after a
    // hot-reload (which mutates the calculator's internal copy via
    // ApplyConfigReload), so future injectors must not read limits from DI.
    // RetentionDays is read live via IOptionsMonitor where it is consumed.
    sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value.AgentBudgets,
    sp.GetRequiredService<ILoggerFactory>().CreateLogger<AgentBudgetCalculator>(),
    TimeProvider.System));
builder.Services.AddSingleton<IAgentBudgetProvider>(sp =>
    sp.GetRequiredService<AgentBudgetCalculator>());
// Separate reload abstraction so AgentConfigHotReload depends on a Core contract
// rather than the concrete calculator implementation type.
builder.Services.AddSingleton<IAgentBudgetConfigReloadable>(sp =>
    sp.GetRequiredService<AgentBudgetCalculator>());
// OrchestratorService implements IAgentRunningCounters. AgentClassRouter also
// depends on it, and OrchestratorService depends on AgentClassRouter — using a
// deferred wrapper breaks that cycle by resolving the singleton lazily on the
// first read, after both have been constructed.
builder.Services.AddSingleton<IAgentRunningCounters>(sp =>
    new DeferredAgentRunningCounters(() => sp.GetRequiredService<OrchestratorService>()));
// OrchestratorService implements IAgentSessionSlotGate (per-agent CLI session
// accounting shared between dispatch work slots and LLM auditor sessions).
// PipelineRunner consumes it and is itself a constructor dependency of
// OrchestratorService — the deferred wrapper breaks that cycle the same way
// DeferredAgentRunningCounters does above.
builder.Services.AddSingleton<IAgentSessionSlotGate>(sp =>
    new DeferredAgentSessionSlotGate(() => sp.GetRequiredService<OrchestratorService>()));
// Worker-pool occupancy for the codeybox.workers.in_use gauge. OrchestratorService
// owns the semaphore-backed pool; resolve it lazily (same cycle-break rationale as
// IAgentRunningCounters) so the observable-metrics hosted service can read the live
// pool total without coupling to the concrete service.
builder.Services.AddSingleton<IWorkerPoolOccupancy>(sp =>
    new DeferredWorkerPoolOccupancy(() => sp.GetRequiredService<OrchestratorService>()));
// Quota-availability snapshot for the codeybox.agent.quota.available_pct gauge.
// Surfaced as a focused contract implemented by AgentClassRouter so telemetry
// does not depend on the concrete router type.
builder.Services.AddSingleton<IAgentQuotaAvailabilitySnapshot>(sp =>
    sp.GetRequiredService<AgentClassRouter>());
builder.Services.AddSingleton<IAgentQuotaAvailabilitySignal>(sp =>
    sp.GetRequiredService<AgentQuotaAvailabilityBroadcaster>());
builder.Services.AddSingleton<IQuotaRetryRouter>(sp =>
    sp.GetRequiredService<AgentClassRouter>());
builder.Services.AddSingleton<IQuotaRetryAdmissionRouter>(sp =>
    sp.GetRequiredService<AgentClassRouter>());
builder.Services.AddSingleton<IAgentRoutingReadiness>(sp =>
    sp.GetRequiredService<AgentClassRouter>());

// --- Credential smoke probes -------------------------------------------------
// Registered as IEnumerable<IAgentSmokeProbe>; the gate resolves by Kind.
// Copilot has no host-side credential smoke probe (its auth surface is not
// directly probeable). The in-VM probe covers binary-presence verification,
// see CopilotInVmSmokeProbe registered below.
builder.Services.AddSingleton<IAgentSmokeProbe>(sp =>
{
    var optionsMonitor = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>();
    var loggerFactory = sp.GetRequiredService<ILoggerFactory>();
    return new ClaudeSmokeProbe(
        sp.GetRequiredService<IHttpClientFactory>(),
        loggerFactory.CreateLogger<ClaudeSmokeProbe>(),
        sp.GetService<TimeProvider>(),
        () => TimeSpan.FromSeconds(optionsMonitor.CurrentValue.QuotaRouter.ProbeRetryMaxDelaySeconds));
});
builder.Services.AddSingleton<IAgentSmokeProbe>(sp =>
    new CodexSmokeProbe(
        sp.GetRequiredService<IHttpClientFactory>(),
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<CodexSmokeProbe>()));
builder.Services.AddSingleton<IAgentSmokeProbe>(sp =>
    // Pass the IGeminiQuotaTokenSource (which also implements
    // IGeminiOAuthTokenSource — same refresher instance) so the smoke probe
    // hits Google with a freshly-refreshed access_token instead of the stale
    // on-disk one. Without this hookup the probe parses ~/.gemini/oauth_creds.json's
    // last-written access_token, which the gemini CLI rotates ~hourly, and the
    // probe eventually 401s — benching a fully-usable agent because the smoke
    // path bypassed the refresh logic the quota path already uses.
    new GeminiSmokeProbe(
        sp.GetRequiredService<IHttpClientFactory>(),
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<GeminiSmokeProbe>(),
        sp.GetService<IGeminiQuotaTokenSource>() as IGeminiOAuthTokenSource));
builder.Services.AddSingleton<IAgentSmokeProbe>(sp =>
    new CursorSmokeProbe(
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<CursorSmokeProbe>()));
builder.Services.AddSingleton<IAgentSmokeProbe>(sp =>
    new OpencodeSmokeProbe(
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<OpencodeSmokeProbe>()));
// Devin: credential-shape check only (CODEYBOX_DEVIN_AUTH_TOML parses and
// carries a token field). The remote GetUserStatus reading is owned by the quota
// probe; the real auth check happens on first CLI call in-VM.
builder.Services.AddSingleton<IAgentSmokeProbe>(sp =>
    new DevinSmokeProbe(
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<DevinSmokeProbe>()));
builder.Services.AddSingleton<IAgentSmokeProbe>(sp =>
    new CavemanCodeSmokeProbe(
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<CavemanCodeSmokeProbe>()));
builder.Services.AddSingleton<IAgentSmokeProbe>(sp =>
    new AntigravitySmokeProbe(
        sp.GetRequiredService<IHttpClientFactory>(),
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<AntigravitySmokeProbe>()));
// Pi: credential-presence check only (ANTHROPIC_API_KEY in the bundle). Pi
// fronts 30+ providers behind one CLI, so no single endpoint validates the
// credential and any provider call would spend real quota; the real auth
// check happens on first CLI call in-VM.
builder.Services.AddSingleton<IAgentSmokeProbe>(sp =>
    new PiSmokeProbe(
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<PiSmokeProbe>()));
// Prime: credential-presence check only (OPENROUTER_API_KEY in the bundle).
// prime-agent fronts many providers behind one CLI, so no single endpoint
// validates the credential and any provider call would spend real quota;
// the real auth check happens on first CLI call in-VM.
builder.Services.AddSingleton<IAgentSmokeProbe>(sp =>
    new PrimeSmokeProbe(
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<PrimeSmokeProbe>()));
// Aider: credential-presence check only (OPENROUTER_API_KEY in the bundle).
// Aider fronts many providers behind one CLI, so no single endpoint validates
// the credential and any provider call would spend real quota; the real auth
// check happens on first CLI call in-VM.
builder.Services.AddSingleton<IAgentSmokeProbe>(sp =>
    new AiderSmokeProbe(
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<AiderSmokeProbe>()));
// Goose: credential-presence check only (OPENROUTER_API_KEY in the bundle).
// Goose fronts 30+ providers behind one CLI, so no single endpoint validates
// the credential and any provider call would spend real quota; the real auth
// check happens on first CLI call in-VM.
builder.Services.AddSingleton<IAgentSmokeProbe>(sp =>
    new GooseSmokeProbe(
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<GooseSmokeProbe>()));
// Autohand: credential-presence check only (AUTOHAND_API_KEY in the bundle).
// Autohand is a multi-provider front with no single lightweight "whoami",
// and any provider call would spend real quota; the real auth check happens
// on first CLI call in-VM.
builder.Services.AddSingleton<IAgentSmokeProbe>(sp =>
    new AutohandSmokeProbe(
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<AutohandSmokeProbe>()));
// Vibe: credential-presence check only (OPENROUTER_API_KEY in the bundle).
// Vibe fronts many providers behind one CLI (the active model selects the
// provider at dispatch time), so no single endpoint validates the credential
// and any provider call would spend real quota; the real auth check happens
// on first CLI call in-VM.
builder.Services.AddSingleton<IAgentSmokeProbe>(sp =>
    new VibeSmokeProbe(
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<VibeSmokeProbe>()));
// Cline: credential-presence check only (OPENROUTER_API_KEY in the bundle).
// Cline is a multi-provider front with no single lightweight "whoami", and
// any provider call would spend real quota; the real auth check happens on
// first CLI call in-VM.
builder.Services.AddSingleton<IAgentSmokeProbe>(sp =>
    new ClineSmokeProbe(
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<ClineSmokeProbe>()));
// Kilo: credential-presence check only (KILO_API_KEY in the bundle).
// Kilo is a multi-provider front with no single lightweight "whoami",
// and any provider call would spend real quota; the real auth check happens
// on first CLI call in-VM.
builder.Services.AddSingleton<IAgentSmokeProbe>(sp =>
    new KiloSmokeProbe(
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<KiloSmokeProbe>()));
// OMP: credential-presence check only (OPENROUTER_API_KEY in the bundle).
// OMP fronts ~60 providers behind one CLI, so no single endpoint validates
// the credential and any provider call would spend real quota; the real auth
// check happens on first CLI call in-VM.
builder.Services.AddSingleton<IAgentSmokeProbe>(sp =>
    new OmpSmokeProbe(
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<OmpSmokeProbe>()));
// Continue: credential-presence check only (OPENROUTER_API_KEY in the
// bundle). Continue is a multi-provider front with no single lightweight
// "whoami", and any provider call would spend real quota; the real auth
// check happens on first CLI call in-VM.
builder.Services.AddSingleton<IAgentSmokeProbe>(sp =>
    new ContinueSmokeProbe(
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<ContinueSmokeProbe>()));
// Qwen: credential-presence check only (OPENAI_API_KEY in the bundle).
// Qwen fronts many providers behind one CLI with no single lightweight
// "whoami", and any provider call would spend real quota; the real auth
// check happens on first CLI call in-VM.
builder.Services.AddSingleton<IAgentSmokeProbe>(sp =>
    new QwenSmokeProbe(
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<QwenSmokeProbe>()));
// Cmd: credential-presence check only (OPENROUTER_API_KEY in the bundle).
// Cmd fronts 150+ providers behind one CLI, so no single endpoint validates
// the credential and any provider call would spend real quota; the real auth
// check happens on first CLI call in-VM. The Command Code account key is
// deliberately not probed: plan-less --local-only BYOK runs satisfy the gate
// with a non-credential placeholder, so absence of a vendor account is not
// a failure.
builder.Services.AddSingleton<IAgentSmokeProbe>(sp =>
    new CmdSmokeProbe(
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<CmdSmokeProbe>()));
// Crush: credential-presence check only (OPENROUTER_API_KEY in the bundle).
// Crush fronts dozens of providers behind one CLI, so no single endpoint
// validates the credential and any provider call would spend real quota;
// the real auth check happens on first CLI call in-VM. No guest config is
// seeded — the CLI reads the key directly from the process environment.
builder.Services.AddSingleton<IAgentSmokeProbe>(sp =>
    new CrushSmokeProbe(
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<CrushSmokeProbe>()));
// dotnet-opencode: credential-presence check only (DOTNETOPENCODE_CONFIG_JSON
// in the bundle). Provider-agnostic BYOK front with no single usage endpoint
// and an interactive-only device login; any provider call would spend real
// quota. The real auth check happens on first CLI call in-VM.
builder.Services.AddSingleton<IAgentSmokeProbe>(sp =>
    new DotNetOpencodeSmokeProbe(
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<DotNetOpencodeSmokeProbe>()));
// Unreal: credential-presence check (OPENROUTER_API_KEY, OPENAI_API_KEY,
// FIREWORKS_API_KEY, or UNREAL_HARNESS_LLM_API_KEY in the bundle) and
// rejection of Codex subscription credentials for account-safety.
builder.Services.AddSingleton<IAgentSmokeProbe>(sp =>
    new UnrealSmokeProbe(
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<UnrealSmokeProbe>()));

// --- In-VM smoke probes ------------------------------------------------------
// Registered as IEnumerable<IInVmSmokeProbe>; InVmSmokeProber resolves by Kind.
// These exec the agent CLI inside a sandbox cloned from the active baseline,
// catching exit-127 / auth-path failures the host-only probes above cannot see.
builder.Services.AddSingleton<IInVmSmokeProbe, ClaudeInVmSmokeProbe>();
builder.Services.AddSingleton<IInVmSmokeProbe, CopilotInVmSmokeProbe>();
builder.Services.AddSingleton<IInVmSmokeProbe, CodexInVmSmokeProbe>();
builder.Services.AddSingleton<IInVmSmokeProbe, GeminiInVmSmokeProbe>();
builder.Services.AddSingleton<IInVmSmokeProbe, CursorInVmSmokeProbe>();
builder.Services.AddSingleton<IInVmSmokeProbe>(sp => new DevinInVmSmokeProbe(
    sp.GetRequiredService<AgentDefaultsSnapshot>()));
builder.Services.AddSingleton<IInVmSmokeProbe, OpencodeInVmSmokeProbe>();
builder.Services.AddSingleton<IInVmSmokeProbe, CavemanCodeInVmSmokeProbe>();
builder.Services.AddSingleton<IInVmSmokeProbe, AntigravityInVmSmokeProbe>();
builder.Services.AddSingleton<IInVmSmokeProbe, CrockInVmSmokeProbe>();
builder.Services.AddSingleton<IInVmSmokeProbe, PiInVmSmokeProbe>();
builder.Services.AddSingleton<IInVmSmokeProbe, AiderInVmSmokeProbe>();
builder.Services.AddSingleton<IInVmSmokeProbe, GooseInVmSmokeProbe>();
builder.Services.AddSingleton<IInVmSmokeProbe, VibeInVmSmokeProbe>();
builder.Services.AddSingleton<IInVmSmokeProbe, PrimeInVmSmokeProbe>();
builder.Services.AddSingleton<IInVmSmokeProbe, AutohandInVmSmokeProbe>();
builder.Services.AddSingleton<IInVmSmokeProbe, ClineInVmSmokeProbe>();
builder.Services.AddSingleton<IInVmSmokeProbe, KiloInVmSmokeProbe>();
builder.Services.AddSingleton<IInVmSmokeProbe, OmpInVmSmokeProbe>();
builder.Services.AddSingleton<IInVmSmokeProbe, ContinueInVmSmokeProbe>();
builder.Services.AddSingleton<IInVmSmokeProbe, QwenInVmSmokeProbe>();
builder.Services.AddSingleton<IInVmSmokeProbe, CmdInVmSmokeProbe>();
builder.Services.AddSingleton<IInVmSmokeProbe, CrushInVmSmokeProbe>();
builder.Services.AddSingleton<IInVmSmokeProbe, DotNetOpencodeInVmSmokeProbe>();
builder.Services.AddSingleton<IInVmSmokeProbe, UnrealInVmSmokeProbe>();
// Startup guard (AC#1): bench any configured AgentClass member with no in-VM
// probe (so a CLI-backed agent that would fail at first dispatch is routed past
// at smoke time, not first dispatch). Agents on
// InVmSmokeOptions.ExemptAgentsWithoutProbe (the default still names copilot
// to preserve back-compat for operators who haven't installed the copilot CLI
// yet) are warned but not benched; a registered IInVmSmokeProbe — including
// CopilotInVmSmokeProbe above — supersedes that exemption and is what actually
// gets executed at probe time.
builder.Services.AddHostedService<InVmSmokeProbeCoverageValidator>();

// --- Model-list probes (used by AgentClassConfigValidator at startup) --------
// Registered as IEnumerable<IAgentModelListProbe>; the validator resolves by Kind.
// Copilot has no probe — its CLI does not accept a --model flag, so AgentClass
// members never carry a Copilot ModelId in the first place.
builder.Services.AddSingleton<IAgentModelListProbe>(sp =>
{
    var loggerFactory = sp.GetRequiredService<ILoggerFactory>();
    var source = sp.GetRequiredService<ClaudeCredentialFileSource>();
    return new ClaudeModelListProbe(
        sp.GetRequiredService<IHttpClientFactory>(),
        () => (
            CredentialFileTokenExtractor.ExtractClaudeAccessToken(source.GetRaw()),
            Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
                ?? Environment.GetEnvironmentVariable("CODEYBOX_CLAUDE_API_KEY")),
        loggerFactory.CreateLogger<ClaudeModelListProbe>());
});
builder.Services.AddSingleton<IAgentModelListProbe>(sp =>
{
    var loggerFactory = sp.GetRequiredService<ILoggerFactory>();
    var source = sp.GetRequiredService<CodexCredentialFileSource>();
    return new CodexModelListProbe(
        sp.GetRequiredService<IHttpClientFactory>(),
        () =>
        {
            var codexAuth = CredentialFileTokenExtractor.ExtractCodexAccessTokens(source.GetRaw());
            return (
                codexAuth.AccessToken,
                codexAuth.AccountId ?? Environment.GetEnvironmentVariable("CODEYBOX_CODEX_ACCOUNT_ID"),
                Environment.GetEnvironmentVariable("OPENAI_API_KEY")
                    ?? Environment.GetEnvironmentVariable("CODEYBOX_CODEX_API_KEY"));
        },
        loggerFactory.CreateLogger<CodexModelListProbe>());
});
builder.Services.AddSingleton<IAgentModelListProbe>(sp =>
{
    var loggerFactory = sp.GetRequiredService<ILoggerFactory>();
    return new OpencodeModelListProbe(
        new DefaultOpencodeCliRunner(),
        binary: Environment.GetEnvironmentVariable("CODEYBOX_OPENCODE_BINARY"),
        loggerFactory.CreateLogger<OpencodeModelListProbe>());
});
builder.Services.AddSingleton<IAgentModelListProbe>(sp =>
{
    var loggerFactory = sp.GetRequiredService<ILoggerFactory>();
    return new CavemanCodeModelListProbe(
        new DefaultCavemanCodeCliRunner(),
        binary: Environment.GetEnvironmentVariable("CODEYBOX_CAVEMANCODE_BINARY"),
        loggerFactory.CreateLogger<CavemanCodeModelListProbe>());
});
builder.Services.AddSingleton<IAgentModelListProbe>(sp =>
{
    var loggerFactory = sp.GetRequiredService<ILoggerFactory>();
    var source = sp.GetRequiredService<GeminiOAuthCredentialFileSource>();
    return new GeminiModelListProbe(
        sp.GetRequiredService<IHttpClientFactory>(),
        () => (
            CredentialFileTokenExtractor.ExtractGeminiAccessToken(source.GetRaw())
                ?? Environment.GetEnvironmentVariable("CODEYBOX_GEMINI_OAUTH_TOKEN"),
            Environment.GetEnvironmentVariable("GEMINI_API_KEY")
                ?? Environment.GetEnvironmentVariable("CODEYBOX_GEMINI_API_KEY")),
        loggerFactory.CreateLogger<GeminiModelListProbe>());
});
builder.Services.AddSingleton<IAgentModelListProbe, CursorModelListProbe>();
// Devin model-list probe: `devin models list --format json` is the
// account-scoped catalog — it needs the CLI installed and authenticated on
// the orchestrator host (the same `devin auth login` that produced the
// credentials file). Absent either, the probe reports Failed and the
// DevinKnownModels seed stays the warn-only validation surface.
builder.Services.AddSingleton<IAgentModelListProbe>(sp =>
{
    var loggerFactory = sp.GetRequiredService<ILoggerFactory>();
    return new DevinModelListProbe(
        new DefaultDevinCliRunner(),
        binary: Environment.GetEnvironmentVariable("CODEYBOX_DEVIN_BINARY"),
        loggerFactory.CreateLogger<DevinModelListProbe>());
});
// Antigravity model-list probe: no reachable endpoint enumerates the agy
// gateway models for our credential (the cloudcode-pa Code Assist surface
// returns the wrong gemini-2.5 catalog; the daily-cloudcode-pa gateway 403s on
// :retrieveUserQuota* and :fetchAvailableModels). The curated
// AntigravityKnownModels list is authoritative, so the probe just returns it.
builder.Services.AddSingleton<IAgentModelListProbe, AntigravityModelListProbe>();
// Crock model-list probe: the crock CLI does not expose a `crock models`
// command and Anthropic's /v1/models returns the on-demand catalog (not the
// batch-eligible subset CrockCode supports), so the probe returns the curated
// CrockKnownModels list. Operator-configured ids that are absent surface as
// a startup warning, not a hard reject.
builder.Services.AddSingleton<IAgentModelListProbe, CrockModelListProbe>();
// Pi model-list probe: `pi --list-models` needs an authenticated provider
// plus network, so it cannot back a host-side startup probe. The curated
// PiKnownModels seed is authoritative; operator-configured ids absent from
// the seed surface as a startup warning, not a hard reject.
builder.Services.AddSingleton<IAgentModelListProbe, PiModelListProbe>();
// Aider model-list probe: `aider --list-models <query>` needs a partial-match
// query, prints an interactive onboarding prompt when no model or key is
// configured, and emits thousands of rows, so it cannot back a host-side
// startup probe. The curated AiderKnownModels seed is authoritative;
// operator-configured ids absent from the seed surface as a startup warning,
// not a hard reject.
builder.Services.AddSingleton<IAgentModelListProbe, AiderModelListProbe>();
// Goose model-list probe: the catalog is per provider and server-side, so it
// cannot back a host-side startup probe. The curated GooseKnownModels seed is
// authoritative; operator-configured ids absent from the seed surface as a
// startup warning, not a hard reject.
builder.Services.AddSingleton<IAgentModelListProbe, GooseModelListProbe>();
// Vibe model-list probe: the catalog is guest-config [[models]] aliases
// resolved inside the sandbox, so it cannot back a host-side startup probe.
// The curated VibeKnownModels seed is authoritative; operator-configured
// aliases absent from the seed surface as a startup warning, not a hard
// reject.
builder.Services.AddSingleton<IAgentModelListProbe, VibeModelListProbe>();
// Prime model-list probe: `prime-agent model list` needs an authenticated
// provider plus network and emits a human-readable table rather than
// machine-readable ids, so it cannot back a host-side startup probe. The
// curated PrimeKnownModels seed is authoritative; operator-configured ids
// absent from the seed surface as a startup warning, not a hard reject.
builder.Services.AddSingleton<IAgentModelListProbe, PrimeModelListProbe>();
// Autohand model-list probe: the catalog is per provider and server-side, so
// it cannot back a host-side startup probe. The curated AutohandKnownModels
// seed is authoritative; operator-configured ids absent from the seed surface
// as a startup warning, not a hard reject.
builder.Services.AddSingleton<IAgentModelListProbe, AutohandModelListProbe>();
// Cline model-list probe: the catalog is per provider and server-side, so it
// cannot back a host-side startup probe. The curated ClineKnownModels seed is
// authoritative; operator-configured ids absent from the seed surface as a
// startup warning, not a hard reject.
builder.Services.AddSingleton<IAgentModelListProbe, ClineModelListProbe>();
// Kilo model-list probe: the catalog is per provider and server-side, so it
// cannot back a host-side startup probe. The curated KiloKnownModels seed is
// authoritative; operator-configured ids absent from the seed surface as a
// startup warning, not a hard reject.
builder.Services.AddSingleton<IAgentModelListProbe, KiloModelListProbe>();
// OMP model-list probe: the catalog is per provider and server-side, and
// `omp models --json` returns an empty set without login state, so it cannot
// back a host-side startup probe. The curated OmpKnownModels seed is
// authoritative; operator-configured ids absent from the seed surface as a
// startup warning, not a hard reject.
builder.Services.AddSingleton<IAgentModelListProbe, OmpModelListProbe>();
// Continue model-list probe: the catalog is per provider and server-side,
// so it cannot back a host-side startup probe. The curated
// ContinueKnownModels seed is authoritative; operator-configured ids absent
// from the seed surface as a startup warning, not a hard reject.
builder.Services.AddSingleton<IAgentModelListProbe, ContinueModelListProbe>();
// Qwen model-list probe: the catalog is per provider and server-side, so
// it cannot back a host-side startup probe. The curated QwenKnownModels
// seed is authoritative; operator-configured ids absent from the seed
// surface as a startup warning, not a hard reject.
builder.Services.AddSingleton<IAgentModelListProbe, QwenModelListProbe>();
// Cmd model-list probe: the catalog is per provider and server-side, so it
// cannot back a host-side startup probe. The curated CmdKnownModels seed is
// served instead (warn-only validation); no quota-meter probe exists (cmd
// status reports Command Code plan state, not the BYOK provider balance),
// so members fall through to the NullQuotaProbe unknown path.
builder.Services.AddSingleton<IAgentModelListProbe, CmdModelListProbe>();
// Crush model-list probe: the catalog is per provider and server-side (the
// `crush models` listing is a static registry, not a live entitlement
// check), so it cannot back a host-side startup probe. The curated
// CrushKnownModels seed is served instead (warn-only validation); no
// quota-meter probe exists (`crush stats` renders HTML with no
// machine-readable balance), so members fall through to the NullQuotaProbe
// unknown path.
builder.Services.AddSingleton<IAgentModelListProbe, CrushModelListProbe>();
// dotnet-opencode model-list probe: the CLI exposes no non-interactive model
// catalog, so it cannot back a host-side startup probe. The curated
// DotNetOpencodeKnownModels seed is authoritative; operator-configured ids
// absent from the seed surface as a startup warning, not a hard reject.
builder.Services.AddSingleton<IAgentModelListProbe, DotNetOpencodeModelListProbe>();
builder.Services.AddSingleton<IAgentModelListProbe, UnrealModelListProbe>();
builder.Services.AddHostedService<AgentClassConfigValidator>();

builder.Services.AddSingleton<SmokeOptions>(sp =>
{
    var cbOpts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    var s = cbOpts.Smoke;
    return new SmokeOptions
    {
        Enabled = s.Enabled,
        CacheTtlMinutes = s.CacheTtlMinutes,
        StartupTimeoutSeconds = s.StartupTimeoutSeconds,
    };
});
builder.Services.AddSingleton<SmokeOptionsSnapshot>(sp =>
    new SmokeOptionsSnapshot(sp.GetRequiredService<SmokeOptions>()));

// Commit-attribution policy — single source of truth for Co-Authored-By,
// CodeyBox-* trailers, and the PR footer. Host defaults bind from
// CodeyBox:CommitAttribution (all true = today's behaviour); per-project
// overrides win at Resolve time. The snapshot is refreshed through the same
// IOptionsMonitor<CodeyBoxOptions>.OnChange path as the session options below
// so edits take effect on the next commit without a restart.
builder.Services.AddSingleton<CodeyBox.Core.CommitAttributionSnapshot>(sp =>
{
    var monitor = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>();
    var live = new CodeyBox.Core.CommitAttributionSnapshot(monitor.CurrentValue.CommitAttribution);
    monitor.OnChange(opts => live.Replace(opts.CommitAttribution));
    return live;
});
builder.Services.AddSingleton<CodeyBox.Core.CommitAttributionPolicy>(sp =>
    new CodeyBox.Core.CommitAttributionPolicy(
        sp.GetRequiredService<CodeyBox.Core.CommitAttributionSnapshot>()));

// Branch-ownership proof — which commit trailers mark a stale owned-branch
// tip as CodeyBox's own history when no prior push was recorded. Bound from
// CodeyBox:UpstreamBranchOwnership and refreshed through the same
// IOptionsMonitor<CodeyBoxOptions>.OnChange path so edits take effect on the
// next push or re-drive without a restart.
builder.Services.AddSingleton<CodeyBox.Core.UpstreamBranchOwnershipSnapshot>(sp =>
{
    var monitor = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>();
    var live = new CodeyBox.Core.UpstreamBranchOwnershipSnapshot(monitor.CurrentValue.UpstreamBranchOwnership.Clone());
    monitor.OnChange(opts => live.Replace(opts.UpstreamBranchOwnership.Clone()));
    return live;
});

builder.Services.AddSingleton<TransitionHealthOptions>(sp =>
{
    var cbOpts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    var t = cbOpts.TransitionHealth;
    return TransitionHealthConfigMapper.ToOptions(t.Enabled, t.WindowHours, t.MaxTransitions);
});
builder.Services.AddSingleton<TransitionHealthOptionsSnapshot>(sp =>
    new TransitionHealthOptionsSnapshot(sp.GetRequiredService<TransitionHealthOptions>()));
builder.Services.AddSingleton<ITransitionHealthDataSource>(sp =>
{
    var cbOpts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteTransitionHealthDataSource(cbOpts.StateDatabasePath);
});
builder.Services.AddSingleton<TransitionHealthService>(sp =>
    new TransitionHealthService(
        sp.GetRequiredService<ITransitionHealthDataSource>(),
        sp.GetRequiredService<TransitionHealthOptionsSnapshot>()));
builder.Services.AddSingleton<AvailabilityOptions>(sp =>
{
    var cbOpts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    var a = cbOpts.Smoke.Availability;
    return new AvailabilityOptions
    {
        FastFailThresholdSeconds = a.FastFailThresholdSeconds,
        MaxConsecutiveFastFails = a.MaxConsecutiveFastFails,
        MaxConsecutiveNoChanges = a.MaxConsecutiveNoChanges,
        PeriodicSweepInterval = TimeSpan.FromSeconds(Math.Max(0, a.PeriodicSweepIntervalSeconds)),
    };
});
builder.Services.AddSingleton<AgentAvailabilityRegistry>(sp => new AgentAvailabilityRegistry(
    sp.GetRequiredService<AvailabilityOptions>(),
    TimeProvider.System,
    sp.GetRequiredService<ILoggerFactory>().CreateLogger<AgentAvailabilityRegistry>()));
// The narrow availability port routing/dispatch/admin consumers bind to —
// same singleton, exposed as the read/run-outcome/snapshot/reset surface.
builder.Services.AddSingleton<IAgentAvailabilityRegistry>(sp =>
    sp.GetRequiredService<AgentAvailabilityRegistry>());
builder.Services.AddSingleton<IAgentEffectiveAvailabilityReader>(sp =>
    sp.GetRequiredService<AgentAvailabilityRegistry>());
builder.Services.AddSingleton<IAgentAvailabilityRecoverySignal>(sp =>
    sp.GetRequiredService<AgentAvailabilityRegistry>());
// The smoke-mutator port the in-VM prober, coverage policy, and host smoke
// services bind to — same singleton, exposed as the exclusion-taxonomy
// surface (MarkSmokeResult / ExcludeForMissingProbe) those owners need.
builder.Services.AddSingleton<ISmokeAvailabilityRegistry>(sp =>
    sp.GetRequiredService<AgentAvailabilityRegistry>());
builder.Services.AddSingleton<IAgentAuthAvailabilityRegistry>(sp =>
    sp.GetRequiredService<AgentAvailabilityRegistry>());
builder.Services.AddSingleton<IAgentAuthRequiredAvailabilityReader>(sp =>
    sp.GetRequiredService<AgentAvailabilityRegistry>());
builder.Services.AddSingleton<IAgentRestorePublisher>(sp =>
    sp.GetRequiredService<AgentAvailabilityRegistry>());
builder.Services.AddSingleton<IAgentDispatchAvailability>(sp => new AgentDispatchAvailability(
    sp.GetService<IAgentEffectiveAvailabilityReader>(),
    sp.GetService<IInVmSmokeGate>(),
    sp.GetRequiredService<SmokeOptionsSnapshot>(),
    sp.GetRequiredService<IAgentPauseController>()));
builder.Services.AddSingleton<IAgentSmokeCache>(sp =>
{
    var opts = sp.GetRequiredService<SmokeOptions>();
    return new AgentSmokeCache(TimeSpan.FromMinutes(opts.CacheTtlMinutes));
});
builder.Services.AddSingleton<CredentialSmokeGate>(sp =>
    new CredentialSmokeGate(
        sp.GetRequiredService<ICredentialProvider>(),
        sp.GetServices<IAgentSmokeProbe>(),
        sp.GetRequiredService<IAgentSmokeCache>(),
        sp.GetRequiredService<SmokeOptionsSnapshot>(),
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<CredentialSmokeGate>()));

// --- In-VM smoke prober ------------------------------------------------------
builder.Services.AddSingleton<InVmSmokeOptions>(sp =>
{
    var cbOpts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    var v = cbOpts.Smoke.InVm;
    return new InVmSmokeOptions
    {
        Enabled = v.Enabled,
        ImageReference = cbOpts.SandboxImageReference,
        AllowedHosts = cbOpts.AgentAllowedHosts,
        // Dispatch calls pass the resolved project sandbox target directly to
        // IInVmSmokeGate. This option is only an explicit operator override for
        // project-less paths such as manual/admin probes and legacy sweeps.
        NetworkProfile = v.NetworkProfile,
        StepTimeoutSeconds = v.StepTimeoutSeconds,
        ProvisionTimeoutSeconds = v.ProvisionTimeoutSeconds,
        GateDeadlineSeconds = v.GateDeadlineSeconds,
        CacheTtlMinutes = v.CacheTtlMinutes,
        SweepIntervalSeconds = v.SweepIntervalSeconds,
        FailClosedOnProbeFault = v.FailClosedOnProbeFault,
        // Null (unset) keeps the InVmSmokeOptions default (copilot); an explicit
        // list — including empty — overrides it so operators can opt every agent
        // into the in-VM coverage requirement.
        ExemptAgentsWithoutProbe = v.ExemptAgentsWithoutProbe is { } ex ? ex : new InVmSmokeOptions().ExemptAgentsWithoutProbe,
    };
});
builder.Services.AddSingleton<IInVmSmokeCache>(sp =>
    new InVmSmokeCache(TimeSpan.FromMinutes(sp.GetRequiredService<InVmSmokeOptions>().CacheTtlMinutes)));
// Single operator-reset port: clears the availability registry AND invalidates
// the in-VM smoke cache atomically, so a reset can never leave a stale cached
// pass to reconcile back onto the registry before the operator's fix is
// re-verified. The admin endpoint depends on this one contract.
builder.Services.AddSingleton<IAgentAvailabilityReset>(sp => new AgentAvailabilityReset(
    sp.GetRequiredService<ISmokeAvailabilityRegistry>(),
    sp.GetRequiredService<IInVmSmokeCache>(),
    sp.GetRequiredService<IAgentRestorePublisher>(),
    sp.GetService<AgentClassRouter>(),
    sp.GetServices<IAgentQuotaProbe>(),
    sp.GetRequiredService<ILoggerFactory>().CreateLogger<AgentAvailabilityReset>()));
builder.Services.AddSingleton<InVmSmokeProber>(sp => new InVmSmokeProber(
    sp.GetRequiredService<ISandboxProvider>(),
    sp.GetRequiredService<IBaselineImageResolver>(),
    sp.GetRequiredService<IBaselineImageProvisioner>(),
    sp.GetRequiredService<ICredentialProvider>(),
    sp.GetServices<IInVmSmokeProbe>(),
    sp.GetRequiredService<ISmokeAvailabilityRegistry>(),
    sp.GetRequiredService<IInVmSmokeCache>(),
    sp.GetRequiredService<IWebhookDispatcher>(),
    sp.GetRequiredService<InVmSmokeOptions>(),
    sp.GetRequiredService<ILoggerFactory>().CreateLogger<InVmSmokeProber>(),
    sp.GetRequiredService<SmokeOptionsSnapshot>(),
    sp.GetRequiredService<IAgentAuthFailureClassifier>(),
    sp.GetRequiredService<IAgentAuthAvailabilityRegistry>()));
// The router consults the prober as a dispatch gate (IInVmSmokeGate) so the
// first work item per baseline is verified in-VM before routing; share the
// single InVmSmokeProber instance so the gate, the background sweep service,
// and the cache all observe the same state.
builder.Services.AddSingleton<IInVmSmokeGate>(sp => sp.GetRequiredService<InVmSmokeProber>());
// Coverage enforcement (startup validator + hot-reload) is a pure config policy
// with no VM provisioning, kept in a separate type from the runtime dispatch
// gate so those consumers depend only on the narrow IInVmSmokeCoveragePolicy
// port rather than the full gate contract (interface segregation).
builder.Services.AddSingleton<IInVmSmokeCoveragePolicy>(sp => new InVmSmokeCoveragePolicy(
    sp.GetServices<IInVmSmokeProbe>(),
    sp.GetRequiredService<ISmokeAvailabilityRegistry>(),
    sp.GetRequiredService<InVmSmokeOptions>(),
    sp.GetRequiredService<SmokeOptionsSnapshot>()));
builder.Services.AddHostedService(sp => new InVmSmokeProbeService(
    sp.GetRequiredService<IInVmSmokeGate>(),
    sp.GetRequiredService<InVmSmokeOptions>(),
    sp.GetRequiredService<ILoggerFactory>().CreateLogger<InVmSmokeProbeService>(),
    sp.GetRequiredService<IProjectRepository>()));

// --- Projects + per-project upstream + audit composer ------------------------
// ProjectRepository observes IOptionsMonitor<ProjectsOptions>, so an
// appsettings.json edit that adds a new project — or changes an existing
// project's audit timeout — takes effect within the framework's debounce
// window (~1 s). The ProjectsOptionsRemovalValidator above rejects edits
// that drop a project with in-flight work items, so reloads that would
// strand running pipelines are surfaced as ERR and the prior project list
// is retained.
builder.Services.AddSingleton<IProjectRepository>(sp => new ProjectRepository(
    sp.GetRequiredService<IOptionsMonitor<ProjectsOptions>>(),
    sp.GetRequiredService<ILogger<ProjectRepository>>(),
    sp.GetService<PresetCatalogOptions>(),
    sp.GetRequiredService<IKnobRegistry>(),
    sp.GetService<IDeploymentDriverRegistry>()));
builder.Services.AddSingleton<IUpstreamRemoteFactory, UpstreamRemoteFactory>();
builder.Services.AddSingleton(TimeProvider.System);
builder.Services.AddSingleton<GitHubAppConnectState>();
// Read the store path from the final service-provider configuration. Test hosts
// add their configuration sources after this registration code has run; reading
// builder.Configuration here would ignore their isolated writable store path.
builder.Services.AddSingleton(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new GitHubAppStore(
        opts.GitHubAppStorePath
            ?? Environment.GetEnvironmentVariable("CODEYBOX_GITHUB_APP_STORE")
            ?? (builder.Environment.IsProduction()
                ? "/var/lib/codeybox/github-apps"
                : Path.Combine(Path.GetTempPath(), $"codeybox-github-apps-{Environment.ProcessId}")));
});
builder.Services.AddSingleton(_ =>
{
    var options = builder.Configuration.GetSection("CodeyBox:Presets").Get<PresetCatalogOptions>()
        ?? new PresetCatalogOptions();
    options.ProjectRoot ??= builder.Environment.ContentRootPath;
    return options;
});
// Bridges the hot-reloadable pipeline-tuning knobs
// (CodeyBox:PipelineTuning:CSharpTestPass*) into the TestRunOptions that
// DotnetTestAuditor reads at run time. Reading through PipelineTuningSnapshot on
// each call keeps blame-hang / test-idle-timeout edits hot-reloadable without a
// restart. Defaults (unset knobs) yield TestRunOptions.Default → byte-identical
// legacy dotnet-test command.
static Func<TestRunOptions> DotnetTestRunOptionsAccessor(IServiceProvider sp)
{
    var tuning = sp.GetRequiredService<PipelineTuningSnapshot>();
    return () =>
    {
        var current = tuning.Current;
        return new TestRunOptions
        {
            BlameHangTimeout = current.CSharpTestPassBlameHangTimeout,
            IdleTimeout = current.CSharpTestPassAuditorIdleTimeout,
        };
    };
}

// Bind the run-options accessor ONCE and share the single closure across the
// preset catalog, the DI-registered test runner, and every per-project catalog
// the ProjectAuditorComposer builds. One closure — all consumers observe the
// same hot-reloadable PipelineTuningSnapshot.
builder.Services.AddSingleton<Func<TestRunOptions>>(DotnetTestRunOptionsAccessor);

// Hot-reloadable test-failure-attribution snapshot sourced from CodeyBoxOptions.
// Rebuilt on IOptionsMonitor emissions by AgentConfigHotReload so a
// configuration edit takes effect without a process restart.
builder.Services.AddSingleton<TestFailureAttributionOptionsSnapshot>(sp =>
{
    var cbOpts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new TestFailureAttributionOptionsSnapshot(cbOpts.TestFailureAttribution);
});

builder.Services.AddSingleton<IPresetCatalog>(sp => new PresetCatalog(
    sp.GetRequiredService<PresetCatalogOptions>(),
    sp.GetRequiredService<Func<TestRunOptions>>(),
    sp.GetRequiredService<TestFailureAttributionOptionsSnapshot>(),
    sp.GetRequiredService<TestSelectionShadowConfig>()));

// The canonical dotnet-test runner, registered so the ITestSelector seam
// (a separate work item) can resolve ITestRunnerAuditor from DI and enumerate
// its TestSuiteDescriptor. The preset catalog builds its own instance for the
// audit run from the csharp language YAML; this registration mirrors that
// command with the same hot-reloadable run options and attribution snapshot.
builder.Services.AddSingleton<ITestRunnerAuditor>(sp => new DotnetTestAuditor(new DotnetTestAuditorOptions
{
    Name = "csharp:test-pass",
    BaseArgv = ["dotnet", "test", "--no-build"],
    CanShortCircuitOnBlockingFinding = true,
    Role = AuditorRole.BuildTestGate,
    BuildTestGateEvidence = BuildTestGateEvidence.Test,
    RunOptionsAccessor = sp.GetRequiredService<Func<TestRunOptions>>(),
    TestFailureAttributionOptions = sp.GetRequiredService<TestFailureAttributionOptionsSnapshot>(),
}));

// Test-selection seam. ConfiguredTestSelector reads Audit:TestSelection:Mode live
// from IOptionsMonitor on every call (hot-reload) and dispatches to the selector
// registered for that mode; the default 'all' maps to RunAllTestSelector, whose
// TestSelection.All keeps the emitted dotnet-test command byte-identical to the
// legacy path. 'coverage-shadow' maps to CoverageTestSelector, which narrows the
// project-graph superset by per-test coverage — ADVISORY ONLY: the per-item
// csharp:test-pass runner computes the decision, still runs the full suite, and
// emits a shadow record (SHADOW-BEFORE-ENFORCE). 'project-graph' maps to
// ProjectGraphTestSelector and is ENFORCING: the per-item csharp:test-pass runner
// executes only the selected subset (fail-safe fallback to the full suite on any
// error or ambiguous result). 'coverage' maps to the same CoverageTestSelector
// instance and is ENFORCING: the runner executes only the coverage-narrowed
// subset nested inside the project-graph superset, descending the
// coverage → project-graph → all fallback ladder on any error or ambiguous
// result. Opt into either enforcing mode only after the soundness gate
// (GET /audit/test-selection/soundness, selector=project-graph or coverage)
// reports readyForEnforcement. The merge/release verification
// path (IRequiredBuildVerifier / process:required-build) deliberately takes NO
// dependency on this seam: it always verifies the full build/test surface
// regardless of Mode.
builder.Services.AddSingleton<ITestSelector>(sp =>
{
    var modeMonitor = sp.GetRequiredService<IOptionsMonitor<TestSelectionOptions>>();
    var coverageOptionsMonitor = sp.GetRequiredService<IOptionsMonitor<CoverageTestSelectionOptions>>();
    var projectGraph = new ProjectGraphTestSelector(() => coverageOptionsMonitor.CurrentValue, TimeProvider.System);
    var coverage = new CoverageTestSelector(
        projectGraph,
        () => coverageOptionsMonitor.CurrentValue,
        TimeProvider.System);
    var selectorsByMode = new Dictionary<TestSelectionMode, ITestSelector>
    {
        [TestSelectionMode.All] = new RunAllTestSelector(),
        [TestSelectionMode.CoverageShadow] = coverage,
        [TestSelectionMode.ProjectGraph] = projectGraph,
        [TestSelectionMode.Coverage] = coverage,
    };
    return new ConfiguredTestSelector(
        () => TestSelectionModeParser.Parse(modeMonitor.CurrentValue.Mode),
        selectorsByMode);
});
// Shadow-record sink (structured logs) and the test-selection configuration
// threaded into every csharp:test-pass runner the preset catalogs build.
// Mode=all (the default) is an instant kill-switch: the runner checks the live
// mode on every run and runs the full suite for anything but coverage-shadow
// (advisory shadow), project-graph (enforcing subset), or coverage (enforcing
// coverage-nested subset).
builder.Services.AddSingleton<ITestSelectionShadowSink, LoggerTestSelectionShadowSink>();
builder.Services.AddSingleton<TestSelectionShadowConfig>(sp => new TestSelectionShadowConfig
{
    Selector = sp.GetRequiredService<ITestSelector>(),
    Sink = sp.GetRequiredService<ITestSelectionShadowSink>(),
    ModeAccessor = () => TestSelectionModeParser.Parse(
        sp.GetRequiredService<IOptionsMonitor<TestSelectionOptions>>().CurrentValue.Mode),
    OptionsAccessor = () => sp.GetRequiredService<IOptionsMonitor<CoverageTestSelectionOptions>>().CurrentValue,
});
// Post-merge baseline production: the scheduler holds at most one pending job
// per project (a second merge before the job starts supersedes it — newest
// commit wins, never two jobs for one project). The hosted service drains it
// through a sandboxed producer run, stores the artifact host-side keyed by
// project + commit (bounded retention), and reports every outcome through the
// status endpoint and a structured event. The audit stager places the newest
// ancestry-reachable fresh baseline at BaselineSandboxPath (read-only) during
// audit sandbox setup. All three self-gate on the global Enabled flag and the
// per-project TestSelectionBaselineEnabled opt-in; unwired projects see no
// behaviour change (selectors fall back to the full suite as before).
builder.Services.AddSingleton<TestSelectionBaselineScheduler>();
builder.Services.AddSingleton<ITestSelectionBaselineStore, TestSelectionBaselineStore>();
builder.Services.AddSingleton<TestSelectionBaselineAuditStager>(sp => new TestSelectionBaselineAuditStager(
    sp.GetRequiredService<ITestSelectionBaselineStore>(),
    sp.GetRequiredService<IGitHost>(),
    () => sp.GetRequiredService<IOptionsMonitor<CoverageTestSelectionOptions>>().CurrentValue,
    sp.GetRequiredService<ILogger<TestSelectionBaselineAuditStager>>(),
    sp.GetService<TimeProvider>()));
builder.Services.AddSingleton<ITestSelectionBaselineJobRunner>(sp => new SandboxTestSelectionBaselineRunner(
    sp.GetRequiredService<ISandboxProvider>(),
    sp.GetRequiredService<IGitHost>(),
    sp.GetRequiredService<IProjectRepository>(),
    sp.GetRequiredService<PipelineOptions>(),
    () => sp.GetRequiredService<IOptionsMonitor<TestSelectionBaselineProductionOptions>>().CurrentValue,
    () => sp.GetRequiredService<IOptionsMonitor<CoverageTestSelectionOptions>>().CurrentValue,
    sp.GetRequiredService<ILogger<SandboxTestSelectionBaselineRunner>>(),
    sp.GetService<TimeProvider>()));
builder.Services.AddHostedService(sp => new TestSelectionBaselineProductionService(
    sp.GetRequiredService<TestSelectionBaselineScheduler>(),
    sp.GetRequiredService<ITestSelectionBaselineStore>(),
    sp.GetRequiredService<ITestSelectionBaselineJobRunner>(),
    sp.GetRequiredService<IProjectRepository>(),
    sp.GetRequiredService<ISandboxProvider>(),
    sp.GetRequiredService<IWebhookDispatcher>(),
    () => sp.GetRequiredService<IOptionsMonitor<TestSelectionBaselineProductionOptions>>().CurrentValue,
    sp.GetRequiredService<ILogger<TestSelectionBaselineProductionService>>(),
    sp.GetService<TimeProvider>()));
builder.Services.AddSingleton<IAuditor, GraphicalSmokeAuditor>();
builder.Services.AddSingleton<IAuditor>(sp => new BuildScriptAuditor(
    () => sp.GetRequiredService<IOptionsMonitor<BuildScriptAuditorOptions>>().CurrentValue));
builder.Services.AddSingleton<IAuditor, PromptRevisionTrailerAuditor>();

// Plan-audit chain — one plan-stage IAuditor per chain test (Targets = plan
// only) that reviews the PLAN against the supplied context before
// implementation. Each is auto-included for every plan-enabled project by
// ProjectAuditorComposer and toggled off per project via ExcludedAuditors. The
// pipeline supplies the resolved review runner per invocation via
// AuditContext.AuditRunner; the baked-in Claude runner is only a host-side
// text-only fallback so the auditor is constructible without an override.
// PlanAuditTests.All is the single source of truth for chain membership.
foreach (var planAuditTest in PlanAuditTests.All)
{
    var test = planAuditTest; // capture per-iteration for the resolver closure
    builder.Services.AddSingleton<IAuditor>(sp => new PlanAuditChainAuditor(new PlanAuditChainAuditorOptions
    {
        Test = test,
        Agent = sp.GetServices<IAgentRunner>().OfType<ClaudeAgentRunner>().First(),
    }));
}
builder.Services.AddSingleton<IMechanicalFixer, DotnetFormatMechanicalFixer>();
builder.Services.AddSingleton<IMechanicalFixerRegistry, MechanicalFixerRegistry>();
builder.Services.AddSingleton<IMechanicalFixerInputProvider, DotnetFormatMechanicalFixerInputProvider>();

// Mutation-testing rigor gate (disabled by default; per-project threshold).
// The auditor short-circuits to pass when Enabled=false, so registering the
// defaults is safe; operators replace IMutationRunner / IMutationRatchetStore
// with their own implementations to turn the gate on. See
// MutationGateRegistration for the shared composition (host and tests use
// the same path).
MutationGateRegistration.Configure(builder.Services, builder.Configuration);

// Deterministic per-item coverage gate (tests:coverage). Runs the test suite
// with coverage and blocks on executable lines CHANGED in the work item's diff
// that no test exercised. Default mode is report-only (non-blocking) so the
// rollout measures uncovered-line volume before it gates merges; flip
// CodeyBox:Audit:Coverage:Mode to "blocking" after calibration. IOptionsMonitor
// so mode/exclusions hot-reload without a restart, consistent with the rest of
// the host. The auditor short-circuits to a pass when the tree has no .NET
// markers or the diff changed no lines, so auto-inclusion is cheap off the
// .NET path.
builder.Services.Configure<AuditSectionOptions>(
    builder.Configuration.GetSection("CodeyBox:Audit"));
builder.Services.AddSingleton<IAuditor>(sp =>
{
    var monitor = sp.GetRequiredService<IOptionsMonitor<AuditSectionOptions>>();
    return new CoverageAuditor(() => monitor.CurrentValue.Coverage);
});

// Plan-adherence reviewer (closes the planning loop on the implementation side).
// Hot-reloadable via CodeyBox:PlanAdherence and enabled by default; the auditor
// self-limits to PLANNED items at run time (no plan artifact -> no-op), so
// unplanned items are unaffected. The accessor mirrors the Func<TestRunOptions>
// pattern so the ProjectAuditorComposer observes the same live IOptionsMonitor
// snapshot and composes the reviewer with the resolving project's agent.
builder.Services.Configure<PlanAdherenceAuditorOptions>(
    builder.Configuration.GetSection("CodeyBox:PlanAdherence"));
builder.Services.AddSingleton<Func<PlanAdherenceAuditorOptions>>(sp =>
{
    var monitor = sp.GetRequiredService<IOptionsMonitor<PlanAdherenceAuditorOptions>>();
    return () => monitor.CurrentValue;
});

// Human deployment reviewer (operator as reviewer through the auditor seam).
// Hot-reloadable via CodeyBox:HumanReview, explicit opt-in (default off); the
// accessor mirrors the Func<TestRunOptions> pattern so the
// ProjectAuditorComposer observes the same live IOptionsMonitor snapshot and
// composes the reviewer into the deployment stage when enabled.
builder.Services.Configure<HumanDeploymentReviewOptions>(
    builder.Configuration.GetSection("CodeyBox:HumanReview"));
builder.Services.AddSingleton<Func<HumanDeploymentReviewOptions>>(sp =>
{
    var monitor = sp.GetRequiredService<IOptionsMonitor<HumanDeploymentReviewOptions>>();
    return () => monitor.CurrentValue;
});

builder.Services.AddSingleton(new RequiredAuditorPolicy(
    builder.Configuration.GetSection("CodeyBox:RequiredAuditors").Get<string[]>() ?? []));
builder.Services.AddSingleton<ProjectAuditorComposer>();
builder.Services.AddSingleton<ProjectMechanicalFixerComposer>();

// --- Built-in deep auditors (release in_review phase) ------------------------
// Registered as IDeepAuditor; ReleaseService resolves the subset configured per
// project by name match. LLM auditors require AgentCredentials at runtime.
builder.Services.AddSingleton<IDeepAuditor, OwaspAsvsDeepAuditor>();
builder.Services.AddSingleton<IDeepAuditor, ArchCoherenceDeepAuditor>();
builder.Services.AddSingleton<IDeepAuditor, DepsCveScanDeepAuditor>();
builder.Services.AddSingleton<IDeepAuditor>(sp => new E2eRegressionDeepAuditor(
    sp.GetRequiredService<ITestCaseStore>(),
    sp.GetRequiredService<IE2eExecutionPool>(),
    sp.GetRequiredService<IE2eReplayRuntime>(),
    sp.GetRequiredService<IReleaseStore>(),
    sp.GetService<IE2eRunStore>(),
    sp.GetService<E2eReplayArtifactAdmissionValidator>(),
    sp.GetService<TimeProvider>() ?? TimeProvider.System,
    sp.GetService<Microsoft.Extensions.Logging.ILogger<E2eRegressionDeepAuditor>>()));

// --- Webhooks ----------------------------------------------------------------
// AllowAutoRedirect=false prevents SSRF via HTTP 3xx redirects to private
// addresses that bypass the blocklist in ValidateWebhookUrl.
builder.Services.AddHttpClient("webhook")
    .ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler
    {
        AllowAutoRedirect = false,
    });
builder.Services.AddSingleton<WebhookEventBroadcaster>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    // WebhookEventBroadcaster's constructor enforces capacity >= 1 and throws
    // ArgumentOutOfRangeException with a clear message naming the bad value.
    return new WebhookEventBroadcaster(opts.WebhookEventBus.RingBufferCapacity);
});
builder.Services.AddSingleton<IWebhookDispatcher>(sp =>
{
    var broadcaster = sp.GetRequiredService<WebhookEventBroadcaster>();
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    if (opts.Webhooks.Count == 0)
        return new BroadcastingWebhookDispatcher(broadcaster, new NullWebhookDispatcher());

    var seenNames = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
    var endpointConfigs = opts.Webhooks.Select(w =>
    {
        if (string.IsNullOrWhiteSpace(w.Name))
            throw new InvalidOperationException("Each webhook endpoint must have a non-empty Name");
        if (w.Name.AsSpan().IndexOfAny(['\n', '\r', '\0']) >= 0)
            throw new InvalidOperationException($"Webhook endpoint Name '{w.Name}' must not contain control characters");
        if (!seenNames.Add(w.Name))
            throw new InvalidOperationException($"Webhook endpoint Name '{w.Name}' is not unique");
        if (w.SecretEnvVar is not null && w.SecretEnvVar.AsSpan().IndexOfAny(['\n', '\r', '\0']) >= 0)
            throw new InvalidOperationException($"Webhooks[{w.Name}].SecretEnvVar must not contain control characters");
        Validation.ValidateWebhookUrl(w.Url, $"Webhooks[{w.Name}].Url");
        if (w.MaxAttempts < 1)
            throw new InvalidOperationException($"Webhooks[{w.Name}].MaxAttempts must be >= 1");
        if (w.InitialBackoffSeconds < 0)
            throw new InvalidOperationException($"Webhooks[{w.Name}].InitialBackoffSeconds must be >= 0");
        if (w.TimeoutSeconds < 1)
            throw new InvalidOperationException($"Webhooks[{w.Name}].TimeoutSeconds must be >= 1");
        return new WebhookEndpointConfig
        {
            Name = w.Name,
            Url = w.Url,
            SecretEnvVar = w.SecretEnvVar,
            EventFilter = w.EventFilter,
            MaxAttempts = w.MaxAttempts,
            InitialBackoffSeconds = w.InitialBackoffSeconds,
            TimeoutSeconds = w.TimeoutSeconds,
        };
    }).ToList();

    var http = new HttpWebhookDispatcher(
        new WebhookDispatcherOptions { Endpoints = endpointConfigs },
        sp.GetRequiredService<IHttpClientFactory>(),
        sp.GetRequiredService<ILogger<HttpWebhookDispatcher>>());
    return new BroadcastingWebhookDispatcher(broadcaster, http);
});

// --- Notifications ------------------------------------------------------------
// Human/systems notification pipeline: conditions evaluate system state,
// rules route matching notifications to providers (email, etc.).
// Safe no-op when unconfigured — no startup failure without SMTP config.
builder.Services.AddSingleton<OrchestratorProgressClock>();
builder.Services.AddSingleton<LeakDetectionSink>();

builder.Services.AddSingleton<INotificationProvider>(sp =>
{
    var logger = sp.GetRequiredService<ILogger<EmailNotificationProvider>>();
    var isDev = sp.GetRequiredService<IHostEnvironment>().IsDevelopment();
    Func<EmailProviderOptions> optsAccessor = () =>
        sp.GetRequiredService<IOptionsMonitor<NotificationsOptions>>().CurrentValue.Email;
    var opts = optsAccessor();
    if (opts.Enabled)
        return new EmailNotificationProvider(optsAccessor, logger, isDevelopment: isDev);
    return new NullNotificationProvider("email");
});

// Chat provider (Slack / Discord incoming webhooks). Safe no-op when disabled
// or when no webhooks are configured; URLs are read from env vars at send time.
builder.Services.AddHttpClient("notifications-chat");
// Dedicated client for interaction response_url round-trips. The URL comes
// from the inbound platform payload, so redirects must not be followed:
// a 3xx to a private address would bypass the ValidateWebhookUrl blocklist.
builder.Services.AddHttpClient("interactions-response")
    .ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler
    {
        AllowAutoRedirect = false,
    });
builder.Services.AddSingleton<INotificationProvider>(sp =>
{
    var logger = sp.GetRequiredService<ILogger<ChatNotificationProvider>>();
    Func<ChatProviderOptions> optsAccessor = () =>
        sp.GetRequiredService<IOptionsMonitor<NotificationsOptions>>().CurrentValue.Chat;
    var opts = optsAccessor();
    if (opts.Enabled)
    {
        var httpClient = sp.GetRequiredService<IHttpClientFactory>().CreateClient("notifications-chat");
        return new ChatNotificationProvider(optsAccessor, httpClient, logger);
    }
    return new NullNotificationProvider("chat");
});

// Shared baseline-bake failure tracker: the Incus provider records every
// bake failure here (and clears on success); /queue/status and the
// baseline_provisioning_blocked notification condition read it. A singleton
// (not a provider interface) so admission-control wrappers cannot hide it.
builder.Services.AddSingleton<BaselineProvisioningBlockedTracker>();
builder.Services.AddSingleton<IBaselineProvisioningBlockedStatusProvider>(
    sp => sp.GetRequiredService<BaselineProvisioningBlockedTracker>());

// ICondition registrations — one per supported condition.
builder.Services.AddSingleton<ICondition, QueueEmptyCondition>();
builder.Services.AddSingleton<ICondition>(sp => new AllQuotasExhaustedCondition(
    sp.GetRequiredService<IEnumerable<IAgentQuotaProbe>>(),
    sp.GetRequiredService<IAgentQuotaGate>(),
    sp.GetRequiredService<IAgentRegistry>(),
    sp.GetRequiredService<ILogger<AllQuotasExhaustedCondition>>()));
builder.Services.AddSingleton<ICondition>(sp => new AgentAuthRequiredCondition(
    sp.GetRequiredService<IAgentAuthRequiredAvailabilityReader>(),
    sp.GetRequiredService<IAgentRegistry>()));
builder.Services.AddSingleton<ICondition, WorkItemPermanentlyFailedCondition>();
builder.Services.AddSingleton<ICondition>(sp => new OrchestratorStallCondition(
    sp.GetRequiredService<OrchestratorProgressClock>(),
    sp.GetRequiredService<IOptionsMonitor<NotificationsOptions>>()));
builder.Services.AddSingleton<ICondition, SandboxLeakReapedCondition>();
builder.Services.AddSingleton<ICondition>(sp =>
    new BaselineProvisioningBlockedCondition(
        sp.GetService<IBaselineProvisioningBlockedStatusProvider>()));

// INotificationBuilder registrations — one per condition.
builder.Services.AddSingleton<INotificationBuilder, QueueEmptyNotificationBuilder>();
builder.Services.AddSingleton<INotificationBuilder>(sp => new AllQuotasExhaustedNotificationBuilder(
    sp.GetRequiredService<IEnumerable<IAgentQuotaProbe>>(),
    sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value.QuotaRouter.MinQuotaPct));
builder.Services.AddSingleton<INotificationBuilder>(sp => new AgentAuthRequiredNotificationBuilder(
    sp.GetRequiredService<IAgentAuthRequiredAvailabilityReader>(),
    sp.GetRequiredService<IAgentRegistry>()));
builder.Services.AddSingleton<INotificationBuilder, WorkItemPermanentlyFailedNotificationBuilder>();
builder.Services.AddSingleton<INotificationBuilder>(sp => new OrchestratorStallNotificationBuilder(
    sp.GetRequiredService<IOptionsMonitor<NotificationsOptions>>()));
builder.Services.AddSingleton<INotificationBuilder, SandboxLeakReapedNotificationBuilder>();
builder.Services.AddSingleton<INotificationBuilder>(sp =>
    new BaselineProvisioningBlockedNotificationBuilder(
        sp.GetService<IBaselineProvisioningBlockedStatusProvider>()));

// Rules engine — BackgroundService that evaluates conditions and dispatches.
builder.Services.AddSingleton<NotificationRulesEngine>();
builder.Services.AddHostedService(sp => sp.GetRequiredService<NotificationRulesEngine>());

// --- Inbound interactions ----------------------------------------------------
// One generic endpoint (POST /webhooks/interactions/{provider}) verifies an
// interaction over the raw body before semantic use, then funnels the answer
// through the same pipeline as POST /workitems/{id}/answer. Disabled by
// default: outbound-only deployments expose nothing new.
// Signing secrets resolve from the env var named by each provider's
// SigningSecretEnvVar — never from config values.
builder.Services.Configure<InteractionsOptions>(
    builder.Configuration.GetSection("CodeyBox:Notifications:Interactions"));
builder.Services.AddSingleton<IInteractionDedupStore, InMemoryInteractionDedupStore>();
builder.Services.AddSingleton<IInteractionVerifier>(sp =>
    new HmacInteractionVerifier("generic", Program.InteractionProviderOpts(sp, "generic")));
builder.Services.AddSingleton<IInteractionVerifier>(sp =>
    new SlackInteractionVerifier("slack", Program.InteractionProviderOpts(sp, "slack")));
builder.Services.AddSingleton<IInteractionVerifier>(sp =>
    new NtfyInteractionVerifier("ntfy", Program.InteractionProviderOpts(sp, "ntfy")));
builder.Services.AddSingleton<IBotFrameworkSigningKeyProvider>(sp =>
    new HttpBotFrameworkSigningKeyProvider(sp.GetRequiredService<IHttpClientFactory>()));
builder.Services.AddSingleton<IInteractionVerifier>(sp =>
    new TeamsInteractionVerifier(
        "teams",
        Program.InteractionProviderOpts(sp, "teams"),
        keyProvider: sp.GetRequiredService<IBotFrameworkSigningKeyProvider>()));
builder.Services.AddSingleton<IInteractionVerifier>(sp =>
    new DiscordInteractionVerifier("discord", Program.InteractionProviderOpts(sp, "discord")));

// --- Changelog automation ----------------------------------------------------
// Named HTTP client for direct Anthropic Messages API calls (changelog generation).
// Reuses api.anthropic.com which is already in AgentAllowedHosts; this client is
// used only from the API process, not from sandbox agents.
builder.Services.AddHttpClient("changelog-claude", client =>
{
    client.Timeout = TimeSpan.FromSeconds(60);
});

builder.Services.AddSingleton<IPullRequestEnumerator>(sp =>
    new CodeyBox.Upstream.GitHub.GitHubPullRequestEnumerator(
        sp.GetRequiredService<IHttpClientFactory>(),
        sp.GetRequiredService<ILogger<CodeyBox.Upstream.GitHub.GitHubPullRequestEnumerator>>()));

builder.Services.AddSingleton<IChangelogGenerator>(sp =>
{
    var monitor = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>();
    return new ClaudeChangelogGenerator(
        sp.GetRequiredService<ICompletionClient>(),
        sp.GetRequiredService<ILogger<ClaudeChangelogGenerator>>(),
        () => monitor.CurrentValue.Changelog);
});

// Changelog webhook HMAC secret — mirrors the SandboxProvider enforcement pattern.
// Changelog automation is opt-in (ChangelogOptions.Enabled defaults to false):
// when disabled the secret is not required and an unconfigured install starts
// cleanly. When enabled outside Development the secret env-var MUST be
// configured so that the POST /webhooks/github/release endpoint always
// validates HMAC signatures.
ValidateChangelogWebhookConfiguration(builder.Configuration, builder.Environment);

// --- SignalR (live agent stdout) ----------------------------------------------
// AgentStdoutHub requires no additional packages on ASP.NET Core 8+.
// Auth is enforced by the existing ApiKeyAuth middleware on the HTTP upgrade
// request — the hub itself needs no [Authorize] attribute because no ASP.NET
// Core authentication scheme is registered.
builder.Services.AddSignalR();
builder.Services.AddSingleton<AgentStdoutBroadcastService>();
builder.Services.AddSingleton<IStdoutBroadcaster>(sp =>
    sp.GetRequiredService<AgentStdoutBroadcastService>());
builder.Services.AddSingleton<IAgentSupervisionNotifier>(sp =>
    sp.GetRequiredService<AgentStdoutBroadcastService>());
builder.Services.AddSingleton<IAgentSupervisionService>(sp => new AgentSupervisionService(
    () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.AgentSupervision,
    sp.GetRequiredService<IAgentSupervisionNotifier>(),
    sp.GetRequiredService<ILogger<AgentSupervisionService>>(),
    Log.Logger));

// --- Audit timeline reader ---------------------------------------------------
builder.Services.AddSingleton(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value.AuditLog;
    return new AuditLogTimelineReader(opts);
});

// --- Persistence + queue + pipeline + worker pool ----------------------------
// Release store must be created BEFORE the work-item store so the releases
// table (referenced by work_items.release_id FK index) is present first.
builder.Services.AddSingleton<IReleaseStore>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteReleaseStore(
        opts.StateDatabasePath,
        sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
builder.Services.AddSingleton<Func<IReleaseStore?>>(sp => () => sp.GetService<IReleaseStore>());
builder.Services.AddSingleton<SqliteWorkItemStore>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteWorkItemStore(
        opts.StateDatabasePath,
        writeGateFactory: sp.GetRequiredService<SqliteDatabaseWriteGateFactory>(),
        // Lazy accessor: the failure-event store points at the same file and is
        // resolved on demand so the two stores have no construction-order coupling.
        failureEventStore: () => sp.GetService<IFailureEventStore>());
});
builder.Services.AddSingleton<IWorkItemStore>(sp => sp.GetRequiredService<SqliteWorkItemStore>());
builder.Services.AddSingleton<IAuditProgressStore>(sp => sp.GetRequiredService<SqliteWorkItemStore>());
builder.Services.AddSingleton<IIdempotencyStore>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteIdempotencyStore(
        opts.StateDatabasePath,
        sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
builder.Services.AddSingleton<ISuggestionStore>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteSuggestionStore(
        opts.StateDatabasePath,
        sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
// --- Work-item attachments ---------------------------------------------------
// Metadata index lives next to the work-item rows in state.db; blobs live on
// disk under a content-addressed root (default ~/.codeybox/attachments).
builder.Services.AddSingleton<SqliteWorkItemAttachmentStore>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteWorkItemAttachmentStore(opts.StateDatabasePath);
});
builder.Services.AddSingleton<IWorkItemAttachmentStore>(sp =>
    sp.GetRequiredService<SqliteWorkItemAttachmentStore>());
builder.Services.AddSingleton<HostWorkItemAttachmentBlobStore>(sp =>
{
    var monitor = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>();
    return new HostWorkItemAttachmentBlobStore(
        () => AttachmentsOptions.ResolveRoot(monitor.CurrentValue.Attachments.RootDirectory),
        sp.GetService<ILogger<HostWorkItemAttachmentBlobStore>>());
});
builder.Services.AddSingleton<IWorkItemAttachmentBlobStore>(sp =>
    sp.GetRequiredService<HostWorkItemAttachmentBlobStore>());
builder.Services.AddSingleton<IWorkItemAttachmentBlobStoreAdmin>(sp =>
    sp.GetRequiredService<HostWorkItemAttachmentBlobStore>());
builder.Services.AddHostedService(sp => new AttachmentCleanupService(
    sp.GetRequiredService<IWorkItemAttachmentStore>(),
    sp.GetRequiredService<IWorkItemAttachmentBlobStoreAdmin>(),
    () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.Attachments,
    sp.GetRequiredService<ILogger<AttachmentCleanupService>>()));
builder.Services.AddSingleton<IWorkItemQuestionStore>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteWorkItemQuestionStore(
        opts.StateDatabasePath,
        sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
builder.Services.AddSingleton<IHumanDeploymentReviewStore>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteHumanDeploymentReviewStore(
        opts.StateDatabasePath,
        sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
builder.Services.AddHostedService(sp => new HumanDeploymentReviewSweeper(
    sp.GetService<IHumanDeploymentReviewStore>(),
    sp.GetService<IDeploymentManager>(),
    sp.GetService<IWorkItemStore>(),
    sp.GetService<IWorkItemQuestionStore>(),
    sp.GetService<ITaskQueue>(),
    sp.GetService<IWebhookDispatcher>(),
    sp.GetService<Func<HumanDeploymentReviewOptions>>(),
    TimeProvider.System,
    sp.GetService<ILogger<HumanDeploymentReviewSweeper>>()));
builder.Services.AddSingleton<ITestCaseStore>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteTestCaseStore(
        opts.StateDatabasePath,
        sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
builder.Services.AddSingleton<IE2eRunStore>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteE2eRunStore(
        opts.StateDatabasePath,
        sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
builder.Services.AddSingleton<IE2eReplayRuntime, E2eReplayRuntime>();
builder.Services.AddSingleton<E2eReplayArtifactAdmissionValidator>();
builder.Services.AddSingleton<E2eRunCancellationRegistry>();
// E2E pool selection is deliberately independent of the coding pipeline's
// admitted ISandboxProvider. PoolKind=remote-ssh builds the existing
// multipass-over-SSH provider; PoolKind=local builds an unwrapped provider
// for development only.
builder.Services.AddSingleton<IE2eExecutionPool>(BuildE2eExecutionPool);
builder.Services.AddHostedService<E2eRunDispatcher>();
// Post-implementation e2e-replay gate. The verifier enqueues a replay run and
// observes it via the same IE2eRunStore the dispatcher drains (cheap-CPU E2E
// pool, never the coding fleet). The gate authors missing replays through the
// optional IE2eReplayAuthoringDriver seam — resolved via GetService so the gate
// degrades to fail-closed (a declared case with no working replay blocks) when
// no deployment-specific driver is wired. Both are consumed by PipelineRunner
// and self-gate on E2eReplayAuthoringOptions.Enabled (off by default).
builder.Services.AddSingleton<IE2eReplayVerifier>(sp => new E2eRunReplayVerifier(
    sp.GetRequiredService<IE2eRunStore>(),
    sp.GetRequiredService<IOptionsMonitor<E2eReplayAuthoringOptions>>(),
    logger: sp.GetRequiredService<ILogger<E2eRunReplayVerifier>>()));
builder.Services.AddSingleton<WorkItemE2eReplayGate>(sp => new WorkItemE2eReplayGate(
    sp.GetRequiredService<ITestCaseStore>(),
    sp.GetRequiredService<IE2eReplayVerifier>(),
    sp.GetRequiredService<IOptionsMonitor<E2eReplayAuthoringOptions>>(),
    driver: sp.GetService<IE2eReplayAuthoringDriver>(),
    logger: sp.GetRequiredService<ILogger<WorkItemE2eReplayGate>>()));
// Best-effort JobTrack test-case export: an item's CodeyBox test cases are
// pushed to JobTrack on the terminal Done transition, but only for projects that
// opt in (Project.JobTrackExport.Enabled). The HTTP client is a named factory
// client so its handler/timeout are shared and the bearer token stays per-request.
builder.Services.AddHttpClient(HttpJobTrackTestCaseClient.HttpClientName, client =>
{
    client.Timeout = TimeSpan.FromSeconds(30);
});
builder.Services.AddSingleton<IJobTrackTestCaseClient>(sp => new HttpJobTrackTestCaseClient(
    sp.GetRequiredService<IHttpClientFactory>()));
builder.Services.AddSingleton<IJobTrackTestCaseExporter>(sp => new JobTrackTestCaseExporter(
    sp.GetRequiredService<ITestCaseStore>(),
    sp.GetRequiredService<IJobTrackTestCaseClient>(),
    sp.GetRequiredService<ILogger<JobTrackTestCaseExporter>>()));
builder.Services.AddSingleton<IAuditReportStore>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteAuditReportStore(
        opts.StateDatabasePath,
        sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
// Opt-in audit check-run publication (forge Checks API). Disabled by default
// at both the global section and the per-project flag; the singletons below
// are inert until an operator enables them, so registration changes no live
// behavior, merge gating, or credentials. Options hot-reload via the monitor.
builder.Services.AddSingleton<IValidateOptions<AuditCheckPublicationOptions>, AuditCheckPublicationOptionsValidator>();
builder.Services.AddOptions<AuditCheckPublicationOptions>()
    .Bind(builder.Configuration.GetSection(AuditCheckPublicationOptions.SectionName))
    .ValidateOnStart();
builder.Services.AddSingleton<IAuditCheckPublicationStore>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteAuditCheckPublicationStore(
        opts.StateDatabasePath,
        sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
builder.Services.AddSingleton<AuditCheckPublicationService>(sp =>
{
    var monitor = sp.GetRequiredService<IOptionsMonitor<AuditCheckPublicationOptions>>();
    return new AuditCheckPublicationService(
        sp.GetRequiredService<IAuditReportStore>(),
        sp.GetRequiredService<IAuditCheckPublicationStore>(),
        () => monitor.CurrentValue,
        TimeProvider.System,
        sp.GetRequiredService<ILogger<AuditCheckPublicationService>>());
});
// Standalone audit runs: durable run store shares state.db; artifacts live
// on disk next to it. The workspace factory defaults to visibly-unavailable
// (missing provider fails the run, never passes it); the executor default
// below only runs registered tool auditors through caller-provided sandboxes
// and is reached solely via the disabled-by-default standalone path.
builder.Services.AddSingleton<IAuditRunStore>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteAuditRunStore(
        opts.StateDatabasePath,
        sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
builder.Services.AddSingleton<IAuditRunArtifactStore>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    var monitor = sp.GetRequiredService<IOptionsMonitor<AuditRunOptions>>();
    var dir = Path.Combine(Path.GetDirectoryName(opts.StateDatabasePath) ?? ".", "audit-run-artifacts");
    return new FileAuditRunArtifactStore(dir, monitor.CurrentValue.MaxArtifactBytes);
});
builder.Services.AddSingleton<IStandaloneAuditRefResolver, ExplicitShaAuditRefResolver>();
builder.Services.AddSingleton<IAuditorRegistry>(sp => new AuditorRegistry(sp.GetServices<IAuditor>()));
builder.Services.AddSingleton<IStandaloneAuditWorkspaceFactory>(sp =>
    new UnavailableAuditWorkspaceFactory("No standalone-audit workspace provider is configured."));
builder.Services.AddSingleton<IStandaloneAuditExecutor, DirectSandboxAuditExecutor>();
builder.Services.AddSingleton<StandaloneAuditService>();
builder.Services.AddSingleton<ITimingStore>(sp =>
{
    // Timing rows have a foreign key to work_items. Ensure the primary store
    // has initialized that shared schema even when a sandbox provider resolves
    // ITimingStore before any endpoint resolves IWorkItemStore.
    _ = sp.GetRequiredService<SqliteWorkItemStore>();
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteTimingStore(
        opts.StateDatabasePath,
        sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
builder.Services.AddSingleton<IFailureEventStore>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteFailureEventStore(
        opts.StateDatabasePath,
        sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
builder.Services.AddSingleton<IDelegationEventStore>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteDelegationEventStore(
        opts.StateDatabasePath,
        optionsAccessor: () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.Delegation,
        writeGateFactory: sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
// Secret-lease handles (identity only, never values). The SQLite table
// survives orchestrator restarts so the reconciliation sweep resumes
// renewal/revocation instead of orphaning live leases.
builder.Services.AddSingleton<ISecretLeaseStore>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteSecretLeaseStore(
        opts.StateDatabasePath,
        sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
builder.Services.AddSingleton<SecretLeaseManager>(sp => new SecretLeaseManager(
    sp.GetRequiredService<ISecretLeaseStore>(),
    sp.GetServices<ILeaseCapableSecretProvider>(),
    options: () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.SecretLeasing,
    log: sp.GetRequiredService<ILogger<SecretLeaseManager>>()));
// Factory registration (not AddHostedService): the sweep reads its knobs
// through a hot-reloadable accessor so SecretLeasing edits apply without
// restart, mirroring the other option-accessor services.
builder.Services.AddSingleton<IHostedService>(sp => new SecretLeaseReconciliationService(
    sp.GetRequiredService<SecretLeaseManager>(),
    sp.GetRequiredService<ISecretLeaseStore>(),
    sp.GetRequiredService<IWorkItemStore>(),
    options: () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.SecretLeasing,
    log: sp.GetRequiredService<ILogger<SecretLeaseReconciliationService>>()));
builder.Services.AddSingleton<ISandboxResourceUsageStore>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteSandboxResourceUsageStore(
        opts.StateDatabasePath,
        sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
builder.Services.AddSingleton<IWorkItemCostStore>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteWorkItemCostStore(
        opts.StateDatabasePath,
        sp.GetRequiredService<AgentCostCalculator>(),
        sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
builder.Services.AddSingleton<IAgentUsageStore>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteAgentUsageStore(
        opts.StateDatabasePath,
        sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
builder.Services.AddSingleton<IAgentStreamSummaryStore>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteAgentStreamSummaryStore(
        opts.StateDatabasePath,
        sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
builder.Services.AddSingleton<IQueueController>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteQueueController(
        opts.StateDatabasePath,
        sp.GetRequiredService<ILogger<SqliteQueueController>>(),
        sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
builder.Services.AddSingleton<SqliteAgentPauseController>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteAgentPauseController(
        opts.StateDatabasePath,
        sp.GetRequiredService<ILogger<SqliteAgentPauseController>>(),
        TimeProvider.System,
        sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
builder.Services.AddSingleton<IAgentPauseController>(sp =>
    sp.GetRequiredService<SqliteAgentPauseController>());
builder.Services.AddSingleton<IAgentPauseSignal>(sp =>
    sp.GetRequiredService<SqliteAgentPauseController>());
builder.Services.AddSingleton<InMemoryTaskQueue>();
builder.Services.AddSingleton<ITaskQueue>(sp => sp.GetRequiredService<InMemoryTaskQueue>());
builder.Services.AddSingleton<WorkItemCreationService>();
builder.Services.AddSingleton(sp => new WorkItemCommandService(
    sp.GetRequiredService<IWorkItemStore>(),
    sp.GetRequiredService<ITaskQueue>(),
    sp.GetRequiredService<IProjectRepository>(),
    sp.GetRequiredService<IAgentRegistry>(),
    sp.GetRequiredService<IKnobRegistry>(),
    sp.GetRequiredService<IWorkerRegistry>(),
    sp.GetRequiredService<AgentClassRouter>(),
    sp.GetRequiredService<CancellationRegistry>(),
    sp.GetRequiredService<IWebhookDispatcher>(),
    sp.GetRequiredService<WorkItemRetrier>(),
    sp.GetRequiredService<ItemStaleProgressWatchdog>(),
    sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>(),
    sp.GetService<ITimingStore>(),
    sp.GetService<WorkItemRepoReaper>()));
builder.Services.AddSingleton<ITaskTemplateRegistry, FileTaskTemplateRegistry>();

// --- Dead-worker registry + reaper -------------------------------------------
builder.Services.AddSingleton<IWorkerRegistry>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteWorkerRegistry(
        opts.StateDatabasePath,
        sp.GetRequiredService<ILogger<SqliteWorkerRegistry>>(),
        writeGateFactory: sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
builder.Services.AddSingleton<DeadWorkerOptions>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value.DeadWorker;
    opts.Validate();
    return opts;
});
builder.Services.AddSingleton<DeadWorkerReaper>(sp =>
{
    // Resolve DeadWorkerOptions through the live CodeyBoxOptions monitor on
    // every sweep. Edits to CodeyBox:DeadWorker:MaxRecoveryAttempts (and
    // DeadWorkerThreshold) take effect on the next sweep without restart.
    // CheckInterval is sampled at PeriodicTimer construction so changes
    // require a restart — documented on the field itself.
    var monitor = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>();
    // Run the same Validate() startup check on the resolved value once so
    // misconfigured DeadWorkerOptions surfaces here (matches the previous
    // factory behaviour where DeadWorkerOptions.Validate() ran at resolve time).
    sp.GetRequiredService<DeadWorkerOptions>();
    return new DeadWorkerReaper(
        sp.GetRequiredService<IWorkerRegistry>(),
        sp.GetRequiredService<IWorkItemStore>(),
        sp.GetRequiredService<ITaskQueue>(),
        () => monitor.CurrentValue.DeadWorker,
        sp.GetRequiredService<ILogger<DeadWorkerReaper>>(),
        sp.GetRequiredService<IWebhookDispatcher>(),
        startupRecoveryBarrier: sp.GetRequiredService<IStartupInitialRecoveryBarrier>(),
        cancellationRegistry: sp.GetRequiredService<CancellationRegistry>());
});
// --- Abandoned temp-entry startup sweep ------------------------------------
// One-shot reap of stale codeybox-* entries in the system temp path left by
// previous deployments and test runs. Runs once at host startup so a tmpfs
// /tmp cannot accumulate RAM-pinning backlog across restarts. It only
// removes entries whose newest write is older than the configured max age,
// so it never interferes with live dispatch. Never fails startup — sweep
// faults are logged.
builder.Services.AddHostedService(sp => new TempSweepStartupService(
    () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.TempSweep,
    sp.GetService<TimeProvider>(),
    sp.GetRequiredService<ILogger<TempSweepStartupService>>(),
    sp.GetRequiredService<ILogger<TempFileSweeper>>()));
builder.Services.AddSingleton<WorkItemRepoReaper>(sp =>
{
    var monitor = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>();
    return new WorkItemRepoReaper(
        sp.GetRequiredService<IGitHost>(),
        sp.GetRequiredService<IWorkItemStore>(),
        () => monitor.CurrentValue.RepoRetention,
        sp.GetRequiredService<ILogger<WorkItemRepoReaper>>(),
        time: sp.GetService<TimeProvider>() ?? TimeProvider.System,
        workerRegistry: sp.GetService<IWorkerRegistry>());
});

// --- Worker progress watchdog -----------------------------------------------
// Lifecycle-wide progress enforcer that complements the dead-worker reaper
// (heartbeat-stale path) and WorkTimeout (agent subprocess only). Trips when
// a bound worker is heartbeating but its item shows no progress: item.updatedAt,
// agent-stream mtime, process CPU, and sandbox activity signals are all stale.
builder.Services.AddSingleton<WorkerProgressWatchdogOptions>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value.WorkerProgressWatchdog;
    opts.Validate();
    return opts;
});
builder.Services.AddSingleton<IActiveSandboxProgressProvider>(sp =>
    sp.GetRequiredService<ISandboxProvider>() as IActiveSandboxProgressProvider
    ?? NullActiveSandboxProgressProvider.Instance);
builder.Services.AddSingleton<IWorkerProgressActivitySource>(sp =>
    new DefaultWorkerProgressActivitySource(sp.GetRequiredService<IActiveSandboxProgressProvider>()));
builder.Services.AddSingleton<WorkerProgressWatchdog>(sp =>
{
    var monitor = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>();
    // Validate the startup-resolved value here too so a misconfigured options
    // block surfaces at DI resolve time, matching the reaper's pattern.
    sp.GetRequiredService<WorkerProgressWatchdogOptions>();
    return new WorkerProgressWatchdog(
        sp.GetRequiredService<IWorkerRegistry>(),
        sp.GetRequiredService<IWorkItemStore>(),
        sp.GetRequiredService<ITaskQueue>(),
        () => monitor.CurrentValue.WorkerProgressWatchdog,
        sp.GetRequiredService<ILogger<WorkerProgressWatchdog>>(),
        sp.GetService<IAgentStreamStore>(),
        sp.GetService<IWebhookDispatcher>(),
        startupRecoveryBarrier: sp.GetRequiredService<IStartupInitialRecoveryBarrier>(),
        activitySource: sp.GetRequiredService<IWorkerProgressActivitySource>(),
        cancellationRegistry: sp.GetRequiredService<CancellationRegistry>());
});

// --- Dispatcher evaluation record -------------------------------------------
// Feeds the item-stale watchdog's dispatch-liveness guard (and queue
// status): the orchestrator notes every deferral/pickup here so a frozen
// UpdatedAt behind quota/cap reads as waiting, not wedged.
builder.Services.AddSingleton<DispatchItemLivenessTracker>();
builder.Services.AddSingleton<IItemDispatchLivenessSource>(
    sp => sp.GetRequiredService<DispatchItemLivenessTracker>());

// --- Per-item stale-updatedAt watchdog --------------------------------------
// Item-centric counterpart to WorkerProgressWatchdog: walks items by state
// (not by the worker registry) and treats an item as wedged when its
// UpdatedAt is frozen past ItemStaleTimeout AND its agent shows no other
// liveness (no recent agent-stream append, no newly-observed sandbox
// activity). Heartbeat / CPU activity alone never counts — that is the
// reconnect-loop wedge this detector owns. Also powers POST /workitems/{id}/recover.
builder.Services.AddSingleton<ItemStaleProgressWatchdog>(sp =>
{
    var monitor = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>();
    sp.GetRequiredService<WorkerProgressWatchdogOptions>();
    return new ItemStaleProgressWatchdog(
        sp.GetRequiredService<IWorkItemStore>(),
        sp.GetRequiredService<ITaskQueue>(),
        sp.GetRequiredService<IWorkerRegistry>(),
        () => monitor.CurrentValue.WorkerProgressWatchdog,
        sp.GetRequiredService<ILogger<ItemStaleProgressWatchdog>>(),
        sp.GetService<IWebhookDispatcher>(),
        startupRecoveryBarrier: sp.GetRequiredService<IStartupInitialRecoveryBarrier>(),
        // Recovery cancels the running pipeline's CT so its finally blocks
        // tear down the active sandbox / VM. Without this the wedged worker
        // can keep running on a row that has been requeued to a fresh slot.
        cancellations: sp.GetRequiredService<CancellationRegistry>(),
        // Liveness inputs for the stale-vs-alive decision: a frozen UpdatedAt
        // with a still-appending stream is a long turn, not a hang. Both are
        // optional — without them the detector falls back to UpdatedAt-only.
        streams: sp.GetService<IAgentStreamStore>(),
        activitySource: sp.GetService<IWorkerProgressActivitySource>(),
        // Dispatcher evaluations (quota / cap / budget deferrals, pickups):
        // a frozen no-worker item the dispatcher is actively deferring is
        // waiting, not stale. Optional — without it the detector falls back
        // to UpdatedAt-only for no-worker items.
        dispatchLiveness: sp.GetRequiredService<IItemDispatchLivenessSource>());
});

// --- Worker pool health watchdog --------------------------------------------
// Dispatcher-level watchdog for a pool that is under-filled while runnable work
// and an available agent exist. Complements WorkerProgressWatchdog, which owns
// per-worker lifecycle stalls after a worker has already been spawned.
builder.Services.AddSingleton<WorkerPoolHealthWatchdogOptions>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value.WorkerPoolHealthWatchdog;
    opts.Validate();
    return opts;
});
builder.Services.AddSingleton<WorkerPoolHealthWatchdog>(sp =>
{
    var monitor = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>();
    sp.GetRequiredService<WorkerPoolHealthWatchdogOptions>();
    return new WorkerPoolHealthWatchdog(
        sp.GetRequiredService<IWorkerPoolHealthSource>(),
        () => monitor.CurrentValue.WorkerPoolHealthWatchdog,
        sp.GetRequiredService<ILogger<WorkerPoolHealthWatchdog>>(),
        quotaRecovery: sp.GetRequiredService<IWorkerPoolQuotaRecovery>(),
        webhooks: sp.GetService<IWebhookDispatcher>(),
        startupRecoveryBarrier: sp.GetRequiredService<IStartupInitialRecoveryBarrier>());
});

// --- Agent cost extractors + calculator ------------------------------------
builder.Services.AddSingleton<IReadOnlyDictionary<AgentKind, IAgentCostExtractor>>(sp =>
{
    var startupLog = sp.GetRequiredService<ILoggerFactory>().CreateLogger("CodeyBox.AgentCosts");
    var registry = sp.GetRequiredService<IAgentRegistry>();
    var extractors = new Dictionary<AgentKind, IAgentCostExtractor>
    {
        [AgentKind.Claude] = new ClaudeCostExtractor(),
        [AgentKind.Codex] = new CodexCostExtractor(),
        [AgentKind.Gemini] = new GeminiCostExtractor(),
        [AgentKind.Cursor] = new CursorCostExtractor(),
        [AgentKind.Opencode] = new OpencodeCostExtractor(),
        [AgentKind.Copilot] = new CopilotCostExtractor(),
        [AgentKind.Antigravity] = new AntigravityCostExtractor(),
        [AgentKind.Crock] = new CrockCostExtractor(),
        [AgentKind.Pi] = new PiCostExtractor(),
        [AgentKind.Aider] = new AiderCostExtractor(),
        [AgentKind.Goose] = new GooseCostExtractor(),
        [AgentKind.Vibe] = new VibeCostExtractor(),
        [AgentKind.Prime] = new PrimeCostExtractor(),
        [AgentKind.DotNetOpencode] = new DotNetOpencodeCostExtractor(),
        [AgentKind.CavemanCode] = new CavemanCodeCostExtractor(),
        [AgentKind.Autohand] = new AutohandCostExtractor(),
        [AgentKind.Cline] = new ClineCostExtractor(),
        [AgentKind.Kilo] = new KiloCostExtractor(),
        [AgentKind.Omp] = new OmpCostExtractor(),
        [AgentKind.Continue] = new ContinueCostExtractor(),
        [AgentKind.Qwen] = new QwenCostExtractor(),
        [AgentKind.Cmd] = new CmdCostExtractor(),
        [AgentKind.Crush] = new CrushCostExtractor(),
        [AgentKind.Devin] = new DevinCostExtractor(),
        [AgentKind.Unreal] = new UnrealCostExtractor(),
    };
    // Warn once at startup for registered agents with no extractor.
    foreach (var kind in registry.Available)
    {
        if (!extractors.ContainsKey(kind))
            startupLog.LogWarning(
                "No cost extractor registered for agent '{Agent}'; token usage will not be extracted, but completed invocations still record elapsed fallback cost rows", kind.Value);
    }
    return extractors;
});
// Bundled per-(agent, model) pricing defaults shipped with CodeyBox so new
// installs get cost reporting without the operator hand-populating every
// entry from provider docs. Operator config under CodeyBox:AgentPricing
// always wins per (agentKind, modelId). See docs/operating/costs.md.
builder.Services.AddSingleton<AgentPricingDefaultsSnapshot>(sp =>
{
    var env = sp.GetRequiredService<IHostEnvironment>();
    return AgentPricingDefaults.Load(env.ContentRootPath);
});
builder.Services.AddSingleton<AgentPricingState>(sp =>
{
    var defaults = sp.GetRequiredService<AgentPricingDefaultsSnapshot>();
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    var merged = AgentPricingMerge.Merge(defaults.Baseline, opts.AgentPricing);
    return new AgentPricingState(defaults, merged);
});
builder.Services.AddSingleton<AgentCostCalculator>(sp =>
{
    var pricingState = sp.GetRequiredService<AgentPricingState>();
    var merged = pricingState.LastMerge;
    var defaults = pricingState.Defaults;
    var startupLog = sp.GetRequiredService<ILoggerFactory>().CreateLogger("CodeyBox.AgentPricing");
    startupLog.LogInformation(
        "AgentPricing loaded: bundled={Bundled}, operator-overrides={Operator}, total={Total} (bundled lastUpdated={LastUpdated})",
        merged.BundledRateCount, merged.OperatorRateCount, merged.TotalRateCount,
        string.IsNullOrEmpty(defaults.Meta.LastUpdated) ? "(unknown)" : defaults.Meta.LastUpdated);
    var extractors = sp.GetRequiredService<IReadOnlyDictionary<AgentKind, IAgentCostExtractor>>();
    AgentCostCalculator.ValidateAtStartup(merged.Options,
        sp.GetRequiredService<IAgentRegistry>().Available, extractors, startupLog);
    var calculator = new AgentCostCalculator(
        new AgentPricingOptions(),
        extractors,
        sp.GetRequiredService<CodeyBox.Core.AgentDefaultsSnapshot>());
    pricingState.ApplySuccessfulMerge(merged, calculator);
    return calculator;
});
// AgentStreamsOptions and IAgentStreamStore register in the shared
// agent-execution composition both hosts call.
// AgentStreamParserOptions guard registers in the shared agent-execution
// composition both hosts call.
// IAgentStreamParser catalog registers in the shared agent-execution
// composition both hosts call.
// Per-provider tool-call counters register in the shared agent-execution
// composition both hosts call.

// Quota-failure detectors and the classifier register in the shared
// agent-execution composition both hosts call.
builder.Services.AddSingleton<IAgentAuthFailureClassifier>(sp =>
{
    var cbOpts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return AuthFailurePatternBinder.Build(cbOpts);
});
// Single composition-root point for the auth-required side-effect handler.
// PipelineRunner and ReleaseService consume the abstraction directly so the
// registry / webhook / logger plumbing is not duplicated across both classes.
builder.Services.AddSingleton<IAgentAuthRequiredHandler>(sp =>
    new AgentAuthRequiredHandler(
        sp.GetRequiredService<IAgentAuthAvailabilityRegistry>(),
        sp.GetRequiredService<IWebhookDispatcher>(),
        sp.GetRequiredService<ILoggerFactory>().CreateLogger<AgentAuthRequiredHandler>()));

builder.Services.AddSingleton<PipelineOptions>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    var startupLog = sp.GetRequiredService<ILoggerFactory>().CreateLogger("CodeyBox.GitIdentity");
    var hostIdentity = HostGitIdentityReader.Read(startupLog);
    return new PipelineOptions
    {
        SandboxImageReference = opts.SandboxImageReference,
        AgentAllowedHosts = opts.AgentAllowedHosts,
        AuditToolAllowedHosts = opts.AuditToolAllowedHosts,
        UpstreamPushMaxAttempts = opts.UpstreamPushMaxAttempts,
        UpstreamPushBackoff = TimeSpan.FromSeconds(opts.UpstreamPushBackoffSeconds),
        ShutdownGrace = TimeSpan.FromSeconds(Math.Max(1, opts.Shutdown.GraceSeconds)),
        PhaseAbsoluteTimeoutMultiplier = opts.PhaseAbsoluteTimeoutMultiplier,
        RequiredBuildVerificationTimeout = TimeSpan.FromSeconds(Math.Max(60, opts.RequiredBuildVerificationTimeoutSeconds)),
        EmitPlanTestCases = opts.EmitPlanTestCases,
        HostGitIdentity = hostIdentity,
        MaxFailureDetailBytes = opts.MaxFailureDetailBytes > 0 ? opts.MaxFailureDetailBytes : SanitizedAgentDetail.DefaultTailMaxBytes,
    };
});
builder.Services.AddSingleton<WorkItemRetrier>(sp => new WorkItemRetrier(
    sp.GetRequiredService<IWorkItemStore>(),
    sp.GetRequiredService<ITaskQueue>(),
    sp.GetRequiredService<IGitHost>(),
    sp.GetRequiredService<ILogger<WorkItemRetrier>>(),
    sp.GetRequiredService<IAgentStreamSummaryStore>(),
    sp.GetRequiredService<IProjectRepository>(),
    sp.GetRequiredService<IReleaseStore>(),
    sp.GetService<IWorkItemQuestionStore>(),
    sp.GetRequiredService<IAuditProgressStore>(),
    sp.GetRequiredService<IBaselineImageResolver>()));

// Shared stale-base remediation router used by both the pipeline's
// upstream-push path and the out-of-band StalePullRequestSweeper. Reads the
// same hot-reloadable StalePullRequestSweep options so the enable flag and
// attempt cap have a single source of truth.
builder.Services.AddSingleton<StaleBaseConflictReworkRouter>(sp => new StaleBaseConflictReworkRouter(
    sp.GetRequiredService<IWorkItemStore>(),
    sp.GetRequiredService<WorkItemRetrier>(),
    () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.StalePullRequestSweep,
    sp.GetRequiredService<ILogger<StaleBaseConflictReworkRouter>>()));
builder.Services.AddOptions<CheckAndActCompletionOptions>()
    .Bind(builder.Configuration.GetSection("CodeyBox:CheckAndActCompletion"));
builder.Services.AddOptions<CompletionClientOptions>()
    .Bind(builder.Configuration.GetSection(CompletionClientOptions.SectionName));
builder.Services.AddSingleton<ICompletionClient>(sp =>
    new CompletionClient(
        sp.GetRequiredService<IHttpClientFactory>(),
        sp.GetRequiredService<IOptionsMonitor<CompletionClientOptions>>(),
        sp.GetRequiredService<ILogger<CompletionClient>>()));
builder.Services.AddSingleton<ICheckAndActCompletionRunner>(sp =>
    new DefaultCheckAndActCompletionRunner(
        sp.GetRequiredService<IHttpClientFactory>(),
        sp.GetRequiredService<IOptionsMonitor<CheckAndActCompletionOptions>>(),
        sp.GetRequiredService<ILogger<DefaultCheckAndActCompletionRunner>>(),
        sp.GetRequiredService<ICompletionClient>()));

builder.Services.AddSingleton<WorkItemTerminalTransition>(sp => new WorkItemTerminalTransition(
    sp.GetRequiredService<IWorkItemStore>(),
    sp.GetRequiredService<IWebhookDispatcher>(),
    sp.GetRequiredService<IProjectRepository>(),
    sp.GetRequiredService<ILogger<WorkItemTerminalTransition>>()));
builder.Services.AddSingleton<IWorkItemTerminalTransition>(sp =>
    sp.GetRequiredService<WorkItemTerminalTransition>());
builder.Services.AddSingleton<IWorkItemTerminalRevisionBuilder>(sp =>
    sp.GetRequiredService<WorkItemTerminalTransition>());
// Base-broken attribution + containment: the verifier sandbox-builds the
// base tip through the same IRequiredBuildVerifier path (verdicts cached
// per SHA); the tracker owns the durable project condition, the per-SHA
// fix-item dedupe, and the dispatcher hold; the monitor clears conditions
// once the base tip builds again.
builder.Services.AddSingleton<IBaseBrokenConditionStore>(sp =>
{
    var opts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    return new SqliteBaseBrokenConditionStore(
        opts.StateDatabasePath,
        sp.GetRequiredService<ILogger<SqliteBaseBrokenConditionStore>>(),
        sp.GetRequiredService<SqliteDatabaseWriteGateFactory>());
});
builder.Services.AddSingleton<BaseBuildVerifier>(sp => new BaseBuildVerifier(
    sp.GetRequiredService<IRequiredBuildVerifier>(),
    sp.GetRequiredService<IToolchainFaultClassifier>(),
    sp.GetRequiredService<ILogger<BaseBuildVerifier>>()));
builder.Services.AddSingleton<BaseBrokenConditionTracker>(sp => new BaseBrokenConditionTracker(
    sp.GetRequiredService<IBaseBrokenConditionStore>(),
    sp.GetRequiredService<IWorkItemStore>(),
    sp.GetService<ITaskQueue>(),
    sp.GetService<IWebhookDispatcher>(),
    sp.GetService<TimeProvider>(),
    sp.GetRequiredService<ILogger<BaseBrokenConditionTracker>>()));
builder.Services.AddSingleton<IBaseBrokenConditionStatusProvider>(sp =>
    sp.GetRequiredService<BaseBrokenConditionTracker>());
builder.Services.AddSingleton<BaseBrokenMonitorService>(sp => new BaseBrokenMonitorService(
    sp.GetRequiredService<BaseBrokenConditionTracker>(),
    sp.GetRequiredService<BaseBuildVerifier>(),
    sp.GetRequiredService<IGitHost>(),
    sp.GetRequiredService<IProjectRepository>(),
    sp.GetRequiredService<IWorkItemStore>(),
    sp.GetRequiredService<PipelineTuningSnapshot>(),
    sp.GetService<TimeProvider>(),
    sp.GetRequiredService<ILogger<BaseBrokenMonitorService>>()));
builder.Services.AddHostedService(sp => sp.GetRequiredService<BaseBrokenMonitorService>());

builder.Services.AddSingleton<PipelineRunner>(sp => new PipelineRunner(
    sp.GetRequiredService<ISandboxProvider>(),
    sp.GetRequiredService<IGitHost>(),
    sp.GetRequiredService<IAgentRegistry>(),
    sp.GetRequiredService<ICredentialProvider>(),
    sp.GetRequiredService<IPullRequestService>(),
    sp.GetRequiredService<IProjectRepository>(),
    sp.GetRequiredService<IUpstreamRemoteFactory>(),
    sp.GetRequiredService<ProjectAuditorComposer>(),
    sp.GetRequiredService<IWorkItemStore>(),
    sp.GetRequiredService<IWebhookDispatcher>(),
    sp.GetRequiredService<PipelineOptions>(),
    sp.GetRequiredService<ILogger<PipelineRunner>>(),
    sp.GetService<CredentialSmokeGate>(),
    sp.GetService<ISuggestionStore>(),
    sp.GetServices<IAgentQuotaProbe>(),
    sp.GetService<QuotaRouterOptions>(),
    sp.GetRequiredService<IAuditReportStore>(),
    null,
    sp.GetRequiredService<IWorkItemCostStore>(),
    sp.GetRequiredService<IReadOnlyDictionary<AgentKind, IAgentCostExtractor>>(),
    sp.GetRequiredService<AgentCostCalculator>(),
    sp.GetService<IWorkItemQuestionStore>(),
    sp.GetRequiredService<IStdoutBroadcaster>(),
    sp.GetService<IAgentStreamStore>(),
    sp.GetService<IQuotaFailureStore>(),
    sp.GetRequiredService<IWorkItemAutoRetryScheduler>(),
    sp.GetService<AgentClassRouter>(),
    sp.GetService<IAgentFallbackHistoryStore>(),
    sp.GetRequiredService<IQuotaFailureClassifier>(),
    sp.GetRequiredService<IReadOnlyDictionary<AgentKind, IAgentToolCallCounter>>(),
    sp.GetService<ITaskQueue>(),
    sp.GetService<OrchestratorOptions>(),
    sp.GetService<IAgentAvailabilityRegistry>(),
    sp.GetService<IAgentRunningCounters>(),
    sp.GetService<AgentConcurrencyOptions>(),
    sp.GetRequiredService<IPreMergeVerifier>(),
    sp.GetRequiredService<AgentConcurrencySnapshot>(),
    usageStore: sp.GetService<IAgentUsageStore>(),
    budgetProvider: sp.GetService<IAgentBudgetProvider>(),
    incrementalRebase: sp.GetRequiredService<IncrementalRebaseSnapshot>(),
    pipelineTuning: sp.GetRequiredService<PipelineTuningSnapshot>(),
    involvement: sp.GetService<IAgentInvolvementStore>(),
    // Resolve through the live IOptionsMonitor so PostAgentTransitionTimeout
    // edits applied via config hot-reload take effect on the next bounded
    // transition without restart, mirroring the watchdog's own sweep accessor.
    watchdogOptionsAccessor: () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.WorkerProgressWatchdog,
    // Resolve through the live IOptionsMonitor so DefaultWorkTimeoutMinutes
    // edits applied via config hot-reload take effect for subsequently
    // dispatched work without restart, mirroring the watchdog's own sweep accessor.
    defaultWorkTimeoutMinutesAccessor: () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.DefaultWorkTimeoutMinutes,
    requiredBuildVerifier: sp.GetRequiredService<IRequiredBuildVerifier>(),
    toolchainFaultClassifier: sp.GetRequiredService<IToolchainFaultClassifier>(),
    toolchainFaultRecords: sp.GetRequiredService<IToolchainFaultRecordStore>(),
    dispatchAvailability: sp.GetService<IAgentDispatchAvailability>(),
    auditProgress: sp.GetRequiredService<IAuditProgressStore>(),
    agentPauseController: sp.GetRequiredService<IAgentPauseController>(),
    promptPreprocessors: sp.GetRequiredService<AgentPromptPreprocessorChain>(),
    knobRegistry: sp.GetRequiredService<IKnobRegistry>(),
    checkCompletionRunner: sp.GetService<ICheckAndActCompletionRunner>(),
    agentSupervision: sp.GetService<IAgentSupervisionService>(),
    // Resumable session worker (item 3 of the rollout). PipelineRunner
    // sees only the ISessionAgentRunner abstraction and the orchestrator-
    // owned dispatch options; the concrete Claude worker is wired into
    // the abstraction here at the composition root. Composed with
    // Project.ClaudeSession.Enabled and the global Enabled flag — the
    // pipeline keeps the legacy independent-phase path for any item that
    // doesn't opt in to all three.
    sessionAgentRunner: sp.GetService<CodeyBox.Agents.Claude.ClaudeSessionWorker>(),
    sessionDispatchOptions: sp.GetService<CodeyBox.Orchestrator.AgentSessionDispatchOptions>(),
    sessionHandleSnapshot: sp.GetService<CodeyBox.Agents.Claude.ClaudeSessionWorker>() is { } worker
        ? worker.SnapshotPersistedHandle
        : null,
    cancellationRegistry: sp.GetRequiredService<CancellationRegistry>(),
    terminalTransitions: sp.GetRequiredService<IWorkItemTerminalTransition>(),
    terminalRevisionBuilder: sp.GetRequiredService<IWorkItemTerminalRevisionBuilder>(),
    mechanicalFixerComposer: sp.GetRequiredService<ProjectMechanicalFixerComposer>(),
    mechanicalFixerInputProviders: sp.GetServices<IMechanicalFixerInputProvider>(),
    authFailureClassifier: sp.GetRequiredService<IAgentAuthFailureClassifier>(),
    authAvailability: sp.GetRequiredService<IAgentAuthAvailabilityRegistry>(),
    inVmSmokeGate: sp.GetService<IInVmSmokeGate>(),
    authRequiredHandler: sp.GetRequiredService<IAgentAuthRequiredHandler>(),
    authRequiredReader: sp.GetRequiredService<IAgentAuthRequiredAvailabilityReader>(),
    testCaseStore: sp.GetService<ITestCaseStore>(),
    mergeScopeResolver: sp.GetRequiredService<IMergeScopeResolver>(),
    quotaAvailabilityPublisher: sp.GetRequiredService<IAgentQuotaAvailabilityPublisher>(),
    e2eReplayGate: sp.GetService<WorkItemE2eReplayGate>(),
    jobTrackExporter: sp.GetService<IJobTrackTestCaseExporter>(),
    deploymentManager: sp.GetService<IDeploymentManager>(),
    deploymentSubstrates: sp.GetService<IDeploymentSubstrateProvider>(),
    humanReviews: sp.GetService<IHumanDeploymentReviewStore>(),
    staleBaseReworkRouter: sp.GetRequiredService<StaleBaseConflictReworkRouter>(),
    flakeEscalation: sp.GetService<NonDeterministicTestEscalationService>(),
    flakeEscalationOptions: sp.GetRequiredService<NonDeterministicTestEscalationSnapshot>(),
    briefComposer: sp.GetRequiredService<ConvergenceBriefComposer>(),
    delegationEvents: sp.GetRequiredService<IDelegationEventStore>(),
    delegationOptionsAccessor: () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.Delegation,
    delegationEscalation: sp.GetService<DelegationEscalationService>(),
    sandboxPlacer: sp.GetRequiredService<SandboxPlacementAcquirer>(),
    secretLeases: sp.GetService<SecretLeaseManager>(),
    sessionSlotGate: sp.GetService<IAgentSessionSlotGate>(),
    // Post-merge per-test coverage baseline production: the scheduler holds
    // at most one pending job per project (newest merge wins), the stager
    // places fresh ancestry-reachable baselines into audit sandboxes, and
    // both are no-ops for projects that never opt in via
    // Project.TestSelectionBaselineEnabled.
    baselineScheduler: sp.GetRequiredService<TestSelectionBaselineScheduler>(),
    baselineProductionOptions: () => sp.GetRequiredService<IOptionsMonitor<TestSelectionBaselineProductionOptions>>().CurrentValue,
    baselineStager: sp.GetRequiredService<TestSelectionBaselineAuditStager>(),
    providerTransientCorrelation: sp.GetRequiredService<ProviderTransientCorrelationTracker>(),
    baseBuildVerifier: sp.GetRequiredService<BaseBuildVerifier>(),
    baseBrokenConditions: sp.GetRequiredService<BaseBrokenConditionTracker>(),
    attributionPolicy: sp.GetRequiredService<CodeyBox.Core.CommitAttributionPolicy>()));
builder.Services.AddSingleton<IPipelineRunner>(sp => sp.GetRequiredService<PipelineRunner>());
// Isolated base-branch fix-item spawner for NotDiffAttributable audit test
// failures. Constructed lazily from the store/queue plus the hot-reloadable
// snapshot so threshold edits apply to the next escalation without restart.
builder.Services.AddSingleton<NonDeterministicTestEscalationService>(sp =>
    new NonDeterministicTestEscalationService(
        sp.GetRequiredService<IWorkItemStore>(),
        sp.GetService<ITaskQueue>(),
        sp.GetRequiredService<NonDeterministicTestEscalationSnapshot>()));

builder.Services.AddSingleton<QuotaRetryScheduler>(sp => new QuotaRetryScheduler(
    sp.GetRequiredService<IWorkItemStore>(),
    sp.GetRequiredService<WorkItemRetrier>(),
    sp.GetRequiredService<OrchestratorOptions>(),
    sp.GetRequiredService<ILogger<QuotaRetryScheduler>>(),
    sp.GetRequiredService<IQuotaRetryRouter>(),
    sp.GetRequiredService<IProjectRepository>(),
    sp.GetRequiredService<IQueueController>(),
    sp.GetRequiredService<IWebhookDispatcher>(),
    sp.GetService<TimeProvider>(),
    sp.GetRequiredService<IBaselineImageResolver>(),
    autoRetryOptionsAccessor: () =>
    {
        var current = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.AutoRetryOnQuotaFailure;
        return OrchestratorOptionsFactory.BuildAutoRetryOptions(
            current.Enabled,
            current.PeriodicCheckInterval,
            current.ClockDriftSafetyMargin,
            current.MaxAutoRetriesPerWorkItem,
            current.MaxWaitingForQuotaResetSweepBatchSize);
    },
    quotaAvailabilitySignal: sp.GetRequiredService<IAgentQuotaAvailabilitySignal>(),
    agentAvailabilityRecoverySignal: sp.GetRequiredService<IAgentAvailabilityRecoverySignal>(),
    pauseSignal: sp.GetRequiredService<IAgentPauseSignal>(),
    auditLogger: Log.Logger));
builder.Services.AddSingleton<TransientRetryScheduler>(sp => new TransientRetryScheduler(
    sp.GetRequiredService<IWorkItemStore>(),
    sp.GetRequiredService<WorkItemRetrier>(),
    sp.GetRequiredService<OrchestratorOptions>(),
    sp.GetRequiredService<ILogger<TransientRetryScheduler>>(),
    sp.GetRequiredService<IWorkItemTerminalTransition>(),
    projects: sp.GetRequiredService<IProjectRepository>(),
    queueController: sp.GetRequiredService<IQueueController>(),
    webhooks: sp.GetRequiredService<IWebhookDispatcher>(),
    timeProvider: sp.GetService<TimeProvider>(),
    transientRetryOptionsAccessor: () =>
    {
        var current = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.AutoRetryOnTransientFailure;
        return OrchestratorOptionsFactory.BuildTransientRetryOptions(
            current.Enabled,
            current.PeriodicCheckInterval,
            current.BaseDelay,
            current.Multiplier,
            current.MaxDelay,
            current.MaxAutoRetriesPerWorkItem,
            current.MaxElapsedTime,
            current.JitterMode);
    }));
builder.Services.AddSingleton<IWorkerPoolQuotaRecovery>(sp =>
    sp.GetRequiredService<QuotaRetryScheduler>());
builder.Services.AddSingleton<IQuotaFailureAutoRetryScheduler>(sp =>
    sp.GetRequiredService<QuotaRetryScheduler>());
builder.Services.AddSingleton<IQuotaRetryDispatchPromoter>(sp =>
    sp.GetRequiredService<QuotaRetryScheduler>());
builder.Services.AddSingleton<ITransientFailureAutoRetryScheduler>(sp =>
    sp.GetRequiredService<TransientRetryScheduler>());
builder.Services.AddSingleton<IWorkItemAutoRetryScheduler>(sp =>
    new WorkItemAutoRetryScheduler(
        sp.GetRequiredService<IQuotaFailureAutoRetryScheduler>(),
        sp.GetRequiredService<ITransientFailureAutoRetryScheduler>()));
builder.Services.AddSingleton<AgentQuotaRecoveryProbeMonitor>();
builder.Services.AddHostedService(sp => sp.GetRequiredService<QuotaRetryScheduler>());
builder.Services.AddHostedService(sp => sp.GetRequiredService<AgentQuotaRecoveryProbeMonitor>());
builder.Services.AddHostedService(sp => sp.GetRequiredService<TransientRetryScheduler>());
builder.Services.AddSingleton<AgentPauseRetryScheduler>(sp => new AgentPauseRetryScheduler(
    sp.GetRequiredService<IWorkItemStore>(),
    sp.GetRequiredService<WorkItemRetrier>(),
    sp.GetRequiredService<IAgentPauseController>(),
    sp.GetRequiredService<ILogger<AgentPauseRetryScheduler>>(),
    sp.GetRequiredService<IAgentPauseSignal>()));
builder.Services.AddHostedService(sp => sp.GetRequiredService<AgentPauseRetryScheduler>());

// IAgentRestoreSignal is implemented by the same AgentAvailabilityRegistry
// singleton — exposed here as the narrow port so the restore-retry scheduler
// can subscribe without depending on the concrete registry type.
builder.Services.AddSingleton<IAgentRestoreSignal>(sp =>
    sp.GetRequiredService<AgentAvailabilityRegistry>());
builder.Services.AddSingleton<AgentRestoreRetryScheduler>(sp => new AgentRestoreRetryScheduler(
    sp.GetRequiredService<IWorkItemStore>(),
    sp.GetRequiredService<WorkItemRetrier>(),
    () =>
    {
        var live = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.AutoRequeueOnAgentRestore;
        return OrchestratorOptionsFactory.BuildAgentRestoreRetryOptions(
            live.Enabled,
            live.LookbackGrace,
            live.PostRestoreMargin,
            live.InvolvementTerminalLookback,
            live.InvolvementTerminalClockSkew,
            live.MaxCandidatesPerSweep,
            live.EventQueueCapacity);
    },
    sp.GetRequiredService<ILogger<AgentRestoreRetryScheduler>>(),
    sp.GetRequiredService<IAgentRestoreSignal>(),
    sp.GetRequiredService<IWebhookDispatcher>(),
    sp.GetRequiredService<IProjectRepository>(),
    sp.GetService<IAgentInvolvementStore>(),
    sp.GetService<TimeProvider>()));
builder.Services.AddHostedService(sp => sp.GetRequiredService<AgentRestoreRetryScheduler>());

// --- Failure-class recovery -------------------------------------------------
// Pure deterministic classifier in front of the hosted recovery service.
// Operators wire alternate classifiers (e.g. LLM-precision layer) by replacing
// the singleton registration; the service treats the interface as authoritative.
builder.Services.AddSingleton<ITerminalFailureClassifier, DefaultTerminalFailureClassifier>();
// --- Delegation triggers ----------------------------------------------------
// Single home for every transition into the delegation phase: the operator
// delegate command and both automatic-escalation conditions. Constructed
// lazily from the store/queue plus the hot-reloadable options so threshold
// edits apply to the next trigger without restart.
builder.Services.AddSingleton<DelegationEscalationService>(sp =>
    new DelegationEscalationService(
        sp.GetRequiredService<IWorkItemStore>(),
        sp.GetService<ITaskQueue>(),
        () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.DelegationEscalation,
        sp.GetService<IWebhookDispatcher>(),
        sp.GetService<IProjectRepository>()));
builder.Services.AddSingleton<TerminalFailureRecoveryService>(sp => new TerminalFailureRecoveryService(
    sp.GetRequiredService<IWorkItemStore>(),
    sp.GetRequiredService<WorkItemRetrier>(),
    sp.GetRequiredService<ITerminalFailureClassifier>(),
    () =>
    {
        var live = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.TerminalFailureRecovery;
        return OrchestratorOptionsFactory.BuildTerminalFailureRecoveryOptions(
            live.Enabled,
            live.PeriodicCheckInterval,
            live.BaseBackoff,
            live.MaxBackoff,
            live.JitterFraction,
            live.MaxAutoRetriesPerWorkItem);
    },
    sp.GetRequiredService<ILogger<TerminalFailureRecoveryService>>(),
    delegationEscalation: sp.GetService<DelegationEscalationService>()));
builder.Services.AddHostedService(sp => sp.GetRequiredService<TerminalFailureRecoveryService>());

builder.Services.AddSingleton<OrchestratorOptions>(sp =>
{
    var cbOpts = sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value;
    var startupLog = sp.GetRequiredService<ILoggerFactory>().CreateLogger("CodeyBox.Orchestrator");
    OrchestratorOptionsFactory.ValidateMaintenanceHoldAgainstDispatchWindow(
        cbOpts.SqliteMaintenance,
        cbOpts.SqliteWriteGate,
        cbOpts.WorkerPool);
    return OrchestratorOptionsFactory.Build(
        cbOpts.Concurrency,
        cbOpts.WorkerPool,
        cbOpts.AutoRetryOnQuotaFailure.Enabled,
        cbOpts.AutoRetryOnQuotaFailure.PeriodicCheckInterval,
        cbOpts.AutoRetryOnQuotaFailure.ClockDriftSafetyMargin,
        cbOpts.AutoRetryOnQuotaFailure.MaxAutoRetriesPerWorkItem,
        startupLog,
        cbOpts.AutoRetryOnQuotaFailure.MaxWaitingForQuotaResetSweepBatchSize) with
    {
        AutoRetryOnTransientFailure = OrchestratorOptionsFactory.BuildTransientRetryOptions(
            cbOpts.AutoRetryOnTransientFailure.Enabled,
            cbOpts.AutoRetryOnTransientFailure.PeriodicCheckInterval,
            cbOpts.AutoRetryOnTransientFailure.BaseDelay,
            cbOpts.AutoRetryOnTransientFailure.Multiplier,
            cbOpts.AutoRetryOnTransientFailure.MaxDelay,
            cbOpts.AutoRetryOnTransientFailure.MaxAutoRetriesPerWorkItem,
            cbOpts.AutoRetryOnTransientFailure.MaxElapsedTime,
            cbOpts.AutoRetryOnTransientFailure.JitterMode),
        ShutdownDrainTimeout = Program.ComputeOrchestratorShutdownDrainTimeout(cbOpts.Shutdown.GraceSeconds),
        TerminalFailureRecovery = OrchestratorOptionsFactory.BuildTerminalFailureRecoveryOptions(
            cbOpts.TerminalFailureRecovery.Enabled,
            cbOpts.TerminalFailureRecovery.PeriodicCheckInterval,
            cbOpts.TerminalFailureRecovery.BaseBackoff,
            cbOpts.TerminalFailureRecovery.MaxBackoff,
            cbOpts.TerminalFailureRecovery.JitterFraction,
            cbOpts.TerminalFailureRecovery.MaxAutoRetriesPerWorkItem),
    };
});
builder.Services.AddSingleton<CancellationRegistry>(sp =>
    new CancellationRegistry(sp.GetRequiredService<IHostApplicationLifetime>().ApplicationStopping));
// --- Release management -------------------------------------------------------
builder.Services.AddSingleton<ReleaseService>(sp => new ReleaseService(
    sp.GetRequiredService<IReleaseStore>(),
    sp.GetRequiredService<IWorkItemStore>(),
    sp.GetRequiredService<IProjectRepository>(),
    sp.GetRequiredService<IWebhookDispatcher>(),
    sp.GetRequiredService<ISandboxProvider>(),
    sp.GetRequiredService<IGitHost>(),
    sp.GetRequiredService<IAgentRegistry>(),
    sp.GetRequiredService<ICredentialProvider>(),
    sp.GetRequiredService<IUpstreamRemoteFactory>(),
    sp.GetServices<IDeepAuditor>(),
    sp.GetRequiredService<IChangelogGenerator>(),
    sp.GetRequiredService<PipelineOptions>(),
    sp.GetRequiredService<ITaskQueue>(),
    sp.GetRequiredService<IHostApplicationLifetime>(),
    sp.GetRequiredService<ILogger<ReleaseService>>(),
    () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.DeepAuditMaxConcurrency,
    () => TimeSpan.FromSeconds(sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.DeepAuditRemediationItemTimeoutSeconds),
    agentStreams: sp.GetService<IAgentStreamStore>(),
    promptPreprocessors: sp.GetRequiredService<AgentPromptPreprocessorChain>(),
    authFailureClassifier: sp.GetRequiredService<IAgentAuthFailureClassifier>(),
    authAvailability: sp.GetRequiredService<IAgentAuthAvailabilityRegistry>(),
    authRequiredHandler: sp.GetRequiredService<IAgentAuthRequiredHandler>(),
    deepAuditFailurePersistenceOptions: () => sp
        .GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>()
        .CurrentValue
        .DeepAuditFailurePersistence,
    timeProvider: sp.GetService<TimeProvider>() ?? TimeProvider.System));

builder.Services.AddHostedService(sp => new ReleaseMainSyncService(
    sp.GetRequiredService<IReleaseStore>(),
    sp.GetRequiredService<IProjectRepository>(),
    sp.GetRequiredService<IWebhookDispatcher>(),
    sp.GetRequiredService<IUpstreamRemoteFactory>(),
    sp.GetRequiredService<ILogger<ReleaseMainSyncService>>()));

builder.Services.AddSingleton<StartupRecoveryBarrier>();
builder.Services.AddSingleton<IStartupRecoveryInputBarrier>(
    sp => sp.GetRequiredService<StartupRecoveryBarrier>());
builder.Services.AddSingleton<IStartupRecoveryInputSink>(
    sp => sp.GetRequiredService<StartupRecoveryBarrier>());
builder.Services.AddSingleton<IStartupInitialRecoveryBarrier>(
    sp => sp.GetRequiredService<StartupRecoveryBarrier>());
builder.Services.AddSingleton<IStartupInitialRecoverySink>(
    sp => sp.GetRequiredService<StartupRecoveryBarrier>());
builder.Services.AddSingleton<OrchestratorService>(sp => new OrchestratorService(
    sp.GetRequiredService<ITaskQueue>(),
    sp.GetRequiredService<IWorkItemStore>(),
    sp.GetRequiredService<IPipelineRunner>(),
    sp.GetRequiredService<CancellationRegistry>(),
    sp.GetRequiredService<OrchestratorOptions>(),
    sp.GetRequiredService<ILogger<OrchestratorService>>(),
    sp.GetRequiredService<AgentClassRouter>(),
    sp.GetRequiredService<IProjectRepository>(),
    sp.GetRequiredService<IQueueController>(),
    sp.GetRequiredService<IWebhookDispatcher>(),
    sp.GetRequiredService<IWorkerRegistry>(),
    sp.GetRequiredService<DeadWorkerOptions>(),
    sp.GetRequiredService<DeadWorkerReaper>(),
    sp.GetRequiredService<ReleaseService>(),
    sp.GetRequiredService<AgentConcurrencyOptions>(),
    sp.GetRequiredService<AgentConcurrencySnapshot>(),
    sp.GetRequiredService<IBaselineImageResolver>(),
    sp.GetRequiredService<OrchestratorProgressClock>(),
    sp.GetRequiredService<QuotaRouterOptions>(),
    sp.GetRequiredService<BudgetDeferralRecheckSnapshot>(),
    sp.GetRequiredService<IStartupRecoveryInputBarrier>(),
    sp.GetRequiredService<IStartupInitialRecoverySink>(),
    dispatchAvailability: sp.GetRequiredService<IAgentDispatchAvailability>(),
    knobRegistry: sp.GetRequiredService<IKnobRegistry>(),
    quotaRetryDispatchPromoter: sp.GetRequiredService<IQuotaRetryDispatchPromoter>(),
    quotaRetryAdmissionRouter: sp.GetRequiredService<IQuotaRetryAdmissionRouter>(),
    failureTracker: sp.GetRequiredService<BackgroundServiceFailureTracker>(),
    repoReaper: sp.GetRequiredService<WorkItemRepoReaper>(),
    reservationLedger: sp.GetRequiredService<QuotaReservationLedger>(),
    costStore: sp.GetService<IWorkItemCostStore>(),
    burnEstimatorOptions: sp.GetService<AgentBurnEstimatorOptions>(),
    dispatchLiveness: sp.GetRequiredService<DispatchItemLivenessTracker>(),
    hostTransientPause: sp.GetRequiredService<ProviderTransientCorrelationTracker>(),
    baseBrokenConditions: sp.GetRequiredService<BaseBrokenConditionTracker>()));
builder.Services.AddSingleton<IInfrastructureDeferralScheduler>(
    sp => sp.GetRequiredService<OrchestratorService>());
builder.Services.AddSingleton<IRefactorProjectGateStatusProvider>(
    sp => sp.GetRequiredService<OrchestratorService>());
builder.Services.AddSingleton<IRefactorProjectDispatchGate>(
    sp => sp.GetRequiredService<OrchestratorService>());
builder.Services.AddSingleton<WorkerPoolHealthCoordinator>(sp => new WorkerPoolHealthCoordinator(
    sp.GetRequiredService<OrchestratorService>(),
    sp.GetRequiredService<IWorkItemStore>(),
    sp.GetRequiredService<ITaskQueue>(),
    sp.GetRequiredService<ILogger<WorkerPoolHealthCoordinator>>(),
    sp.GetRequiredService<IProjectRepository>(),
    sp.GetRequiredService<IQueueController>(),
    sp.GetRequiredService<IAgentRegistry>(),
    sp.GetRequiredService<IAgentRoutingReadiness>(),
    sp.GetRequiredService<IAgentDispatchAvailability>(),
    sp.GetRequiredService<IRefactorProjectDispatchGate>()));
builder.Services.AddSingleton<IWorkerPoolHealthSource>(sp =>
    sp.GetRequiredService<WorkerPoolHealthCoordinator>());
builder.Services.AddSingleton<IAgentCapacitySnapshot>(sp =>
    sp.GetRequiredService<WorkerPoolHealthCoordinator>());
builder.Services.AddHostedService(sp => sp.GetRequiredService<OrchestratorService>());
// R8.1: expose the orchestrator as IShutdownDispatchGate so the
// SandboxShutdownTeardownService can pause new dispatch before the per-VM
// teardown begins (incident 2026-05-29 fix).
builder.Services.AddSingleton<IShutdownDispatchGate>(
    sp => sp.GetRequiredService<OrchestratorService>());
builder.Services.AddHostedService(sp => sp.GetRequiredService<DeadWorkerReaper>());
builder.Services.AddHostedService(sp => sp.GetRequiredService<WorkItemRepoReaper>());
// Run the watchdog as a hosted service. AttachWorkerPoolSlotReleaser is called
// after OrchestratorService is fully constructed so the watchdog can release
// a wedged worker's pool slot synchronously.
builder.Services.AddHostedService(sp =>
{
    var watchdog = sp.GetRequiredService<WorkerProgressWatchdog>();
    watchdog.AttachWorkerPoolSlotReleaser(sp.GetRequiredService<OrchestratorService>());
    return watchdog;
});
builder.Services.AddHostedService(sp =>
{
    var watchdog = sp.GetRequiredService<ItemStaleProgressWatchdog>();
    watchdog.AttachWorkerPoolSlotReleaser(sp.GetRequiredService<OrchestratorService>());
    return watchdog;
});
builder.Services.AddHostedService(sp => sp.GetRequiredService<WorkerPoolHealthWatchdog>());
// R8-core/R8.1: tear down in-flight sandboxes on graceful shutdown using the
// operator-selected SandboxTeardownMode. Suspend is opt-in and writes resume
// bookkeeping so the next process can reattach; Stop is the default and avoids
// the unreliable RAM-snapshot path while preserving PipelineRunner's checkpoint
// recovery path for active work.
// The shutdown half is lifecycle-bound (StoppingAsync). Startup resume defaults
// to background mode and starts after ApplicationStarted so a wedged multipassd
// cannot keep Kestrel offline; OrchestratorService waits for startup recovery
// input before its dead-worker startup recovery sweep. Blocking resume mode
// still runs through IHostedLifecycleService.StartingAsync, so the host awaits
// it natively.
//
// R8.1 (incident 2026-05-29): the shutdown teardown service is wired with the
// orchestrator as an IShutdownDispatchGate so it pauses new dispatch BEFORE
// snapshotting the active sandbox set — without that ordering, the dispatch
// loop keeps creating new sandboxes that race the snapshot. Teardown mode is
// operator-tunable via CodeyBox:Shutdown:SandboxTeardownMode (Stop / Suspend /
// Dispose); default Stop to avoid multipass suspend/qemu-lock wedges unless an
// operator opts in.
// Resolve teardown mode through IOptionsMonitor at shutdown time so a hot config
// edit affects the next graceful shutdown.
builder.Services.AddHostedService(sp =>
{
    var optionsMonitor = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>();
    var shutdown = optionsMonitor.CurrentValue.Shutdown;
    return new SandboxShutdownTeardownService(
        sp.GetRequiredService<ISandboxProvider>(),
        sp.GetRequiredService<IWorkItemStore>(),
        sp.GetRequiredService<ILogger<SandboxShutdownTeardownService>>(),
        nonSuspendTeardownTimeout: TimeSpan.FromSeconds(Math.Max(1, shutdown.GraceSeconds)),
        dispatchGate: sp.GetService<IShutdownDispatchGate>(),
        teardownModeAccessor: () => optionsMonitor.CurrentValue.Shutdown.SandboxTeardownMode,
        teardownBudgetAccessor: () => optionsMonitor.CurrentValue.Shutdown.SandboxTeardownTimeout);
});
// Startup reconciler is registered before the resume handler and runs as a
// background sweep so Multipass recovery cannot keep Kestrel offline. It skips
// VMs with live SuspendedVmName mappings; those are owned by the resume handler
// below, while orphaned Suspending VMs from a prior unclean shutdown get an
// early cleanup attempt before regular leak handling has to deal with them.
builder.Services.AddHostedService(sp => new StartupSandboxReconciliationService(
    sp.GetService<ISandboxProvider>(),
    sp.GetRequiredService<IWorkItemStore>(),
    sp.GetRequiredService<ILogger<StartupSandboxReconciliationService>>()));
builder.Services.AddHostedService(sp => new SandboxResumeOnStartupService(
    sp.GetService<ISandboxProvider>(),
    sp.GetRequiredService<IWorkItemStore>(),
    sp.GetRequiredService<ILogger<SandboxResumeOnStartupService>>(),
    () =>
    {
        var shutdown = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.Shutdown;
        return Program.BuildSandboxStartupResumeOptions(shutdown);
    },
    sp.GetRequiredService<IStartupRecoveryInputSink>(),
    sp.GetRequiredService<IInfrastructureDeferralScheduler>(),
    sp.GetRequiredService<IHostApplicationLifetime>(),
    leakDisposal: sp.GetRequiredService<IManagedSandboxLifecycle>()));

// Hot-reload bridge: subscribes to IOptionsMonitor<CodeyBoxOptions> and pushes
// changes to AgentConcurrency / AgentClasses / AgentBurnEstimator into the
// running router, orchestrator, and burn estimator without a restart. The
// orchestrator/router are constructed with the initial options, so the
// coordinator captures that same baseline at StartAsync to avoid emitting a
// spurious "config_reloaded" entry on the first OnChange.
builder.Services.AddSingleton<AgentConfigHotReload>(sp =>
{
    var pricingState = sp.GetRequiredService<AgentPricingState>();
    return new AgentConfigHotReload(
        sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>(),
        sp.GetRequiredService<OrchestratorService>(),
        sp.GetRequiredService<AgentClassRouter>(),
        sp.GetRequiredService<AgentBurnEstimator>(),
        sp.GetRequiredService<ILogger<AgentConfigHotReload>>(),
        defaults: sp.GetRequiredService<CodeyBox.Core.AgentDefaultsSnapshot>(),
        sanitizerConfig: sp.GetRequiredService<CodeyBox.Core.ClaudeThinkingBlockSanitizerConfig>(),
        networkTolerance: sp.GetRequiredService<CodeyBox.Core.AgentNetworkToleranceSnapshot>(),
        costCalculator: sp.GetRequiredService<AgentCostCalculator>(),
        pricingState: pricingState,
        budgetReloader: sp.GetRequiredService<IAgentBudgetConfigReloadable>(),
        incrementalRebase: sp.GetRequiredService<IncrementalRebaseSnapshot>(),
        flakeEscalation: sp.GetRequiredService<NonDeterministicTestEscalationSnapshot>(),
        pipelineTuning: sp.GetRequiredService<PipelineTuningSnapshot>(),
        budgetDeferralRecheck: sp.GetRequiredService<BudgetDeferralRecheckSnapshot>(),
        circuitBreaker: sp.GetRequiredService<AgentCircuitBreakerSnapshot>(),
        quotaRouterOptions: sp.GetRequiredService<QuotaRouterOptions>(),
        coverage: sp.GetService<IInVmSmokeCoveragePolicy>(),
        smokeOptions: sp.GetRequiredService<SmokeOptionsSnapshot>(),
        testFailureAttribution: sp.GetRequiredService<TestFailureAttributionOptionsSnapshot>(),
        toolchainFaults: sp.GetRequiredService<CodeyBox.Core.ToolchainFaultSnapshot>(),
        pauses: sp.GetRequiredService<IAgentPauseController>(),
        agents: sp.GetRequiredService<IAgentRegistry>(),
        transitionHealth: sp.GetRequiredService<TransitionHealthOptionsSnapshot>(),
        hostPoolSnapshot: sp.GetService<ISandboxProvider>() as ISandboxHostPoolSnapshot,
        sandboxAdmission: sp.GetService<ISandboxProvider>() as SandboxAdmissionControlledProvider,
        configuration: builder.Configuration,
        deployConsistency: sp.GetRequiredService<DeployConsistencyService>(),
        sandboxClasses: sp.GetRequiredService<SandboxClassesSnapshot>(),
        sandboxProviderRegistry: sp.GetRequiredService<ISandboxProviderRegistry>(),
        hostEnvironment: sp.GetRequiredService<IHostEnvironment>(),
        sandboxPlacer: sp.GetRequiredService<SandboxPlacementAcquirer>());
});
builder.Services.AddHostedService(sp => sp.GetRequiredService<AgentConfigHotReload>());
builder.Services.AddHostedService(sp => new StartupSmokeProbeService(
    sp.GetRequiredService<ICredentialProvider>(),
    sp.GetServices<IAgentSmokeProbe>(),
    sp.GetRequiredService<IWebhookDispatcher>(),
    sp.GetRequiredService<SmokeOptionsSnapshot>(),
    sp.GetRequiredService<ILogger<StartupSmokeProbeService>>(),
    sp.GetService<ISmokeAvailabilityRegistry>(),
    sp.GetRequiredService<InVmSmokeOptions>()));
builder.Services.AddSingleton<PeriodicSmokeProbeService>(sp => new PeriodicSmokeProbeService(
    sp.GetRequiredService<ICredentialProvider>(),
    sp.GetServices<IAgentSmokeProbe>(),
    sp.GetRequiredService<IWebhookDispatcher>(),
    sp.GetRequiredService<SmokeOptionsSnapshot>(),
    sp.GetRequiredService<AvailabilityOptions>(),
    sp.GetRequiredService<ISmokeAvailabilityRegistry>(),
    sp.GetRequiredService<ILogger<PeriodicSmokeProbeService>>()));
builder.Services.AddHostedService(sp => sp.GetRequiredService<PeriodicSmokeProbeService>());
// Expose the host-side on-demand probe through the core port so the admin
// /smoke endpoint depends on the abstraction, not the background-service type.
builder.Services.AddSingleton<IHostSmokeProbeRunner>(sp => sp.GetRequiredService<PeriodicSmokeProbeService>());

// Periodic metric samplers. The host runs each IMetricSampler on its own loop,
// re-reading the sampler's Enabled / Interval each cycle so plugin-side
// hot-reload takes effect without a host restart. The first sampler shipping
// against this extension point is the statistics plugin's quota sampler — but
// the host is sampler-agnostic; further plugins (throughput, audit pass rate,
// cost-over-time) can register additional IMetricSampler implementations.
// See docs/extending/plugins.md (IMetricSampler) and docs/extending/statistics-plugin.md.
builder.Services.AddHostedService<MetricSamplerHost>();
builder.Services.AddHostedService(sp => new AuditAgentStartupValidationService(
    sp.GetRequiredService<IProjectRepository>(),
    sp.GetRequiredService<ICredentialProvider>(),
    sp.GetRequiredService<ILogger<AuditAgentStartupValidationService>>()));
// Live accessor: operator edits to CodeyBox:AuditLog:RetainedDays take effect
// on the next daily retention sweep without restart. The Serilog rolling-file
// writer pinned RetainedDays at startup though, so its sink retention does
// require a restart — documented on AuditLogOptions.RetainedDays.
builder.Services.AddHostedService(sp => new AuditReportRetentionService(
    sp.GetRequiredService<IAuditReportStore>(),
    () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.AuditLog.RetainedDays,
    sp.GetRequiredService<ILogger<AuditReportRetentionService>>()));
builder.Services.AddHostedService(sp => new IdempotencyKeyRetentionService(
    sp.GetRequiredService<IIdempotencyStore>(),
    sp.GetRequiredService<ILogger<IdempotencyKeyRetentionService>>()));
builder.Services.AddHostedService(sp => new AgentUsageRetentionService(
    sp.GetRequiredService<IAgentUsageStore>(),
    () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.AgentBudgets,
    sp.GetRequiredService<ILogger<AgentUsageRetentionService>>()));
builder.Services.AddHostedService(sp => new AgentStreamRetentionService(
    sp.GetRequiredService<IAgentStreamStore>(),
    sp.GetRequiredService<ILogger<AgentStreamRetentionService>>()));
builder.Services.AddSingleton<StreamAnalysisService>();
builder.Services.AddHostedService(sp => sp.GetRequiredService<StreamAnalysisService>());
builder.Services.AddHostedService(sp => new BudgetAlertService(
    sp.GetRequiredService<IProjectRepository>(),
    sp.GetRequiredService<IWorkItemCostStore>(),
    sp.GetRequiredService<IQueueController>(),
    sp.GetRequiredService<IWebhookDispatcher>(),
    sp.GetRequiredService<IOptions<CodeyBoxOptions>>().Value.BudgetAlerts,
    sp.GetRequiredService<ILogger<BudgetAlertService>>()));

builder.Services.AddSingleton<CompositeManagedSandboxProvider>(BuildManagedSandboxLifecycleProvider);
builder.Services.AddSingleton<IManagedSandboxLifecycle>(sp => sp.GetRequiredService<CompositeManagedSandboxProvider>());
builder.Services.AddSingleton<SandboxLeakReaper>(sp =>
{
    // Live accessor: thresholds and policy fields (LeakAgeThreshold,
    // PriorProcessOrphanGrace, AutoDispose, MaxConcurrentAutoDispose,
    // PreemptRetention) are re-read on every sweep so operator edits take
    // effect without restart. CheckInterval and Enabled are sampled once at
    // PeriodicTimer construction — limitation documented on the fields themselves.
    var monitor = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>();
    return new SandboxLeakReaper(
        sp.GetRequiredService<IManagedSandboxLifecycle>(),
        sp.GetRequiredService<IWebhookDispatcher>(),
        () => monitor.CurrentValue.SandboxLeak,
        sp.GetRequiredService<ILogger<SandboxLeakReaper>>(),
        sp.GetRequiredService<IWorkItemStore>(),
        leakSink: sp.GetRequiredService<LeakDetectionSink>(),
        phaseAbsoluteTimeoutMultiplierAccessor: () => monitor.CurrentValue.PhaseAbsoluteTimeoutMultiplier,
        timeProvider: TimeProvider.System);
});
builder.Services.AddHostedService(sp => sp.GetRequiredService<SandboxLeakReaper>());

// --- Verification deployment drivers + manager -------------------------------
// Deployment abstraction (chain link 1) + audit-ladder integration (link 2):
// the pipeline lazily provisions ONE deployment per audit iteration from the
// project's recipe once the code stage passes, runs deployment-targeted
// auditors against the live endpoint, and always tears it down. Drivers are
// DI-resolved by their Kind via DeploymentDriverRegistry, so a new kind is
// one new IDeploymentDriver registration + recipe schema entry with zero
// core changes (per AGENTS.md declared-capability pattern). The leak reaper
// sweeps managed sandboxes whose deployment owner no longer exists in the
// manager's active set (orchestrator restart, aborted deploy) — sibling to
// SandboxLeakReaper.
builder.Services.AddSingleton<IDeploymentDriver, WebAppDeploymentDriver>();
builder.Services.AddSingleton<IDeploymentDriver, DaemonDeploymentDriver>();
builder.Services.AddSingleton<IDeploymentDriver, CliDeploymentDriver>();
builder.Services.AddSingleton<IDeploymentDriver, LibraryDeploymentDriver>();
builder.Services.AddSingleton<SandboxDeploymentSubstrateProvider>(sp =>
    new SandboxDeploymentSubstrateProvider(sp.GetRequiredService<ISandboxProvider>()));
builder.Services.AddSingleton<IDeploymentSubstrateProvider>(sp =>
    sp.GetRequiredService<SandboxDeploymentSubstrateProvider>());
builder.Services.AddSingleton<IDeploymentCleanupProvider>(sp =>
    sp.GetRequiredService<SandboxDeploymentSubstrateProvider>());
builder.Services.AddSingleton<IDeploymentDriverRegistry, DeploymentDriverRegistry>();
builder.Services.AddSingleton<IDeploymentManager>(sp => new DeploymentManager(
    sp.GetRequiredService<IDeploymentDriverRegistry>(),
    sp.GetRequiredService<ILogger<DeploymentManager>>()));
builder.Services.AddSingleton<DeploymentLeakReaper>(sp =>
{
    var monitor = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>();
    // The work-item store holds the authoritative SuspendedVmName index — every
    // VM the startup resume handler is going to multipass-start back to Running
    // after an orchestrator restart. Without this filter, the deployment reaper
    // would purge those VMs at LeakAgeThreshold even though SandboxLeakReaper
    // explicitly preserves them via the same index.
    var store = sp.GetRequiredService<IWorkItemStore>();
    Func<CancellationToken, Task<IReadOnlySet<string>>> suspendedNames = async ct =>
    {
        var set = new HashSet<string>(StringComparer.Ordinal);
        await foreach (var item in store.ListSuspendedAsync(ct).ConfigureAwait(false))
        {
            if (string.IsNullOrWhiteSpace(item.SuspendedVmName)) continue;
            if (WorkItemDependencies.TerminalStates.Contains(item.State)) continue;
            set.Add(item.SuspendedVmName!);
        }
        return set;
    };
    return new DeploymentLeakReaper(
        sp.GetRequiredService<IDeploymentCleanupProvider>(),
        sp.GetRequiredService<IDeploymentManager>(),
        () => monitor.CurrentValue.DeploymentLeak,
        sp.GetRequiredService<ILogger<DeploymentLeakReaper>>(),
        clock: null,
        suspendedNameProvider: suspendedNames);
});
builder.Services.AddHostedService(sp => sp.GetRequiredService<DeploymentLeakReaper>());

// --- B1 baseline-image reaper ------------------------------------------------
// Reference-counted GC for content-hashed Multipass baseline VMs. The reaper
// stays inactive when the registered sandbox provider does not implement
// IBaselineImageResolver — the constructor accepts a null resolver and
// ExecuteAsync short-circuits with an info log. Registered as a singleton so
// the /baselines endpoint can read GetLatestReport() through DI.
builder.Services.AddSingleton<BaselineImageReaper>(sp =>
{
    var monitor = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>();
    return new BaselineImageReaper(
        sp.GetRequiredService<IBaselineImageResolver>(),
        sp.GetRequiredService<IWorkItemStore>(),
        () => monitor.CurrentValue.BaselineImageReaper,
        sp.GetRequiredService<ILogger<BaselineImageReaper>>());
});
builder.Services.AddHostedService(sp => sp.GetRequiredService<BaselineImageReaper>());

// Operator-triggered baseline migration (POST /baselines/migrate). Clears the
// per-item baseline pin for in-flight items through the shared write gate so
// they recompute the current-config baseline on next pickup. Singleton so the
// endpoint resolves it via DI; no background loop.
builder.Services.AddSingleton<BaselineMigrationService>(sp =>
{
    var monitor = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>();
    return new BaselineMigrationService(
        sp.GetRequiredService<IWorkItemStore>(),
        sp.GetRequiredService<IBaselineImageResolver>(),
        sp.GetRequiredService<IProjectRepository>(),
        sp.GetService<TimeProvider>() ?? TimeProvider.System,
        () => monitor.CurrentValue.BaselineMigration,
        sp.GetRequiredService<ILogger<BaselineMigrationService>>());
});

// --- Stale-base PR sweeper ---------------------------------------------------
// Periodically polls open PRs across every github-upstream project, detects
// the ones whose base branch has moved and produced a conflict the auto-merger
// can no longer resolve, and fires the upstream.pr_stale_base webhook event so
// operators see the orphan PR within minutes (5-minute SLA per the bug spec).
// See StalePullRequestSweeper.
builder.Services.AddHostedService(sp =>
{
    var monitor = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>();
    return new StalePullRequestSweeper(
        sp.GetRequiredService<IProjectRepository>(),
        sp.GetRequiredService<IUpstreamRemoteFactory>(),
        sp.GetRequiredService<IWebhookDispatcher>(),
        () => monitor.CurrentValue.StalePullRequestSweep,
        sp.GetRequiredService<ILogger<StalePullRequestSweeper>>(),
        time: null,
        store: sp.GetRequiredService<IWorkItemStore>(),
        reworkRouter: sp.GetRequiredService<StaleBaseConflictReworkRouter>());
});

// --- Plugin foundation -------------------------------------------------------
// One-off startup reconciliation for stranded upstream pushes (owned-branch
// lease-guard parks and other settled items with an open PR on their own
// branch). Detection only — the operator re-drive endpoint carries the
// authorization the lease guard requires.
builder.Services.AddSingleton<UpstreamRedriveService>(sp => new UpstreamRedriveService(
    sp.GetRequiredService<IWorkItemStore>(),
    sp.GetRequiredService<IProjectRepository>(),
    sp.GetRequiredService<IUpstreamRemoteFactory>(),
    sp.GetRequiredService<WorkItemRetrier>(),
    sp.GetRequiredService<ILogger<UpstreamRedriveService>>(),
    sp.GetRequiredService<CodeyBox.Core.UpstreamBranchOwnershipSnapshot>(),
    sp.GetRequiredService<CodeyBox.Core.CommitAttributionPolicy>()));
builder.Services.AddHostedService(sp => new StaleUpstreamRedriveDetector(
    sp.GetRequiredService<UpstreamRedriveService>(),
    sp.GetRequiredService<ILogger<StaleUpstreamRedriveDetector>>()));
// Discovers assemblies from CodeyBox:Plugins, registers plugin types under
// their Core interfaces before the container is frozen, then runs
// IPluginInitializer.InitializeAsync at startup via PluginInitializationService.
// See docs/extending/plugins.md for author guidance, allowlist config, and threat model.
preDiscoveredPlugins = builder.Services.AddCodeyBoxPlugins(builder.Configuration);

// Plugin-contributed sandbox provider kinds. Allowlisted plugins implementing
// ISandboxProvider are indexed here by their normalised Name; the registry
// factory resolves them, and member validation accepts them. The catalog
// is host-owned: it validates names and refuses built-in collisions, while
// egress classification stays in HostPlatformSupport (every plugin kind is
// NotEnforced). See docs/extending/sandbox-plugins.md for the trust model.
builder.Services.AddSingleton<PluginSandboxProviderCatalog>(sp =>
{
    var entries = new List<(string PluginId, CodeyBox.Core.ISandboxProvider Provider)>();
    foreach (var plugin in preDiscoveredPlugins ?? [])
    {
        foreach (var type in plugin.RegisteredTypes)
        {
            if (typeof(CodeyBox.Core.ISandboxProvider).IsAssignableFrom(type))
                entries.Add((plugin.PluginId, (CodeyBox.Core.ISandboxProvider)sp.GetRequiredService(type)));
        }
    }
    return new PluginSandboxProviderCatalog(entries);
});

var app = builder.Build();

// Required-configuration gate. Validates every setting that is mandatory in
// non-Development environments (plus the API-key secret, which is mandatory
// everywhere unless auth is disabled) before the host starts resolving
// services, so the failure is attributable to configuration rather than to a
// DI call site. A missing setting used to surface as an unhandled
// InvalidOperationException escaping from a DI factory during host startup:
// a DI stack trace, SIGABRT/core dump, and exit 134, indistinguishable from a
// crash-loop. The gate reports ALL missing settings in one pass instead.
// The DI-time guards stay in place as defense in depth for direct
// resolutions. Development defaults (e.g. the implicit 'process' provider)
// are unaffected: the validator only reports failures that would actually
// throw in the current environment.
//
// The gate throws (rather than exiting here) so test hosts observe the same
// failure the DI guards would raise. The real binary converts this exact
// exception to a clean stderr diagnostic with a conventional non-zero exit
// code via the unhandled-exception handler registered at the top of Main;
// genuine crashes keep their existing behaviour.
{
    var requiredFailures = RequiredConfigurationValidator.Validate(app.Configuration, app.Environment);
    if (requiredFailures.Count > 0)
        throw new RequiredConfigurationException(app.Environment.EnvironmentName, requiredFailures);
}

// Force the immutable-options baseline and retaining monitor cache to exist
// before the host starts observing file-change reloads.
_ = app.Services.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue;

// Compose the Antigravity quota token source eagerly so the keyring-availability
// warning in its factory is emitted once at startup rather than on the first
// probe pickup. Singleton wiring guarantees the factory (and the warning) run
// exactly once.
_ = app.Services.GetRequiredService<IAntigravityQuotaTokenSource>();

// Convert WorkItemStoreDiskFullException into a clean 503 instead of letting
// the raw exception escape the HTTP layer. Once SQLite refuses to accept
// writes there is no recovery without operator intervention; returning a
// service-unavailable response is the closest thing to "stop accepting new
// work cleanly" the bug report asked for.
app.Use(async (ctx, next) =>
{
    try
    {
        await next();
    }
    catch (WorkItemStoreDiskFullException ex)
    {
        var logger = ctx.RequestServices.GetRequiredService<ILoggerFactory>()
            .CreateLogger("CodeyBox.Api.DiskFull");
        logger.LogCritical(ex, "Refusing request {Path}: state store reports disk full ({Operation})",
            ctx.Request.Path, ex.Operation);
        ctx.Response.Clear();
        ctx.Response.StatusCode = StatusCodes.Status503ServiceUnavailable;
        ctx.Response.Headers["Retry-After"] = "300";
        ctx.Response.ContentType = "application/json";
        await ctx.Response.WriteAsync(
            "{\"error\":\"state store full\",\"detail\":\"host disk is exhausted; no further state transitions can be persisted\"}");
    }
});

// Resolve the Prometheus exporter options once so middleware and endpoint
// mapping see a consistent view. The options were validated at host build
// time; this just reads the snapshot. Toggling Enabled at runtime is NOT
// supported (the exporter is wired into the metric provider builder).
var prometheusOpts = builder.Configuration
    .GetSection("CodeyBox:Otel:Prometheus")
    .Get<PrometheusExporterOptions>() ?? new PrometheusExporterOptions();

// When the Prometheus scrape endpoint is enabled AND RequireApiKey is off,
// exempt EXACTLY that path from API-key auth. Scrapers (Prometheus, conky,
// curl-from-cron) typically cannot send the Bearer token. The exemption is
// exact-path only so a sibling route or descendant can't piggy-back on it.
var prometheusAnonymousPaths = (prometheusOpts.Enabled && !prometheusOpts.RequireApiKey)
    ? new[] { prometheusOpts.Path }
    : Array.Empty<string>();
var anonymousExactPaths = prometheusAnonymousPaths
    .Concat(["/github-app/start", "/github-app/callback"])
    .ToArray();

app.UseApiKeyAuth(
    anonymousPrefixes: ["/healthz", "/webhooks/"],
    anonymousExactPaths: anonymousExactPaths);

// Idempotency-Key support for mutating endpoints — see IdempotencyMiddleware
// for behaviour. Ordered after auth so unauthenticated requests can't poison
// the cache, and before endpoint mapping so all mutating handlers benefit.
IdempotencyMiddleware.Use(app);

WorkItemEndpoints.Map(app);
TestCaseEndpoints.Map(app);
E2eRunEndpoints.Map(app);
WorkItemAttachmentEndpoints.Map(app);
TaskTemplateEndpoints.Map(app);
WorkItemTimingsEndpoints.Map(app);
WorkItemFailureEventsEndpoints.Map(app);
WorkItemCostsEndpoints.Map(app);
AgentPricingEndpoints.Map(app);
ProjectBudgetEndpoints.Map(app);
WorkItemDiffEndpoints.Map(app);
WorkItemDossierEndpoints.Map(app);
SuggestionEndpoints.Map(app);
GitHubAppConnectEndpoints.Map(app);
AuditReportEndpoints.Map(app);
AuditProgressEndpoints.Map(app);
AuditRunEndpoints.Map(app);
AgentStreamEndpoints.Map(app);
SseEndpoints.Map(app);
ChangelogEndpoints.Map(app);
InteractionEndpoints.Map(app);
FleetEndpoints.Map(app);
PluginEndpoints.Map(app);
WorkerRegistryEndpoints.Map(app);
ExecutorEndpoints.Map(app);
ExecutorPhaseEndpoints.Map(app);
AgentSupervisionEndpoints.Map(app);
SandboxEndpoints.Map(app);
SandboxResourceUsageEndpoints.Map(app);
BaselineEndpoints.Map(app);
QuotaRetryStatusEndpoints.Map(app);
QuotaHistoryEndpoints.Map(app);
CapacityEndpoints.Map(app);
ResetCreditEndpoints.Map(app);
ResetAdviceEndpoints.Map(app);
ReleaseEndpoints.Map(app);
AgentPauseEndpoints.Map(app);
TestSelectionSoundnessEndpoints.Map(app);
TestSelectionBaselineEndpoints.Map(app);
ConfigReloadEndpoints.Map(app);
DeployConsistencyEndpoints.Map(app);
app.MapMajordomoMcp();
app.MapMajordomoProposals();
app.MapMajordomoConversation();

// Prometheus scrape endpoint — registered only when the exporter is enabled
// so the surface is invisible (route not on the table) by default. Mapped
// after the API-key middleware so the exemption above takes effect when
// RequireApiKey=false; when RequireApiKey=true, the middleware enforces the
// Bearer token on this path like any other endpoint.
if (prometheusOpts.Enabled)
{
    app.MapPrometheusScrapingEndpoint(prometheusOpts.Path);
}

app.MapHub<AgentStdoutHub>("/hubs/agent-stdout");

app.MapGet("/quota", async (
    IEnumerable<IAgentQuotaProbe> probes,
    AgentClassRouter? router,
    IQuotaFailureStore? failureStore,
    QuotaRouterOptions options,
    IAgentQuotaGate quotaGate,
    IAgentBudgetProvider? budgetProvider,
    IAgentPauseController? agentPauses,
    ILoggerFactory loggerFactory,
    CancellationToken ct) =>
{
    var now = DateTimeOffset.UtcNow;
    IReadOnlyList<QuotaFailureObservation> failures = failureStore is null
        ? Array.Empty<QuotaFailureObservation>()
        : await failureStore.ListRecentAsync(TimeSpan.FromMinutes(60), now, ct);
    var pausedStates = agentPauses is null
        ? Array.Empty<AgentPauseState>()
        : await agentPauses.ListPausedAsync(ct);
    var pausedByKey = pausedStates.ToDictionary(
        s => s.AgentInstanceId ?? s.Agent.Value,
        s => s,
        StringComparer.OrdinalIgnoreCase);
    var pausedByAgent = pausedStates
        .Where(s => s.AgentInstanceId is null)
        .ToDictionary(s => s.Agent, s => s);
    var quotaLog = loggerFactory.CreateLogger("Quota");
    var subscriptionProbes = AgentQuotaProbeCatalog.BuildSubscriptionProbes(probes);
    var fallbackKinds = subscriptionProbes.Select(p => p.Kind).Distinct().ToList();
    var representedProbeKeys = new HashSet<(AgentKind Agent, string? ModelId)>();

    var snapshots = new List<object>();
    var kindAggregateCounts = new Dictionary<string, int>(StringComparer.OrdinalIgnoreCase);
    async Task AddSnapshotAsync(AgentMembership member, string? classId, string? classDisplayName)
    {
        var resolution = AgentQuotaProbeCatalog.ResolveSubscriptionProbe(subscriptionProbes, member, quotaLog);
        AgentQuotaSnapshot snapshot;
        if (resolution.Conflict is not null)
        {
            representedProbeKeys.Add((member.Agent, member.ModelId));
            snapshot = AgentQuotaProbeCatalog.ConflictUnknownSnapshot(resolution.Conflict);
        }
        else if (resolution.Probe is null)
        {
            return;
        }
        else
        {
            representedProbeKeys.Add((member.Agent, member.ModelId));
            snapshot = await resolution.Probe.GetAvailabilityAsync(member, ct);
        }
        var poolName = QuotaPoolResolver.NormalizePoolName(member.Pool);
        string? poolKind = null;
        if (poolName is not null
            && options.Pools.TryGetValue(poolName, out var poolOpts)
            && poolOpts is not null)
            poolKind = poolOpts.Kind.ToString();
        // A depleting-balance pool is never reported with a reset instant,
        // even if the probe echoed one.
        var latestSnapshot = poolKind == nameof(QuotaPoolKind.DepletingBalance)
            ? QuotaPoolMasks.WithoutResetInstants(snapshot)
            : snapshot;
        var recentFailuresForProbe = failures
            .Where(f => f.Agent == member.Agent && f.ObservedAt >= now - options.ObservedFailureWindow)
            .ToList();
        var recentDefaultFailure = recentFailuresForProbe.Any(f => f.ModelId is null);
        var recentFailure = recentFailuresForProbe.Count > 0;
        var paused = pausedByKey.TryGetValue(member.RouteKey, out var pause)
            || pausedByAgent.TryGetValue(member.Agent, out pause);
        var modelKeys = snapshot.PerModel.Keys
            .Concat(recentFailuresForProbe.Where(f => f.ModelId is not null).Select(f => f.ModelId!))
            .Distinct(StringComparer.OrdinalIgnoreCase)
            .ToList();
        Task<AgentQuotaGateVerdict> EvaluateGateAsync(
            AgentMembership gateMember, bool hasRecentFailure) =>
            quotaGate.EvaluateAsync(
                gateMember,
                snapshot,
                now,
                hasRecentFailure,
                "recent observed quota failure",
                ct);
        var defaultMember = member with { ModelId = null };
        // Refused members surface WHY, including which quota window binds, so
        // a plan with weekly headroom but an exhausted monthly window reads as
        // constrained-by-monthly instead of generically out of quota. Allowed
        // members keep a null reason, as before. The allow bit and the reason
        // come from ONE verdict so they cannot diverge.
        var defaultVerdict = paused ? null : await EvaluateGateAsync(defaultMember, recentFailure);
        var defaultModelVerdict = paused ? null : await EvaluateGateAsync(defaultMember, recentDefaultFailure);
        var dispatchReason = paused
            ? $"paused by operator: {pause?.PausedReason}"
            : defaultVerdict?.RefusalReason;
        var perModelWouldAllow = new Dictionary<string, bool>(StringComparer.OrdinalIgnoreCase);
        foreach (var modelId in modelKeys)
        {
            if (paused)
            {
                perModelWouldAllow[modelId] = false;
                continue;
            }
            var modelMember = member with { ModelId = modelId };
            var modelHasRecentFailure = recentFailuresForProbe.Any(f =>
                f.Agent == member.Agent &&
                string.Equals(f.ModelId, modelId, StringComparison.OrdinalIgnoreCase));
            perModelWouldAllow[modelId] =
                (await EvaluateGateAsync(modelMember, modelHasRecentFailure)).Allow;
        }
        snapshots.Add(new
        {
            agent = member.Agent.Value,
            agentInstanceId = member.RouteKey,
            instanceId = member.InstanceId,
            classId,
            classDisplayName,
            billing = member.Billing.ToString(),
            modelId = member.ModelId,
            pool = poolName,
            poolKind,
            latestSnapshot,
            observedFailuresLast60m = failures
                .Where(f => f.Agent == member.Agent)
                .GroupBy(f => new { f.ProjectId, f.ModelId, f.FailureKind })
                .Select(g => new
                {
                    projectId = g.Key.ProjectId?.Value,
                    modelId = g.Key.ModelId,
                    failureKind = g.Key.FailureKind.ToString(),
                    count = g.Count(),
                    latestObservedAt = g.Max(x => x.ObservedAt),
                })
                .ToList(),
            paused,
            pausedReason = pause?.PausedReason,
            pausedAt = pause?.PausedAt,
            pausedBy = pause?.PausedBy,
            pauseExpiresAt = pause?.ExpiresAt,
            dispatchStatus = paused ? "paused" : "quota",
            dispatchReason,
            bindingWindow = snapshot.BindingWindow,
            windowSummary = QuotaWindowBinding.FormatWindowSummary(
                snapshot.Windows, snapshot.AvailablePct),
            wouldAllow = defaultVerdict?.Allow ?? false,
            defaultModelWouldAllow = defaultModelVerdict?.Allow ?? false,
            perModelWouldAllow,
        });
        kindAggregateCounts[member.Agent.Value] =
            kindAggregateCounts.TryGetValue(member.Agent.Value, out var count) ? count + 1 : 1;
    }

    if (router is not null)
    {
        var seenMemberRows = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
        foreach (var entry in router.SnapshotConfiguredMembers())
        {
            if (entry.Member.Billing != AgentBilling.Subscription)
                continue;
            if (!seenMemberRows.Add($"{entry.Member.RouteKey}\0{entry.Member.ModelId ?? string.Empty}"))
                continue;
            await AddSnapshotAsync(entry.Member, entry.ClassId, entry.DisplayName);
        }
    }

    foreach (var kind in fallbackKinds)
    {
        if (representedProbeKeys.Any(k => k.Agent == kind && k.ModelId is null))
            continue;

        await AddSnapshotAsync(new AgentMembership
        {
            Agent = kind,
            Billing = AgentBilling.Subscription,
            QualityScore = 100,
        }, classId: null, classDisplayName: null);
    }

    var budgets = new List<object>();
    bool budgetsError = false;
    if (budgetProvider is not null)
    {
        IReadOnlyList<AgentBudgetUsageView> views;
        try
        {
            views = await budgetProvider.SummariseAllAsync(ct);
        }
        catch (Exception ex)
        {
            // Surface the failure to operators polling /quota (e.g. during an
            // incident) rather than masquerading as "no budgets configured".
            loggerFactory.CreateLogger("Quota").LogWarning(
                ex, "Quota: budget summarisation failed; returning budgetsError=true");
            views = Array.Empty<AgentBudgetUsageView>();
            budgetsError = true;
        }
        foreach (var v in views)
        {
            budgets.Add(new
            {
                agent = v.Agent,
                model = v.Model,
                windows = v.Windows.Select(w => new
                {
                    kind = w.Kind,
                    hours = w.Hours,
                    usedCents = w.UsedCents,
                    limitCents = w.LimitCents,
                    percentRemaining = Math.Round(w.PercentRemaining, 2),
                    resetAt = w.ResetAt,
                }).ToList(),
            });
        }
    }

    return Results.Ok(new
    {
        generatedAt = now,
        minQuotaPct = options.MinQuotaPct,
        unknownPolicy = options.UnknownPolicy.ToString(),
        observedFailureWindowMinutes = options.ObservedFailureWindow.TotalMinutes,
        intraKindRoutingPolicy = options.IntraKindRoutingPolicy.ToString(),
        probes = snapshots,
        kindAggregates = kindAggregateCounts
            .OrderBy(kv => kv.Key, StringComparer.OrdinalIgnoreCase)
            .Select(kv => new
            {
                agent = kv.Key,
                instances = kv.Value,
            })
            .ToList(),
        pausedAgents = pausedStates.Select(s => new
        {
            agent = s.Agent.Value,
            agentInstanceId = s.AgentInstanceId,
            paused = s.Paused,
            pausedAt = s.PausedAt,
            pausedReason = s.PausedReason,
            pausedBy = s.PausedBy,
            expiresAt = s.ExpiresAt,
            updatedAt = s.UpdatedAt,
        }).ToList(),
        budgets,
        budgetsError,
        observedFailuresLast60m = failures,
    });
});

app.MapGet("/concurrency", async (
    OrchestratorService orchestrator,
    AgentClassRouter router,
    IAgentBurnEstimator burnEstimator,
    IAgentAvailabilityRegistry? availability,
    CancellationToken ct) =>
{
    var state = orchestrator.GetConcurrencyState();

    // Latest avg-burn per agent for every kind appearing in caps or running.
    var allAgents = new HashSet<string>(
        state.PerAgentCaps.Keys
            .Concat(state.CurrentlyRunningPerAgent.Keys),
        StringComparer.OrdinalIgnoreCase);

    var burns = new List<object>(allAgents.Count);
    foreach (var name in allAgents)
    {
        var est = await burnEstimator.GetEstimateAsync(new AgentKind(name), ct);
        burns.Add(new
        {
            agent = name,
            avgBurnPctPerItem = est.AvgBurnPctPerItem,
            sampleCount = est.SampleCount,
            status = est.Status.ToString(),
        });
    }

    // Per-class rate-aware fit estimates (one entry per subscription member).
    var fits = new List<MemberFitView>();
    foreach (var classId in router.ClassIds)
    {
        var classFits = await router.SummariseFitsAsync(classId, ct);
        fits.AddRange(classFits);
    }

    // Smoke-gate / fast-fail exclusion state, one entry per agent the registry
    // has seen. The /concurrency endpoint is the canonical operator surface for
    // "why isn't this agent picking up work" — exclusion has to live alongside
    // burn / fit so the operator sees the full picture without joining JSON.
    var availabilityView = availability?.Snapshot() ?? Array.Empty<AgentAvailabilitySnapshot>();

    return Results.Ok(new
    {
        globalMaxConcurrent = state.GlobalMaxConcurrent,
        currentlyRunningTotal = state.CurrentlyRunningTotal,
        perAgentCaps = state.PerAgentCaps,
        perAgentAuditCaps = state.PerAgentAuditCaps,
        // The cap-compared total: every in-flight agent CLI session on the
        // route — work turns plus LLM auditor sessions.
        currentlyRunningPerAgent = state.CurrentlyRunningPerAgent,
        currentlyRunningWorkPerAgent = state.CurrentlyRunningWorkPerAgent,
        currentlyRunningAuditPerAgent = state.CurrentlyRunningAuditPerAgent,
        burnEstimates = burns,
        memberFits = fits.Select(f => new
        {
            classId = f.ClassId,
            agent = f.Agent.Value,
            modelId = f.ModelId,
            availablePct = f.AvailablePct,
            avgBurnPctPerItem = f.AvgBurnPctPerItem,
            sampleCount = f.SampleCount,
            status = f.BurnEstimateStatus.ToString(),
            fitInWindow = double.IsFinite(f.FitInWindow) ? f.FitInWindow : (double?)null,
            runningOnAgent = f.RunningOnAgent,
        }),
        agentAvailability = availabilityView.Select(s => new
        {
            agent = s.Agent.Value,
            excluded = s.Excluded,
            reason = s.Reason,
            consecutiveFastFails = s.ConsecutiveFastFails,
            consecutiveNoChanges = s.ConsecutiveNoChanges,
            lastSmokePassedAt = s.LastSmokePassedAt,
            lastSmokeFailedAt = s.LastSmokeFailedAt,
            lastFastFailAt = s.LastFastFailAt,
            lastNoChangesAt = s.LastNoChangesAt,
        }),
    });
});

// ── Admin: agent availability ─────────────────────────────────────────────
// Operators use these endpoints after correcting a smoke / fast-fail
// exclusion (e.g. installing the missing binary, rotating credentials) to
// either trigger an immediate probe or to clear the fast-fail counter.

app.MapPost("/admin/agent/{name}/smoke", async (
    string name,
    IHostSmokeProbeRunner hostProbe,
    IInVmSmokeGate inVmGate,
    IAgentAvailabilityRegistry registry,
    CancellationToken ct) =>
{
    // Canonical AgentKind values are lowercase ("cursor", "claude", ...) so a
    // capitalised typo (POST /admin/agent/Cursor/smoke) used to return 404
    // even when the underlying probe was registered. Normalise so case
    // never silently shadows the operator's intent.
    var kind = new AgentKind(name.ToLowerInvariant());

    // Host-side credential probe (env-var presence on the orchestrator host).
    var hostResult = await hostProbe.ProbeAsync(kind, ct);

    // In-VM gate: the real in-sandbox CLI verification the host probe could not
    // be (exit 127 / auth-path drift / workspace-trust). Force a re-probe so an
    // operator who just corrected such an issue clears the in-VM bench here
    // rather than waiting for the next background sweep — otherwise "smoke ok"
    // from the host probe could mask a standing in-VM exclusion. Routes through
    // the IInVmSmokeGate port, not the concrete prober. Null when in-VM smoke is
    // disabled or no in-VM probe is registered for this agent.
    var inVmAvailability = await inVmGate.ForceProbeAsync(kind, ct);

    // 404 only when neither layer knows this agent — a typo, not a healthy agent
    // that simply has one probe layer.
    if (hostResult is null && inVmAvailability is null)
        return Results.NotFound(new { error = $"no smoke probe registered for agent '{Validation.DescribeUntrustedValue(name)}'" });

    var availability = registry.GetAvailability(kind);
    object? hostSmoke = hostResult is null ? null : new
    {
        ok = hostResult.Ok,
        reason = hostResult.FailureReason,
        durationMs = (long)hostResult.Duration.TotalMilliseconds,
    };
    object? inVmSmoke = inVmAvailability is null ? null : new
    {
        available = inVmAvailability.Available,
        reason = inVmAvailability.Reason,
    };
    return Results.Ok(new
    {
        agent = kind.Value,
        smoke = hostSmoke,
        inVmSmoke,
        availability = new
        {
            available = availability.Available,
            reason = availability.Reason,
        },
    });
});

app.MapPost("/admin/agent/{name}/reset", (
    string name,
    HttpContext httpContext,
    ApiKeyState apiKeyState,
    IAgentAvailabilityRegistry registry,
    IAgentRegistry agents,
    IAgentAvailabilityReset reset) =>
{
    if (!ApiKeyAuth.IsAuthorized(httpContext, apiKeyState))
    {
        httpContext.Response.Headers["WWW-Authenticate"] = "Bearer";
        return Results.Text("unauthorized", statusCode: StatusCodes.Status401Unauthorized);
    }

    // Mirror /smoke: normalise to lowercase so case-mismatched names match the
    // canonical kinds returned by IAgentRegistry.Available.
    var kind = new AgentKind(name.ToLowerInvariant());
    // Validate the agent is actually registered; without this, a typo
    // (e.g. /admin/agent/curser/reset) silently returns 200 and the operator
    // never realises the call did nothing.
    if (!agents.Available.Contains(kind))
        return Results.NotFound(new { error = $"unknown agent '{Validation.DescribeUntrustedValue(name)}'" });
    // Single reset port: clears the registry AND invalidates the in-VM smoke
    // cache together, so a stale cached pass can't reconcile straight back onto
    // the registry before the operator's fix is re-verified. The same call
    // also clears every cached quota-exhaustion verdict for the agent (router
    // in-process gates plus probe-side runtime 429 overrides): a bench that
    // was recorded on stale or misattributed evidence must not survive every
    // administrative action but a process restart. The clear is audit-logged
    // with the calling operator.
    reset.Reset(kind);
    var clearedBy = ApiKeyAuth.TryGetPrincipal(httpContext, out var principal) && principal is not null
        ? principal.Name
        : "operator";
    var exhaustion = reset.ResetQuotaExhaustion(kind, clearedBy);
    var availability = registry.GetAvailability(kind);
    return Results.Ok(new
    {
        agent = kind.Value,
        availability = new
        {
            available = availability.Available,
            reason = availability.Reason,
        },
        quotaExhaustion = new
        {
            routerCleared = exhaustion.RouterEntriesCleared,
            probeCleared = exhaustion.ProbeEntriesCleared,
            evidence = exhaustion.ClearedEvidence,
        },
    });
});

app.MapGet("/admin/agents/availability", (IAgentAvailabilityRegistry registry) =>
{
    return Results.Ok(new
    {
        agents = registry.Snapshot().Select(s => new
        {
            agent = s.Agent.Value,
            excluded = s.Excluded,
            reason = s.Reason,
            consecutiveFastFails = s.ConsecutiveFastFails,
            consecutiveNoChanges = s.ConsecutiveNoChanges,
            lastSmokePassedAt = s.LastSmokePassedAt,
            lastSmokeFailedAt = s.LastSmokeFailedAt,
            lastFastFailAt = s.LastFastFailAt,
            lastNoChangesAt = s.LastNoChangesAt,
        }),
    });
});

app.MapGet("/events/schema", () => Results.Ok(EventSchema.GetSchema()));

app.MapGet("/healthz", (ISandboxProvider sandboxes, DeployConsistencyService consistency) =>
{
    // Surface free-disk metrics for each path the disk-guard monitors so
    // dashboards can alert before the orchestrator starts deferring or the
    // state store hits SQLITE_FULL. Providers opt in by implementing the
    // IDiskGuardedSandboxProvider capability interface — providers without
    // a disk-guard report an empty list, preserving the previous response
    // shape on a best-effort basis.
    object[] disk = sandboxes is IDiskGuardedSandboxProvider guarded
        ? guarded.SampleDiskGuardState().Select(s => (object)new
        {
            path = s.Path,
            freeBytes = s.FreeBytes,
            thresholdBytes = s.ThresholdBytes,
            belowThreshold = s.FreeBytes is long b && b < s.ThresholdBytes,
        }).ToArray()
        : [];

    // Deploy consistency is refreshed on every probe so operators can observe
    // a git pull moving the checkout ahead of bin/ without restarting. The
    // refresh is a few capped file reads and never throws.
    var report = consistency.Refresh();
    return Results.Ok(new
    {
        status = "ok",
        sandbox = new
        {
            provider = sandboxes.Name,
            isolation = sandboxes.IsolationLevel.ToString()
        },
        disk,
        deploy = DeployConsistencyEndpoints.BuildPayload(report),
    });
});

Program.RunHost(app);

namespace CodeyBox.Api
{
    /// <summary>
    /// Provider-neutral lifecycle inventory retained across a process restart
    /// during a hot-reload provider cutover. IDs must name providers registered
    /// in the API's reloadable provider set.
    /// </summary>
    public sealed class SandboxProviderCutoverConfig
    {
        public const int MaximumRetainedInventoryProviders =
            ReloadableSandboxProvider.MaximumRetainedInventoryProviders;

        /// <summary>
        /// Provider IDs whose managed sandboxes and baselines must continue to
        /// be inventoried and reaped even when another provider is selected.
        /// </summary>
        public List<string> RetainedInventoryProviders { get; set; } = [];
    }

    /// <summary>
    /// Hot-reloadable settings for
    /// <c>CodeyBox:SandboxProvider=incus</c>. Changes under
    /// <c>CodeyBox:Incus</c> (except the restart-only project and staging
    /// identities) are captured by the next provider operation. Existing
    /// sandboxes retain their provisioning topology, while host-process
    /// cleanup and transient exec retry policies are read live.
    ///
    /// The configured storage pool must already exist and use the ZFS or Btrfs
    /// driver; ZFS is strongly recommended for VM workloads.
    /// See <c>docs/concepts/sandboxes.md</c> for the host setup and security
    /// requirements.
    /// </summary>
    public sealed class IncusSandboxConfig
    {
        private static readonly IncusSandboxOptions Defaults = new();

        /// <summary>Incus CLI executable name or absolute path.</summary>
        public string BinaryPath { get; set; } = Defaults.BinaryPath;

        /// <summary>Restart-only dedicated non-default restricted Incus project that owns all CodeyBox instances; created and verified idempotently when absent.</summary>
        public string ProjectName { get; set; } = Defaults.ProjectName;

        /// <summary>Name of the pre-created ZFS or Btrfs storage pool used for VM roots and COW clones.</summary>
        public string StoragePoolName { get; set; } = Defaults.StoragePoolName;

        /// <summary>Incus VM image used when a sandbox spec has no explicit image reference.</summary>
        public string DefaultImage { get; set; } = Defaults.DefaultImage;

        /// <summary>Prefix for ordinary provider-owned VM instance names.</summary>
        public string InstanceNamePrefix { get; set; } = Defaults.InstanceNamePrefix;

        /// <summary>Prefix for content-addressed baked baseline VM names.</summary>
        public string BaselineNamePrefix { get; set; } = Defaults.BaselineNamePrefix;

        /// <summary>Use lazily baked baselines and COW <c>incus copy</c> clones for sandbox creation.</summary>
        public bool UseBaselineImages { get; set; } = Defaults.UseBaselineImages;

        /// <summary>Enable UEFI Secure Boot for newly initialized Incus VMs.</summary>
        public bool SecureBoot { get; set; } = Defaults.SecureBoot;

        /// <summary>
        /// Shell commands run once while baking a baseline or during a full
        /// launch.
        /// </summary>
        public List<string> ExtraRuncmd { get; set; } = [.. Defaults.ExtraRuncmd];

        /// <summary>Host package-cache files or directories copied during Incus baseline or full-launch provisioning.</summary>
        public List<PackageCacheSeedConfig> PackageCacheSeeds { get; set; } = [];

        /// <summary>Guest path of the shared NuGet fallback folder served read-only instead of copied into the writable package root.</summary>
        public string NuGetFallbackGuestPath { get; set; } = Defaults.NuGetFallbackGuestPath;

        /// <summary>Serve NuGet-targeted package seeds as read-only fallback folders; disable to keep the legacy per-VM copy for every seed.</summary>
        public bool ShareNuGetPackageSeedsAsFallback { get; set; } = Defaults.ShareNuGetPackageSeedsAsFallback;

        /// <summary>Host-staged executables copied during Incus baseline or full-launch provisioning.</summary>
        public List<ExecutableProvisionConfig> ExecutableProvisions { get; set; } = [];

        /// <summary>
        /// Additional top-level cloud-init YAML merged into generated user
        /// data. This is operator-visible configuration and must not contain
        /// secrets.
        /// </summary>
        public string? ExtraCloudInit { get; set; } = Defaults.ExtraCloudInit;

        /// <summary>Restart-only host directory for isolated mount snapshots and provider staging.</summary>
        public string? StagingDirectory { get; set; } = Defaults.StagingDirectory;

        /// <summary>
        /// Additional canonical host-directory roots that Incus may expose
        /// through virtiofs. <c>GitRootDirectory</c> and the enabled shared
        /// upstream mirror directory are always included.
        /// </summary>
        public List<string> AllowedHostMountRoots { get; set; } = [.. Defaults.AllowedHostMountRoots];

        /// <summary>Numeric non-root guest user ID; must match the effective host UID when attaching any host path.</summary>
        public uint GuestUserId { get; set; } = Defaults.GuestUserId;

        /// <summary>Numeric non-root guest group ID; must match the effective host GID when attaching any host path.</summary>
        public uint GuestGroupId { get; set; } = Defaults.GuestGroupId;

        /// <summary>Absolute home directory of the configured guest user.</summary>
        public string GuestHome { get; set; } = Defaults.GuestHome;

        /// <summary>Default deadline for a single Incus CLI lifecycle operation.</summary>
        public TimeSpan OperationTimeout { get; set; } = Defaults.OperationTimeout;

        /// <summary>Provider-side upper bound for one guest command; caller and sandbox wall-clock limits may be shorter.</summary>
        public TimeSpan ExecTimeout { get; set; } = Defaults.ExecTimeout;

        /// <summary>
        /// Deadline applied to a cold Incus image/root initialization operation and,
        /// separately, to executable staging/install, verification, and package-cache
        /// seeding (including host input capture).
        /// </summary>
        public TimeSpan ImageProvisioningTimeout { get; set; } = Defaults.ImageProvisioningTimeout;

        /// <summary>Deadline for VM boot and guest readiness.</summary>
        public TimeSpan VmStartTimeout { get; set; } = Defaults.VmStartTimeout;

        /// <summary>Deadline for a graceful VM stop.</summary>
        public TimeSpan VmStopTimeout { get; set; } = Defaults.VmStopTimeout;

        /// <summary>Deadline for cloud-init to finish inside a newly booted VM.</summary>
        public TimeSpan CloudInitTimeout { get; set; } = Defaults.CloudInitTimeout;

        /// <summary>Deadline for a virtiofs mount to become usable in the guest.</summary>
        public TimeSpan MountReadyTimeout { get; set; } = Defaults.MountReadyTimeout;

        /// <summary>Delay between VM/agent readiness probes.</summary>
        public TimeSpan ReadinessPollInterval { get; set; } = Defaults.ReadinessPollInterval;

        /// <summary>Upper bound for the guest-agent readiness poll interval; the poll backs off exponentially from <see cref="ReadinessPollInterval"/> to this cap so a boot storm does not hammer incusd.</summary>
        public TimeSpan MaxReadinessPollInterval { get; set; } = Defaults.MaxReadinessPollInterval;

        /// <summary>Delay before the recovery stack re-attempts a sandbox creation deferred because an Incus liveness deadline tripped under concurrent boot load.</summary>
        public TimeSpan ProvisioningRetryRecheckIn { get; set; } = Defaults.ProvisioningRetryRecheckIn;

        /// <summary>Allowlisted exact Incus error signatures classified as transient host infrastructure. Hot-reloadable.</summary>
        public List<string> TransientInfrastructureSignatures { get; set; } = [.. Defaults.TransientInfrastructureSignatures];

        /// <summary>Independent deadline for terminating and draining one Incus CLI process tree.</summary>
        public TimeSpan CliProcessCleanupTimeout { get; set; } = Defaults.CliProcessCleanupTimeout;

        /// <summary>Delay between Linux Incus CLI process-group absence probes during cleanup.</summary>
        public TimeSpan CliProcessGroupExitPollInterval { get; set; } = Defaults.CliProcessGroupExitPollInterval;

        /// <summary>Attempts to read an active guest exec process-group ID before forced cleanup.</summary>
        public int ExecPidPollAttempts { get; set; } = Defaults.ExecPidPollAttempts;

        /// <summary>Attempts to delete and verify each transient guest exec control file.</summary>
        public int ExecControlFileCleanupAttempts { get; set; } = Defaults.ExecControlFileCleanupAttempts;

        /// <summary>Attempts to read and validate a guest exec completion sentinel.</summary>
        public int ExecCompletionProbeAttempts { get; set; } = Defaults.ExecCompletionProbeAttempts;

        /// <summary>Delayed recovery attempts after immediate interrupted-exec recovery fails; zero disables delayed recovery.</summary>
        public int InterruptedExecRecoveryRetryAttempts { get; set; } = Defaults.InterruptedExecRecoveryRetryAttempts;

        /// <summary>Delay before each delayed interrupted-exec recovery attempt.</summary>
        public TimeSpan InterruptedExecRecoveryRetryDelay { get; set; } = Defaults.InterruptedExecRecoveryRetryDelay;

        /// <summary>Maximum number of concurrent heavy Incus lifecycle/device operations.</summary>
        public int MaxConcurrentOperations { get; set; } = Defaults.MaxConcurrentOperations;

        /// <summary>Maximum VM boots (incus start + guest-agent readiness) in flight at once — staggers boots so a boot storm does not starve incusd and blow the readiness window. Hot-reloadable.</summary>
        public int MaxConcurrentBoots { get; set; } = Defaults.MaxConcurrentBoots;

        /// <summary>Inter-boot stagger in milliseconds applied after acquiring a boot slot. Zero disables the delay.</summary>
        public int BootLaunchDelayMs { get; set; } =
            (int)Defaults.BootLaunchDelay.TotalMilliseconds;

        /// <summary>Maximum stdout bytes retained from one Incus CLI invocation.</summary>
        public int MaxCliStdoutBytes { get; set; } = Defaults.MaxCliStdoutBytes;

        /// <summary>Maximum stderr bytes retained from one Incus CLI invocation.</summary>
        public int MaxCliStderrBytes { get; set; } = Defaults.MaxCliStderrBytes;

        /// <summary>Bounded in-memory stdout tail retained by agent-turn streaming execs. Hot-reloadable.</summary>
        public int AgentExecTailStdoutBytes { get; set; } = Defaults.AgentExecTailStdoutBytes;

        /// <summary>Bounded in-memory stderr tail retained by agent-turn streaming execs. Hot-reloadable.</summary>
        public int AgentExecTailStderrBytes { get; set; } = Defaults.AgentExecTailStderrBytes;

        /// <summary>Capture best-effort guest resource metrics before sandbox teardown.</summary>
        public bool CaptureResourceMetrics { get; set; } = Defaults.CaptureResourceMetrics;

        /// <summary>Deadline for the best-effort resource metrics capture during teardown.</summary>
        public TimeSpan ResourceMetricsCaptureTimeout { get; set; } = Defaults.ResourceMetricsCaptureTimeout;

        /// <summary>Interval used by the guest peak-memory sampler.</summary>
        public TimeSpan ResourceMetricsSampleInterval { get; set; } = Defaults.ResourceMetricsSampleInterval;

        /// <summary>Default vCPU allocation baked into baseline VMs.</summary>
        public int BaselineCpus { get; set; } = Defaults.BaselineCpus;

        /// <summary>Default baseline VM memory allocation in bytes.</summary>
        public long BaselineMemoryBytes { get; set; } = Defaults.BaselineMemoryBytes;

        /// <summary>Default baseline root-disk size in bytes.</summary>
        public long BaselineDiskBytes { get; set; } = Defaults.BaselineDiskBytes;

        /// <summary>Maximum bytes accepted for one host-staged executable.</summary>
        public long MaxExecutableProvisionBytes { get; set; } = Defaults.MaxExecutableProvisionBytes;

        /// <summary>Maximum aggregate bytes accepted across host-staged executables.</summary>
        public long MaxAggregateExecutableProvisionBytes { get; set; } = Defaults.MaxAggregateExecutableProvisionBytes;

        /// <summary>Maximum bytes accepted for one package-cache seed.</summary>
        public long MaxPackageCacheSeedBytes { get; set; } = Defaults.MaxPackageCacheSeedBytes;

        /// <summary>Maximum aggregate bytes accepted across package-cache seeds.</summary>
        public long MaxAggregatePackageCacheSeedBytes { get; set; } = Defaults.MaxAggregatePackageCacheSeedBytes;

        /// <summary>Maximum filesystem entries inspected while copying one package-cache seed.</summary>
        public int MaxPackageCacheSeedEntries { get; set; } = Defaults.MaxPackageCacheSeedEntries;

        /// <summary>Maximum aggregate bytes copied into private host staging for one sandbox.</summary>
        public long MaxSnapshotBytes { get; set; } = Defaults.MaxSnapshotBytes;

        /// <summary>Maximum files, directories, and links copied into private host staging for one sandbox.</summary>
        public int MaxSnapshotEntries { get; set; } = Defaults.MaxSnapshotEntries;

        /// <summary>Maximum direct-mount entries inspected while choosing a host-to-guest identity probe.</summary>
        public int MaxReadinessProbeEntries { get; set; } = Defaults.MaxReadinessProbeEntries;

        /// <summary>Maximum logical size of one guest tmpfs device.</summary>
        public long MaxTmpfsDeviceBytes { get; set; } = Defaults.MaxTmpfsDeviceBytes;

        /// <summary>Maximum aggregate logical size of all guest tmpfs devices in one sandbox.</summary>
        public long MaxAggregateTmpfsBytes { get; set; } = Defaults.MaxAggregateTmpfsBytes;
    }

    public sealed class MultipassSandboxConfig
    {
        /// <summary>
        /// Number of <c>cloud-init status --wait</c> attempts before falling
        /// back to the Multipass readiness probe for exit 1.
        /// </summary>
        public int CloudInitReadyRetryAttempts { get; set; } =
            MultipassSandboxOptions.DefaultCloudInitReadyRetryAttempts;

        /// <summary>
        /// Deadline for the post-launch poll that waits for the VM to reach
        /// the <c>Running</c> state, and for each blocking cloud-init readiness
        /// probe. Defaults to 3 minutes. Bump on hosts that observe boot
        /// contention under concurrent launches.
        /// </summary>
        public TimeSpan VmStartTimeout { get; set; } =
            MultipassSandboxOptions.DefaultVmStartTimeout;

        /// <summary>
        /// Deadline for the post-stop poll that waits for the VM to reach the
        /// <c>Stopped</c> state. Defaults to 2 minutes.
        /// </summary>
        public TimeSpan VmStopTimeout { get; set; } =
            MultipassSandboxOptions.DefaultVmStopTimeout;

        /// <summary>
        /// Max concurrent multipass launch/start operations.
        /// Independent of worker pool concurrency. Default 2.
        /// </summary>
        public int MaxConcurrentBoots { get; set; } =
            MultipassSandboxOptions.DefaultMaxConcurrentBoots;

        /// <summary>
        /// Optional inter-boot delay in milliseconds. 0 = no delay.
        /// </summary>
        public int BootLaunchDelayMs { get; set; } =
            (int)MultipassSandboxOptions.DefaultBootLaunchDelay.TotalMilliseconds;

        /// <summary>
        /// When true, disables the detached agent-output HTTP-ingest transport
        /// (#290) so all agent execs use the attached <c>multipass exec</c> pipe.
        /// Repair switch for the merge-phase regression where the detached
        /// transport drops a freshly-created sandbox's agent stdout + exit code.
        /// </summary>
        public bool DisableAgentOutputHttpIngest { get; set; }

        /// <summary>
        /// When true, multipass sandbox disposal makes one short best-effort
        /// in-VM exec before delete/preserve teardown to capture resource
        /// metrics for capacity planning. Default false.
        /// </summary>
        public bool CaptureResourceMetrics { get; set; }

        /// <summary>
        /// Timeout for the best-effort resource metrics capture exec. Values
        /// less than or equal to zero use the provider default (5 seconds).
        /// </summary>
        public int ResourceMetricsCaptureTimeoutSeconds { get; set; } =
            (int)MultipassSandboxOptions.DefaultResourceMetricsCaptureTimeout.TotalSeconds;
    }

    /// <summary>
    /// Configuration for <c>CodeyBox:SandboxProvider=multipass-remote</c>.
    /// Drives the SSH-backed multipass provider that runs each work-item VM
    /// on a remote host while the orchestrator brain stays local.
    /// </summary>
    public sealed class MultipassRemoteSandboxConfig
    {
        /// <summary>
        /// Default SSH destination passed verbatim to <c>ssh &lt;target&gt;</c>.
        /// Required for single-host mode; optional when every executor host
        /// under <see cref="ExecutorHosts"/> supplies its own target.
        /// </summary>
        public string? SshTarget { get; set; }

        /// <summary>OpenSSH binary. Default <c>ssh</c> (resolved via $PATH).</summary>
        public string? SshBinary { get; set; }

        /// <summary>Optional SSH port override.</summary>
        public int? SshPort { get; set; }

        /// <summary>Identity file path. Null = use whatever <c>~/.ssh/config</c> / agent resolves.</summary>
        public string? SshKeyPath { get; set; }

        /// <summary>Extra <c>-o Key=Value</c> options appended verbatim. Validated to look like <c>Key=Value</c> with no whitespace.</summary>
        public IList<string>? ExtraSshOptions { get; set; }

        /// <summary>
        /// When true, host key trust-on-first-use (<c>StrictHostKeyChecking=accept-new</c>).
        /// Leave false in production — let an unknown host key fail loudly.
        /// </summary>
        public bool AcceptUnknownHostKeys { get; set; }

        /// <summary>OpenSSH <c>ServerAliveInterval</c> seconds. Null = provider default (30).</summary>
        public int? ServerAliveIntervalSeconds { get; set; }

        /// <summary>OpenSSH <c>ServerAliveCountMax</c>. Null = provider default (6).</summary>
        public int? ServerAliveCountMax { get; set; }

        /// <summary>OpenSSH <c>ConnectTimeout</c> seconds. Null = provider default (20).</summary>
        public int? ConnectTimeoutSeconds { get; set; }

        /// <summary>Local tar binary used by the staging pipeline. Default <c>tar</c>.</summary>
        public string? LocalTarBinary { get; set; }

        /// <summary>Maximum tar bytes accepted from a remote writable mount during sync-back. Null = provider default.</summary>
        public long? StageOutMaxArchiveBytes { get; set; }

        /// <summary>Maximum non-metadata tar entries accepted during remote sync-back validation. Null = provider default.</summary>
        public int? StageOutMaxEntries { get; set; }

        /// <summary>Maximum declared-payload/archive-byte ratio accepted during remote sync-back validation. Null = provider default.</summary>
        public double? StageOutMaxExpansionRatio { get; set; }

        /// <summary>Maximum stdout/stderr bytes accepted from remote inventory commands. Null = provider default.</summary>
        public int? RemoteInventoryMaxOutputBytes { get; set; }

        /// <summary>Absolute path to <c>multipass</c> on the remote host.</summary>
        public string? RemoteMultipassPath { get; set; }

        /// <summary>Absolute path on the remote host where per-sandbox staging dirs live.</summary>
        public string? RemoteStagingRoot { get; set; }

        /// <summary>Default multipass image alias when SandboxSpec.ImageReference is empty.</summary>
        public string? DefaultImage { get; set; }

        /// <summary>Deadline for waiting on the VM to reach <c>Running</c>. Null = provider default.</summary>
        public TimeSpan? VmStartTimeout { get; set; }

        /// <summary>Deadline for waiting on the VM to reach <c>Stopped</c>. Null = provider default.</summary>
        public TimeSpan? VmStopTimeout { get; set; }

        /// <summary>VM-state polling interval used during waits. Null = provider default.</summary>
        public TimeSpan? VmStateCheckInterval { get; set; }

        /// <summary>
        /// Naming prefix the provider applies to every VM it creates on the
        /// remote host. Used by <c>multipass list</c> filtering and by the
        /// leak-dispose safety check that refuses to delete arbitrary VMs.
        /// </summary>
        public string? VmNamePrefix { get; set; }

        /// <summary>
        /// Optional host-local cap for the legacy single-host shape. Null means
        /// uncapped here; global WorkerPool sandbox/worker gates still apply.
        /// </summary>
        public int? MaxConcurrentSandboxes { get; set; }

        /// <summary>No new VMs are placed on this host while true; existing VMs drain.</summary>
        public bool Cordoned { get; set; }

        /// <summary>Operator health gate. False routes new VMs away from this host.</summary>
        public bool Healthy { get; set; } = true;

        /// <summary>
        /// Logical network profiles this host accepts. Empty or "*" means all;
        /// "(default)" matches sandboxes with no explicit network profile.
        /// </summary>
        public IList<string>? AllowedNetworkProfiles { get; set; }

        /// <summary>Retry delay when no executor host currently has eligible capacity.</summary>
        public TimeSpan? PlacementRecheckIn { get; set; }

        /// <summary>Runtime unhealthy backoff after an SSH transport drop.</summary>
        public TimeSpan? RuntimeUnhealthyBackoff { get; set; }

        /// <summary>
        /// Multi-host executor pool. Host entries inherit unset SSH/staging
        /// fields from this top-level block. When empty, the top-level block is
        /// treated as one legacy host named "default".
        /// </summary>
        public IList<MultipassRemoteExecutorHostConfig>? ExecutorHosts { get; set; }

        /// <summary>
        /// Maps logical network-profile names to bridge names on the remote
        /// Multipass host(s). When omitted (null/empty), the remote provider
        /// falls back to the global <c>SandboxNetworkProfiles</c> map for
        /// backward compatibility.
        /// </summary>
        public Dictionary<string, string>? NetworkProfiles { get; set; }
    }

    public sealed class MultipassRemoteExecutorHostConfig
    {
        public string? Id { get; set; }
        public string? SshTarget { get; set; }
        public string? SshBinary { get; set; }
        public int? SshPort { get; set; }
        public string? SshKeyPath { get; set; }
        public IList<string>? ExtraSshOptions { get; set; }
        public bool? AcceptUnknownHostKeys { get; set; }
        public int? ServerAliveIntervalSeconds { get; set; }
        public int? ServerAliveCountMax { get; set; }
        public int? ConnectTimeoutSeconds { get; set; }
        public string? LocalTarBinary { get; set; }
        public long? StageOutMaxArchiveBytes { get; set; }
        public int? StageOutMaxEntries { get; set; }
        public double? StageOutMaxExpansionRatio { get; set; }
        public int? RemoteInventoryMaxOutputBytes { get; set; }
        public string? RemoteMultipassPath { get; set; }
        public string? RemoteStagingRoot { get; set; }
        public string? DefaultImage { get; set; }
        public TimeSpan? VmStartTimeout { get; set; }
        public TimeSpan? VmStopTimeout { get; set; }
        public TimeSpan? VmStateCheckInterval { get; set; }
        public string? VmNamePrefix { get; set; }
        public int? MaxConcurrentSandboxes { get; set; }
        public bool? Cordoned { get; set; }
        public bool? Healthy { get; set; }
        public IList<string>? AllowedNetworkProfiles { get; set; }
    }

    /// <summary>
    /// Per-host configuration for the E2E replay pool. Capacity belongs here,
    /// not on <see cref="MultipassRemoteSandboxConfig"/>, so the normal coding
    /// fleet's remote provider config remains focused on SSH/provider settings.
    /// </summary>
    public sealed class E2eMultipassRemoteHostConfig
    {
        /// <summary>Remote Multipass provider settings for this E2E host.</summary>
        public MultipassRemoteSandboxConfig RemoteSandbox { get; set; } = new();

        /// <summary>
        /// Per-host lease cap. Null defaults to one replay per host; the global
        /// <c>E2eExecution:MaxConcurrent</c> still caps aggregate pool pressure.
        /// </summary>
        public int? MaxConcurrent { get; set; }

        public string? SshTarget { get => RemoteSandbox.SshTarget; set => RemoteSandbox.SshTarget = value; }
        public string? SshBinary { get => RemoteSandbox.SshBinary; set => RemoteSandbox.SshBinary = value; }
        public int? SshPort { get => RemoteSandbox.SshPort; set => RemoteSandbox.SshPort = value; }
        public string? SshKeyPath { get => RemoteSandbox.SshKeyPath; set => RemoteSandbox.SshKeyPath = value; }
        public IList<string>? ExtraSshOptions { get => RemoteSandbox.ExtraSshOptions; set => RemoteSandbox.ExtraSshOptions = value; }
        public bool AcceptUnknownHostKeys { get => RemoteSandbox.AcceptUnknownHostKeys; set => RemoteSandbox.AcceptUnknownHostKeys = value; }
        public int? ServerAliveIntervalSeconds { get => RemoteSandbox.ServerAliveIntervalSeconds; set => RemoteSandbox.ServerAliveIntervalSeconds = value; }
        public int? ServerAliveCountMax { get => RemoteSandbox.ServerAliveCountMax; set => RemoteSandbox.ServerAliveCountMax = value; }
        public int? ConnectTimeoutSeconds { get => RemoteSandbox.ConnectTimeoutSeconds; set => RemoteSandbox.ConnectTimeoutSeconds = value; }
        public string? LocalTarBinary { get => RemoteSandbox.LocalTarBinary; set => RemoteSandbox.LocalTarBinary = value; }
        public string? RemoteMultipassPath { get => RemoteSandbox.RemoteMultipassPath; set => RemoteSandbox.RemoteMultipassPath = value; }
        public string? RemoteStagingRoot { get => RemoteSandbox.RemoteStagingRoot; set => RemoteSandbox.RemoteStagingRoot = value; }
        public string? DefaultImage { get => RemoteSandbox.DefaultImage; set => RemoteSandbox.DefaultImage = value; }
        public TimeSpan? VmStartTimeout { get => RemoteSandbox.VmStartTimeout; set => RemoteSandbox.VmStartTimeout = value; }
        public TimeSpan? VmStopTimeout { get => RemoteSandbox.VmStopTimeout; set => RemoteSandbox.VmStopTimeout = value; }
        public TimeSpan? VmStateCheckInterval { get => RemoteSandbox.VmStateCheckInterval; set => RemoteSandbox.VmStateCheckInterval = value; }
        public string? VmNamePrefix { get => RemoteSandbox.VmNamePrefix; set => RemoteSandbox.VmNamePrefix = value; }

        public static implicit operator E2eMultipassRemoteHostConfig(MultipassRemoteSandboxConfig config)
            => new() { RemoteSandbox = config };
    }

    /// <summary>
    /// Configuration for <c>CodeyBox:SandboxProvider=sprites</c>. The Sprites
    /// rc30 create API accepts only name, capacity wait, and URL auth settings;
    /// CPU/RAM/region values are retained as explicit no-op operator hints.
    /// </summary>
    public sealed class SpritesSandboxConfig
    {
        /// <summary>Sprites REST/WebSocket API base URL. Default <c>https://api.sprites.dev</c>.</summary>
        public string ApiBaseUrl { get; set; } = "https://api.sprites.dev";

        /// <summary>Environment variable read for the bearer token. Default <c>SPRITES_TOKEN</c>.</summary>
        public string TokenEnvironmentVariable { get; set; } = "SPRITES_TOKEN";

        /// <summary>Managed sprite name prefix. Must remain <c>codeybox-</c>-compatible for leak reaping.</summary>
        public string NamePrefix { get; set; } = SpritesSandboxProvider.DefaultNamePrefix;

        /// <summary>Whether create should wait for capacity before returning.</summary>
        public bool WaitForCapacity { get; set; }

        /// <summary>
        /// URL auth setting sent on create. Sprites supports <c>sprite</c> (default,
        /// bearer-token-authenticated per-sprite URL) and <c>public</c>. Setting
        /// <c>public</c> drops access control on the sprite's per-sprite HTTP endpoint
        /// while a work item runs inside it (source tree, agent process, staged mounts),
        /// leaving it reachable without the bearer token — a foot-gun that silently
        /// removes network-level access control on a live work sandbox. Prefer
        /// <c>sprite</c> unless you have an explicit reason and a separate boundary.
        /// </summary>
        public string UrlAuth { get; set; } = "sprite";

        /// <summary>Safety ceiling for paged list calls during leak reaping.</summary>
        public int MaxListPages { get; set; } = 100;

        /// <summary>
        /// Test-only escape hatch for local mock servers. Production Sprites
        /// traffic carries bearer tokens and exec environment variables, so
        /// the provider rejects <c>http://</c> unless this is explicitly true.
        /// </summary>
        public bool AllowUnsafeHttp { get; set; }

        /// <summary>
        /// Explicit downgrade for non-secret tmpfs mounts. Sprites has no
        /// tmpfs API, so the default is to reject <c>SandboxMount.Tmpfs</c>.
        /// When true, non-credential tmpfs paths are created as ordinary
        /// sprite directories and remain subject to sprite persistence until
        /// teardown succeeds.
        /// </summary>
        public bool AllowPersistentTmpfsDowngrade { get; set; }

        /// <summary>
        /// Shell commands run inside each fresh sprite to provision it (rc30
        /// create has no image/baseline field). They execute BEFORE the work
        /// item's egress allow-list is applied and BEFORE mounts are staged,
        /// so they run against OPEN egress until the default-deny policy is
        /// posted after provisioning completes and before the agent runs. This
        /// is deliberate: these operator-trusted commands need to reach package
        /// registries (npm/apt/curl), and no agent code or credential material
        /// is present yet. Use to install agent CLIs and project toolchains.
        /// Note: with open egress, a curl-piped installer can reach arbitrary
        /// hosts; only list commands you trust.
        /// </summary>
        public List<string> SetupCommands { get; set; } = [];

        /// <summary>Sprites egress allow-list domains keyed by CodeyBox network profile name.</summary>
        public Dictionary<string, List<string>> NetworkProfiles { get; set; } = new(StringComparer.OrdinalIgnoreCase);

        /// <summary>Maximum base64 stdout bytes accepted for directory sync-back.</summary>
        public int MaxSyncArchiveBase64Bytes { get; set; } = 128 * 1024 * 1024;

        /// <summary>Maximum compressed gzip/tar bytes accepted for directory sync-back.</summary>
        public int MaxSyncArchiveBytes { get; set; } = 96 * 1024 * 1024;

        /// <summary>Maximum summed regular-file bytes accepted for directory sync-back.</summary>
        public long MaxSyncArchiveExpandedBytes { get; set; } = 512L * 1024 * 1024;

        /// <summary>Maximum tar entries accepted for directory sync-back.</summary>
        public int MaxSyncArchiveEntries { get; set; } = 200_000;

        /// <summary>Maximum base64 stdout bytes accepted for single-file sync-back.</summary>
        public int MaxFileSyncBase64Bytes { get; set; } = 64 * 1024 * 1024;

        /// <summary>Maximum decoded bytes accepted for single-file sync-back.</summary>
        public long MaxFileSyncBytes { get; set; } = 48L * 1024 * 1024;

        /// <summary>Operator hint only; Sprites rc30 has no create-time CPU field.</summary>
        public int? DefaultCpuCount { get; set; }

        /// <summary>Operator hint only; Sprites rc30 has no create-time RAM field.</summary>
        public long? DefaultMemoryBytes { get; set; }

        /// <summary>Operator hint only; Sprites rc30 has no create-time region field.</summary>
        public string? Region { get; set; }
    }

    /// <summary>
    /// Top-level options bag bound from the <c>CodeyBox</c> configuration
    /// section. See <c>docs/reference/configuration.md</c> for the full hot-reload
    /// contract per field. Summary of the rule of thumb consumers should
    /// follow when adding new fields:
    /// <list type="bullet">
    /// <item><b>Hot-reloadable</b> fields are read fresh from
    ///   <see cref="IOptionsMonitor{T}"/> on each consumer access (or
    ///   re-applied via the <c>AgentConfigHotReload</c> bridge). Today:
    ///   <c>TemplateDirectory</c>, <c>MaxTemplateChecks</c>, <c>AgentConcurrency</c>, <c>AgentClasses</c>, <c>AgentScoreModifiers</c>,
    ///   <c>AgentBurnEstimator</c>, <c>AgentPauses</c>, <c>AgentPricing</c>, <c>SqliteWriteGate</c>,
    ///   <c>WorkerPool.MaxConcurrentWorkers</c>, <c>WorkerPool.MaxConcurrentSandboxes</c>,
    ///   <c>WorkerPool.MinSpawnInterval</c>, <c>Smoke.Enabled</c>, <c>DeadWorker</c>
    ///   (per-sweep), <c>Shutdown.SandboxResumeMode</c>,
    ///   <c>Shutdown.SandboxResumeTimeout</c>,
    ///   <c>Shutdown.SandboxAdoptionDeadlineSeconds</c>, <c>SandboxLeak</c>
    ///   (thresholds, per-sweep),
    ///   <c>AuditLog.RetainedDays</c> (DB retention, per-sweep), and the
    ///   sandbox launch fields (<c>Multipass*</c>, <c>Incus.*</c> except
    ///   <c>Incus.ProjectName</c> and effective <c>Incus.StagingDirectory</c>, the guarded
    ///   <c>multipass</c>↔<c>incus</c> <c>SandboxProvider</c> switch,
    ///   <c>SandboxNetworkProfiles</c>,
    ///   per-launch), and <c>Shutdown.SandboxTeardownMode</c> (next graceful
    ///   shutdown).</item>
    /// <item><b>Startup-only and rejected</b> on reload by
    ///   <see cref="ImmutableCodeyBoxOptionsValidator"/>:
    ///   <c>SandboxProvider</c> changes other than the guarded
    ///   <c>multipass</c>↔<c>incus</c> switch, <c>StateDatabasePath</c>,
    ///   <c>GitRootDirectory</c>, <c>GitCommandMaxOutputBytes</c>,
    ///   <c>Incus.ProjectName</c>, effective
    ///   <c>Incus.StagingDirectory</c>, <c>AgentStreams.Path</c>,
    ///   <c>EnableSharedUpstreamMirror</c>, and
    ///   <c>SharedUpstreamMirrorDirectory</c>. The retaining
    ///   options-monitor cache keeps the startup value visible to consumers
    ///   after a rejected reload.</item>
    /// <item><b>Startup-only by capture</b> — bound into a downstream
    ///   singleton (PipelineOptions, OrchestratorOptions, QuotaRouterOptions,
    ///   Smoke cache TTL, AvailabilityOptions, WebhookEventBroadcaster,
    ///   HttpWebhookDispatcher, ClaudeChangelogGenerator, Serilog sinks,
    ///   etc.) at startup. Edits land in <see cref="IOptionsMonitor{T}.CurrentValue"/>
    ///   but the captured singleton continues to use the prior value until
    ///   restart. Add a hot-reload bridge if/when an operator-facing knob
    ///   should not require restart.</item>
    /// </list>
    /// </summary>
    public sealed class CodeyBoxOptions
    {
        public List<ApiClientOptions> ApiClients { get; set; } = [];
        public string? PublicBaseUrl { get; set; }
        public string GitRootDirectory { get; set; } = CodeyBox.Core.HostPathPolicy.DefaultGitRootDirectory();
        public int GitCommandMaxOutputBytes { get; set; } = LocalGitHostOptions.DefaultGitCommandMaxOutputBytes;
        public bool EnableSharedUpstreamMirror { get; set; } = false;
        public string SharedUpstreamMirrorDirectory { get; set; } = "_upstream-mirror";
        public string StateDatabasePath { get; set; } = CodeyBox.Core.HostPathPolicy.DefaultStateDatabasePath();
        /// <summary>
        /// File-store backing GitHub App installations and OAuth state.
        /// Bound (not ad-hoc) so strict unbound-key validation accepts it in
        /// every host, including test hosts that isolate it per fixture.
        /// Null means "use the environment default" (production path or a
        /// per-process temp directory outside production).
        /// </summary>
        public string? GitHubAppStorePath { get; set; } = null;
        public SqliteWriteGateOptions SqliteWriteGate { get; set; } = new();
        public SqliteMaintenanceOptions SqliteMaintenance { get; set; } = new();
        public string TemplateDirectory { get; set; } = "templates";
        public const int DefaultMaxTemplateChecks = 256;
        public const int MaximumMaxTemplateChecks = 1000;
        public int MaxTemplateChecks { get; set; } = DefaultMaxTemplateChecks;
        public string SandboxImageReference { get; set; } = "";
        public string[] AgentAllowedHosts { get; set; } = ["api.anthropic.com", "api.openai.com", "api.githubcopilot.com", "generativelanguage.googleapis.com"];
        public string[] AuditToolAllowedHosts { get; set; } =
        [
            "api.nuget.org",
            "www.nuget.org",
            "pypi.org",
            "files.pythonhosted.org",
            "registry.npmjs.org",
            "vuln.go.dev",
            "proxy.golang.org",
            "sum.golang.org",
            "crates.io",
            "index.crates.io",
            "static.crates.io",
            "github.com",
            "release-assets.githubusercontent.com",
            "semgrep.dev",
            "registry.semgrep.dev",
            "api.semgrep.dev",
        ];
        /// <summary>
        /// Legacy concurrency knob (deprecated). Used as
        /// <see cref="WorkerPool"/>.<see cref="WorkerPoolOptions.MaxConcurrentWorkers"/>
        /// only when that key is not explicitly set; a deprecation warning is emitted.
        /// When both are set, <see cref="WorkerPool"/>.<see cref="WorkerPoolOptions.MaxConcurrentWorkers"/>
        /// wins. Prefer <c>WorkerPool:MaxConcurrentWorkers</c> for new configuration.
        /// </summary>
        public int? Concurrency { get; set; }

        /// <summary>Worker pool sizing and spawn-pacing configuration.</summary>
        public WorkerPoolOptions WorkerPool { get; set; } = new();

        /// <summary>Per-agent concurrency caps (codex/claude/gemini/...) layered on top of WorkerPool.</summary>
        public AgentConcurrencyOptions AgentConcurrency { get; set; } = new();

        /// <summary>
        /// Per-agent dispatch failure circuit breaker: benches an agent that
        /// fails dispatch repeatedly (any kind of failure) within a rolling
        /// window, independent of quota classification. Hot-reloads via
        /// <see cref="AgentCircuitBreakerSnapshot"/>.
        /// </summary>
        public AgentCircuitBreakerOptions AgentCircuitBreaker { get; set; } = new();

        /// <summary>Per-agent burn-rate estimator config (rate-aware dispatch gate).</summary>
        public AgentBurnEstimatorOptions AgentBurnEstimator { get; set; } = new();

        /// <summary>Per-agent/per-model multi-window spend budgets (synthetic quota for the router).</summary>
        public AgentBudgetOptions AgentBudgets { get; set; } = new();

        /// <summary>
        /// Per-agent default model IDs. Keyed by <c>AgentKind.Value</c>
        /// (case-insensitive). The runner uses this value in <c>--model</c>
        /// when no per-item override is provided and the class member does
        /// not carry an explicit <c>ModelId</c>. Edits hot-reload via
        /// <see cref="Core.AgentDefaultsSnapshot"/> and take effect on the
        /// next dispatched agent run.
        /// </summary>
        public Dictionary<string, string?> AgentDefaults { get; set; } =
            new(StringComparer.OrdinalIgnoreCase);

        /// <summary>
        /// Per-agent network tolerance settings. Keyed by <c>AgentKind.Value</c>
        /// (case-insensitive). The runner uses these values to override the CLI
        /// network tolerance settings (e.g. retries, timeouts). Edits hot-reload via
        /// <see cref="Core.AgentNetworkToleranceSnapshot"/> and take effect on the
        /// next dispatched agent run. Defaults: Codex request retries = 8,
        /// Codex stream retries = 15, Codex stream idle timeout unset, Claude
        /// API timeout unset. Timeout values are capped at the API's maximum
        /// work-attempt window (480 minutes).
        /// </summary>
        public Dictionary<string, AgentNetworkToleranceOptions?> AgentNetworkTolerance { get; set; } =
            AgentNetworkToleranceOptions.DefaultByAgent();

        /// <summary>
        /// Toolchain-fault signatures over gate subprocess results. Keyed by
        /// signature name (case-insensitive); each entry declares its match,
        /// the fault class it denotes, and its disposition (retry, fail, or
        /// escalate). A new signature for a language the repository has never
        /// built requires no code change — add an entry here. Edits hot-reload
        /// via <see cref="Core.ToolchainFaultSnapshot"/> and take effect on the
        /// next gate run. Platform-agnostic built-ins (signal termination,
        /// OOM kill, disk exhaustion, .NET runtime crash) always apply even
        /// when this dictionary is empty.
        /// </summary>
        public Dictionary<string, ToolchainFaultSignatureOptions?> ToolchainFaults { get; set; } =
            new(StringComparer.OrdinalIgnoreCase);

        /// <summary>
        /// Operator-configured per-agent pauses. Keyed by agent kind value.
        /// Applied at startup and hot-reloaded by <see cref="AgentConfigHotReload"/>.
        /// Runtime API/work-item pauses remain persisted in SQLite separately;
        /// removing an entry here resumes only pauses owned by config.
        /// </summary>
        public Dictionary<string, AgentPauseConfig> AgentPauses { get; set; } =
            new(StringComparer.OrdinalIgnoreCase);

        /// <summary>Graceful shutdown drain and preemption timing.</summary>
        public ShutdownOptions Shutdown { get; set; } = new();

        /// <summary>
        /// Deprecated compatibility section for older configs that set
        /// <c>CodeyBox:PlanReview:UseAuditors</c>. Auditor-backed plan review
        /// is always enabled by the pipeline; this option is accepted only so
        /// strict unbound-key validation does not reject existing deployments.
        /// </summary>
        public PlanReviewOptions PlanReview { get; set; } = new();

        /// <summary>Heartbeat and dead-worker reaper configuration.</summary>
        public DeadWorkerOptions DeadWorker { get; set; } = new();

        /// <summary>
        /// Leased workload secrets: TTL, renewal window, sweep cadence, and
        /// revocation bounds. Hot-reloadable through
        /// <c>IOptionsMonitor</c>; edits take effect on the next sweep or
        /// materialisation without restart.
        /// </summary>
        public Core.SecretLeasingOptions SecretLeasing { get; set; } = new();

        /// <summary>
        /// Lifecycle-wide worker progress watchdog: catches the
        /// "heartbeating-but-no-progress" wedge (pre-agent setup hang OR
        /// post-agent commit/transition hang) that neither the dead-worker
        /// reaper nor <c>WorkTimeout</c> covers. Hot-reloadable: edits to
        /// <c>ProgressTimeout</c>, <c>AutoRecover</c>,
        /// <c>ProcessCpuProgressSignalEnabled</c>,
        /// <c>ActiveSandboxProgressSignalEnabled</c>, and
        /// <c>PostAgentTransitionTimeout</c> take effect on the next sweep
        /// without restart. <c>CheckInterval</c> is sampled at
        /// PeriodicTimer construction and requires a restart to change.
        /// </summary>
        public WorkerProgressWatchdogOptions WorkerProgressWatchdog { get; set; } = new();

        /// <summary>
        /// Dispatcher-level watchdog for under-filled pools with runnable work.
        /// Hot-reloadable: timeout and recovery settings are read on each sweep.
        /// </summary>
        public WorkerPoolHealthWatchdogOptions WorkerPoolHealthWatchdog { get; set; } = new();

        public const int DefaultMaxBulkItems = 1000;
        public const int MaximumMaxBulkItems = 10_000;
        public int MaxBulkItems { get; set; } = DefaultMaxBulkItems;

        /// <summary>
        /// Crock agent sandbox wiring — most importantly the host
        /// <c>crock daemon</c> socket path. The runner refuses to dispatch
        /// when <c>HostDaemonSocketPath</c> is unset because the public
        /// tunnel-in-VM shape is incompatible with the sandbox network model.
        /// Hot-reloadable through <c>IOptionsMonitor</c>.
        /// </summary>
        public CrockSandboxOptions Crock { get; set; } = new();

        /// <summary>
        /// Goose runner settings: the <c>--provider</c> id the bundled member
        /// routes (shipped as <c>openrouter</c>) and the autonomous turn bound
        /// passed as <c>--max-turns</c>. Hot-reloadable through
        /// <c>IOptionsMonitor</c>. The provider API key itself is NOT here —
        /// it arrives through the credential chain as
        /// <c>CODEYBOX_GOOSE_API_KEY</c> so the secret never sits in config.
        /// </summary>
        public GooseOptions Goose { get; set; } = new();

        /// <summary>
        /// Autohand runner settings: the provider id seeded into the guest
        /// <c>~/.autohand/config.json</c> (shipped as <c>openrouter</c>).
        /// Hot-reloadable through <c>IOptionsMonitor</c>. The provider API
        /// key itself is NOT here — it arrives through the credential chain
        /// as <c>CODEYBOX_AUTOHAND_API_KEY</c> so the secret never sits in
        /// config.
        /// </summary>
        public AutohandOptions Autohand { get; set; } = new();

        /// <summary>
        /// Cline runner settings: the provider id passed as <c>-P/--provider</c>
        /// (shipped as <c>openrouter</c>). Hot-reloadable through
        /// <c>IOptionsMonitor</c>. The provider API key itself is NOT here —
        /// it arrives through the credential chain as
        /// <c>CODEYBOX_CLINE_API_KEY</c> so the secret never sits in config.
        /// The default matters because cline's built-in default provider is
        /// the <c>cline</c> vendor account: without <c>-P</c> the run ignores
        /// the provider key and fails fast on vendor auth.
        /// </summary>
        public ClineOptions Cline { get; set; } = new();
        /// Kilo Code runner settings: the OpenAI-compatible inference
        /// endpoint seeded into the guest <c>~/.config/kilo/kilo.jsonc</c>
        /// (shipped as OpenRouter v1). Hot-reloadable through
        /// <c>IOptionsMonitor</c>. The provider API key itself is NOT here —
        /// it arrives through the credential chain as
        /// <c>CODEYBOX_KILO_API_KEY</c> so the secret never sits in config.
        /// </summary>
        public KiloOptions Kilo { get; set; } = new();
        /// Continue runner settings: the OpenAI-compatible inference
        /// endpoint seeded into the guest <c>~/.continue/config.yaml</c>
        /// single-model entry as <c>apiBase</c> (shipped as OpenRouter v1).
        /// Hot-reloadable through <c>IOptionsMonitor</c>. The provider API
        /// key itself is NOT here — it arrives through the credential chain
        /// as <c>CODEYBOX_CONTINUE_API_KEY</c> so the secret never sits in
        /// config.
        public ContinueOptions Continue { get; set; } = new();

        /// <summary>
        /// GitHub Copilot CLI runner configuration. Subscription mode by default; setting
        /// <c>Provider.BaseUrl</c> switches inference to an OpenAI-compatible endpoint (BYOK).
        /// The BYOK credential is deliberately not here — it arrives through the credential chain
        /// as <c>CODEYBOX_COPILOT_PROVIDER_API_KEY</c> so the secret never sits in config.
        /// </summary>
        public CopilotOptions Copilot { get; set; } = new();

        /// <summary>
        /// Google Antigravity (<c>agy</c>) runner and quota-probe settings. Bound from
        /// <c>CodeyBox:Antigravity</c>.
        /// </summary>
        public AntigravitySectionOptions Antigravity { get; set; } = new();

        /// <summary>
        /// Prime Agent (<c>prime-agent</c>) runner settings, notably the
        /// <c>--provider</c> default. Bound from <c>CodeyBox:Prime</c>.
        /// </summary>
        public PrimeSectionOptions Prime { get; set; } = new();

        /// <summary>
        /// Vibe (<c>vibe</c>) runner settings, notably the autonomous turn
        /// bound passed as <c>--max-turns</c>. Bound from <c>CodeyBox:Vibe</c>.
        /// Hot-reloadable through <c>IOptionsMonitor</c>. The provider API key
        /// itself is NOT here — it arrives through the credential chain as
        /// <c>CODEYBOX_VIBE_API_KEY</c> so the secret never sits in config.
        /// </summary>
        public VibeOptions Vibe { get; set; } = new();

        public int UpstreamPushMaxAttempts { get; set; } = 5;
        public int UpstreamPushBackoffSeconds { get; set; } = 15;

        /// <summary>
        /// Multiplier applied to each phase's per-attempt timeout to get its
        /// absolute wall-clock cap. Bound to
        /// <see cref="Orchestrator.PipelineOptions.DefaultPhaseAbsoluteTimeoutMultiplier"/>:
        /// <c>SandboxLeakOptions.DefaultLeakAgeThreshold</c> derives from that
        /// constant, so this default MUST track it or the shipped leak
        /// threshold silently stops covering the multiplier actually in force.
        /// </summary>
        public double PhaseAbsoluteTimeoutMultiplier { get; set; } = Orchestrator.PipelineOptions.DefaultPhaseAbsoluteTimeoutMultiplier;

        /// <summary>
        /// Global default work-phase wall-clock budget in minutes, applied to
        /// work items that carry neither a per-item timeout nor a per-project
        /// <c>WorkTimeoutMinutes</c> (see <see cref="Core.WorkTimeoutPolicy"/>
        /// for the precedence rules). Read live from the options monitor at
        /// every dispatch, so edits hot-reload: the value in force for
        /// subsequently dispatched work changes without a rebuild or restart.
        /// In-flight iterations keep the budget they started with. Values
        /// outside 1..480 are clamped at resolution time so a typo cannot
        /// disable the timeout. The shipped default stays 240 — the defect
        /// was that the value was unreachable, not that 240 is wrong.
        /// </summary>
        public int DefaultWorkTimeoutMinutes { get; set; } = Core.WorkTimeoutPolicy.DefaultMinutes;

        /// <summary>
        /// Hard ceiling (seconds) on a single required-build verification
        /// across every phase / resume path. Defaults to 15 minutes; raise
        /// for very large .NET solutions or lower to fail faster during
        /// infrastructure degradation. Floor 60 s. Captured once at startup
        /// into <see cref="PipelineOptions.RequiredBuildVerificationTimeout"/>;
        /// edits require restart.
        /// </summary>
        public int RequiredBuildVerificationTimeoutSeconds { get; set; } = 900;

        /// <summary>
        /// When true (default), approving a plan (the <c>plan</c> knob on) emits
        /// and reconciles a test case per declared plan scenario, linked to the
        /// work item. Unplanned items never reach this path and are unaffected.
        /// Set false to keep the planning phase without materialising test cases.
        /// Captured once at startup into
        /// <see cref="PipelineOptions.EmitPlanTestCases"/>; edits require restart.
        /// </summary>
        public bool EmitPlanTestCases { get; set; } = true;

        /// <summary>
        /// Upper bound on the tail of agent stdout/stderr retained in failure details (bytes).
        /// Defaults to 32 KiB. Captured once at startup into
        /// <see cref="PipelineOptions.MaxFailureDetailBytes"/>; edits require restart.
        /// </summary>
        public int MaxFailureDetailBytes { get; set; } = SanitizedAgentDetail.DefaultTailMaxBytes;

        /// <summary>
        /// Optional runtime flake attribution for parsed dotnet test failures.
        /// When enabled, the failing test names are rerun against the
        /// merge-base/base checkout in the same sandbox and classified as
        /// diff-attributable only when they pass on base and fail on the diff.
        /// When disabled, or when the base rerun cannot be performed,
        /// classification fails closed to diff-attributable.
        /// Hot-reloadable via <see cref="AgentConfigHotReload"/>.
        /// </summary>
        public TestFailureAttributionOptions TestFailureAttribution { get; set; } = new();

        /// <summary>
        /// Maximum concurrent release deep-audit phases across all releases.
        /// Bounds LLM/sandbox resource usage. Default 4.
        /// Hot-reloadable: read on each deep-audit start attempt.
        /// </summary>
        public int DeepAuditMaxConcurrency { get; set; } = 4;

        /// <summary>
        /// Maximum seconds to wait for a single remediation work item to reach a
        /// terminal state before failing the deep audit. Default 1800 (30 min).
        /// Hot-reloadable: read on each remediation dispatch.
        /// </summary>
        public int DeepAuditRemediationItemTimeoutSeconds { get; set; } = 1800;

        /// <summary>
        /// Bounded retry policy for persisting an unexpected deep-audit failure.
        /// Hot-reloadable: captured at the start of each failure reconciliation.
        /// </summary>
        public DeepAuditFailurePersistenceOptions DeepAuditFailurePersistence { get; set; } = new();

        /// <summary>Pipeline-runner quota-fallback and retry tuning. Hot-reloadable.</summary>
        public PipelineTuningOptions PipelineTuning { get; set; } = new();

        /// <summary>Per-project budget-cap deferral recheck intervals. Hot-reloadable.</summary>
        public BudgetDeferralRecheckOptions BudgetDeferralRecheck { get; set; } = new();

        /// <summary>
        /// Which sandbox provider to use. One of: <c>incus</c>, <c>multipass</c>,
        /// <c>multipass-remote</c>, <c>sprites</c>, <c>bubblewrap</c>,
        /// <c>process</c>.
        /// Default is empty — startup defaults to 'process' in Development
        /// and refuses to start in other environments.
        /// A process that starts with <c>multipass</c> or <c>incus</c> may
        /// hot-switch between those two providers. All other changes require
        /// a restart and are rejected during reload.
        /// </summary>
        public string? SandboxProvider { get; set; }

        /// <summary>
        /// Trust classification for repository and agent-controlled input. Defaults to Untrusted outside
        /// Development, where only a provider advertising dedicated-kernel isolation is admitted.
        /// </summary>
        public string? WorkloadTrust { get; set; }

        /// <summary>Explicit acknowledgement for trusted workloads using shared-kernel isolation.</summary>
        public bool AcknowledgeSharedKernelRisk { get; set; }

        /// <summary>Auditors that every project must compose and cannot exclude.</summary>
        public IReadOnlyList<string> RequiredAuditors { get; set; } = [];

        /// <summary>
        /// Provider-neutral lifecycle inventory retained during a hot-reload
        /// sandbox-provider cutover.
        /// </summary>
        public SandboxProviderCutoverConfig SandboxProviderCutover { get; set; } = new();

        /// <summary>
        /// Override that lets <c>process</c> sandbox load outside Development.
        /// Don't.
        /// </summary>
        public bool DangerouslyAllowProcessSandbox { get; set; }

        /// <summary>
        /// Incus VM, baseline, storage, and CLI settings. Full settings are
        /// consumed when Incus is selected or retained for cutover inventory;
        /// dormant-provider routing reads only the baseline namespace. Fields
        /// other than <c>ProjectName</c> and the effective
        /// <c>StagingDirectory</c> are hot-reloaded for the next Incus
        /// operation.
        /// </summary>
        public IncusSandboxConfig Incus { get; set; } = new();

        /// <summary>
        /// Extra cloud-init YAML appended to the auto-generated network policy
        /// when SandboxProvider=multipass. Use only for top-level cloud-init
        /// directives CodeyBox does not generate (e.g. <c>packages:</c> or
        /// <c>apt:</c>). Use <see cref="MultipassExtraRuncmd"/> for install
        /// commands; duplicate generated blocks such as <c>runcmd:</c> and
        /// <c>write_files:</c> are rejected by the Multipass provider.
        /// </summary>
        public string? MultipassExtraCloudInit { get; set; }

        /// <summary>Multipass sandbox launch-time readiness tuning.</summary>
        public MultipassSandboxConfig MultipassSandbox { get; set; } = new();

        /// <summary>
        /// Configuration for <c>SandboxProvider=multipass-remote</c>. Optional;
        /// only consumed when that provider is selected.
        /// </summary>
        public MultipassRemoteSandboxConfig? MultipassRemoteSandbox { get; set; }

        /// <summary>
        /// Configuration for <c>SandboxProvider=sprites</c>. Optional; provider
        /// defaults to the public sprites.dev API and <c>SPRITES_TOKEN</c>.
        /// </summary>
        public SpritesSandboxConfig? Sprites { get; set; }

        /// <summary>
        /// Dedicated remote Multipass configuration for the E2E replay pool.
        /// This intentionally does not fall back to
        /// <see cref="MultipassRemoteSandbox"/> when E2E execution is enabled:
        /// replay load must target a separately sized cheap CPU pool rather
        /// than the coding-agent remote fleet.
        /// </summary>
        public E2eMultipassRemoteHostConfig? E2eMultipassRemoteSandbox { get; set; }

        /// <summary>
        /// Multi-host E2E replay fleet. When populated, this list supersedes
        /// <see cref="E2eMultipassRemoteSandbox"/> and the E2E pool distributes
        /// clone-per-test leases across the configured cheap CPU hosts.
        /// </summary>
        public List<E2eMultipassRemoteHostConfig> E2eMultipassRemoteSandboxes { get; set; } = [];

        /// <summary>
        /// Maps logical network-profile names → host bridge names. Operators
        /// configure these bridges once via scripts/setup-host-networks.sh;
        /// the orchestrator then attaches each VM to the matching bridge,
        /// where host-side nftables rules enforce egress.
        ///
        /// Empty → no host-enforced profile is selectable. Multipass then
        /// has only its blocked default bridge; Incus instances are created
        /// without a NIC. For functional egress, populate this and run
        /// setup-host-networks.sh.
        ///
        /// Example:
        /// <code>
        /// "SandboxNetworkProfiles": {
        ///   "isolated":  "cb-iso",
        ///   "claude":    "cb-claude",
        ///   "multi-llm": "cb-multi-llm",
        ///   "graphical": "cb-graphical",
        ///   "majordomo": "cb-majordomo"
        /// }
        /// </code>
        /// Bridge names are limited to 15 characters by Linux IFNAMSIZ. Incus
        /// additionally requires profile names to be valid identifiers of at
        /// most 63 ASCII letters, digits, hyphens, underscores, or dots;
        /// Multipass does not impose that profile-name limit. Multipass
        /// attaches the selected bridge as a second NIC; Incus uses it as the
        /// VM's only NIC and does not inherit an Incus NAT profile.
        /// </summary>
        public Dictionary<string, string> SandboxNetworkProfiles { get; set; } = new(StringComparer.OrdinalIgnoreCase)
        {
            [CodeyBox.Sandbox.SandboxConventions.GraphicalNetworkProfile] = "cb-graphical",
            [CodeyBox.Orchestrator.MajordomoSandboxOptions.DefaultNetworkProfile] = CodeyBox.Orchestrator.MajordomoSandboxOptions.DefaultBridgeName,
        };

        /// <summary>
        /// Shell commands run inside the sandbox VM at first boot, after
        /// the orchestrator's route swap (so they have working egress).
        /// Use for one-shot setup the project needs in the sandbox —
        /// installing the agent CLI, the language toolchain, any auditor
        /// tools the audit policy expects to be present. Each entry is a
        /// single shell command (multi-line OK).
        /// </summary>
        public List<string> MultipassExtraRuncmd { get; set; } = [];

        /// <summary>
        /// When true, the Multipass provider lazily bakes a per-profile
        /// baseline VM on first use (running the standard cloud-init +
        /// MultipassExtraRuncmd install once), then clones it for every
        /// subsequent sandbox of that profile. Cuts each VM cold-start from
        /// ~5-10 min to ~10s. The baselines stay stopped at rest.
        ///
        /// Delete the baselines (<c>multipass delete --purge cb-baseline-*</c>)
        /// to force a re-bake after changing MultipassExtraRuncmd.
        /// </summary>
        public bool MultipassUseBaselineImages { get; set; } = false;

        /// <summary>
        /// Configurable list of package cache seeds to copy from the host to the baseline VM at bake time.
        /// </summary>
        public List<PackageCacheSeedConfig> MultipassPackageCacheSeeds { get; set; } = [];

        /// <summary>
        /// Executable binaries to ship into the baseline VM at bake time. Each
        /// entry copies one host file to an absolute VM path with mode 0755 and
        /// optional symlinks (e.g. into <c>/usr/local/bin</c>). Use when the
        /// upstream installer is non-durable (a <c>curl … | bash</c> URL has
        /// drifted or now serves HTML) and the operator already has a vetted
        /// copy of the binary staged on the host.
        /// </summary>
        public List<ExecutableProvisionConfig> MultipassExecutableProvisions { get; set; } = [];

        /// <summary>
        /// Disk-guard preflight configuration. Enabled by default
        /// (<see cref="DiskGuardOptions.Enabled"/>=<c>true</c>,
        /// <see cref="DiskGuardOptions.MinFreeBytes"/>=10 GiB); every
        /// sandbox creation checks the provider's backing storage and defers
        /// the work item (same machinery as the budget cap) when it is below
        /// the threshold. Multipass additionally checks its configured host
        /// paths; Incus checks the selected storage pool, shared additional
        /// paths, and its effective staging directory. Set
        /// <c>CodeyBox:DiskGuard:Enabled=false</c> to disable.
        /// </summary>
        public DiskGuardOptions DiskGuard { get; set; } = new();

        /// <summary>
        /// Outbound webhook endpoints. Empty list disables webhooks entirely.
        /// Each entry configures one HTTPS target that receives pipeline events.
        /// </summary>
        public List<WebhookEndpointOptions> Webhooks { get; set; } = [];

        /// <summary>
        /// In-process event broadcaster used by the SSE endpoints
        /// (<c>GET /workitems/events</c> and <c>GET /workitems/{id}/events</c>).
        /// Shared with the webhook dispatcher so SSE subscribers and webhook
        /// receivers see the same event surface.
        /// </summary>
        public WebhookEventBusOptions WebhookEventBus { get; set; } = new();

        /// <summary>
        /// Audit log configuration: rolling file paths, retention, and size caps.
        /// </summary>
        public AuditLogOptions AuditLog { get; set; } = new();

        /// <summary>Structured agent stdout stream capture configuration.</summary>
        public AgentStreamsOptions AgentStreams { get; set; } = new();

        /// <summary>Options for composing convergence briefs from work item history.</summary>
        public ConvergenceBriefOptions ConvergenceBrief { get; set; } = new();

        /// <summary>Knobs for the operator-triggered delegation phase (result-diff bounds).</summary>
        public DelegationOptions Delegation { get; set; } = new();

        /// <summary>Triggers for the delegation phase: operator command plus automatic escalation.</summary>
        public DelegationEscalationOptions DelegationEscalation { get; set; } = new();

        /// <summary>Config-gated live human supervision and injection channel.</summary>
        public AgentSupervisionOptions AgentSupervision { get; set; } = new();

        /// <summary>Read-only analytics parser configuration for captured agent streams.</summary>
        public AgentStreamParserOptions AgentStreamAnalysis { get; set; } = new();

        /// <summary>
        /// Agent class definitions for quota-aware routing. Each class lists one or
        /// more agent members in preference order. See docs/concepts/agent-classes.md.
        /// </summary>
        public List<AgentClassOptions> AgentClasses { get; set; } = [];

        /// <summary>
        /// Sandbox class definitions modelling sandbox capacity the way agent
        /// classes model agent capacity. Each class lists one or more sandbox
        /// members with a preference score, capacity, and capability tags.
        /// Empty by default: a default single-member class is synthesized
        /// from <c>CodeyBox:SandboxProvider</c> so the work-phase placement
        /// path has a member to select without requiring new configuration.
        /// </summary>
        public List<SandboxClassOptions> SandboxClasses { get; set; } = [];

        /// <summary>
        /// Executor phase dispatch knobs (see
        /// <see cref="CodeyBox.Orchestrator.ExecutorPhaseDispatchOptions"/>):
        /// stage-out bounds, payload limits, and the placement recheck
        /// backoff a transient sandbox-placement refusal requeues under.
        /// Hot-reloadable.
        /// </summary>
        public CodeyBox.Orchestrator.ExecutorPhaseDispatchOptions ExecutorPhaseDispatch { get; set; } = new();

        /// <summary>
        /// Per-sandbox egress-verification opt-in (see
        /// <see cref="CodeyBox.Core.EgressVerificationOptions"/>): the
        /// provider kinds whose provider-host filters (for example Tart
        /// Softnet) may serve profiled work after the host's canary passes
        /// for the sandbox, plus the canary endpoints and bounds.
        /// Hot-reloadable. Empty by default: nothing is verifiable and every
        /// plugin kind stays <c>NotEnforced</c>.
        /// </summary>
        public CodeyBox.Core.EgressVerificationOptions EgressVerification { get; set; } = new();

        /// <summary>
        /// Optional reusable agent instances. AgentClass members can reference
        /// these by InstanceId, allowing multiple subscriptions for the same
        /// agent kind to be pooled independently.
        /// </summary>
        public List<AgentInstanceOptions> AgentInstances { get; set; } = [];

        /// <summary>Quota router tuning knobs.</summary>
        public QuotaRouterConfig QuotaRouter { get; set; } = new();

        /// <summary>
        /// Operator-extensible per-agent quota stderr patterns. Keys are agent
        /// kind values (e.g. <c>cursor</c>); each entry adds a substring + kind
        /// to the per-provider detector's built-in defaults. See
        /// docs/operating/quota.md for the schema and supported agent kinds.
        /// </summary>
        public Dictionary<string, List<QuotaFailurePatternOptions>> QuotaFailurePatterns { get; set; } = new(StringComparer.OrdinalIgnoreCase);

        /// <summary>
        /// Operator-extensible per-agent provider-transient signatures. Keys
        /// are agent kind values (e.g. <c>devin</c>, <c>copilot</c>); each
        /// entry adds a .NET regular expression + transient family to the
        /// per-provider detector's built-in exact signatures. Matched against
        /// stderr, stdout, and the summary. Hot-reloaded without a restart.
        /// See docs/operating/quota.md for the schema.
        /// </summary>
        public Dictionary<string, List<ProviderTransientSignatureOptions>> ProviderTransientSignatures { get; set; } = new(StringComparer.OrdinalIgnoreCase);

        /// <summary>
        /// Operator-extensible per-agent auth/login-prompt output patterns.
        /// Keys are agent kind values (e.g. <c>antigravity</c>); each entry adds
        /// a case-insensitive stderr/stdout substring to the built-in login-prompt
        /// detector. Keep stdout patterns narrowly tied to CLI login transcripts
        /// because stdout can contain model-produced task text.
        /// </summary>
        public Dictionary<string, List<AuthFailurePatternOptions>> AuthFailurePatterns { get; set; } = new(StringComparer.OrdinalIgnoreCase);

        /// <summary>
        /// Time-of-day score modifiers. Applied as small effective-score adjustments
        /// to act as tiebreakers between near-equivalent models during peak cost windows.
        /// See docs/reference/configuration.md for the schedule schema.
        /// </summary>
        public AgentScoreModifiersOptions AgentScoreModifiers { get; set; } = new();

        /// <summary>Credential smoke test tuning knobs.</summary>
        public SmokeConfig Smoke { get; set; } = new();

        /// <summary>
        /// Commit/PR attribution switches. All default to true (today's
        /// behaviour). Hot-reloadable: the snapshot takes effect on the next
        /// commit. Per-project overrides win over these host defaults.
        /// </summary>
        public CodeyBox.Core.CommitAttributionOptions CommitAttribution { get; set; } = new();

        /// <summary>
        /// Ownership proof for stale CodeyBox-owned branch tips with no
        /// recorded push: which commit trailers must mark every exclusive
        /// commit, and how many commits are examined. Hot-reloadable: the
        /// snapshot takes effect on the next push or re-drive.
        /// </summary>
        public CodeyBox.Core.UpstreamBranchOwnershipOptions UpstreamBranchOwnership { get; set; } = new();

        /// <summary>
        /// Pipeline transition-health metric tuning. Controls the
        /// <c>/fleet/transition-health</c> endpoint's rolling window and
        /// optional "last N transitions" cap. Hot-reloadable.
        /// </summary>
        public TransitionHealthConfig TransitionHealth { get; set; } = new();

        /// <summary>Agent token pricing for cost estimation. See docs/operating/costs.md.</summary>
        public AgentPricingOptions AgentPricing { get; set; } = new();

        /// <summary>Monthly cost-budget alert sweep configuration. See docs/operating/budgets.md.</summary>
        public BudgetAlertOptions BudgetAlerts { get; set; } = new();

        /// <summary>Automatic retry for quota-failed items.</summary>
        public AutoRetryOnQuotaFailureConfig AutoRetryOnQuotaFailure { get; set; } = new();

        /// <summary>Automatic retry for transient transport/network failed items.</summary>
        public AutoRetryOnTransientFailureConfig AutoRetryOnTransientFailure { get; set; } = new();

        /// <summary>
        /// Operator-extensible transient transport/network stderr/stdout
        /// patterns appended to <see cref="AgentFailureClassifier"/>'s built-in
        /// conservative defaults.
        /// </summary>
        public List<string> TransientNetworkFailurePatterns { get; set; } = [];

        /// <summary>
        /// Failure-class recovery policy. Classifies every terminal failure
        /// (Failed, AuditFailed, MergeConflictResolutionFailed) and routes by
        /// class — see <see cref="TerminalFailureRecoveryConfig"/>. Replaces the
        /// external operator chaperone's blunt requeue reflex.
        /// </summary>
        public TerminalFailureRecoveryConfig TerminalFailureRecovery { get; set; } = new();

        /// <summary>
        /// Auto-requeue policy for infra-failed work items on agent recovery —
        /// see <see cref="AutoRequeueOnAgentRestoreConfig"/>. Enabled by
        /// default so restored agents automatically drain outage-window
        /// infra-failed victims through normal routing.
        /// </summary>
        public AutoRequeueOnAgentRestoreConfig AutoRequeueOnAgentRestore { get; set; } = new();

        /// <summary>OpenTelemetry export configuration. See docs/operating/observability.md.</summary>
        public OtelOptions Otel { get; set; } = new();

        /// <summary>Changelog automation configuration. See docs/operating/releases.md.</summary>
        public ChangelogOptions Changelog { get; set; } = new();

        /// <summary>
        /// Human/systems notification rules and provider configuration.
        /// Edits hot-reload via IOptionsMonitor — conditions, cooldowns,
        /// and provider routing take effect on the next sweep without restart.
        /// Empty Rules list = notifications disabled.
        /// </summary>
        public NotificationsOptions Notifications { get; set; } = new();

        /// <summary>
        /// Sandbox leak reaper configuration. The reaper periodically scans for
        /// <c>codeybox-*</c> Multipass VMs that outlived their work item and logs
        /// (or optionally auto-disposes) them. See docs/operating/sandbox-reliability.md.
        /// </summary>
        public SandboxLeakOptions SandboxLeak { get; set; } = new();

        /// <summary>
        /// Verification-deployment leak reaper configuration. Sweeps managed
        /// sandboxes that outlived an <see cref="IDeploymentManager"/>-tracked
        /// deployment (orchestrator crash / aborted deploy). Same pattern as
        /// <see cref="SandboxLeak"/>; running both is safe — each scopes to
        /// its own concern.
        /// </summary>
        public DeploymentLeakOptions DeploymentLeak { get; set; } = new();

        /// <summary>
        /// Work-item bare git repository clone retention and reaping configuration.
        /// Reaps clones for terminal work items (Done, Failed, Cancelled, etc.) and
        /// sweeps already-terminal clones left behind across restarts.
        /// </summary>
        public RepoRetentionOptions RepoRetention { get; set; } = new();

        /// <summary>
        /// Startup sweep over the system temp path that removes stale
        /// <c>codeybox-*</c> entries abandoned by previous deployments and
        /// test runs. Bind under <c>CodeyBox:TempSweep</c>. Matters most on
        /// hosts where <c>/tmp</c> is a tmpfs: unreaped entries pin RAM until
        /// reboot, and an OOM killer resolving that pressure chooses its own
        /// victim. See <see cref="TempSweepOptions"/>.
        /// </summary>
        public TempSweepOptions TempSweep { get; set; } = new();

        /// <summary>
        /// Alias for <see cref="RepoRetention"/>.
        /// </summary>
        public RepoRetentionOptions RepoReaper
        {
            get => RepoRetention;
            set => RepoRetention = value;
        }

        /// <summary>
        /// B1 baseline-image reaper configuration. Reference-counted GC for
        /// the content-hashed baseline VMs produced by the Multipass
        /// provider; inactive when the registered sandbox provider does not
        /// implement <see cref="IBaselineImageResolver"/>.
        /// </summary>
        public BaselineImageReaperOptions BaselineImageReaper { get; set; } = new();

        /// <summary>
        /// Operator baseline-migration configuration (POST /baselines/migrate).
        /// Bounds how many pinned items a single migrate call inspects and
        /// clears. See <see cref="BaselineMigrationService"/>.
        /// </summary>
        public BaselineMigrationOptions BaselineMigration { get; set; } = new();

        /// <summary>
        /// Stale-base PR sweeper configuration. Detects open CodeyBox-authored
        /// PRs whose base branch has moved and produced a merge conflict the
        /// orchestrator can no longer resolve in-pipeline, and fires the
        /// <c>upstream.pr_stale_base</c> webhook event so operators see the
        /// orphan PR within minutes. See <see cref="StalePullRequestSweeper"/>.
        /// </summary>
        public StalePullRequestSweeperOptions StalePullRequestSweep { get; set; } = new();

        /// <summary>
        /// Startup config-validation knobs. Controls whether AgentClass ModelId
        /// values are cross-checked against the provider's live model list.
        /// </summary>
        public ConfigValidationOptions ConfigValidation { get; set; } = new();

        /// <summary>
        /// Deploy-consistency probing. Bound from <c>CodeyBox:DeployConsistency</c>.
        /// </summary>
        public DeployConsistencyOptions DeployConsistency { get; set; } = new();

        /// <summary>
        /// Between-iteration incremental rebase toggle. When enabled,
        /// <see cref="CodeyBox.Orchestrator.PipelineRunner"/> runs the
        /// pickup-time rebase flow as best-effort between audit iterations
        /// so the work branch stays close to base BETWEEN reworks (smaller
        /// and rarer merge-time conflicts). Off by default. Hot-reloadable.
        /// </summary>
        public IncrementalRebaseOptions IncrementalRebase { get; set; } = new();

        /// <summary>
        /// NotDiffAttributable flake-escalation thresholds. When enabled (the
        /// default), an audit test failure that reproduces on the base branch
        /// spawns (or reuses) an isolated base-branch fix item and parks the
        /// parent on a dependsOn gate instead of burning rework iterations.
        /// All thresholds are hot-reloadable.
        /// </summary>
        public NonDeterministicTestEscalationOptions NonDeterministicTestEscalation { get; set; } = new();

        /// <summary>
        /// Claude thinking-block transcript sanitizer configuration.
        /// Bound from <c>CodeyBox:ClaudeThinkingBlockSanitizer</c>.
        /// Gate behind this flag (default <c>true</c>) while the upstream
        /// thinking-block immutability bug is open; disable once Anthropic
        /// ships a fix.
        /// </summary>
        public ClaudeThinkingBlockSanitizerOptions ClaudeThinkingBlockSanitizer { get; set; } = new();

        /// <summary>
        /// Claude resumable-session worker configuration. Bound from
        /// <c>CodeyBox:ClaudeSession</c>. The session worker is OFF by default;
        /// every Claude dispatch keeps using the existing one-shot
        /// <c>ClaudeAgentRunner</c> until an operator opts in here. See
        /// <see cref="CodeyBox.Agents.Claude.ClaudeSessionWorkerOptions"/> for
        /// behaviour.
        /// </summary>
        public ClaudeSessionOptions ClaudeSession { get; set; } = new();

        /// <summary>
        /// End-to-end replay execution pool configuration. Bound from
        /// <c>CodeyBox:E2eExecution</c>. Sizes the cheap CPU-only VM pool that
        /// runs committed e2e-replay artifacts; intentionally separate from the
        /// orchestrator's coding-worker fleet so E2E load never competes for
        /// agent-dispatch slots. Disabled by default — operators opt in per
        /// deployment.
        /// </summary>
        public E2eExecutionOptions E2eExecution { get; set; } = new();

        /// <summary>
        /// Work-item attachments storage configuration. Hot-reloadable: the
        /// root directory, limits, and TTL are read on every upload, sweep,
        /// and orphan scan.
        /// </summary>
        public AttachmentsOptions Attachments { get; set; } = new();
    }

    /// <summary>
    /// Deprecated compatibility plan-review options. The review loop is always
    /// auditor-backed; <see cref="UseAuditors"/> is ignored.
    /// </summary>
    public sealed class PlanReviewOptions
    {
        public bool UseAuditors { get; set; } = true;
    }

    /// <summary>
    /// Startup config-validation knobs. Bound from <c>CodeyBox:ConfigValidation</c>.
    /// </summary>
    public sealed class ConfigValidationOptions
    {
        /// <summary>
        /// When <c>true</c>, an <see cref="AgentClassOptions"/> member whose
        /// <c>ModelId</c> is not present in the provider's live model list
        /// throws at startup. Default <c>false</c> (warn only) so disconnected
        /// dev/UAT hosts still come up.
        /// </summary>
        public bool FailOnUnknownModel { get; set; } = false;

        /// <summary>
        /// Unbound CodeyBox configuration key detection. Catches typos /
        /// stale renames under <c>CodeyBox:*</c> that the .NET binder would
        /// otherwise drop silently.
        /// </summary>
        public UnboundKeyValidationOptions UnboundKeys { get; set; } = new();
    }

    /// <summary>
    /// Deploy-consistency probing. Bound from <c>CodeyBox:DeployConsistency</c>.
    /// The check compares the commit stamped into the binaries at build time
    /// against the commit checked out on disk and warns when the working tree
    /// has moved ahead of <c>bin/</c>. Read live from configuration on every
    /// refresh so edits take effect without a restart.
    /// </summary>
    public sealed class DeployConsistencyOptions
    {
        /// <summary>
        /// Optional override for the checkout root the consistency check
        /// probes for <c>.git/HEAD</c>. When unset, the root is auto-detected
        /// by walking up from the application base directory. Set this when
        /// the service runs from binaries copied outside the checkout.
        /// </summary>
        public string? RepoRoot { get; set; }
    }

    /// <summary>
    /// Tuning for the startup unbound-key inspector. Bound from
    /// <c>CodeyBox:ConfigValidation:UnboundKeys</c>.
    /// </summary>
    public sealed class UnboundKeyValidationOptions
    {
        /// <summary>
        /// Master switch. Default <c>true</c> — every startup walks the
        /// operator-provided <c>CodeyBox:*</c> tree against the typed options
        /// graph.
        /// </summary>
        public bool Enabled { get; set; } = true;

        /// <summary>
        /// <c>"strict"</c> (default) throws at startup; <c>"warn"</c>
        /// downgrades to a single warning log. Any other value is treated as
        /// <c>"strict"</c>.
        /// </summary>
        public string Mode { get; set; } = "strict";

        /// <summary>
        /// Operator-supplied full configuration paths under <c>CodeyBox:*</c>
        /// whose subtrees are skipped entirely (exact, case-insensitive
        /// match). Use for extension namespaces bound outside
        /// <c>CodeyBoxOptions</c> / <c>ProjectsOptions</c>. The built-in
        /// defaults already cover the framework-internal separately-bound
        /// sections (BuildScriptAudit, Mutation, Plugins, …) by walking them
        /// with their typed root POCO so typos inside still surface.
        /// </summary>
        public List<string> AdditionalExemptPaths { get; set; } = new();
    }

    /// <summary>
    /// Per-agent operator pause config. Bound from
    /// <c>CodeyBox:AgentPauses:{agent}</c>.
    /// </summary>
    public sealed class AgentPauseConfig
    {
        /// <summary>
        /// Whether this config entry should pause the agent. Default true so
        /// a present entry is a pause declaration.
        /// </summary>
        public bool Paused { get; set; } = true;

        /// <summary>Operator-visible pause reason.</summary>
        public string? Reason { get; set; }

        /// <summary>Optional absolute auto-resume time.</summary>
        public DateTimeOffset? ExpiresAt { get; set; }

        /// <summary>
        /// Optional relative auto-resume duration in seconds, measured from the
        /// reload that applies a changed config value.
        /// </summary>
        public int? DurationSeconds { get; set; }
    }

    /// <summary>
    /// Claude thinking-block transcript sanitizer configuration.
    /// Bound from <c>CodeyBox:ClaudeThinkingBlockSanitizer</c>.
    /// </summary>
    public sealed class ClaudeThinkingBlockSanitizerOptions
    {
        /// <summary>
        /// Master switch. Default <c>true</c> while the upstream
        /// thinking-block immutability bug is open. Disable once
        /// Anthropic ships a fix.
        /// </summary>
        public bool Enabled { get; set; } = true;
    }

    /// <summary>
    /// Configuration for a package-cache file or directory copied during VM provisioning.
    /// </summary>
    public sealed class PackageCacheSeedConfig
    {
        public string HostSourcePath { get; set; } = string.Empty;
        public string VmDestPath { get; set; } = string.Empty;
        public double? MaxSizeMB { get; set; }
    }

    /// <summary>
    /// Config-bound shape of <see cref="BaselineExecutableProvision"/>.
    /// </summary>
    public sealed class ExecutableProvisionConfig
    {
        public string HostSourcePath { get; set; } = string.Empty;
        public string VmDestPath { get; set; } = string.Empty;
        public List<string> VmSymlinks { get; set; } = [];
        public string? Label { get; set; }
    }

    /// <summary>
    /// Claude resumable-session worker configuration. Bound from
    /// <c>CodeyBox:ClaudeSession</c>. See
    /// <see cref="CodeyBox.Agents.Claude.ClaudeSessionWorker"/>.
    /// </summary>
    public sealed class ClaudeSessionOptions
    {
        /// <summary>
        /// Master switch. Default <c>false</c> — Claude dispatches keep using
        /// the legacy one-shot runner unless an operator opts in here.
        /// </summary>
        public bool Enabled { get; set; } = false;

        /// <summary>
        /// When true (default), each <c>SendTurnAsync</c> emits a
        /// <see cref="CodeyBox.Agents.Claude.ClaudeSessionTurnMetrics"/>
        /// snapshot to the registered metrics sink so the cache_read share is
        /// observable. Disable for A/B comparisons against the one-shot path.
        /// </summary>
        public bool EmitTurnMetrics { get; set; } = true;

        /// <summary>
        /// Command-delivery + billing channel for new Claude session turns.
        /// Accepts <c>"print"</c> (default — today's <c>claude --print --resume</c>
        /// path) or <c>"acp"</c> (Agent Client Protocol, drives
        /// <c>claude --ide</c> off the metered <c>-p</c> pool). Case-insensitive,
        /// hot-reloadable: subsequent turns observe the new value on the next
        /// dispatch. Invalid values fall back to <c>"print"</c>.
        /// </summary>
        public string Transport { get; set; } = "print";

        /// <summary>
        /// Optional per-agent-class-member transport overrides. Map key is
        /// the agent-class-member name (case-insensitive); value is
        /// <c>"print"</c> or <c>"acp"</c>. Edit via
        /// <c>CodeyBox:ClaudeSession:TransportOverridesByAgentClassMember:&lt;member&gt;</c>.
        /// </summary>
        public Dictionary<string, string> TransportOverridesByAgentClassMember { get; set; }
            = new(StringComparer.OrdinalIgnoreCase);

        /// <summary>
        /// Optional per-project transport overrides. Map key is the project id
        /// (case-insensitive); value is <c>"print"</c> or <c>"acp"</c>.
        /// </summary>
        public Dictionary<string, string> TransportOverridesByProject { get; set; }
            = new(StringComparer.OrdinalIgnoreCase);

        /// <summary>
        /// Session-path enhancement: inject a single pre-emptive self-review
        /// turn after the initial work turn (before the formal audit) using
        /// the composed checklist from the project's auditors. Default off.
        /// </summary>
        public PreemptiveSelfReviewConfig PreemptiveSelfReview { get; set; } = new();
    }

    /// <summary>
    /// Sub-config block for <see cref="ClaudeSessionOptions.PreemptiveSelfReview"/>.
    /// </summary>
    public sealed class PreemptiveSelfReviewConfig
    {
        /// <summary>
        /// Default <c>false</c>. When <c>true</c>, session-mode work items run
        /// one extra warm-session turn after the initial work turn carrying
        /// the auditor-derived self-review guidance. The formal audit remains
        /// independent and owns the pass/fail decision.
        /// </summary>
        public bool Enabled { get; set; }
    }

    public sealed class AutoRetryOnQuotaFailureConfig
    {
        public bool Enabled { get; set; } = false;
        public string PeriodicCheckInterval { get; set; } = "00:05:00";
        public string ClockDriftSafetyMargin { get; set; } = "00:02:00";
        public int MaxAutoRetriesPerWorkItem { get; set; } = 3;
        public int MaxWaitingForQuotaResetSweepBatchSize { get; set; } =
            AutoRetryOnQuotaFailureOptions.DefaultWaitingForQuotaResetSweepBatchSize;
    }

    public sealed class AutoRetryOnTransientFailureConfig
    {
        public bool Enabled { get; set; } = true;
        public string PeriodicCheckInterval { get; set; } = "00:01:00";
        public string BaseDelay { get; set; } = "00:00:30";
        public double Multiplier { get; set; } = 2.0;
        public string MaxDelay { get; set; } = "00:15:00";
        public int MaxAutoRetriesPerWorkItem { get; set; } = 5;
        public string MaxElapsedTime { get; set; } = "01:00:00";
        public string JitterMode { get; set; } = "Full";
    }

    /// <summary>
    /// Bound from <c>CodeyBox:TerminalFailureRecovery</c>. Hot-reloadable.
    /// All TimeSpan-shaped values use the standard <c>HH:MM:SS</c> format.
    /// See <see cref="CodeyBox.Orchestrator.TerminalFailureRecoveryOptions"/>
    /// for runtime semantics.
    /// </summary>
    public sealed class TerminalFailureRecoveryConfig
    {
        public bool Enabled { get; set; } = false;
        public string PeriodicCheckInterval { get; set; } = "00:05:00";
        public string BaseBackoff { get; set; } = "00:01:00";
        public string MaxBackoff { get; set; } = "00:30:00";
        public double JitterFraction { get; set; } = 0.2;
        public int MaxAutoRetriesPerWorkItem { get; set; } = 3;
    }

    /// <summary>
    /// Bound from <c>CodeyBox:AutoRequeueOnAgentRestore</c>. Hot-reloadable
    /// except <see cref="EventQueueCapacity"/>, which sizes the scheduler
    /// channel at startup. See
    /// <see cref="CodeyBox.Orchestrator.AgentRestoreRetryScheduler"/> for
    /// runtime semantics.
    /// </summary>
    public sealed class AutoRequeueOnAgentRestoreConfig
    {
        /// <summary>
        /// Master switch for restore-driven infra-failure sweeps. Default
        /// <c>true</c>; set false only when an operator wants to perform these
        /// recovery sweeps manually.
        /// </summary>
        public bool Enabled { get; set; } = true;

        /// <summary>
        /// Non-negative <see cref="TimeSpan"/> string subtracted from the
        /// restore event's outage start when selecting failed candidates.
        /// </summary>
        public string LookbackGrace { get; set; } = AgentRestoreRetryOptions.DefaultLookbackGraceConfigValue;

        /// <summary>
        /// Non-negative <see cref="TimeSpan"/> string added after the restore
        /// timestamp to absorb ordering races between terminal writes and the
        /// restore signal.
        /// </summary>
        public string PostRestoreMargin { get; set; } = AgentRestoreRetryOptions.DefaultPostRestoreMarginConfigValue;

        /// <summary>
        /// Non-negative <see cref="TimeSpan"/> string used to match a failed
        /// agent-involvement row to a nearby terminal work-item write.
        /// </summary>
        public string InvolvementTerminalLookback { get; set; } = AgentRestoreRetryOptions.DefaultInvolvementTerminalLookbackConfigValue;

        /// <summary>
        /// Non-negative <see cref="TimeSpan"/> string allowing failed involvement
        /// rows to land slightly after the terminal work-item update they
        /// explain.
        /// </summary>
        public string InvolvementTerminalClockSkew { get; set; } = AgentRestoreRetryOptions.DefaultInvolvementTerminalClockSkewConfigValue;

        /// <summary>
        /// Positive cap applied inside the work-item store before buffering
        /// restore-sweep candidates. Default 500.
        /// </summary>
        public int MaxCandidatesPerSweep { get; set; } = AgentRestoreRetryOptions.DefaultMaxCandidatesPerSweep;

        /// <summary>
        /// Positive bounded-channel capacity for pending restore notifications.
        /// Startup-only; restart the API to apply changes. Default 128.
        /// </summary>
        public int EventQueueCapacity { get; set; } = AgentRestoreRetryOptions.DefaultEventQueueCapacity;

    }

    /// <summary>
    /// Disk-guard preflight configuration. Bound from <c>CodeyBox:DiskGuard</c>.
    /// </summary>
    public sealed class DiskGuardOptions
    {
        public const int MaximumAdditionalPaths = 64;

        /// <summary>
        /// Master switch. Default true so a stock deployment refuses to launch
        /// new sandboxes when the host is out of disk; set false to disable
        /// the preflight entirely (e.g. on a development laptop where the
        /// staging path lives on a small partition).
        /// </summary>
        public bool Enabled { get; set; } = true;

        /// <summary>
        /// Minimum free bytes per monitored mount. Below this the provider
        /// throws <c>SandboxDiskDeferredException</c> and the orchestrator
        /// reschedules the pickup. Default 10 GiB.
        /// </summary>
        public long MinFreeBytes { get; set; } = 10L * 1024 * 1024 * 1024;

        /// <summary>
        /// Path under which Multipass stores VM images. Default matches the
        /// snap install. Override for non-snap installs or custom data
        /// directories.
        /// </summary>
        public string MultipassDataPath { get; set; } = "/var/snap/multipass/common/data";

        /// <summary>
        /// Recheck delay before retrying a deferred work item. Defaults to
        /// 5 minutes. Same form as other TimeSpan options
        /// (<c>hh:mm:ss</c>).
        /// </summary>
        public string RecheckIn { get; set; } = "00:05:00";

        /// <summary>
        /// Extra host paths checked by VM providers in addition to their
        /// provider-owned backing storage. The wiring automatically adds the
        /// state-database directory, and Incus also adds its effective staging
        /// directory, so those writes are not the first to hit ENOSPC. At most
        /// <see cref="MaximumAdditionalPaths"/> paths may be configured.
        /// </summary>
        public List<string> AdditionalPaths { get; set; } = [];
    }

    public sealed class ShutdownOptions
    {
        /// <summary>
        /// Maximum time the host waits for in-flight phases to preempt or drain
        /// during SIGTERM/Ctrl-C. Defaults to 60 seconds.
        /// </summary>
        public int GraceSeconds { get; set; } = 60;

        /// <summary>
        /// Whether startup sandbox resume runs in the background after host
        /// startup begins, or blocks startup while still applying
        /// <see cref="SandboxResumeTimeout"/> per VM. Default Background keeps
        /// the HTTP control plane available even when a prior VM is wedged.
        /// Hot-reloadable for the next resume sweep.
        /// Bound from <c>CodeyBox:Shutdown:SandboxResumeMode</c>.
        /// </summary>
        public SandboxResumeMode SandboxResumeMode { get; set; } = SandboxResumeMode.Background;

        /// <summary>
        /// Caller-side cap for each persisted VM's startup resume call. This is
        /// distinct from the provider's own VM start/readiness timeout: it also
        /// protects the orchestrator from providers or daemons that do not
        /// observe cancellation. Hot-reloadable for pending resume attempts.
        /// Bound from <c>CodeyBox:Shutdown:SandboxResumeTimeout</c>.
        /// </summary>
        public TimeSpan SandboxResumeTimeout { get; set; } = SuspendTimeoutPolicy.DefaultFloor;

        /// <summary>
        /// Upper bound on how long the startup resume handler waits for an
        /// adopted in-VM agent process to finish post-resume. Long enough that
        /// a real LLM call can finish, short enough that a wedged agent does
        /// not delay the startup resume sweep indefinitely. Defaults to
        /// <see cref="SandboxStartupResumePolicy.DefaultAdoptionDeadline"/>.
        /// Hot-reloadable for pending adoption attempts.
        /// Bound from <c>CodeyBox:Shutdown:SandboxAdoptionDeadlineSeconds</c>.
        /// </summary>
        public int SandboxAdoptionDeadlineSeconds { get; set; } =
            (int)SandboxStartupResumePolicy.DefaultAdoptionDeadline.TotalSeconds;

        /// <summary>
        /// How to tear down in-flight worker sandboxes during graceful shutdown.
        /// Hot-reloadable: read by the shutdown handler when graceful shutdown
        /// begins, so an operator can switch modes without restarting first.
        /// Default <see cref="SandboxTeardownMode.Stop"/>: avoid RAM snapshots
        /// and cleanly stop/preserve the VM on graceful shutdown. Operators who
        /// explicitly want RAM-state preservation can opt in to
        /// <see cref="SandboxTeardownMode.Suspend"/>; it freezes RAM via
        /// <c>multipass suspend</c> and resumes on next startup, but can hit the
        /// qemu disk-image write-lock wedge that caused the 2026-05-29 incident.
        /// <see cref="SandboxTeardownMode.Dispose"/> remains available for full
        /// delete-and-purge teardown.
        /// </summary>
        public SandboxTeardownMode SandboxTeardownMode { get; set; } = SandboxTeardownMode.Stop;

        /// <summary>
        /// Overall budget for the Stop/Dispose per-VM teardown fan-out during
        /// graceful shutdown. In-flight items are checkpointed to the state DB
        /// BEFORE any VM call, so VMs still running when this budget expires
        /// are simply left for the next boot's startup reconciliation and
        /// stranded-item recovery — the process exits instead of blocking past
        /// the service manager's stop timeout (systemd SIGKILLs past
        /// <c>TimeoutStopSec</c>, which corrupts in-flight phases). Default 20
        /// seconds: with the default 60 second <see cref="GraceSeconds"/>
        /// drain, worst-case shutdown stays well under a 90 second stop
        /// timeout. Raise it only together with the stop timeout, keeping
        /// teardown budget + drain + a few seconds of reserve under the limit.
        /// Hot-reloadable: read when graceful shutdown begins.
        /// Bound from <c>CodeyBox:Shutdown:SandboxTeardownTimeout</c>.
        /// Applies to Stop/Dispose only; Suspend keeps its RAM-scaled per-VM
        /// timeouts by design (its pre-suspend mapping already guarantees
        /// recoverability, and aborting a snapshot early would defeat the
        /// opt-in state-preservation contract).
        /// </summary>
        public TimeSpan SandboxTeardownTimeout { get; set; } =
            SandboxShutdownTeardownService.DefaultTeardownBudget;
    }

    /// <summary>
    /// OpenTelemetry export configuration. Bound from <c>CodeyBox:Otel</c>.
    /// Off by default — set <see cref="Enabled"/> to true to opt in.
    /// </summary>
    public sealed class OtelOptions
    {
        /// <summary>Enable OTel export. Default false. Nothing is registered when false.</summary>
        public bool Enabled { get; set; } = false;

        /// <summary>OTel service.name resource attribute. Default "codeybox".</summary>
        public string ServiceName { get; set; } = "codeybox";

        /// <summary>OTel service.version — typically a git SHA or release tag.</summary>
        public string? ServiceVersion { get; set; }

        /// <summary>OTLP collector endpoint, e.g. http://localhost:4317.</summary>
        public string? OtlpEndpoint { get; set; }

        /// <summary>
        /// Optional CSV of extra headers forwarded to the OTLP collector,
        /// e.g. <c>x-honeycomb-team=abc,x-dataset=prod</c>.
        /// </summary>
        public string? OtlpHeaders { get; set; }

        /// <summary>OTLP wire format. Either <c>grpc</c> (default) or <c>httpprotobuf</c>.</summary>
        public string ExportProtocol { get; set; } = "grpc";

        /// <summary>Extra OTel resource attributes merged into every span and metric point.</summary>
        public Dictionary<string, string> ResourceAttributes { get; set; } = [];

        /// <summary>
        /// In-process Prometheus scrape exporter. Off by default; opt in by
        /// setting <c>CodeyBox:Otel:Prometheus:Enabled=true</c>. Runs alongside
        /// the OTLP push exporter (when <see cref="Enabled"/> is also true), or
        /// stands alone as the only metric exporter when OTLP is disabled.
        /// </summary>
        public PrometheusExporterOptions Prometheus { get; set; } = new();

        /// <summary>
        /// Validates the options, throwing <see cref="InvalidOperationException"/> when
        /// <see cref="Enabled"/> is true and the configuration is incomplete or invalid.
        /// Also validates <see cref="Prometheus"/> when the scrape exporter is enabled.
        /// Safe to call when both are disabled — no-ops immediately.
        /// </summary>
        public static void Validate(OtelOptions opts)
        {
            PrometheusExporterOptions.Validate(opts.Prometheus);

            if (!opts.Enabled) return;

            // The endpoint may come from appsettings OR the standard
            // OTEL_EXPORTER_OTLP_ENDPOINT env var, so telemetry can be enabled
            // from the conventional env-only bootstrap without duplicating it
            // under CodeyBox:Otel. Only one of the two is required.
            var envEndpoint = Environment.GetEnvironmentVariable("OTEL_EXPORTER_OTLP_ENDPOINT");
            var hasEnvEndpoint = !string.IsNullOrWhiteSpace(envEndpoint);

            if (string.IsNullOrWhiteSpace(opts.OtlpEndpoint) && !hasEnvEndpoint)
                throw new InvalidOperationException(
                    "CodeyBox:Otel:OtlpEndpoint or the OTEL_EXPORTER_OTLP_ENDPOINT environment " +
                    "variable must be set when CodeyBox:Otel:Enabled=true.");

            // Validate the appsettings endpoint when supplied; an env-only
            // endpoint is validated by the OTel SDK at export time.
            if (!string.IsNullOrWhiteSpace(opts.OtlpEndpoint)
                && (!Uri.TryCreate(opts.OtlpEndpoint, UriKind.Absolute, out var endpointUri)
                    || endpointUri.Scheme is not "http" and not "https"))
                throw new InvalidOperationException(
                    $"CodeyBox:Otel:OtlpEndpoint '{opts.OtlpEndpoint}' is not a valid http/https URL.");

            // Skip appsettings ExportProtocol validation when OTEL_EXPORTER_OTLP_PROTOCOL
            // is set: ConfigureOtlp defers to the env var at export time (the SDK reads
            // it directly), so a stale/invalid appsettings value is harmless and must
            // not block startup of an env-only bootstrap.
            var envProtocol = Environment.GetEnvironmentVariable("OTEL_EXPORTER_OTLP_PROTOCOL");
            if (string.IsNullOrWhiteSpace(envProtocol)
                && opts.ExportProtocol is not "grpc" and not "httpprotobuf")
                throw new InvalidOperationException(
                    $"CodeyBox:Otel:ExportProtocol '{opts.ExportProtocol}' is not valid. " +
                    "Expected 'grpc' or 'httpprotobuf'.");
        }

        /// <summary>
        /// Parses an <c>OTEL_RESOURCE_ATTRIBUTES</c>-style value
        /// (<c>key1=val1,key2=val2</c>) into resource attribute pairs. Returns an
        /// empty list for null/blank input. Malformed entries (no <c>=</c>, blank
        /// key) are skipped.
        /// </summary>
        public static IReadOnlyList<KeyValuePair<string, object>> ParseResourceAttributesEnv(string? raw)
        {
            if (string.IsNullOrWhiteSpace(raw)) return [];
            var result = new List<KeyValuePair<string, object>>();
            foreach (var pair in raw.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries))
            {
                var idx = pair.IndexOf('=');
                if (idx <= 0) continue;
                var key = pair[..idx].Trim();
                var value = pair[(idx + 1)..].Trim();
                if (key.Length == 0) continue;
                result.Add(new KeyValuePair<string, object>(key, value));
            }
            return result;
        }
    }

    /// <summary>
    /// In-process Prometheus scrape exporter configuration. Bound from
    /// <c>CodeyBox:Otel:Prometheus</c>. Off by default. Exposes the SAME
    /// metric instruments the OTLP push pipeline carries, rendered in
    /// Prometheus exposition format (dots → underscores, tags → labels), so a
    /// Prometheus scraper / curl / kioskish dashboard widget can read fleet
    /// state directly without an OTLP collector in the path.
    /// </summary>
    /// <remarks>
    /// The exporter is wired into the OpenTelemetry metrics pipeline at host
    /// build time, so toggling <see cref="Enabled"/> requires a restart;
    /// hot-reloading the option does nothing on its own. <see cref="Path"/>
    /// and <see cref="RequireApiKey"/> are also captured at startup.
    /// </remarks>
    public sealed class PrometheusExporterOptions
    {
        /// <summary>
        /// Master switch. Default <c>false</c>. When false, the Prometheus
        /// exporter is not registered with the meter provider and the scrape
        /// endpoint is not mapped, so the surface is invisible (no 401, no
        /// 404 — the route simply does not exist on the routing table).
        /// </summary>
        public bool Enabled { get; set; } = false;

        /// <summary>
        /// Scrape endpoint path. Default <c>/metrics</c>. Must begin with
        /// <c>/</c> and contain at least one non-slash character.
        /// </summary>
        public string Path { get; set; } = "/metrics";

        /// <summary>
        /// When <c>true</c>, the scrape endpoint requires the same
        /// <c>Authorization: Bearer &lt;key&gt;</c> header as every other API
        /// endpoint. When <c>false</c> (default), the scrape path is exempted
        /// from API-key auth at request time. The exemption is scoped to the
        /// EXACT configured <see cref="Path"/> — no descendants, no sibling
        /// routes, no other verbs picking up the bypass.
        /// </summary>
        /// <remarks>
        /// The default <c>false</c> assumes the deployment binds the API to
        /// localhost (or a private network) for the operator's own scrape
        /// stack. The exposed series carry fleet/quota gauges and runtime /
        /// HTTP instrumentation — non-sensitive operational data. If the API
        /// is reachable from a public network, set <c>RequireApiKey=true</c>.
        /// </remarks>
        public bool RequireApiKey { get; set; } = false;

        /// <summary>
        /// Validates the options, throwing <see cref="InvalidOperationException"/>
        /// when <see cref="Enabled"/> is true and the configuration is invalid.
        /// No-ops when disabled.
        /// </summary>
        public static void Validate(PrometheusExporterOptions opts)
        {
            if (!opts.Enabled) return;

            // Reject blank or malformed paths early. Without this, the
            // Prometheus middleware would happily map "/" or "" and either
            // shadow the root or fail at runtime with an opaque routing error.
            if (string.IsNullOrWhiteSpace(opts.Path)
                || opts.Path[0] != '/'
                || opts.Path.TrimStart('/').Length == 0)
                throw new InvalidOperationException(
                    $"CodeyBox:Otel:Prometheus:Path '{opts.Path}' is not valid. " +
                    "Expected a path beginning with '/' (e.g. '/metrics').");
        }
    }

    /// <summary>
    /// Global changelog automation options. Bound from <c>CodeyBox:Changelog</c>.
    /// Per-project overrides are applied via <c>Project.Changelog</c>.
    /// </summary>
    public sealed class ChangelogOptions
    {
        /// <summary>
        /// Enable or disable changelog automation globally. Default false:
        /// changelog automation is opt-in per project (see
        /// docs/operating/releases.md), so an unconfigured install starts
        /// cleanly with the webhook receiver failing closed.
        /// </summary>
        public bool Enabled { get; set; } = false;

        /// <summary>
        /// LLM agent to use for generation. Currently only "claude" is supported.
        /// Default "claude".
        /// </summary>
        public string GeneratorAgent { get; set; } = "claude";

        /// <summary>
        /// Optional model override for the generator LLM call, e.g. "claude-opus-4-7".
        /// Defaults to "claude-opus-4-7".
        /// </summary>
        public string? GeneratorModelId { get; set; }

        /// <summary>
        /// Completion endpoint for the generator LLM call. Configured default for the
        /// previously hardcoded endpoint. Default "https://api.anthropic.com/v1/messages".
        /// </summary>
        public string GeneratorBaseUrl { get; set; } = "https://api.anthropic.com/v1/messages";

        /// <summary>
        /// Wire protocol for the generator LLM call. Default AnthropicMessages.
        /// </summary>
        public CodeyBox.Core.CompletionWireApi GeneratorWireApi { get; set; } = CodeyBox.Core.CompletionWireApi.AnthropicMessages;

        /// <summary>
        /// Optional API key for the generator LLM call. When unset, falls back to the
        /// CODEYBOX_CLAUDE_API_KEY environment variable.
        /// </summary>
        public string? GeneratorApiKey { get; set; }

        /// <summary>
        /// Anthropic API version header value sent when <see cref="GeneratorWireApi"/>
        /// is AnthropicMessages. Default "2023-06-01".
        /// </summary>
        public string GeneratorAnthropicVersion { get; set; } = "2023-06-01";

        /// <summary>
        /// Path to CHANGELOG.md within the project repo. Default "CHANGELOG.md".
        /// </summary>
        public string ChangelogPath { get; set; } = "CHANGELOG.md";

        /// <summary>
        /// Section header format. Supports {tag} and {date:yyyy-MM-dd} placeholders.
        /// Default: "## [{tag}] - {date:yyyy-MM-dd}".
        /// </summary>
        public string SectionHeaderFormat { get; set; } = "## [{tag}] - {date:yyyy-MM-dd}";

        /// <summary>
        /// Name of the environment variable holding the HMAC-SHA256 secret for
        /// validating incoming GitHub release webhooks. Required when
        /// <see cref="Enabled"/> is true and the host runs outside Development
        /// (startup fails without it); the webhook endpoint rejects all
        /// requests with 401 while the secret is missing at runtime.
        /// </summary>
        public string? GitHubWebhookSecretEnvVar { get; set; }
    }

    /// <summary>
    /// Credential smoke test options. Bound from <c>CodeyBox:Smoke</c>.
    /// </summary>
    public sealed class SmokeConfig
    {
        /// <summary>Enable or disable the smoke gate. Default true.</summary>
        public bool Enabled { get; set; } = true;

        /// <summary>Result cache TTL in minutes. Default 15.</summary>
        public int CacheTtlMinutes { get; set; } = 15;

        /// <summary>Per-agent timeout for the startup probe in seconds. Default 10.</summary>
        public int StartupTimeoutSeconds { get; set; } = 10;

        /// <summary>
        /// Tuning for the availability registry (fast-fail circuit breaker +
        /// periodic smoke probe sweep). Bound from <c>CodeyBox:Smoke:Availability</c>.
        /// </summary>
        public AvailabilityConfig Availability { get; set; } = new();

        /// <summary>
        /// Tuning for the in-VM smoke prober (binary-presence + auth checks run
        /// inside a sandbox cloned from the active baseline). Bound from
        /// <c>CodeyBox:Smoke:InVm</c>.
        /// </summary>
        public InVmSmokeConfig InVm { get; set; } = new();
    }

    /// <summary>
    /// Config binding for the transition-health metric. Bound from
    /// <c>CodeyBox:TransitionHealth</c>. All fields are hot-reloadable; see
    /// <see cref="TransitionHealthOptionsSnapshot"/>.
    /// </summary>
    public sealed class TransitionHealthConfig
    {
        /// <summary>Enable the <c>/fleet/transition-health</c> endpoint and computation. Default true.</summary>
        public bool Enabled { get; set; } = true;

        /// <summary>
        /// Rolling window in hours. Default 24. Floor 5 / 60 (5 minutes),
        /// ceiling 30 * 24 (30 days). Values outside the range are clamped at
        /// binding time.
        /// </summary>
        public double WindowHours { get; set; } = 24.0;

        /// <summary>
        /// Optional "last N transitions" cap. Null = use the wall-clock window
        /// only. When set, the score is computed over the most recent
        /// <c>MaxTransitions</c> transitions regardless of how long ago they
        /// happened. Floor 50, ceiling 100_000.
        /// </summary>
        public int? MaxTransitions { get; set; }
    }

    /// <summary>Config binding for the in-VM smoke prober.</summary>
    public sealed class InVmSmokeConfig
    {
        /// <summary>Enable or disable the in-VM smoke prober. Default true.</summary>
        public bool Enabled { get; set; } = true;

        /// <summary>Per-step exec timeout inside the sandbox, in seconds. Default 30.</summary>
        public int StepTimeoutSeconds { get; set; } = 30;

        /// <summary>
        /// Hard wall-clock timeout on VM provisioning (the
        /// <see cref="ISandboxProvider.CreateAsync"/> call), in seconds. Default 120.
        /// The per-step exec timeout cannot bound this because no sandbox exists
        /// to exec into; a wedged baseline clone would otherwise hang the
        /// dispatch gate forever. Non-positive disables it (tests / synthetic
        /// clocks). See <see cref="InVmSmokeOptions.ProvisionTimeoutSeconds"/>.
        /// </summary>
        public int ProvisionTimeoutSeconds { get; set; } = 120;

        /// <summary>
        /// Top-level deadline on the dispatch-gate call (defect-in-depth net for
        /// any inner step the per-operation timeouts don't cover), in seconds.
        /// Default 180. Non-positive disables it. See
        /// <see cref="InVmSmokeOptions.GateDeadlineSeconds"/>.
        /// </summary>
        public int GateDeadlineSeconds { get; set; } = 180;

        /// <summary>Result cache TTL per baseline ref, in minutes. Default 60.</summary>
        public int CacheTtlMinutes { get; set; } = 60;

        /// <summary>Background sweep interval in seconds. Default 300 (5 min); set 0 to disable.</summary>
        public int SweepIntervalSeconds { get; set; } = 300;

        /// <summary>
        /// Fail-closed dispatch-gate policy. When true (the default), an in-VM
        /// probe that cannot reach a verdict (provisioning/exec/timeout/credential
        /// fault) temporarily benches the agent so the router never dispatches to
        /// an unverified CLI; the bench self-heals on the next successful probe.
        /// Set false only on infra so flaky that benching disrupts more than the
        /// exit-127 / auth cascade it guards against. See
        /// <see cref="InVmSmokeOptions.FailClosedOnProbeFault"/>.
        /// </summary>
        public bool FailClosedOnProbeFault { get; set; } = true;

        /// <summary>
        /// Explicit host network profile for project-less probe paths. Dispatch
        /// gates pass the resolved project sandbox target directly, so this is
        /// not used as a fallback for work items.
        /// </summary>
        public string? NetworkProfile { get; set; }

        /// <summary>
        /// Agents allowed to route without a registered in-VM smoke probe.
        /// Uncovered agents are otherwise benched at startup (AC#1). Defaults to
        /// <c>copilot</c> when unset, preserving back-compat for operators who
        /// have not yet installed the Copilot CLI in their baseline image —
        /// when CopilotInVmSmokeProbe is registered the probe runs and the
        /// exemption is unused. Set explicitly to override.
        /// </summary>
        public List<string>? ExemptAgentsWithoutProbe { get; set; }
    }

    /// <summary>Config binding for the availability registry.</summary>
    public sealed class AvailabilityConfig
    {
        /// <summary>Fast-fail threshold in seconds. Default 10.</summary>
        public int FastFailThresholdSeconds { get; set; } = 10;

        /// <summary>Consecutive sub-threshold non-zero exits before excluding. Default 3.</summary>
        public int MaxConsecutiveFastFails { get; set; } = 3;

        /// <summary>
        /// Consecutive DISTINCT work items that the agent leaves empty-diff
        /// (clean exit, no commit) before the no-changes circuit breaker
        /// excludes the agent. Default 3. Set 0 (or negative) to disable.
        /// </summary>
        public int MaxConsecutiveNoChanges { get; set; } = 3;

        /// <summary>Background sweep interval in seconds. Default 300 (5 min); set 0 to disable.</summary>
        public int PeriodicSweepIntervalSeconds { get; set; } = 300;
    }

    /// <summary>Config binding for a single agent class (see CodeyBox:AgentClasses).</summary>
    public sealed class AgentClassOptions
    {
        public string Id { get; set; } = string.Empty;
        public string DisplayName { get; set; } = string.Empty;
        /// <summary>
        /// Optional class-level opt-in for the Claude resumable-session worker.
        /// Per-member settings override this value.
        /// </summary>
        public AgentClassClaudeSessionOptions? ClaudeSession { get; set; }
        public List<AgentMembershipOptions> Members { get; set; } = [];
    }

    public sealed class AgentClassClaudeSessionOptions
    {
        public bool? Enabled { get; set; }
    }

    /// <summary>Config binding for a reusable routable agent instance.</summary>
    public sealed class AgentInstanceOptions
    {
        /// <summary>
        /// Stable instance id. Values without a slash are rendered as
        /// <c>{Agent}/{Id}</c>; values that already contain a slash are used as
        /// full route keys.
        /// </summary>
        public string Id { get; set; } = string.Empty;

        /// <summary>Underlying agent kind, e.g. "claude", "codex".</summary>
        public string Agent { get; set; } = string.Empty;

        /// <summary>Host OAuth/auth JSON file for this instance.</summary>
        public string? CredentialFilePath { get; set; }

        /// <summary>Host env var containing a raw token/API key for this instance.</summary>
        public string? TokenEnvironmentVariable { get; set; }

        /// <summary>Host env var containing CLI auth JSON for this instance.</summary>
        public string? AuthJsonEnvironmentVariable { get; set; }

        /// <summary>Optional companion settings file, used by Gemini OAuth.</summary>
        public string? SettingsFilePath { get; set; }

        /// <summary>Optional sandbox destination path for file-materializing runners.</summary>
        public string? DestinationPath { get; set; }

        /// <summary>Optional override for the sandbox env var used for token injection.</summary>
        public string? SandboxEnvironmentVariable { get; set; }

        /// <summary>
        /// Optional named provider entry for this instance (today: a
        /// <c>CodeyBox:Copilot:Providers</c> entry for copilot instances).
        /// Null means the agent-global provider configuration.
        /// </summary>
        public string? Provider { get; set; }
    }

    /// <summary>Config binding for one member of an agent class.</summary>
    public sealed class AgentMembershipOptions
    {
        /// <summary>Agent kind value, e.g. "claude", "codex".</summary>
        public string Agent { get; set; } = string.Empty;
        /// <summary>Optional instance id or route key. Null means the default per-kind instance.</summary>
        public string? InstanceId { get; set; }
        /// <summary>
        /// Optional quota pool this member draws from (must name an entry in
        /// <c>CodeyBox:QuotaRouter:Pools</c>). Members of one pool share a
        /// single reading, floor, and reservation escrow. Null keeps legacy
        /// per-agent keying. An unknown name fails closed at dispatch.
        /// </summary>
        public string? Pool { get; set; }
        /// <summary>"Subscription" or "PayPerApi".</summary>
        public string Billing { get; set; } = "Subscription";
        /// <summary>Optional model override, e.g. "claude-opus-4-7".</summary>
        public string? ModelId { get; set; }
        /// <summary>Inline host OAuth/auth JSON file for this member instance.</summary>
        public string? CredentialFilePath { get; set; }
        /// <summary>Inline host env var containing a raw token/API key for this member instance.</summary>
        public string? TokenEnvironmentVariable { get; set; }
        /// <summary>Inline host env var containing CLI auth JSON for this member instance.</summary>
        public string? AuthJsonEnvironmentVariable { get; set; }
        /// <summary>Inline companion settings file, used by Gemini OAuth.</summary>
        public string? SettingsFilePath { get; set; }
        /// <summary>Inline sandbox destination path for file-materializing runners.</summary>
        public string? DestinationPath { get; set; }
        /// <summary>Inline override for the sandbox env var used for token injection.</summary>
        public string? SandboxEnvironmentVariable { get; set; }
        /// <summary>
        /// Inline named provider entry for this member instance (today: a
        /// <c>CodeyBox:Copilot:Providers</c> entry for copilot members).
        /// Null means the agent-global provider configuration.
        /// </summary>
        public string? Provider { get; set; }
        /// <summary>
        /// Operator-curated capability score (0–200). Required; no silent default.
        /// See docs/concepts/agent-classes.md for recommended seed values.
        /// </summary>
        public int? QualityScore { get; set; }
        /// <summary>
        /// Optional reasoning-effort knob, e.g. "high". Required for Gemini
        /// members with QualityScore >= 90.
        /// </summary>
        public string? ReasoningMode { get; set; }
        /// <summary>
        /// Clearance/capability tags this member is trusted to handle, e.g.
        /// <c>["sensitive", "architectural"]</c>. Default empty — members with
        /// no tags can only run work items that require no tags. See
        /// docs/concepts/agent-classes.md for the recommended tag vocabulary.
        /// </summary>
        public List<string> Capabilities { get; set; } = [];
        /// <summary>
        /// Optional member-level override for the Claude resumable-session
        /// worker. Null inherits the containing class setting.
        /// </summary>
        public AgentClassClaudeSessionOptions? ClaudeSession { get; set; }
    }

    /// <summary>Quota router tuning. Bound from CodeyBox:QuotaRouter.</summary>
    public sealed class QuotaRouterConfig
    {
        /// <summary>
        /// Fallback floor used when the ramp can't be computed (probe didn't
        /// surface a ResetAt, or no ramp window is configured for the agent).
        /// Default 10. See <see cref="StartFloorPct"/> /
        /// <see cref="EndFloorPct"/> / <see cref="RampWindowSeconds"/> for the
        /// ramped floor that supersedes this when the window IS known.
        /// </summary>
        public double MinQuotaPct { get; set; } = 10.0;
        /// <summary>
        /// Per-window absolute floors, keyed by provider window name
        /// (e.g. <c>five_hour</c>, <c>seven_day</c>). Dispatch requires every
        /// window's available percentage to be at or above its window's
        /// floor — block if any window is below its own floor — using the
        /// per-window readings the probe surfaces in
        /// <c>AgentQuotaSnapshot.PerModel[].Windows</c>. Unlisted windows
        /// fall back to <see cref="MinQuotaPct"/>. The 5 h window's absolute
        /// budget is far smaller than the 7 d, so 10 % of 5 h is thin headroom
        /// for the in-flight + cache-staleness overshoot during a burst (up to
        /// MaxConcurrent concurrent long opus runs already dispatched + new
        /// dispatches inside <c>QuotaCacheTtlSeconds</c>); a higher 5 h floor
        /// absorbs that overshoot. Default <c>{five_hour: 25}</c> for
        /// MaxConcurrent=4; tune up for higher fleet concurrency. Hot-reloadable.
        /// </summary>
        public Dictionary<string, double> MinQuotaPctByWindow { get; set; }
            = new(StringComparer.OrdinalIgnoreCase)
            {
                ["five_hour"] = 25.0,
            };
        /// <summary>
        /// Early-window quota floor — the effective minimum just after the
        /// quota window resets. Reserves headroom for the operator's
        /// interactive session and monitoring on a freshly-reset week.
        /// Default 25.
        /// </summary>
        public double StartFloorPct { get; set; } = 25.0;
        /// <summary>
        /// Late-window quota floor — the effective minimum as the quota
        /// window approaches reset. Drains otherwise-stranded quota right
        /// before the use-it-or-lose-it reset. Default 3.
        /// </summary>
        public double EndFloorPct { get; set; } = 3.0;
        /// <summary>
        /// Length of the binding quota window the ramp is computed against,
        /// in seconds. Default 604800 (7 days, claude/codex weekly cap).
        /// </summary>
        public int RampWindowSeconds { get; set; } = 7 * 24 * 60 * 60;
        /// <summary>
        /// Optional per-agent ramp window length, keyed by agent kind value.
        /// Lets the operator pin a 24h window for one agent and a 7-day
        /// window for another without touching code. Entries with
        /// non-positive seconds are ignored.
        /// </summary>
        public Dictionary<string, int> RampWindowByAgentSeconds { get; set; }
            = new(StringComparer.OrdinalIgnoreCase);
        /// <summary>
        /// Optional per-agent floor overrides keyed by agent kind value
        /// (e.g. <c>codex</c>, <c>claude</c>). Omitted agents and omitted
        /// fields inherit the global ramp/fallback settings above. Set
        /// low values such as StartFloorPct=1, EndFloorPct=0, MinQuotaPct=1
        /// to burn a work-only agent close to empty while keeping oversight
        /// agents on the global reserve. Hot-reloadable.
        /// </summary>
        public Dictionary<string, QuotaRouterFloorConfig> FloorByAgent { get; set; }
            = new(StringComparer.OrdinalIgnoreCase);
        /// <summary>
        /// Operator-declared quota pools, keyed by pool name
        /// (case-insensitive). Each pool names one underlying account or
        /// subscription; class members join a pool via their <c>Pool</c>
        /// reference and then share one reading, one floor, and one
        /// reservation escrow. Membership is operator-declared here — never
        /// derived from credential material. Empty (the default) keeps legacy
        /// per-agent keying. Hot-reloadable.
        /// </summary>
        public Dictionary<string, QuotaPoolConfig> Pools { get; set; }
            = new(StringComparer.OrdinalIgnoreCase);
        /// <summary>
        /// Per-pool floor overrides keyed by pool name (case-insensitive),
        /// alongside <see cref="FloorByAgent"/>. For a pool member the higher
        /// of the pool-resolved and agent-resolved floors wins; with only one
        /// present it applies directly. Resetting-window pools use the
        /// percentage fields; depleting-balance pools use <c>MinBalance</c>
        /// (absolute units) — mixing units is rejected at load.
        /// Hot-reloadable.
        /// </summary>
        public Dictionary<string, QuotaPoolFloorConfig> FloorByPool { get; set; }
            = new(StringComparer.OrdinalIgnoreCase);
        /// <summary>Seconds to wait before re-probing when all subscription members are exhausted. Default 300 (5 min).</summary>
        public int QuotaRecheckIntervalSeconds { get; set; } = 300;
        /// <summary>
        /// Seconds a cached in-process exhaustion verdict is trusted without
        /// revalidation. Older verdicts are re-checked against a live probe
        /// before they may keep refusing dispatches. Default 900 (15 min).
        /// </summary>
        public int ExhaustionRevalidationAgeSeconds { get; set; } = 900;
        /// <summary>
        /// Seconds between event-driven recovery probes for members already
        /// observed as quota-unusable. Default 5.
        /// </summary>
        public int QuotaRecoveryProbeIntervalSeconds { get; set; } =
            QuotaRouterDefaults.DefaultQuotaRecoveryProbeIntervalSeconds;
        /// <summary>
        /// Maximum parked quota rows inspected by each event-driven recovery
        /// eligibility pass. Default 128.
        /// </summary>
        public int MaxQuotaRecoveryProbeEligibilityScan { get; set; } =
            QuotaRouterDefaults.DefaultQuotaRecoveryProbeEligibilityScanLimit;
        /// <summary>Seconds to cache a probe result. Default 60.</summary>
        public int QuotaCacheTtlSeconds { get; set; } = 60;
        /// <summary>
        /// Seconds to cache quota snapshots while an agent is operator-paused.
        /// Active/routable agents still use <see cref="QuotaCacheTtlSeconds"/>.
        /// Default 3600 (1 hour). Hot-reloadable.
        /// </summary>
        public int PausedQuotaCacheTtlSeconds { get; set; } = 3600;
        /// <summary>
        /// Maximum age in seconds of a retained last-known-good snapshot while
        /// an agent is operator-paused. Default 5400 (90 min). Hot-reloadable.
        /// </summary>
        public int PausedProbeMaxStalenessSeconds { get; set; } = 5400;
        /// <summary>
        /// Maximum number of paused route quota snapshots retained in memory.
        /// Default 1024. Hot-reloadable.
        /// </summary>
        public int PausedQuotaMaxCacheEntries { get; set; } = 1024;
        /// <summary>How the router treats unknown probe snapshots. Default UseObservedFailures.</summary>
        public QuotaUnknownPolicy UnknownPolicy { get; set; } = QuotaUnknownPolicy.UseObservedFailures;
        /// <summary>Minutes a recent quota-shaped failure blocks the same agent/model. Default 10.</summary>
        public int ObservedFailureWindowMinutes { get; set; } = 10;
        /// <summary>Minutes observed quota failures are retained in state.db. Default 30.</summary>
        public int ObservedFailureRetentionMinutes { get; set; } = 30;
        /// <summary>
        /// Tolerance in seconds for clock skew between executor and
        /// orchestrator hosts when validating an executor-reported reading's
        /// observed time. A report dated further in the future than this is
        /// rejected. Default 300 (5 min). Hot-reloadable.
        /// </summary>
        public int ReportedReadingClockSkewSeconds { get; set; } =
            QuotaRouterDefaults.DefaultReportedReadingClockSkewSeconds;
        /// <summary>
        /// Seconds before a cap-spill-deferred work item is reconsidered (every
        /// eligible class member was at its per-agent concurrency cap). Default
        /// 15; the orchestrator's own atomic-reservation defer uses the same
        /// 15s cadence, so leave defaults aligned unless you have a reason.
        /// </summary>
        public int CapRetryIntervalSeconds { get; set; } = 15;
        /// <summary>
        /// Default "how many concurrent burns fit in the remaining quota window"
        /// used when the estimator has no historical samples yet. Keeps the
        /// dispatch queue from stalling on cold start. Default 2.0.
        /// </summary>
        public double ColdStartFitInWindow { get; set; } = 2.0;
        /// <summary>
        /// Multiplier for DeadlineAwareDrain. Default 1.0 follows the even pace;
        /// values above 1.0 bias dispatch ahead of pace so free/manual refills are
        /// less likely to strand quota. Hot-reloadable.
        /// </summary>
        public double DrainAggressiveness { get; set; } = 1.0;
        /// <summary>
        /// Operator-declared expected free/manual reset points, keyed by agent kind
        /// value. Each entry may provide explicit <c>Timestamps</c> and/or a
        /// recurring <c>CadenceSeconds</c> with <c>CadenceAnchor</c>. Hot-reloadable.
        /// </summary>
        public Dictionary<string, QuotaRouterExpectedResetConfig> ExpectedResets { get; set; }
            = new(StringComparer.OrdinalIgnoreCase);
        /// <summary>
        /// How pooled instances of the same agent kind are ordered. Default
        /// MostQuotaFirst maximizes runway; RoundRobin spreads wear; Sticky
        /// keeps later phases on the selected instance when available;
        /// DeadlineAwareDrain drains use-it-or-lose-it subscription quota toward
        /// its floor by the nearest known or expected reset. Hot-reloadable.
        /// </summary>
        public IntraKindRoutingPolicy IntraKindRoutingPolicy { get; set; } =
            IntraKindRoutingPolicy.MostQuotaFirst;
        /// <summary>
        /// Estimated quota cost of one dispatch, in quota-percentage points.
        /// The reservation ledger escrows this per authorised dispatch so
        /// concurrent workers sharing one cached probe reading cannot jointly
        /// overshoot the floor. Cold-start default 5.0; set near the typical
        /// per-item burn for the fleet. Hot-reloadable.
        /// </summary>
        public double DispatchReservationEstimatePct { get; set; } = 5.0;
        /// <summary>
        /// Per-agent override for <see cref="DispatchReservationEstimatePct"/>,
        /// keyed by agent kind value. Non-positive entries are ignored.
        /// Hot-reloadable.
        /// </summary>
        public Dictionary<string, double> DispatchReservationEstimatePctByAgent { get; set; }
            = new(StringComparer.OrdinalIgnoreCase);
        /// <summary>
        /// Work-denominated alternative to
        /// <see cref="DispatchReservationEstimatePct"/>: how many dispatches'
        /// worth of quota one reservation escrows, converted through the
        /// member's measured per-item burn. Null (the default) keeps the
        /// percentage chain. Requires measured burn (which itself needs
        /// <c>CodeyBox:AgentBurnEstimator:WindowTokenBudget</c> for the agent).
        /// Hot-reloadable.
        /// </summary>
        public double? DispatchReservationEstimateItems { get; set; }
        /// <summary>
        /// Per-agent override for <see cref="DispatchReservationEstimateItems"/>,
        /// keyed by agent kind value. Non-positive or non-finite entries are
        /// rejected at load. Hot-reloadable.
        /// </summary>
        public Dictionary<string, double> DispatchReservationEstimateItemsByAgent { get; set; }
            = new(StringComparer.OrdinalIgnoreCase);
        /// <summary>
        /// Safety factor applied to the measured per-item burn when deriving a
        /// per-dispatch reservation (derived = burn × this). Default 1.5.
        /// Non-positive disables derivation. Hot-reloadable.
        /// </summary>
        public double DispatchReservationBurnMultiplier { get; set; } = 1.5;
        /// <summary>
        /// Minimum measured samples before burn-derived reservations (or
        /// items-denominated estimates/floors) apply. Default 3. Hot-reloadable.
        /// </summary>
        public int DispatchReservationBurnMinSamples { get; set; } = 3;
        /// <summary>
        /// Work-denominated alternative to <see cref="MinQuotaPct"/>: the
        /// fallback floor in dispatches' worth of quota. Null (the default)
        /// keeps the percentage floor. Requires measured burn. Hot-reloadable.
        /// </summary>
        public double? MinQuotaItems { get; set; }
        /// <summary>
        /// Lower bound for any reservation estimate, in quota-percentage
        /// points. A missing, zero, or negative estimate resolves to at least
        /// this — a dispatch must never silently reserve nothing. Default 0.5.
        /// Hot-reloadable.
        /// </summary>
        public double DispatchReservationMinPct { get; set; } = 0.5;
        /// <summary>
        /// Upper bound for any single reservation, in quota-percentage points.
        /// Guards against a misconfigured estimate pinning the pool. Default
        /// 25. Hot-reloadable.
        /// </summary>
        public double DispatchReservationMaxPct { get; set; } = 25.0;
        /// <summary>
        /// Maximum age in seconds of a quota reservation before the orphan
        /// sweep reaps it. Backstop only — prompt release flows through the
        /// worker-slot lifecycle. Must exceed the longest legitimate phase.
        /// Default 21600 (6 hours). Hot-reloadable.
        /// </summary>
        public int QuotaReservationMaxAgeSeconds { get; set; } = 6 * 60 * 60;
        /// <summary>
        /// Additional retries on a transient probe failure (network error / timeout / 5xx)
        /// before recording the failure. Total attempts = 1 + this value. Default 2.
        /// Hot-reloadable.
        /// </summary>
        public int ProbeMaxRetries { get; set; } = 2;
        /// <summary>
        /// Base retry backoff in milliseconds; doubles each attempt. Default 250 ms.
        /// Hot-reloadable.
        /// </summary>
        public int ProbeRetryInitialDelayMs { get; set; } = 250;
        /// <summary>
        /// Maximum between-retry delay in seconds, including provider
        /// Retry-After values. Default 300 (5 min). Hot-reloadable.
        /// </summary>
        public int ProbeRetryMaxDelaySeconds { get; set; } = 300;
        /// <summary>
        /// Consecutive probe failures tolerated before the probe stops returning
        /// the retained last-known-good snapshot. Default 3. Hot-reloadable.
        /// </summary>
        public int ProbeMaxConsecutiveFailures { get; set; } = 3;
        /// <summary>
        /// Maximum age in seconds of a retained last-known-good snapshot before
        /// it is dropped in favour of <c>AvailablePct=-1</c>. Default 300 (5 min).
        /// Hot-reloadable.
        /// </summary>
        public int ProbeMaxStalenessSeconds { get; set; } = 300;
        /// <summary>
        /// Maximum OAuth refresh response body accepted by the subscription
        /// quota-token refreshers (Claude/Codex/Gemini), in bytes. The shared
        /// refresh reader enforces this <i>before</i> buffering by streaming
        /// under <c>HttpCompletionOption.ResponseHeadersRead</c>; oversize
        /// bodies fail the refresh (probe maps to "unknown") instead of being
        /// buffered or parsed. Default 8192 — a legitimate refresh payload is
        /// a few hundred bytes of JSON. Hot-reloadable.
        /// </summary>
        public int OauthRefreshMaxBodyBytes { get; set; } = CodeyBox.Agents.OauthCredentialRefresherBounds.DefaultMaxRefreshBodyBytes;
        /// <summary>
        /// Per-stream cap (stdout/stderr), in chars, for agent-CLI child-process
        /// output captured during OAuth token refresh. Output beyond the cap is
        /// discarded while the pipes are still drained, so a chatty child can
        /// neither exhaust memory nor block on a full buffer. Only the exit code
        /// is observed. Default 1048576 (1 MiB). Hot-reloadable.
        /// </summary>
        public int OauthRefreshMaxCliOutputChars { get; set; } = CodeyBox.Agents.OauthCredentialRefresherBounds.DefaultMaxCliOutputChars;
    }

    /// <summary>
    /// Per-agent quota floor override. Null fields inherit the corresponding
    /// global <see cref="QuotaRouterConfig"/> setting.
    /// </summary>
    public sealed class QuotaRouterFloorConfig
    {
        /// <summary>Fallback floor used when the ramp cannot be computed.</summary>
        public double? MinQuotaPct { get; set; }

        /// <summary>Early-window ramp floor for this agent.</summary>
        public double? StartFloorPct { get; set; }

        /// <summary>Late-window ramp floor for this agent.</summary>
        public double? EndFloorPct { get; set; }

        /// <summary>Optional ramp-window length in seconds for this agent.</summary>
        public int? RampWindowSeconds { get; set; }

        /// <summary>
        /// Work-denominated fallback floor for this agent, in dispatches'
        /// worth of quota. Competes with the percentage floor via maximum.
        /// Requires measured burn. Hot-reloadable.
        /// </summary>
        public double? MinQuotaItems { get; set; }
    }

    /// <summary>
    /// Operator-declared quota pool: one underlying account or subscription.
    /// Bound from <c>CodeyBox:QuotaRouter:Pools:&lt;name&gt;</c>.
    /// </summary>
    public sealed class QuotaPoolConfig
    {
        /// <summary>
        /// Replenishment kind: <c>ResettingWindow</c> (subscription allowance
        /// that returns to full; readings and floors are percentages) or
        /// <c>DepletingBalance</c> (prepaid credit that never resets; readings
        /// and floors are absolute values). Case-insensitive. Default
        /// <c>ResettingWindow</c>.
        /// </summary>
        public string Kind { get; set; } = "ResettingWindow";

        /// <summary>
        /// Human-readable unit for absolute balances on a depleting-balance
        /// pool (e.g. <c>"credits"</c>). Informational only.
        /// </summary>
        public string? BalanceUnit { get; set; }

        /// <summary>
        /// Estimated cost of one dispatch in the pool's native unit
        /// (percentage points for resetting-window pools, absolute balance
        /// units for depleting-balance pools). Null falls back to the global
        /// reservation estimate. Set explicitly for balance pools.
        /// </summary>
        public double? ReservationEstimate { get; set; }

        /// <summary>
        /// Work-denominated alternative to <see cref="ReservationEstimate"/>
        /// for resetting-window pools: how many dispatches' worth of quota one
        /// reservation escrows (e.g. 1 reserves one item's worth). Converted
        /// through the member's measured per-item burn; without enough samples
        /// the percentage chain applies. Rejected on depleting-balance pools.
        /// Hot-reloadable.
        /// </summary>
        public double? ReservationEstimateItems { get; set; }

        /// <summary>
        /// Where this pool's probe runs: <c>OrchestratorDirect</c> (the
        /// default — the orchestrator holds the credential and probes
        /// directly, exactly as today) or <c>ExecutorReported</c> (an
        /// executor host holding the credential probes locally and reports
        /// readings; the orchestrator meters the pool from the latest fresh
        /// report). Case-insensitive. Hot-reloadable.
        /// </summary>
        public string ProbeSource { get; set; } = "OrchestratorDirect";

        /// <summary>
        /// Maximum age in seconds of an executor-reported reading before the
        /// pool reads as unknown. Applies only to <c>ExecutorReported</c>
        /// pools. Zero means the default (300); negative values are rejected.
        /// Hot-reloadable.
        /// </summary>
        public int ReportedReadingMaxAgeSeconds { get; set; } =
            QuotaRouterDefaults.DefaultReportedReadingMaxAgeSeconds;

        /// <summary>
        /// Executor host ids authorised to report readings for this pool.
        /// Applies only to <c>ExecutorReported</c> pools: reports from any
        /// other host are rejected. Matched by exact equality against the
        /// executor's registered host id. Hot-reloadable.
        /// </summary>
        public List<string> HolderHostIds { get; set; } = [];
    }

    /// <summary>
    /// Per-pool quota floor override. Which fields are legal depends on the
    /// pool's kind: resetting-window pools use the percentage fields,
    /// depleting-balance pools use <see cref="MinBalance"/>. Mixing units is
    /// rejected at configuration load.
    /// </summary>
    public sealed class QuotaPoolFloorConfig
    {
        /// <summary>Fallback percentage floor (resetting-window pools).</summary>
        public double? MinQuotaPct { get; set; }

        /// <summary>Early-window ramp percentage floor (resetting-window pools).</summary>
        public double? StartFloorPct { get; set; }

        /// <summary>Late-window ramp percentage floor (resetting-window pools).</summary>
        public double? EndFloorPct { get; set; }

        /// <summary>Optional ramp-window length in seconds (resetting-window pools).</summary>
        public int? RampWindowSeconds { get; set; }

        /// <summary>
        /// Absolute floor in the pool's balance units (depleting-balance
        /// pools). Dispatch is refused terminally at or below this value.
        /// Defaults to 0 when unset.
        /// </summary>
        public double? MinBalance { get; set; }

        /// <summary>
        /// Work-denominated floor for resetting-window pools, in dispatches'
        /// worth of quota (e.g. 1 keeps headroom for one more dispatch).
        /// Competes with the percentage floor via maximum. Requires measured
        /// burn. Rejected on depleting-balance pools. Hot-reloadable.
        /// </summary>
        public double? MinQuotaItems { get; set; }
    }

    /// <summary>
    /// Declared quota refills that the provider probe cannot see until they fire.
    /// Used only by DeadlineAwareDrain.
    /// </summary>
    public sealed class QuotaRouterExpectedResetConfig
    {
        /// <summary>Explicit reset timestamps. Past values are ignored by the router.</summary>
        public List<DateTimeOffset> Timestamps { get; set; } = [];

        /// <summary>Recurring reset period in seconds. Requires <see cref="CadenceAnchor"/>.</summary>
        public int? CadenceSeconds { get; set; }

        /// <summary>Anchor timestamp for the recurring cadence.</summary>
        public DateTimeOffset? CadenceAnchor { get; set; }
    }

    /// <summary>
    /// One operator-supplied quota-failure pattern entry. Appended to a
    /// detector's built-in defaults; matched against stderr and stdout
    /// substring case-insensitively. Bound from
    /// <c>CodeyBox:QuotaFailurePatterns:&lt;agent-kind&gt;</c>.
    /// </summary>
    public sealed class QuotaFailurePatternOptions
    {
        /// <summary>The substring to search for in stderr/stdout.</summary>
        public string Pattern { get; set; } = string.Empty;
        /// <summary>How to classify the failure when the substring matches.</summary>
        public QuotaFailureKind Kind { get; set; } = QuotaFailureKind.LimitReached;
    }

    /// <summary>
    /// One operator-supplied provider-transient signature entry. Appended to
    /// the per-agent detector's built-in exact signatures and matched as a
    /// .NET regular expression (case-insensitive, singleline) against stderr,
    /// stdout, and the summary. Bound from
    /// <c>CodeyBox:ProviderTransientSignatures:&lt;agent-kind&gt;</c>.
    /// Patterns must name a multi-token provider diagnostic — never a bare
    /// word or status code — so model prose cannot match. Hot-reloaded: edits
    /// take effect without a restart.
    /// </summary>
    public sealed class ProviderTransientSignatureOptions
    {
        /// <summary>The .NET regular expression to match.</summary>
        public string Pattern { get; set; } = string.Empty;
        /// <summary>Which transient family to report on match.</summary>
        public ProviderTransientKind Kind { get; set; } = ProviderTransientKind.InfraTransport;
    }

    /// <summary>
    /// One operator-supplied auth/login-prompt pattern entry. Appended to the
    /// built-in defaults and matched case-insensitively against the configured
    /// stream. Bound from <c>CodeyBox:AuthFailurePatterns:&lt;agent-kind&gt;</c>.
    /// Defaults to stderr-only because stdout can contain model-controlled task
    /// text; stdout patterns should be narrowly formed CLI login transcripts.
    /// </summary>
    public sealed class AuthFailurePatternOptions
    {
        /// <summary>The substring to search for.</summary>
        public string Pattern { get; set; } = string.Empty;
        /// <summary>
        /// Stream to search. Defaults to stderr. Use Stdout or StderrAndStdout
        /// only for narrow CLI-auth transcript signatures.
        /// </summary>
        public AuthFailurePatternStream Stream { get; set; } = AuthFailurePatternStream.Stderr;
    }

    /// <summary>
    /// Pure conversion from operator-supplied
    /// <see cref="CodeyBoxOptions.AuthFailurePatterns"/> to a wired
    /// <see cref="IAgentAuthFailureClassifier"/>. Extracted from the DI factory
    /// so the binding shape (config section name, per-agent dictionary,
    /// pattern filtering, conversion to <see cref="AuthFailurePattern"/>) is
    /// reachable from unit tests without booting the full host — a bug in
    /// any of those steps would otherwise silently disable the operator's
    /// extensibility hook for new CLI login prompts.
    /// </summary>
    public static class AuthFailurePatternBinder
    {
        public static IAgentAuthFailureClassifier Build(CodeyBoxOptions options)
        {
            ArgumentNullException.ThrowIfNull(options);
            var extras = options.AuthFailurePatterns is null
                ? new Dictionary<string, IReadOnlyList<AuthFailurePattern>>(StringComparer.OrdinalIgnoreCase)
                : options.AuthFailurePatterns
                    .Where(kvp => !string.IsNullOrWhiteSpace(kvp.Key))
                    .ToDictionary(
                        kvp => kvp.Key,
                        kvp => (IReadOnlyList<AuthFailurePattern>)(kvp.Value ?? new List<AuthFailurePatternOptions>())
                            .Where(p => !string.IsNullOrWhiteSpace(p.Pattern))
                            .Select(p => new AuthFailurePattern(p.Pattern, p.Stream))
                            .ToArray(),
                        StringComparer.OrdinalIgnoreCase);
            return new AgentAuthFailureClassifier(extras);
        }
    }

    /// <summary>
    /// Pure conversion from operator-supplied
    /// <see cref="CodeyBoxOptions.ProviderTransientSignatures"/> to the
    /// hot-reloadable <see cref="ProviderTransientSignatureStore"/>. Extracted
    /// from the DI wiring so the binding shape (config section name,
    /// per-agent dictionary, pattern filtering) is reachable from unit tests
    /// without booting the full host.
    /// </summary>
    public static class ProviderTransientSignatureBinder
    {
        public static IReadOnlyDictionary<string, ProviderTransientSignature[]> Build(CodeyBoxOptions options)
        {
            ArgumentNullException.ThrowIfNull(options);
            if (options.ProviderTransientSignatures is null)
                return new Dictionary<string, ProviderTransientSignature[]>(StringComparer.OrdinalIgnoreCase);
            return options.ProviderTransientSignatures
                .Where(kvp => !string.IsNullOrWhiteSpace(kvp.Key))
                .ToDictionary(
                    kvp => kvp.Key,
                    kvp => (kvp.Value ?? new List<ProviderTransientSignatureOptions>())
                        .Where(p => p is not null && !string.IsNullOrWhiteSpace(p.Pattern))
                        .Select(p => new ProviderTransientSignature(p.Pattern.Trim(), p.Kind))
                        .ToArray(),
                    StringComparer.OrdinalIgnoreCase);
        }

        public static void SyncStore(CodeyBoxOptions options)
        {
            ArgumentNullException.ThrowIfNull(options);
            ProviderTransientSignatureStore.SyncAgents(
                Build(options).ToDictionary(
                    kvp => kvp.Key,
                    kvp => (IEnumerable<ProviderTransientSignature>?)kvp.Value,
                    StringComparer.OrdinalIgnoreCase));
        }

        /// <summary>
        /// Reload-safe <see cref="SyncStore"/> wrapper: invalid operator
        /// patterns keep the prior live table (the sync is atomic) and report
        /// the rejection instead of throwing through the options-refresh
        /// pipeline, which would disturb every other re-bound section.
        /// Startup still fails loudly through
        /// <see cref="CodeyBoxOptionsValidator"/>.
        /// </summary>
        public static bool TrySyncStore(CodeyBoxOptions options, out string? error)
        {
            ArgumentNullException.ThrowIfNull(options);
            try
            {
                SyncStore(options);
                error = null;
                return true;
            }
            catch (ArgumentException ex)
            {
                error = ex.Message;
                return false;
            }
        }
    }

    /// <summary>
    /// Top-level score-modifier config. Bound from <c>CodeyBox:AgentScoreModifiers</c>.
    /// </summary>
    public sealed class AgentScoreModifiersOptions
    {
        /// <summary>Time-of-day modifier entries.</summary>
        public List<TimeOfDayModifierOptions> ByTimeOfDay { get; set; } = [];
    }

    /// <summary>One time-of-day modifier entry.</summary>
    public sealed class TimeOfDayModifierOptions
    {
        /// <summary>Agent kind value, e.g. "claude".</summary>
        public string Agent { get; set; } = string.Empty;
        /// <summary>
        /// Score delta applied during matching windows. Negative values reduce
        /// effective score; positive values increase it. Bounded to ±5 at startup.
        /// </summary>
        public int Modifier { get; set; }
        /// <summary>Human annotation for config readability; not used at runtime.</summary>
        public string? Comment { get; set; }
        /// <summary>Windows during which the modifier is active.</summary>
        public List<TimeWindowOptions> Windows { get; set; } = [];
    }

    /// <summary>A single UTC time window within a week.</summary>
    public sealed class TimeWindowOptions
    {
        /// <summary>Three-letter day codes: Mon, Tue, Wed, Thu, Fri, Sat, Sun.</summary>
        public List<string> Days { get; set; } = [];
        /// <summary>Window start time in HH:mm UTC (inclusive).</summary>
        public string StartUtc { get; set; } = "00:00";
        /// <summary>Window end time in HH:mm UTC (exclusive). Wrap-around is supported (e.g. 22:00–02:00).</summary>
        public string EndUtc { get; set; } = "00:00";
    }

    /// <summary>
    /// Per-endpoint webhook options, bound from the CodeyBox:Webhooks config array.
    /// </summary>
    public sealed class WebhookEndpointOptions
    {
        public string Name { get; set; } = string.Empty;
        public string Url { get; set; } = string.Empty;
        public string? SecretEnvVar { get; set; }
        public List<string> EventFilter { get; set; } = [];
        public int MaxAttempts { get; set; } = 3;
        public int InitialBackoffSeconds { get; set; } = 1;
        public int TimeoutSeconds { get; set; } = 10;
    }

    /// <summary>
    /// In-process event broadcaster configuration. Drives both the SSE
    /// endpoints' Last-Event-ID replay and the per-work-item ring buffer
    /// size used to feed reconnecting clients.
    /// </summary>
    public sealed class WebhookEventBusOptions
    {
        /// <summary>
        /// Number of recent events retained per work item (and globally)
        /// for SSE Last-Event-ID resume. Older events are evicted FIFO.
        /// </summary>
        public int RingBufferCapacity { get; set; } = 1000;

        /// <summary>
        /// How often the SSE handler emits a ':keepalive' comment when the
        /// stream is otherwise idle. Default 15s — half of AWS ALB's 60s
        /// idle timeout, so proxies don't reap connections that are simply
        /// not transmitting events.
        /// </summary>
        public int HeartbeatSeconds { get; set; } = 15;
    }

    /// <summary>
    /// Rolling file log configuration. Paths are resolved relative to the
    /// API process's working directory when they are not absolute.
    /// See <c>docs/operating/logging.md</c> for details.
    /// </summary>
    public sealed class AuditLogOptions
    {
        /// <summary>
        /// Path template for the main rolling log (all severity levels).
        /// Default: <c>logs/codeybox-.json</c> — the date is inserted before
        /// the trailing dot by Serilog's file sink.
        /// </summary>
        public string Path { get; set; } = "logs/codeybox-.json";

        /// <summary>
        /// Path template for the audit-only rolling log (<c>Audit=true</c>
        /// events only). Default: <c>logs/audit-.json</c>.
        /// </summary>
        public string AuditPath { get; set; } = "logs/audit-.json";

        /// <summary>Days of rolled files to keep. Must be >= 1. Default: 30.</summary>
        public int RetainedDays { get; set; } = 30;

        /// <summary>Per-file size cap before rolling. Default: 100 MiB.</summary>
        public long MaxFileSizeBytes { get; set; } = 100 * 1024 * 1024;

        /// <summary>
        /// Rolling file sink for the orchestrator's plain-text console stream
        /// (the same lines Serilog writes to stdout). Enabled by default so the
        /// process bounds its own run-log retention instead of relying on an
        /// external shell-redirect (which historically grew without bound).
        /// </summary>
        public ConsoleLogOptions ConsoleLog { get; set; } = new();
    }

    /// <summary>
    /// Configuration for the rolling console / run-log sink. The default
    /// settings keep ~14 rolled files of up to 100 MiB each (≈ 1.4 GiB peak
    /// disk) and roll on both calendar day and size; disable by setting
    /// <c>Enabled=false</c> if the operator manages run-log capture out of
    /// process. <see cref="RetainedFileCountLimit"/> and
    /// <see cref="MaxFileSizeBytes"/> are re-read on every write, so edits
    /// hot-reload without a restart; only <see cref="Path"/> is pinned at
    /// startup.
    /// </summary>
    public sealed class ConsoleLogOptions
    {
        /// <summary>
        /// Toggle for the rolling run-log file sink. Stdout/console output is
        /// unaffected — turning this off only stops writing the duplicate
        /// rolling file.
        /// </summary>
        public bool Enabled { get; set; } = true;

        /// <summary>
        /// Path template for the rolling run log. The sink inserts the UTC date
        /// before the trailing dot (e.g. <c>codeybox-console-20260618.log</c>).
        /// Relative paths resolve from the process working directory. Pinned
        /// at startup (not hot-reloadable).
        /// </summary>
        public string Path { get; set; } = "logs/codeybox-console-.log";

        /// <summary>
        /// Total number of rolled files to retain across all dates / size
        /// segments. Counted-by-file (not by day) so the cap holds even when
        /// size rolling produces several segments in a single day, and so the
        /// total footprint stays bounded at
        /// <c>RetainedFileCountLimit x MaxFileSizeBytes</c> regardless of write
        /// rate. Retention also evicts by bytes, so oversized segments
        /// inherited from older settings age out until the bound holds again.
        /// Must be >= 1. Default: 14. Hot-reloadable.
        /// </summary>
        public int RetainedFileCountLimit { get; set; } = 14;

        /// <summary>
        /// Per-file size cap before rolling to a new segment. Combined with
        /// the day boundary, this is what actually keeps individual files
        /// readable with tail / less. It also caps each individual log record:
        /// a record that would not fit is truncated (with a marker) rather
        /// than written whole, which is what keeps the total footprint bound
        /// exact. Must be >= 1 MiB. Default: 100 MiB.
        /// Hot-reloadable.
        /// </summary>
        public long MaxFileSizeBytes { get; set; } = 100 * 1024 * 1024;
    }
}

// Exposed for WebApplicationFactory<Program> in integration tests.
public partial class Program
{
    internal static ReloadableSandboxProvider BuildReloadableSandboxProvider(
        IServiceProvider sp,
        ILoggerFactory loggerFactory)
    {
        var options = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>();
        var multipassBaselineNamespace = new MultipassSandboxOptions();
        // Active-sandbox tracking (_activeNames / _activeOwners) lives inside
        // each provider instance, so every construction path must share ONE
        // instance per backend kind. A second IncusSandboxProvider built here
        // lists placement-created sandboxes as untracked while they are still
        // mid-phase (same backend Name, so the lifecycle composite dedupes the
        // instance the placement path actually owns) — the leak reaper then
        // destroys live VMs. The registry is the single construction
        // authority; the router borrows its per-kind instances rather than
        // building twins.
        return new ReloadableSandboxProvider(
            () => options.CurrentValue.SandboxProvider ?? string.Empty,
            () => options.CurrentValue.SandboxProviderCutover?.RetainedInventoryProviders ?? [],
            [
                new ReloadableSandboxProvider.ProviderRegistration(
                    SandboxProviderKinds.Multipass,
                    () => sp.GetRequiredService<ISandboxProviderRegistry>().EnsureKind(SandboxProviderKinds.Multipass),
                    baselineRef => MultipassSandboxProvider.IsOwnedBaselineRef(
                        multipassBaselineNamespace,
                        baselineRef)),
                new ReloadableSandboxProvider.ProviderRegistration(
                    SandboxProviderKinds.Incus,
                    () => sp.GetRequiredService<ISandboxProviderRegistry>().EnsureKind(SandboxProviderKinds.Incus),
                    IncusSandboxProvider.IsRoutableBaselineRef),
            ],
            loggerFactory.CreateLogger<ReloadableSandboxProvider>());
    }

    internal static CompositeManagedSandboxProvider BuildManagedSandboxLifecycleProvider(IServiceProvider sp)
    {
        var singleton = sp.GetRequiredService<ISandboxProvider>();
        var providers = new List<IManagedSandboxLifecycle> { singleton };
        // Touch the catalog first: snapshot construction warms every configured
        // provider kind into the registry, so the registry snapshot below covers
        // the members placement can actually select. Registry-built providers
        // would otherwise be invisible to the leak reaper and operator dispose
        // endpoints whenever the pipeline — rather than the legacy singleton —
        // created the sandbox. Entries whose backend is already covered (same
        // provider name as an earlier entry — e.g. the registry's plain
        // multipass behind the singleton's reloadable multipass router) are
        // skipped: same backend means identical inventory, and listing it twice
        // would make name-based disposal ambiguous.
        _ = sp.GetRequiredService<SandboxClassesSnapshot>();
        var seenNames = new HashSet<string>(providers.Select(static p => p.Name), StringComparer.Ordinal);
        foreach (var registration in sp.GetRequiredService<ISandboxProviderRegistry>().ListRegistered())
        {
            if (seenNames.Add(registration.Provider.Name))
                providers.Add(registration.Provider);
        }
        var e2eManaged = sp.GetRequiredService<IE2eExecutionPool>() is IManagedSandboxProviderSource source
            ? source.ManagedSandboxProviders.ToArray()
            : [];
        providers.AddRange(e2eManaged);
        // Leak-sweep inventory scope: a registered provider no sandbox class
        // member references is skipped by default — an unused backend (e.g. a
        // configured-but-unselected remote pool) is never listed and can never
        // block disposal of other providers' leaks. The primary singleton and
        // the E2E managed sources are always inventoried; everything else must
        // be named by a member's provider kind (or opted back in via
        // CodeyBox:SandboxLeak:InventoryUnreferencedProviders, e.g. while
        // draining a decommissioned backend). Evaluated live so catalog
        // hot-reloads take effect on the next sweep without a restart.
        bool ShouldInventory(IManagedSandboxLifecycle lifecycle)
        {
            if (ReferenceEquals(lifecycle, singleton))
                return true;
            foreach (var managed in e2eManaged)
            {
                if (ReferenceEquals(managed, lifecycle))
                    return true;
            }
            var leakOptions = sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.SandboxLeak;
            if (leakOptions.InventoryUnreferencedProviders)
                return true;
            foreach (var sandboxClass in sp.GetRequiredService<SandboxClassesSnapshot>().Current)
            {
                foreach (var member in sandboxClass.Members)
                {
                    if (string.Equals(member.ProviderKind, lifecycle.Name, StringComparison.OrdinalIgnoreCase))
                        return true;
                }
            }
            return false;
        }
        return new CompositeManagedSandboxProvider(
            providers,
            ShouldInventory,
            () => sp.GetRequiredService<IOptionsMonitor<CodeyBoxOptions>>().CurrentValue.SandboxLeak,
            sp.GetService<ILogger<CompositeManagedSandboxProvider>>()
                ?? NullLogger<CompositeManagedSandboxProvider>.Instance,
            TimeProvider.System);
    }

    /// <summary>
    /// Enforces the changelog webhook secret requirement at startup.
    /// Changelog automation is opt-in: when disabled, no secret is required.
    /// When enabled without a secret, Development logs a warning while other
    /// environments fail fast so an enabled webhook endpoint can never run
    /// without HMAC signature verification.
    /// </summary>
    /// <param name="configuration">Application configuration.</param>
    /// <param name="environment">Host environment.</param>
    /// <exception cref="InvalidOperationException">
    /// Thrown when changelog automation is enabled without
    /// <c>CodeyBox:Changelog:GitHubWebhookSecretEnvVar</c> outside Development.
    /// </exception>
    internal static void ValidateChangelogWebhookConfiguration(
        IConfiguration configuration, IHostEnvironment environment)
    {
        ArgumentNullException.ThrowIfNull(configuration);
        ArgumentNullException.ThrowIfNull(environment);

        // Bind through ChangelogOptions so the Enabled default lives in exactly
        // one place (the property initializer).
        var bound = configuration.GetSection("CodeyBox:Changelog").Get<ChangelogOptions>()
            ?? new ChangelogOptions();
        if (!bound.Enabled || !string.IsNullOrEmpty(bound.GitHubWebhookSecretEnvVar))
            return;

        if (environment.IsDevelopment())
        {
            Log.Warning(
                "CodeyBox:Changelog:GitHubWebhookSecretEnvVar is not configured. " +
                "GitHub release webhooks will be rejected with 401 until a secret is set. " +
                "This is a configuration error in non-Development environments.");
            return;
        }

        throw RequiredConfigurationValidator.CreateAggregateException(
            configuration,
            environment,
            RequiredConfigurationValidator.ChangelogSecretMessage);
    }

    /// <summary>
    /// Resolve <c>HostOptions.ShutdownTimeout</c> from operator config, the
    /// resolved provider's suspend capability, and the hot-reloadable teardown
    /// mode.
    /// Shutdown:GraceSeconds bounds the normal request-drain / preempt-checkpoint
    /// window. Suspend-capable providers keep a conservative ceiling because
    /// <c>Shutdown.SandboxTeardownMode</c> is read through
    /// <c>IOptionsMonitor</c> when shutdown begins, while
    /// <c>HostOptions.ShutdownTimeout</c> is captured once at startup. An
    /// operator can therefore hot-reload Stop/Dispose to Suspend immediately
    /// before stopping the process, and the host must still have enough time to
    /// finish writing each VM's RAM snapshot (the RAM-scaled
    /// <see cref="SuspendTimeoutPolicy"/> budget — 30 min for the default 12 GiB
    /// VM) and drains in parallel batches, so a deployment with more in-flight
    /// VMs than the batch cap spans <c>ceil(N/batch)</c> sequential waves. The
    /// ceiling must cover the slowest wave-chain PLUS the post-suspend drain
    /// grace (suspend runs in StoppingAsync, the preempt-checkpoint /
    /// listener-drain window runs after), not one VM, or the host SIGKILLs us
    /// mid-snapshot on a later wave or mid-drain.
    /// ShutdownTimeout is a CEILING, not a fixed wait: a shutdown with
    /// nothing to suspend still returns as soon as every hosted service's
    /// StoppingAsync completes, so raising it only affects the suspend case.
    ///
    /// <para>The concurrent-sandbox bound is resolved through
    /// <see cref="OrchestratorOptionsFactory.ResolveSandboxCounts"/> — the same
    /// precedence/defaulting path the admission-control decorator uses for
    /// <c>WorkerPool:MaxConcurrentSandboxes</c> — so the shutdown reserve matches
    /// the actual live-VM ceiling. It deliberately skips the startup range
    /// rejection: the ceiling must stay computable for any stored config, while
    /// the startup DI path still fails fast on unsatisfiable values. All VMs are provisioned at
    /// <see cref="SandboxResourceLimits.Default"/> (no per-VM RAM override is
    /// wired through SandboxSpec today), so the default profile RAM is the
    /// largest per-VM suspend budget the host must cover.</para>
    /// </summary>
    internal static TimeSpan ComputeHostShutdownTimeout(
        CodeyBoxOptions cbOpts, bool providerSupportsSuspend, ILogger log)
    {
        var grace = TimeSpan.FromSeconds(Math.Max(1, cbOpts.Shutdown.GraceSeconds));
        var maxConcurrent = OrchestratorOptionsFactory
            .ResolveSandboxCounts(cbOpts.Concurrency, cbOpts.WorkerPool, log)
            .MaxConcurrentSandboxes;
        return SuspendTimeoutPolicy.ResolveHostShutdownTimeout(
            providerSupportsSuspend, grace, maxConcurrent);
    }

    internal static TimeSpan ComputeOrchestratorShutdownDrainTimeout(int graceSeconds)
    {
        var grace = TimeSpan.FromSeconds(Math.Max(1, graceSeconds));
        var reserve = grace >= TimeSpan.FromSeconds(10)
            ? TimeSpan.FromSeconds(5)
            : TimeSpan.FromMilliseconds(Math.Max(100, grace.TotalMilliseconds * 0.2));
        var drain = grace - reserve;
        return drain > TimeSpan.Zero ? drain : TimeSpan.FromMilliseconds(100);
    }

    internal static SandboxStartupResumeOptions BuildSandboxStartupResumeOptions(
        ShutdownOptions shutdown)
    {
        ArgumentNullException.ThrowIfNull(shutdown);

        return new SandboxStartupResumeOptions
        {
            Mode = shutdown.SandboxResumeMode == SandboxResumeMode.Blocking
                ? SandboxStartupResumeMode.Blocking
                : SandboxStartupResumeMode.Background,
            ResumeTimeout = shutdown.SandboxResumeTimeout,
            AdoptionDeadline = TimeSpan.FromSeconds(shutdown.SandboxAdoptionDeadlineSeconds),
        };
    }

    /// <summary>
    /// Live per-provider options accessor for an inbound interaction
    /// verifier: the verifier reads current options per call through the
    /// monitor, so hot-reloaded configuration takes effect without a
    /// restart.
    /// </summary>
    internal static Func<InteractionProviderOptions?> InteractionProviderOpts(
        IServiceProvider sp, string providerName)
    {
        var monitor = sp.GetRequiredService<IOptionsMonitor<InteractionsOptions>>();
        return () => monitor.CurrentValue.Providers.FirstOrDefault(p =>
            string.Equals(p.Provider, providerName, StringComparison.OrdinalIgnoreCase));
    }

    /// <summary>
    /// Runs the application host, resolving and capturing the
    /// <see cref="BackgroundServiceFailureTracker"/> singleton before the host
    /// executes. When <see cref="IHost.Run"/> returns, the service provider
    /// is already disposed; inspecting the pre-resolved tracker avoids an
    /// <see cref="ObjectDisposedException"/> on shutdown and maps a recorded
    /// background-service fault to a non-zero process exit code.
    /// </summary>
    /// <param name="host">The host to run.</param>
    internal static void RunHost(IHost host)
    {
        ArgumentNullException.ThrowIfNull(host);

        // Pre-resolve tracker while host.Services is alive. host.Run()
        // disposes the host (and its container) before returning.
        var failureTracker = host.Services.GetService<BackgroundServiceFailureTracker>();

        try
        {
            host.Run();

            // StopHost maps a BackgroundService fault to a graceful host shutdown,
            // which would otherwise exit 0 exactly like an intentional stop. A
            // recorded fault means the orchestrator died (e.g. sustained SQLite
            // write-gate outage); exit non-zero so supervisors detect and restart.
            if (failureTracker?.Fault is not null)
            {
                Log.Error(
                    failureTracker.Fault,
                    "Host stopped after a background service fault; exiting non-zero");
                Environment.ExitCode = BackgroundServiceFailureTracker.ResolveExitCode(backgroundServiceFaulted: true);
            }
        }
        catch (Exception ex)
        {
            Log.Fatal(ex, "Host terminated unexpectedly");
            throw;
        }
        finally
        {
            Log.CloseAndFlush();
        }
    }
}