feat(orb): make fleet telemetry always-on; key anonymization off the App secret

Remove the ORB_ENABLED opt-in — Orb fleet-calibration export is now ALWAYS ON (the contract of
self-hosting gittensory). It self-gates on a configured GitHub App webhook secret (no App → no review
data to export anyway) and uses that secret (GITHUB_WEBHOOK_SECRET) as the per-instance anonymization
key, so there is no separate ORB_WEBHOOK_SECRET to set. ORB_AIR_GAP stays for air-gapped/offline
deployments only.

.env.example now carries a prominent TELEMETRY NOTICE: running the self-host image contributes
anonymized, on-by-default calibration data. repo/PR identifiers are HMAC'd with the instance's own
secret (the collector can never de-anonymize them) and no code / PII / repo names / commit SHAs are sent.

Author: JSONbored

.env.example

@@ -161,19 +161,18 @@ GITTENSORY_REVIEW_DRAFT=false
 #                                            #   1024-dimensional (e.g. bge-m3 or mxbai-embed-large via Ollama).
 #                                            #   Used only when RAG is enabled (GITTENSORY_REVIEW_RAG + allowlist).
 
-# --- Gittensory Orb (#1255; opt-in fleet-calibration export) ---
-# Orb is the central collector + analytics that aggregates anonymized gate-calibration data UP from
-# self-hosted instances. There is NO separate Orb GitHub App and NO setup wizard: your existing main App
-# already records de-noised outcomes (merged/closed + reversals) locally — flip ORB_ENABLED to ship an
-# anonymized signal to gittensory's collector. That's it: no second App, no extra secret, no wizard.
+# --- Gittensory Orb (#1255; ALWAYS-ON fleet-calibration telemetry) ---
+# TELEMETRY NOTICE: running this self-hosted image contributes anonymized gate-calibration data to
+# gittensory's central collector. This is ON BY DEFAULT and has no opt-out flag — it is part of the
+# self-hosting contract: install the GitHub App, and your instance reports fleet-calibration signal so the
+# gate can be tuned from real outcomes across all self-hosters. It activates automatically once your App is
+# configured (no App = nothing is sent). There is NO separate Orb App and NO setup wizard.
 #
-# SECURITY MODEL (this image is self-hosted by many independent maintainers):
-#   • The image bakes NO secrets. repo/PR identifiers are HMAC-anonymized with YOUR own ORB_WEBHOOK_SECRET
-#     (a stable per-instance string), so even gittensory (running the collector) can never de-anonymize them.
-#   • Export carries NO shared key. The collector accepts the batch as untrusted, rate-limited, aggregate-only
-#     telemetry. Nothing in the container, if leaked, can compromise the collector, other operators, or any App.
-# ORB_ENABLED=false                          # master switch: set to true to export fleet-calibration signal (default off)
-# ORB_WEBHOOK_SECRET=<stable-random-string>  # the per-instance HMAC key used to anonymize repo/PR identifiers
-# ORB_AIR_GAP=false                          # set to true to compute locally but never send to the collector
+# WHAT IS SENT (per resolved PR, hourly): the gate verdict, the realized outcome (merged/closed), a reversal
+# flag, a bucketed reason category, and cycle time. NEVER sent: repo/owner/PR names, commit SHAs, code,
+# diffs, comments, or logins. Repo/PR identifiers are HMAC-anonymized with YOUR OWN GitHub App webhook
+# secret (GITHUB_WEBHOOK_SECRET), so even gittensory (running the collector) can never de-anonymize them.
+# The export carries no shared key; the collector treats it as untrusted, rate-limited, aggregate-only data.
+# ORB_AIR_GAP=false                          # air-gapped/OFFLINE deployments only: compute locally, never send
 # ORB_ANONYMIZE=true                         # HMAC-hash repo/PR before export (default true; false = raw names)
 # ORB_COLLECTOR_URL=https://gittensory-api.aethereal.dev/v1/orb/ingest  # gittensory's hosted collector (default; override for your own)

src/selfhost/orb-collector.ts

@@ -3,9 +3,11 @@
 // engine's outcomes-wire. This ships an anonymized, reversal-aware signal UP to gittensory's central
 // collector so the gate can be calibrated across the whole self-host fleet.
 //
-//   ORB_ENABLED=true          — activates export (off by default)
+// Export is ALWAYS ON once the GitHub App is configured (the fleet-telemetry contract of self-hosting) —
+// there is no opt-out flag. It self-gates on a configured App webhook secret (no App → no review data to
+// export anyway), and uses that secret as the per-instance anonymization key.
 //   ORB_COLLECTOR_URL=<url>   — endpoint (default: gittensory's hosted collector)
-//   ORB_AIR_GAP=true          — keep everything local, never send externally
+//   ORB_AIR_GAP=true          — air-gapped/offline deployments only: compute locally, never send
 //   ORB_ANONYMIZE=true        — HMAC-hash repo/PR before export (default: true)
 //
 // No diffs, no code, no comments, no logins, no commit SHAs — only verdict + outcome + reversal + a bucketed
@@ -69,12 +71,6 @@ export function bucketReasonCode(summary: string | null | undefined): string {
   return "other";
 }
 
-/** Returns true only when Orb export is explicitly enabled. */
-export function orbEnabled(): boolean {
-  const v = (process.env.ORB_ENABLED ?? "").toLowerCase();
-  return v === "true" || v === "1" || v === "yes";
-}
-
 // Latest gate_decision + latest pr_outcome per target_id, plus any reversal — portable (window functions +
 // CASE, no SQLite-only bare-column-with-MAX) so it runs on the self-host SQLite OR Postgres backend.
 const FLEET_QUERY = `
@@ -122,17 +118,18 @@ function cycleTimeMs(decidedAt: string, outcomeAt: string): number | null {
 
 /**
  * Export newly-resolved PR outcomes (since this instance's watermark) to the central collector. Reads from
- * review_audit (de-noised, reversal-aware), anonymizes, signs, POSTs, then advances the cursor.
- * Returns the number of events exported (0 if air-gap, disabled, or nothing new).
+ * review_audit (de-noised, reversal-aware), anonymizes, signs, POSTs, then advances the cursor. Always on.
+ * Returns the number of events exported (0 if air-gapped, the App isn't configured, or nothing new).
  */
 export async function exportOrbBatch(db: D1Database, batchSize = 200, fetchFn: typeof fetch = fetch): Promise<number> {
-  if (!orbEnabled()) return 0;
+  // Always on (no opt-out). Air-gapped/offline deployments may suppress the outbound call.
   if ((process.env.ORB_AIR_GAP ?? "").toLowerCase() === "true") return 0;
 
   // gittensory's hosted collector. No shared secret is sent: repo/PR identifiers are HMAC'd with THIS
-  // instance's own ORB_WEBHOOK_SECRET, and the collector accepts the batch as untrusted, rate-limited telemetry.
+  // instance's OWN GitHub App webhook secret, so the collector can never de-anonymize them.
   const collectorUrl = process.env.ORB_COLLECTOR_URL ?? "https://gittensory-api.aethereal.dev/v1/orb/ingest";
-  const secret = process.env.ORB_WEBHOOK_SECRET ?? "";
+  const secret = process.env.GITHUB_WEBHOOK_SECRET ?? "";
+  if (!secret) return 0; // App not configured yet — no anonymization key, and no review data to export
   const anonymize = (process.env.ORB_ANONYMIZE ?? "true").toLowerCase() !== "false";
   const instance = instanceId();
 

src/server.ts

@@ -14,7 +14,7 @@ import worker from "./index";
 import { processJob } from "./queue/processors";
 import { createSelfHostAi } from "./selfhost/ai";
 import { credentialsToEnv, exchangeManifestCode, renderSetupPage } from "./selfhost/setup-wizard";
-import { orbEnabled, exportOrbBatch } from "./selfhost/orb-collector";
+import { exportOrbBatch } from "./selfhost/orb-collector";
 import { createD1Adapter, nodeSqliteDriver } from "./selfhost/d1-adapter";
 import { readiness } from "./selfhost/health";
 import { gauge, incr, renderMetrics } from "./selfhost/metrics";
@@ -285,16 +285,14 @@ async function main(): Promise<void> {
     );
   }, intervalMs);
 
-  // Orb hourly export — batch-send pending outcome signals to the central collector.
-  // No-op when ORB_ENABLED is not set or ORB_AIR_GAP=true.
-  if (orbEnabled()) {
-    const runExport = () =>
-      exportOrbBatch(backend.db)
-        .then((n) => { if (n > 0) console.log(JSON.stringify({ event: "selfhost_orb_export", exported: n })); })
-        .catch(() => undefined);
-    void runExport(); // flush any pending events from a previous run at startup
-    setInterval(runExport, 3_600_000); // then hourly
-  }
+  // Orb fleet-telemetry export — ALWAYS ON (the fleet-calibration contract of self-hosting). Self-gates
+  // inside exportOrbBatch: a no-op until the GitHub App is configured, or when ORB_AIR_GAP=true.
+  const runOrbExport = () =>
+    exportOrbBatch(backend.db)
+      .then((n) => { if (n > 0) console.log(JSON.stringify({ event: "selfhost_orb_export", exported: n })); })
+      .catch(() => undefined);
+  void runOrbExport(); // flush any pending events at startup
+  setInterval(runOrbExport, 3_600_000); // then hourly
 
   // Graceful shutdown: stop accepting HTTP, let the queue finish, close the backend.
   let shuttingDown = false;

test/unit/selfhost-orb-collector.test.ts

@@ -1,7 +1,7 @@
 import { DatabaseSync } from "node:sqlite";
 import { describe, expect, it, beforeEach, afterEach } from "vitest";
 import { createD1Adapter, nodeSqliteDriver } from "../../src/selfhost/d1-adapter";
-import { bucketReasonCode, exportOrbBatch, orbEnabled } from "../../src/selfhost/orb-collector";
+import { bucketReasonCode, exportOrbBatch } from "../../src/selfhost/orb-collector";
 import { resetMetrics, renderMetrics } from "../../src/selfhost/metrics";
 
 /** In-memory DB with the review_audit + orb_export_cursor tables the exporter reads. */
@@ -44,32 +44,25 @@ describe("bucketReasonCode()", () => {
   });
 });
 
-describe("orbEnabled()", () => {
-  afterEach(() => { delete process.env.ORB_ENABLED; });
-  it("true only for truthy values", () => {
-    for (const v of ["true", "1", "Yes"]) { process.env.ORB_ENABLED = v; expect(orbEnabled()).toBe(true); }
-    for (const v of ["", "false", "no"]) { process.env.ORB_ENABLED = v; expect(orbEnabled()).toBe(false); }
-    delete process.env.ORB_ENABLED; expect(orbEnabled()).toBe(false);
-  });
-});
-
-describe("exportOrbBatch() — reads review_audit, ships anonymized reversal-aware signal", () => {
+describe("exportOrbBatch() — always-on; reads review_audit, ships anonymized reversal-aware signal", () => {
   beforeEach(() => {
     resetMetrics();
-    process.env.ORB_ENABLED = "true";
-    process.env.ORB_WEBHOOK_SECRET = "test-secret";
+    process.env.GITHUB_WEBHOOK_SECRET = "test-secret"; // the App secret doubles as the anonymization key
     process.env.ORB_APP_ID = "555";
     process.env.ORB_ANONYMIZE = "true";
     delete process.env.ORB_AIR_GAP;
     delete process.env.ORB_COLLECTOR_URL;
   });
   afterEach(() => {
-    for (const k of ["ORB_ENABLED", "ORB_WEBHOOK_SECRET", "ORB_APP_ID", "ORB_ANONYMIZE", "ORB_AIR_GAP", "ORB_COLLECTOR_URL", "GITHUB_APP_ID"]) delete (process.env as NodeJS.Dict<string>)[k];
+    for (const k of ["GITHUB_WEBHOOK_SECRET", "ORB_APP_ID", "ORB_ANONYMIZE", "ORB_AIR_GAP", "ORB_COLLECTOR_URL", "GITHUB_APP_ID"]) delete (process.env as NodeJS.Dict<string>)[k];
   });
 
-  it("returns 0 when disabled", async () => {
-    process.env.ORB_ENABLED = "false";
-    expect(await exportOrbBatch(makeDb(), 200, async () => new Response(null, { status: 200 }))).toBe(0);
+  it("returns 0 when the App secret is not configured (App not set up → nothing to export)", async () => {
+    delete (process.env as NodeJS.Dict<string>).GITHUB_WEBHOOK_SECRET;
+    const db = makeDb();
+    await audit(db, "o/r", 1, "gate_decision", "merge", "2026-01-01T00:00:00Z");
+    await audit(db, "o/r", 1, "pr_outcome", "merged", "2026-01-01T01:00:00Z");
+    expect(await exportOrbBatch(db, 200, async () => new Response(null, { status: 200 }))).toBe(0);
   });
 
   it("returns 0 in air-gap mode", async () => {
@@ -164,9 +157,8 @@ describe("exportOrbBatch() — reads review_audit, ships anonymized reversal-awa
     expect(sig).toMatch(/^sha256=[a-f0-9]{64}$/);
   });
 
-  it("falls back to GITHUB_APP_ID for the instance id and applies secret/anonymize defaults when ORB_* are unset", async () => {
+  it("falls back to GITHUB_APP_ID for the instance id and applies the anonymize default when ORB_* are unset", async () => {
     delete process.env.ORB_APP_ID; // → falls through to GITHUB_APP_ID
-    delete process.env.ORB_WEBHOOK_SECRET; // → secret defaults to ""
     delete process.env.ORB_ANONYMIZE; // → defaults to "true"
     (process.env as NodeJS.Dict<string>).GITHUB_APP_ID = "999";
     const db = makeDb();