Add a config-push/rollout-control write path to fleet analytics

[JSONbored]

Problem: The existing fleet-analytics ingest pipeline is read-only telemetry aggregation today — there's no way to push configuration changes or rollout instructions back to individual instances through it.

Area: ORB / Fleet ops

Proposal: Add a write path (config push, rollout targeting) to the existing fleet infrastructure rather than building a second, parallel system.

Deliverables:

• A working config-push path built on the existing fleet-analytics infrastructure.

[linear-code]

JSO-3562

[JSONbored]

Design pass before implementation (per request) — reading the actual ingest/relay/broker code changed which existing infrastructure this should build on, and surfaced a trust-boundary question worth deciding explicitly before any code lands.

Finding 1: "fleet analytics" is the wrong infrastructure to extend — the relay/broker pipeline is the right one

The issue's title points at fleet-analytics (POST /v1/orb/ingest, orb_signals/orb_instances, GET /v1/internal/fleet/analytics), but that pipeline is structurally unsuited to a write/push channel:

• POST /v1/orb/ingest's auth (isAuthorizedOrbIngest) is a single shared bearer token, fail-open when unset — every sender uses the same credential. The instance_id in the payload is a self-reported hash the server never verifies against anything (src/selfhost/orb-collector.ts's instanceId(secret), upserted as-is into orb_instances). There is no way to reliably address one specific instance through this pipe — anyone who knows or guesses an instance_id can claim it.
• The response is { accepted: number } | { error: string } — an ack only. The self-host sender (exportOrbBatch) never even reads the response body today, so "add a payload to the ingest response" would need new client-side wiring too, not just a server-side change.

The relay/broker pipeline (orb_relay_pending table + POST /v1/orb/relay/pull, src/orb/relay.ts) is the right fit instead:

• Real per-instance-adjacent auth: a hashed enrollment secret bound server-side to an installation_id at issue time (orb_enrollments.secret_hash), not a shared token.
• Self-host containers using pull mode are already polling this endpoint periodically (draining GitHub webhook events) — a config-push message can ride the same poll loop with zero new client-side polling infrastructure.
• The table shape (delivery_id, installation_id, event_name, raw_body, created_at) is close to generic already; event_name isn't DB-enforced to any enum.

Reusing this satisfies "rather than building a second, parallel system" — just not the system the issue's title names. Building on orb_instances/ingest instead would mean actually building a second, parallel (and less secure) delivery mechanism next to the one that already exists and already has the right trust properties.

Finding 2: a real trust-boundary question needs deciding before any payload design

Self-host today owns its own settings entirely — resolveRepositorySettings always reads the instance's own local DB, and .loopover.yml is fetched by each instance directly from GitHub. There is no existing precedent anywhere in this codebase for "central mutates a remote self-host's behavior." That's not an oversight to fix — it's the operator-sovereignty model this whole config-as-code system (.loopover.yml > DB > defaults) is built on.

So "config push" needs a scope decision: is this for Orb's own operational state, or for a self-hoster's product configuration (gate settings, review policy)? I'd recommend restricting v1 to the former — things Orb itself already legitimately coordinates (enrollment lifecycle, opt-in capability announcements, deprecation notices) — and explicitly NOT auto-applying anything that would silently override an operator's own .loopover.yml/DB settings. If a "recommended default" use case is wanted later, it should land as a new, lowest-priority layer below today's built-in safe defaults (never above DB or config-as-code), advisory-only, surfaced to the operator rather than auto-applied. Flagging this as the one decision in this design that materially changes scope depending on the answer.

Concrete shape (scoped to Orb-operational pushes, per the above)

• Migration: add kind TEXT NOT NULL DEFAULT 'github_webhook' to orb_relay_pending — the column doesn't exist today (only event_name, free-text, currently always a GitHub webhook event name). A real discriminator instead of overloading event_name with a namespaced string.
• Enqueue side: a new internal-only write path (requireAppRole(..., ["operator"])-gated, mirroring the kill-switch endpoint's auth shape) that inserts one orb_relay_pending row per targeted installation_id with kind = 'config_push' and a typed raw_body (e.g. { pushId, message, capability?, deprecatesAt? }).
• Consumption side: src/server.ts's pull-drain loop currently funnels every drained row straight into enqueueWebhookByEnv, which unconditionally does JSON.parse(rawBody) as GitHubWebhookPayload. This needs a branch on kind before that call — route config_push rows to a new, small handler instead of the GitHub-webhook queue. This is the one piece of "real work," not just plumbing.
• Targeting granularity — a known, accepted limitation: the queue is installation_id-scoped, not per-container. One installation can have multiple enrolled containers today (orb_enrollments.installation_id has no uniqueness constraint — see the existing #1783 tie-break comment in relay.ts) with no way to route a specific container's pull separately. Building real per-container addressing now would be scope creep ahead of real demand (nothing in the codebase suggests multi-container-per-installation is an actual current pattern rather than a schema accident). Recommend accepting installation-level targeting for v1 and revisiting only if that assumption turns out wrong.
• "Rollout targeting" — start with an explicit target list, not a rollout engine: there is no percentage/canary/gradual-enable primitive anywhere in this codebase to build on, and orb_instances.last_seen_at (the one recency signal that exists) lives in the other, disjoint identity space (ingest's instance_id, not orb_enrollments.installation_id) with no join between the two today. A v1 "rollout" should mean an operator supplying an explicit list of installation_ids to target, not a generic percentage selector — that's real scope, not a shortcut, and avoids building rollout-percentage machinery speculatively.

Suggested breakdown for follow-up issues (mirroring how the ORB/AMS hosting plan got split earlier)

1. Migration + enqueueConfigPush/typed payload + internal write endpoint (operator-gated, explicit target list).
2. Self-host consumption: kind-based dispatch in the pull-drain loop, a config_push handler distinct from enqueueWebhookByEnv.
3. Whatever the handler actually does with a received push — scoped separately once (1) and (2) exist, since "receive and surface a notice to the operator" and "receive and act on a capability toggle" are different amounts of work and shouldn't block on each other.

Not implementing this now, per the ask — this is the design/plan deliverable. Each of the three pieces above is small and independently one-shot-PR-sized once someone picks it up.