@open-everywhere/core 0.1.0

package/agent/observability/telemetry.ts

@@ -0,0 +1,819 @@
+// Anonymous usage telemetry — EMIT side only (the collector is a separate, later
+// project). Default ON, fail-open,
+// never blocks a turn: mirrors ship.ts's bounded-queue / drop-oldest / warn-once /
+// fire-and-forget idioms almost verbatim, as its own sibling module (a different
+// destination, a different — CLOSED — event vocabulary, a different env surface).
+//
+// THE EVENT VOCABULARY IS CLOSED (a design note "Event
+// schema"; `wizard.started`/`wizard.completed` added 2026-07-07 per the same
+// night's backlog decision — the install-wizard funnel;
+// `oe.reaction.added`/`oe.reaction.removed` added for inbound reaction
+// ingestion — channels/reaction-ingest.ts): `EVENT_SCHEMA` below is
+// the single source of truth both for what this module will actually SEND and for
+// the never-collected contract in docs/deploy/telemetry.md. `emitTelemetry`
+// enforces it at the one call site：an unregistered event name is dropped
+// (warn-once); an attribute key outside its event's own allow-list is dropped
+// (warn-once) — so a future call site can never silently widen the payload, only
+// a deliberate edit to EVENT_SCHEMA can.
+//
+// WIZARD EVENTS ARE A DIFFERENT CONSENT REGIME than the other six: those six obey
+// OE_TELEMETRY/DO_NOT_TRACK only (the operator "consents by deploying, having read
+// the boot line"). `wizard.started`/`wizard.completed` are additionally gated by
+// an EXPLICIT accept/decline/redirect prompt the install wizard (`packages/create`)
+// shows before either can fire — the wizard IS the disclosure surface, so a human
+// is always at the keyboard when consent is captured. `emitTelemetry` itself does
+// not know about that prompt (it only enforces the closed vocabulary below); the
+// wizard's own call sites (`packages/create/src/telemetry.ts`) are what withhold
+// the call entirely on decline — see that file for the ordering guarantee.
+//
+// FIRST-BOOT GRACE WINDOW (the .NET flaw this design must not repeat: "first run
+// transmits in the same run as the notice"): the boot disclosure line always prints
+// before anything is transmitted, but on the VERY FIRST boot — the one that mints
+// this instance's anonymous id — literally NOTHING is sent, not even the heartbeat.
+// `oe.instance.first_boot` is deferred and sent on the NEXT boot (or, for the
+// store-unavailable/ephemeral path, the next call within the same warm process —
+// there is nothing durable to defer across a cold start there, which is an accepted
+// gap: an ephemeral id's "first boot" is scoped to one warm instance's lifetime).
+//
+// CONFIG PRECEDENCE: OE_TELEMETRY=off > DO_NOT_TRACK (any truthy value) > the
+// redirect URL. A redirect (`OE_TELEMETRY_OTLP_URL`) is a FULL redirect — 100% of
+// the payload goes there, nothing is ever teed to the default collector (the
+// PostHog "opt-out didn't stop network calls" trap, avoided by construction: there
+// is exactly one destination computed per read, never two).
+//
+// Wire format: OTLP/JSON logs (`resourceLogs[].scopeLogs[].logRecords[]`,
+// lowerCamelCase, int64s as decimal strings — OTLP spec 1.10.0), with the
+// `eventName` LogRecord field naming the event. Resource attributes are stamped
+// once per batch. See docs/deploy/telemetry.md for one full example payload.
+
+import { randomUUID } from "node:crypto";
+import { getOperationalStore } from "../operational/provider.js";
+import { getAppInfo } from "../commands/core.js";
+import { getProvider as getMemoryProvider } from "../memory/provider.js";
+import { getConfig } from "../access/config.js";
+import { onVercel } from "../access/platform.js";
+import { admitProviderRegistration } from "../access/provider-selection.js";
+
+// --- the closed vocabulary ---------------
+
+/** Every attribute key an event is allowed to carry. Anything else is dropped at
+ *  `emitTelemetry` (warn-once) — this table IS the contract, not a suggestion. */
+export const EVENT_SCHEMA: Readonly<Record<string, readonly string[]>> = Object.freeze({
+  "oe.instance.first_boot": Object.freeze([]),
+  "oe.instance.heartbeat": Object.freeze([
+    "oe.surfaces",
+    "oe.memory_provider",
+    "oe.operational_provider",
+    "oe.model.primary",
+    "oe.model.utility",
+    "oe.domains.bucket",
+    "oe.telemetry.dropped",
+  ]),
+  "oe.turn.completed": Object.freeze([
+    "oe.surface",
+    "oe.kind",
+    "gen_ai.request.model",
+    "oe.tokens.bucket",
+    "oe.steps.bucket",
+    "oe.latency.bucket",
+  ]),
+  // TIME TO FIRST OUTPUT (OPE-1626, hooks/telemetry.ts) — one row per turn, written when the
+  // turn's FIRST step completes. It measures the wall clock from the turn's start to the END of
+  // that step, THAT STEP'S TOOL EXECUTION INCLUDED (eve raises `step.completed` from the AI SDK's
+  // `onStepFinish`, after the step's tool calls have run). So it is an UPPER BOUND on time-to-first
+  // -output, not a floor, and it says nothing about usefulness. A separate
+  // event rather than an attribute on `oe.turn.completed`, because a turn that HANGS emits no
+  // completion row and that is the case an on-call rotation most needs to see. Same three
+  // low-cardinality labels the completion row carries, and no precise count.
+  "oe.turn.first_output": Object.freeze(["oe.surface", "oe.kind", "oe.latency.bucket"]),
+  "oe.turn.failed": Object.freeze(["oe.surface", "oe.error.code"]),
+  "oe.error.uncaught": Object.freeze(["oe.component", "oe.error.name"]),
+  "oe.feature.used": Object.freeze(["oe.feature", "oe.outcome"]),
+  // An audit line dropped after ONE re-attempt (audit/audit.ts appendAudit — best-effort by
+  // contract). Low-cardinality: the audit ACTION name and the PLATFORM, both OE-controlled
+  // labels — never an org id, a principal, or any row detail. Lets an operator see audit-write
+  // health (a Neon blip) without the log itself being the only witness to its own gaps.
+  "oe.audit.dropped": Object.freeze(["oe.action", "oe.platform"]),
+  // Inbound reaction ingestion (channels/reaction-ingest.ts). Deliberately low-cardinality:
+  // surface (slack|discord), whether it landed on the bot's own reply (bool), and the emoji
+  // BUCKET (positive|negative|other) — never a channel id, a user id, or a raw emoji name.
+  "oe.reaction.added": Object.freeze(["oe.surface", "oe.on_bot_reply", "oe.emoji_class"]),
+  "oe.reaction.removed": Object.freeze(["oe.surface", "oe.on_bot_reply", "oe.emoji_class"]),
+  // The install-wizard funnel (packages/create) — see the header comment above on
+  // its distinct, explicit-consent regime.
+  "wizard.started": Object.freeze(["oe.wizard.version", "oe.wizard.platform"]),
+  "wizard.completed": Object.freeze(["oe.wizard.version", "oe.wizard.platform", "oe.wizard.steps_completed"]),
+});
+
+/** Resource attribute keys this module will ever stamp — the never-collected list's
+ *  positive counterpart (docs/deploy/telemetry.md quotes both verbatim). */
+export const RESOURCE_ATTR_KEYS: readonly string[] = Object.freeze([
+  "service.name",
+  "service.version",
+  "service.instance.id",
+  "deployment.environment.name",
+  "oe.host",
+  "oe.node.major",
+  "oe.instance.ephemeral",
+]);
+
+/**
+ * THE CLOSED VOCABULARY for `oe.feature` and `oe.outcome` — every value any call site in the tree
+ * emits, and nothing else.
+ *
+ * 🔴 THESE LISTS ARE GATED IN BOTH DIRECTIONS (OPE-1365). `emitTelemetry` itself enforces attribute
+ * KEYS only, so for a while these lists were a comment: the OPE-1290 diff added the wait feature and
+ * its four outcomes, ten other features and seven other outcomes were already being emitted without
+ * ever being declared, and nothing anywhere noticed. `packages/core/scripts/telemetry-test.ts` now
+ * scans every real `emitTelemetry(...)` call site and fails BOTH ways — a literal value outside
+ * these lists, and a value declared here that no call site emits. A vocabulary nothing checks
+ * describes the code it was written against, not the code that ships.
+ *
+ * 🔴 THE SCAN READS LITERALS, AND `emitTelemetry` CLOSES THE REST (OPE-1371). A call site that
+ * passes a hoisted variable is invisible to the scan, and five real emits do exactly that — so for a
+ * while nothing kept those variables inside these lists. The emitter now checks the VALUE of
+ * `oe.feature` and `oe.outcome` against {@link CLOSED_ATTR_VALUES} and drops an undeclared one
+ * before the record is queued, naming it in the deploy log. Both halves stay: the scan catches the
+ * mistake at review time, the emitter at run time. Values only a variable can carry are listed in
+ * the test's `DYNAMIC_ONLY_OUTCOMES`, each against the file that produces it, and the test verifies
+ * that file still contains the value. Prefer a literal at the call site wherever the shape allows
+ * one; a variable there buys nothing and keeps the scan blind.
+ *
+ * `docs/deploy/telemetry.md`'s operator-facing "what we send" table quotes both lists, and the same
+ * test pins the table to them — the doc under-declared what an approve click sends for months. Keep
+ * the two honest together.
+ */
+export const FEATURE_VALUES = Object.freeze([
+  "agent_created",
+  "approval_requested",
+  "approval_decided",
+  "approval_judge_contradicted",
+  "bash_hang_guard",
+  "pr_opened",
+  "routine_cancelled",
+  "routine_fired",
+  "routine_permission_card",
+  "routine_permission_card_wait",
+  "skill_created",
+  "skill_deleted",
+  "spend_cap_hit",
+  "spend_checkpoint",
+  "stall_guard",
+  "webhook_declared",
+  "webhook_received",
+  "webhook_rotated",
+] as const);
+// "declined" is NOT "failed": an approved action that refused itself in-band because the world
+// moved between the card and the click (approvals/webhook.ts's duplicate-source decline, OPE-188).
+// "noop" is a third thing again — a delete or a cancel that found nothing to act on.
+// "deadline", "stale", "gone" and "unreadable" are the routine permission card's TIMED WAIT
+// (OPE-1290): the auto-decline, an approval that armed nothing, a card that stopped being
+// answerable, and a window whose last look at the card failed. Its "approved"/"declined" arms reuse
+// the two above.
+// "unknown", "not-judge-lift", "already-recorded" and "recorded" are the judge-contradiction
+// producer's four answers (approvals/judge-contradiction.ts, OPE-965).
+// "halted" is the break-glass halt arrow at the CLICK (approvals/flow.ts, OPE-1604) — a click
+// refused because a halt covers the row's frozen address. It is NOT "denied": that one means the
+// clicker lacked standing, and telling the two apart is the whole reason an incident review can
+// count how many clicks the stop actually caught.
+// 🔴 THE SHIPPED DEFAULT EMITS NONE OF THE WAIT OUTCOMES. `approvals.routineCardWaitSeconds` ships
+// 0, and both call sites in `approvals/flow.ts` return before reaching the emit — so the wait's
+// "disarmed" outcome exists as a return value and is deliberately NOT in this list, because no row
+// carries it.
+export const OUTCOME_VALUES = Object.freeze([
+  "ok",
+  "failed",
+  "noop",
+  "declined",
+  "denied",
+  "withheld",
+  "deduped",
+  "approved",
+  "autoapproved",
+  "rejected",
+  "granted",
+  "continued",
+  "tripped",
+  "expired",
+  "unverified",
+  "deadline",
+  "stale",
+  "gone",
+  "unreadable",
+  "unknown",
+  "not-judge-lift",
+  "already-recorded",
+  "recorded",
+  "halted",
+] as const);
+
+/**
+ * The attribute keys whose VALUES are closed too, and the sets that close them (OPE-1371).
+ *
+ * 🔴 THIS IS WHAT MAKES THE VOCABULARY A CONTROL RATHER THAN A CONVENTION. `emitTelemetry` filtered
+ * attribute KEYS and never looked at values, so the two lists above were enforced only by
+ * `packages/core/scripts/telemetry-test.ts`'s SOURCE SCAN — and that scan reads string LITERALS at
+ * the call site. Five emits pass the value in a hoisted variable (`approvals/flow.ts`'s two wait
+ * emits, `approvals/routine-cancel.ts`, `approvals/skill-delete.ts`, `approvals/webhook.ts`), and
+ * every one of them is invisible to it. Nothing undeclared shipped, because each variable could only
+ * hold a declared value; nothing KEPT it that way. Change one `delivered ? "ok" : "failed"` into
+ * `delivered ? "ok" : err.code` and an arbitrary string reached the wire while
+ * `docs/deploy/telemetry.md` still told a DPO the enum was closed.
+ *
+ * The emitter now refuses such a value at the last point before it is queued, so a variable site is
+ * held to the same list as a literal one. The source scan stays: it catches the mistake at review
+ * time, this catches it at run time, and neither makes the other redundant.
+ */
+const CLOSED_ATTR_VALUES: Readonly<Record<string, ReadonlySet<string>>> = Object.freeze({
+  "oe.feature": new Set<string>(FEATURE_VALUES),
+  "oe.outcome": new Set<string>(OUTCOME_VALUES),
+});
+
+// --- bucket helpers (pure — exported for tests) ---------------------------------------------
+
+/** Turn-total token bucket (log-scale, never a precise count). */
+export function tokensBucket(total: number): string {
+  if (total < 1_000) return "<1k";
+  if (total < 10_000) return "1-10k";
+  if (total < 100_000) return "10-100k";
+  if (total < 1_000_000) return "100k-1M";
+  return ">1M";
+}
+
+/** Step-count bucket for one turn. */
+export function stepsBucket(steps: number): string {
+  if (steps <= 1) return "1";
+  if (steps <= 5) return "2-5";
+  if (steps <= 20) return "6-20";
+  return ">20";
+}
+
+/** Wall-clock latency bucket (ms) for one turn. */
+export function latencyBucket(ms: number): string {
+  if (ms < 5_000) return "<5s";
+  if (ms < 15_000) return "5-15s";
+  if (ms < 60_000) return "15-60s";
+  if (ms < 300_000) return "1-5m";
+  return ">5m";
+}
+
+/** Configured-domain-count bucket (never the exact count — can't fingerprint an org's structure). */
+export function domainsBucket(count: number): string {
+  if (count <= 0) return "0";
+  if (count === 1) return "1";
+  if (count <= 5) return "2-5";
+  return "6+";
+}
+
+// --- config -----------------------------------------------------------------------------
+
+interface TelemetryConfig {
+  readonly enabled: boolean;
+  readonly debug: boolean;
+  readonly url: string;
+  readonly headers: Readonly<Record<string, string>>;
+  /** True when OE_TELEMETRY_OTLP_URL is set — a FULL redirect, never a tee. */
+  readonly redirected: boolean;
+}
+
+/** Pre-launch placeholder collector project (a tiny separate Vercel project + Neon
+ *  free tier — a design note "Collector architecture"). May move to
+ *  a custom domain before launch; keep this the ONE named constant callers/docs cite,
+ *  never inlined elsewhere, so that move is a one-line change. */
+export const DEFAULT_TELEMETRY_URL = "https://oe-telemetry.vercel.app/v1/logs";
+
+function isOffValue(raw: string | undefined): boolean {
+  if (!raw) return false;
+  const v = raw.trim().toLowerCase();
+  return v === "off" || v === "0" || v === "false";
+}
+
+/** DO_NOT_TRACK: "any truthy value disables everything" (per the plan — honored as a
+ *  cheap courtesy, not cited as legitimation; consoledonottrack.com has lapsed). */
+function isDntTruthy(raw: string | undefined): boolean {
+  if (!raw) return false;
+  const v = raw.trim().toLowerCase();
+  return v !== "" && v !== "0" && v !== "false" && v !== "off" && v !== "no";
+}
+
+function parseHeaders(raw: string | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!raw) return out;
+  for (const pair of raw.split(",")) {
+    const eq = pair.indexOf("=");
+    if (eq <= 0) continue;
+    const key = pair.slice(0, eq).trim();
+    const value = pair.slice(eq + 1).trim();
+    if (key) out[key] = value;
+  }
+  return out;
+}
+
+let config: TelemetryConfig | undefined; // undefined = not read yet (memoized like ship.ts)
+
+function readTelemetryConfig(): TelemetryConfig {
+  if (config !== undefined) return config;
+  // Precedence: OE_TELEMETRY=off > DO_NOT_TRACK (truthy) > the redirect URL.
+  const enabled = !isOffValue(process.env.OE_TELEMETRY) && !isDntTruthy(process.env.DO_NOT_TRACK);
+  const debug = process.env.OE_TELEMETRY_DEBUG === "1";
+  const redirectUrl = process.env.OE_TELEMETRY_OTLP_URL?.trim();
+  config = {
+    enabled,
+    debug,
+    url: redirectUrl || DEFAULT_TELEMETRY_URL,
+    headers: parseHeaders(process.env.OE_TELEMETRY_OTLP_HEADERS),
+    redirected: Boolean(redirectUrl),
+  };
+  return config;
+}
+
+/**
+ * Drop the memoized config so the NEXT read re-derives it from the current env.
+ * Config is memoized once per process (like ship.ts) because in the normal boot
+ * path env vars never change mid-process. The install wizard is the one legitimate
+ * exception: its interactive "redirect to your own collector" answer mutates
+ * `process.env.OE_TELEMETRY_OTLP_URL` mid-process and must take effect on the very
+ * next emit — call this right after that mutation, before any further telemetry
+ * call. (Distinct from `__resetTelemetryForTest`, which also clears the queue/
+ * instance/dedupe state for a full test reset.)
+ */
+export function resetTelemetryConfigCache(): void {
+  config = undefined;
+}
+
+/** Whether telemetry is enabled right now (config precedence applied). Exported for
+ *  the `/oe status` line and for tests. */
+export function telemetryEnabled(): boolean {
+  return readTelemetryConfig().enabled;
+}
+
+/** `/oe status`'s `telemetry:` line — "off" / "on (default collector)" / "on (custom endpoint)". */
+export function telemetryStatusLine(): string {
+  const cfg = readTelemetryConfig();
+  if (!cfg.enabled) return "off";
+  return cfg.redirected ? "on (custom endpoint)" : "on (default collector)";
+}
+
+// --- instance id + first-boot grace window -----------------------------------------------
+
+const INSTANCE_ID_META_KEY = "telemetry.instanceId";
+const FIRST_BOOT_PENDING_META_KEY = "telemetry.firstBootPending";
+
+interface InstanceInfo {
+  readonly id: string;
+  readonly ephemeral: boolean;
+}
+
+let cachedInstance: InstanceInfo | null = null;
+let initStarted = false;
+
+// Store-unavailable fallback — module-level only (lost every cold start, which is
+// fine: there is nothing durable to lose). Runs the SAME mint->pending->send state
+// machine as the durable path, just scoped to this one warm process's lifetime.
+let ephemeralState: { id: string; pending: boolean } | null = null;
+
+// Plain console output (the boot disclosure line + warn-once diagnostics) —
+// deliberately NOT a shipped telemetry record, and independent of ship.ts's console
+// capture (that module wraps console for LOG shipping; this one doesn't touch it).
+function rawLog(line: string): void {
+  console.log(line);
+}
+
+const warnedReasons = new Set<string>();
+function warnOnce(reason: string): void {
+  if (warnedReasons.has(reason)) return;
+  warnedReasons.add(reason);
+  rawLog(`[open-everywhere:telemetry] ${reason}`);
+}
+
+/** The EXACT boot disclosure line
+ *  when telemetry is enabled — printed BEFORE anything is ever transmitted, every boot. */
+const BOOT_LINE_ON =
+  "[open-everywhere:telemetry] anonymous usage telemetry is ON — see docs/deploy/telemetry.md; " +
+  "OE_TELEMETRY=off or DO_NOT_TRACK=1 disables";
+const BOOT_LINE_OFF =
+  "[open-everywhere:telemetry] anonymous usage telemetry is OFF (OE_TELEMETRY / DO_NOT_TRACK) — see docs/deploy/telemetry.md";
+
+function printBootDisclosureLine(): void {
+  rawLog(telemetryEnabled() ? BOOT_LINE_ON : BOOT_LINE_OFF);
+}
+
+export interface ResolvedInstance {
+  readonly id: string;
+  readonly ephemeral: boolean;
+  /** True only when THIS call minted a brand-new id — nothing durable existed
+   *  before it. Callers that don't own the app's own first-boot/heartbeat
+   *  lifecycle (the install wizard, below) use this to stay silent on a true
+   *  first-ever resolution without having to know the internal pending flag. */
+  readonly justMinted: boolean;
+}
+
+/**
+ * Resolve (minting if necessary) this deployment's durable anonymous instance id
+ * — the SAME id the app's own boot lifecycle (`oe.instance.first_boot`/heartbeat,
+ * below) and the install wizard (`packages/create`) both key off, so there is
+ * exactly one id per install, never one per caller. Sets `cachedInstance` as a
+ * side effect (so a subsequent `emitTelemetry` can send). Deliberately does NOT
+ * decide any first-boot/heartbeat emission itself — that stays
+ * `resolveInstanceAndMaybeEmitFirstBoot`'s job below, so a caller like the wizard
+ * can resolve the id under its OWN consent gate without silently triggering the
+ * app's own lifecycle events (which are gated only by `OE_TELEMETRY`/
+ * `DO_NOT_TRACK`, not by the wizard's explicit accept/decline prompt). Never
+ * throws — falls back to an ephemeral per-process id when the operational store
+ * is unreachable.
+ */
+export async function resolveInstanceId(): Promise<ResolvedInstance> {
+  try {
+    const store = getOperationalStore();
+    const existing = await store.getMeta(INSTANCE_ID_META_KEY);
+    if (existing == null) {
+      const id = randomUUID();
+      await store.setMeta(INSTANCE_ID_META_KEY, id);
+      await store.setMeta(FIRST_BOOT_PENDING_META_KEY, "1");
+      cachedInstance = { id, ephemeral: false };
+      return { id, ephemeral: false, justMinted: true };
+    }
+    cachedInstance = { id: existing, ephemeral: false };
+    return { id: existing, ephemeral: false, justMinted: false };
+  } catch {
+    // Operational store unavailable — ephemeral id, in-process-only grace window.
+    if (!ephemeralState) {
+      ephemeralState = { id: randomUUID(), pending: true };
+      cachedInstance = { id: ephemeralState.id, ephemeral: true };
+      return { id: ephemeralState.id, ephemeral: true, justMinted: true };
+    }
+    cachedInstance = { id: ephemeralState.id, ephemeral: true };
+    return { id: ephemeralState.id, ephemeral: true, justMinted: false };
+  }
+}
+
+/**
+ * Resolve this instance's id and — respecting the first-boot grace window — emit
+ * `oe.instance.first_boot` and arm the heartbeat. Never throws. On the VERY FIRST
+ * boot (id just minted) this sends ZERO bytes and returns immediately: no
+ * first_boot, no heartbeat, nothing — the deferred event fires on the NEXT boot.
+ */
+async function resolveInstanceAndMaybeEmitFirstBoot(): Promise<void> {
+  const resolved = await resolveInstanceId();
+  if (resolved.justMinted) return; // very first boot ever — zero bytes transmitted (grace window)
+
+  if (resolved.ephemeral) {
+    if (ephemeralState?.pending) {
+      ephemeralState.pending = false;
+      emitTelemetry("oe.instance.first_boot", {});
+    }
+    maybeHeartbeat();
+    return;
+  }
+
+  try {
+    const store = getOperationalStore();
+    const pending = await store.getMeta(FIRST_BOOT_PENDING_META_KEY);
+    if (pending === "1") {
+      await store.setMeta(FIRST_BOOT_PENDING_META_KEY, "0");
+      emitTelemetry("oe.instance.first_boot", {});
+    }
+    maybeHeartbeat();
+  } catch {
+    // Store became unreachable between the two calls — best-effort, never throws.
+  }
+}
+
+/**
+ * The one-call install used by the instrumentation setup seam (every boot). Prints
+ * the disclosure line BEFORE anything is transmitted, then resolves the instance id
+ * and (respecting the grace window) fires first_boot/heartbeat. Idempotent per
+ * process (a second call in the same boot/warm instance is a no-op). Returns a
+ * Promise so tests can await it deterministically; the instrumentation setup seam
+ * calls it WITHOUT awaiting (`defineInstrumentation`'s `setup` is synchronous —
+ * this must never block boot; resolution proceeds in the background).
+ */
+export async function initTelemetry(): Promise<void> {
+  printBootDisclosureLine();
+  if (initStarted) return;
+  initStarted = true;
+  if (!telemetryEnabled()) return; // disabled — resolve nothing, transmit nothing
+  await resolveInstanceAndMaybeEmitFirstBoot();
+}
+
+// --- heartbeat (≤1/6h PER PROCESS, lazy on turn activity + cold boot; no store write on the hot
+// path, so the instance-wide bound is the collector's dedupe on (instance_id, 6h window) — see
+// maybeHeartbeat's header, and docs/deploy/telemetry.md's oe.instance.heartbeat row) --
+
+const HEARTBEAT_INTERVAL_MS = 6 * 60 * 60 * 1000;
+let lastHeartbeatAt = 0;
+
+// Registry — one credential-presence probe per EXTRACTED provider bundle (OPE-114 stage 4
+// addendum), mirroring the identity-mapper/capability-manifest/routine-dispatch registries: an
+// extracted bundle owns ITS OWN fingerprint entirely — hardcoding a bundle's own bot-token
+// env-var name here would be exactly the vendor-coupling residue boundary-test.ts's
+// provider-bundle section 6 checks for (core keeps ZERO of it once a platform is extracted —
+// see that file's PROVIDER_VENDOR_STRINGS table for the pinned fingerprint list). Unregistered ⇒
+// the surface never reports present (fail-closed — the heartbeat under-reports rather than
+// fabricates).
+//
+// Every extracted platform (slack, linear, teams, discord, github) now registers through its own
+// registerXOps() — core carries no inline per-platform env check (OPE-488 moved teams; OPE-495
+// moved the last two, discord and github). `surfacesWithCreds()` still builds a Set (below) as a
+// generic safety net against any future double registration, never a live double-count case today.
+const SURFACE_CREDENTIAL_PROBES: Record<string, () => boolean> = {};
+
+/** Register (or replace) one EXTRACTED provider's credential-presence probe for the heartbeat's
+ *  `surfacesWithCreds` diagnostic. Exported so a provider bundle (slack, linear, teams, discord,
+ *  github all ride it today) reports its own configured-ness without core hardcoding its vendor
+ *  env-var name. */
+export function registerSurfaceCredentialProbe(platform: string, probe: () => boolean): void {
+  if (!admitProviderRegistration(platform, "surface-credential-probe")) return;
+  SURFACE_CREDENTIAL_PROBES[platform] = probe;
+}
+
+function surfacesWithCreds(): string[] {
+  // A Set, not an array: a platform registered by more than one caller (e.g. mid-migration) must
+  // never double-count in the census — OPE-488. No platform has an inline arm any more (OPE-495),
+  // so this is a generic safety net today, not a live double-count case.
+  const present = new Set<string>();
+  // Extracted provider bundles register a probe here (OPE-114): their cred-detection (and its
+  // vendor env names) lives in the bundle, so core keeps zero vendor residue for extracted
+  // platforms (linear + slack + teams + discord + github ride this today).
+  for (const [platform, probe] of Object.entries(SURFACE_CREDENTIAL_PROBES)) {
+    try {
+      if (probe()) present.add(platform);
+    } catch {
+      /* a misbehaving probe must never break the heartbeat — best-effort */
+    }
+  }
+  try {
+    if ((getConfig().loadWebhooks?.() ?? []).length > 0) present.add("webhooks");
+  } catch {
+    /* config not registered (bare script/test context) — best-effort */
+  }
+  return [...present].sort();
+}
+
+function domainsCount(): number {
+  try {
+    return getConfig().loadDomains().length;
+  } catch {
+    return 0;
+  }
+}
+
+function memoryProviderId(): string {
+  try {
+    return getMemoryProvider().id;
+  } catch {
+    return "unknown";
+  }
+}
+
+function operationalProviderId(): string {
+  try {
+    return getOperationalStore().id;
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * Emit `oe.instance.heartbeat` if the last one was ≥6h ago (in-memory only — no
+ * store write on this hot path; serverless cold-boot storms are handled by
+ * COLLECTOR-SIDE dedupe on (instance_id, 6h window), not here). Safe to call on
+ * every turn and on cold boot; no-ops silently when the instance isn't resolved yet.
+ */
+export function maybeHeartbeat(now: number = Date.now()): void {
+  if (!cachedInstance) return;
+  if (now - lastHeartbeatAt < HEARTBEAT_INTERVAL_MS) return;
+  lastHeartbeatAt = now;
+  const appInfo = getAppInfo();
+  emitTelemetry("oe.instance.heartbeat", {
+    "oe.surfaces": surfacesWithCreds(),
+    "oe.memory_provider": memoryProviderId(),
+    "oe.operational_provider": operationalProviderId(),
+    "oe.model.primary": appInfo.primaryModel,
+    "oe.model.utility": appInfo.utilityModel,
+    "oe.domains.bucket": domainsBucket(domainsCount()),
+    "oe.telemetry.dropped": droppedTelemetryCount(),
+  });
+}
+
+// --- envelope + queue + transport (mirrors ship.ts's idioms) --------------------------------
+
+export type TelemetryAttrValue = string | number | boolean | readonly string[];
+export type TelemetryAttrs = Readonly<Record<string, TelemetryAttrValue>>;
+
+interface QueuedTelemetryRecord {
+  readonly eventName: string;
+  readonly attributes: TelemetryAttrs;
+  readonly timeUnixNano: string;
+}
+
+const QUEUE_HARD_CAP = 200; // low-cardinality, low-volume — a dead endpoint must not grow memory
+const BATCH_MAX = 20;
+const FLUSH_MS = 2_000;
+
+let queue: QueuedTelemetryRecord[] = [];
+let flushTimer: ReturnType<typeof setTimeout> | undefined;
+let droppedCount = 0;
+let fetchImpl: typeof fetch = (...args) => fetch(...args);
+
+/** Records dropped so far (queue overflow / failed flushes) — self-reported in the
+ *  heartbeat's `oe.telemetry.dropped` field, and for tests/diagnostics. */
+export function droppedTelemetryCount(): number {
+  return droppedCount;
+}
+
+function nowUnixNano(): string {
+  // int64 as a DECIMAL STRING per OTLP spec 1.10.0.
+  return (BigInt(Date.now()) * 1_000_000n).toString();
+}
+
+function environmentName(): "production" | "preview" | "development" {
+  const v = process.env.VERCEL_ENV;
+  if (v === "production" || v === "preview" || v === "development") return v;
+  return process.env.NODE_ENV === "production" ? "production" : "development";
+}
+
+function nodeMajorVersion(): number {
+  const major = Number(process.versions.node.split(".")[0]);
+  return Number.isFinite(major) ? major : 0;
+}
+
+function resourceAttributes(): Record<string, string | number | boolean> {
+  const appInfo = getAppInfo();
+  const attrs: Record<string, string | number | boolean> = {
+    "service.name": "open-everywhere",
+    // `unversioned` on a deploy that carries no package version (OPE-1057) — deliberately NOT the
+    // deployment sha. A sha identifies the build, but on a private operator fork it is not a public
+    // fact, and this attribute has no per-attribute opt-out for one to hide behind. An honest
+    // non-answer is the safe value here; the sha stays on the surfaces an operator can decline to
+    // mount (`agent_version`) or has to ask for (`/oe status`).
+    "service.version": appInfo.version,
+    "service.instance.id": cachedInstance?.id ?? "unknown",
+    "deployment.environment.name": environmentName(),
+    "oe.host": onVercel() ? "vercel" : "node",
+    "oe.node.major": nodeMajorVersion(),
+  };
+  if (cachedInstance?.ephemeral) attrs["oe.instance.ephemeral"] = true;
+  return attrs;
+}
+
+function otlpValue(v: TelemetryAttrValue): Record<string, unknown> {
+  if (Array.isArray(v)) return { arrayValue: { values: v.map((s) => ({ stringValue: String(s) })) } };
+  if (typeof v === "boolean") return { boolValue: v };
+  if (typeof v === "number") return Number.isInteger(v) ? { intValue: String(v) } : { doubleValue: v };
+  return { stringValue: String(v) };
+}
+
+function otlpAttributes(attrs: Record<string, TelemetryAttrValue>): { key: string; value: Record<string, unknown> }[] {
+  return Object.entries(attrs).map(([key, value]) => ({ key, value: otlpValue(value) }));
+}
+
+/** Build the OTLP/JSON logs payload for a batch of records (pure — exported for
+ *  tests). Resource attributes are stamped ONCE per batch, per the OTLP shape. */
+export function buildOtlpPayload(records: readonly QueuedTelemetryRecord[]): Record<string, unknown> {
+  return {
+    resourceLogs: [
+      {
+        resource: { attributes: otlpAttributes(resourceAttributes()) },
+        scopeLogs: [
+          {
+            scope: { name: "open-everywhere-telemetry" },
+            logRecords: records.map((r) => ({
+              timeUnixNano: r.timeUnixNano,
+              eventName: r.eventName,
+              attributes: otlpAttributes(r.attributes),
+            })),
+          },
+        ],
+      },
+    ],
+  };
+}
+
+/**
+ * Emit one telemetry event. NEVER throws. Enforces the CLOSED vocabulary:
+ * an unregistered `eventName` is dropped whole (warn-once); an attribute key
+ * outside that event's own allow-list is dropped individually (warn-once) —
+ * the rest of the event still sends. No-ops when disabled, when the instance
+ * id isn't resolved yet, or (in debug mode) after logging the would-be payload
+ * instead of queuing it.
+ */
+export function emitTelemetry(eventName: string, attrs: TelemetryAttrs = {}): void {
+  try {
+    const allowed = EVENT_SCHEMA[eventName];
+    if (!allowed) {
+      warnOnce(`unknown event "${eventName}" — dropped (outside the closed vocabulary)`);
+      return;
+    }
+    const filtered: Record<string, TelemetryAttrValue> = {};
+    for (const [key, value] of Object.entries(attrs)) {
+      if (!allowed.includes(key)) {
+        warnOnce(`event "${eventName}" attribute "${key}" is outside its closed vocabulary — dropped`);
+        continue;
+      }
+      const closed = CLOSED_ATTR_VALUES[key];
+      if (closed !== undefined && !closed.has(value as string)) {
+        // 🔴 THE ATTRIBUTE IS DROPPED, NOT THE EVENT (OPE-1371). The event still counts — losing it
+        // would turn a vocabulary slip into a hole in the operator's own numbers — and the offending
+        // value is named in the deploy log, once per distinct value, so the mistake is loud where a
+        // developer looks and silent on the wire. `warnOnce` rather than a bare `console.error`
+        // because an undeclared value in a hot path would otherwise log on every turn.
+        warnOnce(`event "${eventName}" attribute "${key}" carries undeclared value ${JSON.stringify(value)} — dropped (the vocabulary is closed)`);
+        continue;
+      }
+      filtered[key] = value;
+    }
+
+    const cfg = readTelemetryConfig();
+    if (!cfg.enabled) return;
+    if (!cachedInstance) {
+      warnOnce("event dropped — instance id not resolved yet");
+      return;
+    }
+
+    const record: QueuedTelemetryRecord = { eventName, attributes: filtered, timeUnixNano: nowUnixNano() };
+
+    if (cfg.debug) {
+      rawLog(`[open-everywhere:telemetry] (debug — not sent) ${JSON.stringify(buildOtlpPayload([record]))}`);
+      return;
+    }
+
+    queue.push(record);
+    if (queue.length > QUEUE_HARD_CAP) {
+      queue.splice(0, queue.length - QUEUE_HARD_CAP);
+      droppedCount++;
+    }
+    if (queue.length >= BATCH_MAX) {
+      void flushTelemetry();
+      return;
+    }
+    if (!flushTimer) {
+      flushTimer = setTimeout(() => void flushTelemetry(), FLUSH_MS);
+      (flushTimer as { unref?: () => void }).unref?.();
+    }
+  } catch {
+    // Observability must never throw into the caller.
+  }
+}
+
+/**
+ * Flush the queue now — fire-and-forget POST of the OTLP/JSON payload. All
+ * transport failures are swallowed (batch dropped, one warning per distinct
+ * reason); await-able so a turn-end hook can give the POST a chance to land
+ * before serverless suspend.
+ */
+export async function flushTelemetry(): Promise<void> {
+  const cfg = readTelemetryConfig();
+  if (flushTimer) {
+    clearTimeout(flushTimer);
+    flushTimer = undefined;
+  }
+  if (!cfg.enabled || queue.length === 0) return;
+  const batch = queue;
+  queue = [];
+  try {
+    const headers: Record<string, string> = { "content-type": "application/json", ...cfg.headers };
+    const res = await fetchImpl(cfg.url, { method: "POST", headers, body: JSON.stringify(buildOtlpPayload(batch)) });
+    if (!res.ok) {
+      droppedCount += batch.length;
+      warnOnce(`ingest rejected ${res.status} — dropping batches with this status until it recovers`);
+    }
+  } catch (err) {
+    droppedCount += batch.length;
+    warnOnce(`ingest unreachable (${err instanceof Error ? err.message : String(err)}) — dropping batches`);
+  }
+}
+
+// --- test seams ------------------------------------------------------------------------
+
+/** TEST SEAM — reset every module-level state slot and optionally inject a fetch. */
+export function __resetTelemetryForTest(overrides: { fetchImpl?: typeof fetch } = {}): void {
+  config = undefined;
+  queue = [];
+  if (flushTimer) {
+    clearTimeout(flushTimer);
+    flushTimer = undefined;
+  }
+  droppedCount = 0;
+  warnedReasons.clear();
+  fetchImpl = overrides.fetchImpl ?? ((...args) => fetch(...args));
+  cachedInstance = null;
+  initStarted = false;
+  ephemeralState = null;
+  lastHeartbeatAt = 0;
+}
+
+/** TEST SEAM — current queue length. */
+export function __queueLengthForTest(): number {
+  return queue.length;
+}
+
+/** TEST SEAM — inject a resolved instance directly (skip the store round-trip). */
+export function __setInstanceForTest(info: InstanceInfo | null): void {
+  cachedInstance = info;
+}
+
+/** TEST SEAM — force the heartbeat throttle open/closed. */
+export function __setLastHeartbeatForTest(at: number): void {
+  lastHeartbeatAt = at;
+}