@oxygen-agent/cli 1.893.0 → 1.906.0

package/node_modules/@oxygen/shared/dist/egress-transport-readiness.js

@@ -0,0 +1,67 @@
+/**
+ * Shared/dedicated send-drain handoff timing. The worker and every status
+ * surface must evaluate the same readiness envelope: inventory existence alone
+ * is not proof that a dedicated process may claim sends yet.
+ */
+/** Longest a process may reuse one control-plane scope snapshot. */
+export const EGRESS_SEND_SCOPE_CACHE_MAX_AGE_MS = 60_000;
+/** Longest a tenant cycle may start provider sends under that snapshot. */
+export const EGRESS_SEND_AUTHORITY_RETENTION_MS = 45_000;
+/** Clock/scheduling margin between the old authority expiring and the new one starting. */
+export const EGRESS_SEND_HANDOFF_MARGIN_MS = 5_000;
+/**
+ * No new drain may become authoritative until every old cached scope AND every
+ * send cycle started on that cache's final millisecond have expired.
+ */
+export const DEDICATED_EGRESS_HANDOFF_DELAY_MS = EGRESS_SEND_SCOPE_CACHE_MAX_AGE_MS
+    + EGRESS_SEND_AUTHORITY_RETENTION_MS
+    + EGRESS_SEND_HANDOFF_MARGIN_MS;
+export const DEDICATED_EGRESS_LIVENESS_MAX_AGE_MS = 30 * 60_000;
+const FLY_DEDICATED_APP_PATTERN = /^oxygen-egress-(dev|prod)-[a-z0-9][a-z0-9-]*$/;
+export function evaluateDedicatedEgressTransportReadiness(input, now = Date.now()) {
+    const createdAtMs = input.createdAt?.getTime() ?? Number.POSITIVE_INFINITY;
+    if (now - createdAtMs < DEDICATED_EGRESS_HANDOFF_DELAY_MS) {
+        return { ready: false, reason: "handoff_pending" };
+    }
+    const verifiedAtMs = input.vendorVerifiedAt?.getTime() ?? Number.NEGATIVE_INFINITY;
+    if (now - verifiedAtMs > DEDICATED_EGRESS_LIVENESS_MAX_AGE_MS) {
+        return { ready: false, reason: "vendor_verification_missing_or_stale" };
+    }
+    return { ready: true };
+}
+/**
+ * The app name Fly assigns to this inventory row, or null when the row cannot
+ * authorize any dedicated process. Automated Fly purchase stores the app name
+ * as metadata.vendor_order_id because one app is exactly one vendor lease.
+ */
+export function readFlyDedicatedEgressAppName(input) {
+    const raw = input.metadata?.vendor_order_id;
+    if (typeof raw !== "string" || raw.length > 63)
+        return null;
+    const match = FLY_DEDICATED_APP_PATTERN.exec(raw);
+    return match?.[1] === input.environment ? raw : null;
+}
+/**
+ * Fly-specific readiness shared by the drain, status, and purchase replay.
+ * Timestamps cannot authorize an app by themselves: an orphan process for the
+ * same org must match the exact active row's immutable Fly app identity.
+ */
+export function evaluateFlyDedicatedEgressTransportReadiness(input, now = Date.now()) {
+    const appName = readFlyDedicatedEgressAppName(input);
+    if (!appName)
+        return { ready: false, reason: "dedicated_app_identity_missing" };
+    const readiness = evaluateDedicatedEgressTransportReadiness(input, now);
+    return readiness.ready ? { ready: true, appName } : readiness;
+}
+/**
+ * Retiring a drain is the inverse handoff: shared must remain excluded until
+ * every process that could have cached dedicated authority has expired it.
+ * Writers stamp this field with DB time while preserving the rest of metadata.
+ */
+export function dedicatedEgressRetirementStillCooling(metadata, now = Date.now()) {
+    const raw = metadata?.transport_retired_at;
+    if (typeof raw !== "string")
+        return false;
+    const retiredAt = Date.parse(raw);
+    return Number.isFinite(retiredAt) && now - retiredAt <= DEDICATED_EGRESS_HANDOFF_DELAY_MS;
+}

package/node_modules/@oxygen/shared/dist/index.d.ts

@@ -24,6 +24,7 @@ export * from "./crm-activity-events.js";
 export * from "./column-types.js";
 export * from "./copilot-errors.js";
 export * from "./copilot-journeys.js";
+export * from "./copilot-plan.js";
 export * from "./credit-guidance.js";
 export * from "./directory.js";
 export * from "./email-tracking-token.js";
@@ -49,6 +50,7 @@ export * from "./member-columns.js";
 export * from "./microsoft-consent-url.js";
 export * from "./networks.js";
 export * from "./person-name.js";
+export * from "./product-doctrine.js";
 export * from "./recipes.js";
 export * from "./sequence-template.js";
 export * from "./sequence-crm-events.js";
@@ -75,6 +77,7 @@ export * from "./postgres-text.js";
 export * from "./tags.js";
 export * from "./telemetry.js";
 export * from "./tenant-database-secret.js";
+export * from "./egress-transport-readiness.js";
 export * from "./timing.js";
 export * from "./type-guards.js";
 export * from "./worker-failures-queue.js";

package/node_modules/@oxygen/shared/dist/index.js

@@ -24,6 +24,7 @@ export * from "./crm-activity-events.js";
 export * from "./column-types.js";
 export * from "./copilot-errors.js";
 export * from "./copilot-journeys.js";
+export * from "./copilot-plan.js";
 export * from "./credit-guidance.js";
 export * from "./directory.js";
 export * from "./email-tracking-token.js";
@@ -49,6 +50,7 @@ export * from "./member-columns.js";
 export * from "./microsoft-consent-url.js";
 export * from "./networks.js";
 export * from "./person-name.js";
+export * from "./product-doctrine.js";
 export * from "./recipes.js";
 export * from "./sequence-template.js";
 export * from "./sequence-crm-events.js";
@@ -86,6 +88,7 @@ export * from "./postgres-text.js";
 export * from "./tags.js";
 export * from "./telemetry.js";
 export * from "./tenant-database-secret.js";
+export * from "./egress-transport-readiness.js";
 export * from "./timing.js";
 export * from "./type-guards.js";
 export * from "./worker-failures-queue.js";

package/node_modules/@oxygen/shared/dist/langfuse.d.ts

@@ -1,4 +1,3 @@
-import { Langfuse } from "langfuse";
 type EnvMap = Record<string, string | undefined>;
 export type LlmObservationLevel = "DEBUG" | "DEFAULT" | "WARNING" | "ERROR";
 export type LlmTraceBody = {
@@ -10,6 +9,13 @@ export type LlmTraceBody = {
     output?: unknown;
     metadata?: Record<string, unknown>;
     tags?: string[];
+    /**
+     * Root-observation span. v3 emitted a durationless trace object; v5's root IS
+     * an observation, so a root emitted once at completion should carry the real
+     * turn/run window. Defaults to "now" for both when omitted.
+     */
+    startTime?: Date;
+    endTime?: Date;
 };
 export type LlmSpanBody = {
     id: string;
@@ -22,6 +28,14 @@ export type LlmSpanBody = {
     endTime?: Date;
     level?: LlmObservationLevel;
     statusMessage?: string | null;
+    /**
+     * v5 observations-first correlation. Pass the SAME sessionId/userId the trace
+     * carries: in v5 these live on every observation, and session-level cost only
+     * adds up if the cost-bearing generations carry the session too. Optional so
+     * an emitter that has no session still traces.
+     */
+    sessionId?: string | null;
+    userId?: string | null;
 };
 export type LlmGenerationBody = LlmSpanBody & {
     model?: string | null;
@@ -36,6 +50,9 @@ export type LlmEventBody = {
     input?: unknown;
     metadata?: Record<string, unknown>;
     startTime?: Date;
+    /** See LlmSpanBody.sessionId. */
+    sessionId?: string | null;
+    userId?: string | null;
 };
 export type LlmTracingClient = {
     trace(body: LlmTraceBody): void;
@@ -53,16 +70,51 @@ export type LlmTracingClient = {
  */
 export declare function isLlmTracingEnabled(env?: EnvMap): boolean;
 export declare function resolveLlmTracingEnvironment(env?: EnvMap): string;
-type LangfuseLike = Pick<Langfuse, "trace" | "span" | "generation" | "event" | "flushAsync" | "shutdownAsync"> & {
-    on?: (event: string, listener: (...args: unknown[]) => void) => void;
+/**
+ * Deterministic Langfuse trace id for an external seed (copilot turn id, agent
+ * run id, AI-column run id).
+ *
+ * Byte-identical to `createTraceId(seed)` from @langfuse/tracing — sha256 of the
+ * UTF-8 seed, first 32 hex chars — but SYNCHRONOUS. The official helper returns
+ * a Promise (it uses WebCrypto), and every cross-link site here writes the id on
+ * a hot, synchronous path: the tenant ledger's `turn_started` payload and the
+ * Axiom `copilot.turn.finished` rollup both carry `langfuse_trace_id`, and a
+ * tracer's `traceId` is read synchronously. langfuse.test.ts pins this against
+ * the SDK's own implementation so the two can never drift.
+ */
+export declare function llmTraceIdForSeed(seed: string): string;
+export type LlmEmissionKind = "span" | "generation" | "event";
+/** v5 correlating attributes, propagated onto the emitted observation. */
+export type LlmCorrelation = {
+    traceName?: string;
+    userId?: string;
+    sessionId?: string;
+    tags?: string[];
+};
+export type LlmEmission = {
+    kind: LlmEmissionKind;
+    /** External seed (turn/run id) — hashed into the W3C trace id. */
+    traceSeed: string;
+    name: string;
+    /** Observation-level attributes, already compacted/bounded. */
+    attributes: Record<string, unknown>;
+    /** Correlating attributes applied via propagateAttributes(). */
+    correlation: LlmCorrelation;
+    startTime: Date;
+    endTime?: Date;
+};
+export type LlmEmitter = {
+    emit(emission: LlmEmission): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
 };
 /**
  * Construct a fail-open Langfuse client, or `null` when tracing is disabled or
  * misconfigured. Prefer the process-wide `getLlmTracingClient` in app code;
- * this direct factory exists for tests (inject `langfuseImpl`).
+ * this direct factory exists for tests (inject `emitterImpl`).
  */
 export declare function createLlmTracingClient(env?: EnvMap, options?: {
-    langfuseImpl?: LangfuseLike;
+    emitterImpl?: LlmEmitter;
 }): LlmTracingClient | null;
 export declare function getLlmTracingClient(env?: EnvMap): LlmTracingClient | null;
 /** Flush the singleton if it exists. Never rejects. Hang off request/cycle ends. */

package/node_modules/@oxygen/shared/dist/langfuse.js

@@ -1,18 +1,40 @@
 // LLM-observability transport (ADR 0014): Langfuse is the ONE sanctioned store
 // for full prompt/completion/tool-IO payloads. Axiom stays metadata-only (log.ts
 // redaction drops prompt/input/output-named fields BY DESIGN — that boundary is
-// unchanged), and PostHog stays sanitized product analytics. This module
-// deliberately rides the official `langfuse` SDK's own batched ingestion instead
-// of the OTel pipeline so prompt-bearing telemetry can never reach the Axiom
-// OTLP exporters by construction.
+// unchanged), and PostHog stays sanitized product analytics.
+//
+// Langfuse SDK v5 is OpenTelemetry-based, so the v3-era "never touch OTel"
+// isolation is now bought a different way: this module builds its OWN
+// TracerProvider, hands it to Langfuse via setLangfuseTracerProvider(), and
+// NEVER calls .register(). That matters — @vercel/otel (web) and NodeSDK
+// (worker) install Axiom OTLP exporters on the GLOBAL provider, and every
+// processor on a provider sees every span it creates. Registering globally
+// would therefore ship prompts, completions and tool IO straight into
+// oxygen-traces. The private provider is the load-bearing part of this file.
 //
 // Fail-open doctrine: tracing must never fail or stall product work. Every
 // method swallows internally (worst case: one throttled metadata-only warn via
 // log()), `flush()`/`shutdown()` never reject and are time-bounded, and a
-// missing flag/key yields `null` (callers no-op). Deterministic observation ids
-// are the caller's job — Langfuse upserts by id, which is what makes worker
-// lease-reclaim replays converge instead of duplicating.
-import { Langfuse } from "langfuse";
+// missing flag/key yields `null` (callers no-op).
+//
+// v5 semantics (CHANGED from v3):
+//   * Trace ids stay deterministic: sha256(seed) — same trace per turn/run, so
+//     lease-reclaim replays still converge onto ONE trace. See
+//     llmTraceIdForSeed.
+//   * Observation ids can NO LONGER be chosen. v5 observation ids are W3C span
+//     ids minted by OTel. The caller's stable id (`gen:<turn>:<n>`, `tool:…`)
+//     is preserved as metadata.oxygen_observation_id for correlation, but it no
+//     longer upserts: a replayed slice appends duplicate observations to the
+//     same trace instead of overwriting them.
+//   * v5 is observations-first: correlating attributes (userId, sessionId,
+//     tags) must ride EVERY observation, not just the root, or per-session cost
+//     rollups miss the cost-bearing generations. They are applied through
+//     propagateAttributes() around each emission — which is why the span/
+//     generation/event bodies carry sessionId/userId at all.
+//   * Trace-level input/output is deprecated in v5. Overall IO goes on the ROOT
+//     observation instead; setTraceIO()/setActiveTraceIO() are deliberately not
+//     used here.
+import { createHash } from "node:crypto";
 import { log } from "./log.js";
 const FLUSH_TIMEOUT_MS = 5_000;
 const WARN_THROTTLE_MS = 30_000;
@@ -56,6 +78,34 @@ export function resolveLlmTracingEnvironment(env = process.env) {
         return flyEnv === "production" ? "production" : "development";
     return "development";
 }
+/**
+ * Deterministic Langfuse trace id for an external seed (copilot turn id, agent
+ * run id, AI-column run id).
+ *
+ * Byte-identical to `createTraceId(seed)` from @langfuse/tracing — sha256 of the
+ * UTF-8 seed, first 32 hex chars — but SYNCHRONOUS. The official helper returns
+ * a Promise (it uses WebCrypto), and every cross-link site here writes the id on
+ * a hot, synchronous path: the tenant ledger's `turn_started` payload and the
+ * Axiom `copilot.turn.finished` rollup both carry `langfuse_trace_id`, and a
+ * tracer's `traceId` is read synchronously. langfuse.test.ts pins this against
+ * the SDK's own implementation so the two can never drift.
+ */
+export function llmTraceIdForSeed(seed) {
+    return createHash("sha256").update(seed, "utf8").digest("hex").slice(0, 32);
+}
+/**
+ * Deterministic synthetic parent span id for one trace.
+ *
+ * v5 does not let a caller choose observation ids, and the worker emits a single
+ * run's observations from different processes and slices — so there is no real
+ * root span id to nest under. Every observation of a run instead attaches to
+ * this stable pseudo-parent, which reproduces EXACTLY the flat shape the v3
+ * adapter already produced (v3 passed only `traceId`, never
+ * `parentObservationId`, so observations were already siblings of the trace).
+ */
+function rootSpanIdForSeed(seed) {
+    return createHash("sha256").update(`langfuse-root:${seed}`, "utf8").digest("hex").slice(0, 16);
+}
 // Bound one JSON-bearing field. Over the cap → an explicit truncation marker
 // (never a silently clipped payload that parses as complete).
 function boundJsonField(value) {
@@ -79,7 +129,7 @@ function boundJsonField(value) {
 function compact(body) {
     const out = {};
     for (const [key, value] of Object.entries(body)) {
-        if (value === undefined)
+        if (value === undefined || value === null)
             continue;
         out[key] = key === "input" || key === "output" ? boundJsonField(value) : value;
     }
@@ -97,13 +147,89 @@ function boundedNever(rejectable, warn) {
         });
     });
 }
+/**
+ * The real v4 emitter. Everything OTel is loaded LAZILY, on first emission, so
+ * a runtime with tracing disabled (the packed CLI, every test) never pays for
+ * the OTel tree — matching the "inert unless enabled" doctrine the flag already
+ * promises.
+ */
+function createOtelEmitter(env, warn) {
+    let handle = null;
+    const init = () => {
+        handle ??= (async () => {
+            try {
+                const [{ LangfuseSpanProcessor }, { BasicTracerProvider }, tracing] = await Promise.all([
+                    import("@langfuse/otel"),
+                    import("@opentelemetry/sdk-trace-base"),
+                    import("@langfuse/tracing"),
+                ]);
+                const processor = new LangfuseSpanProcessor({
+                    publicKey: env.LANGFUSE_PUBLIC_KEY,
+                    secretKey: env.LANGFUSE_SECRET_KEY,
+                    ...(env.LANGFUSE_BASE_URL?.trim() ? { baseUrl: env.LANGFUSE_BASE_URL.trim() } : {}),
+                    environment: resolveLlmTracingEnvironment(env),
+                });
+                // PRIVATE provider. Deliberately NOT .register()ed — see the file
+                // header: the global provider carries the Axiom OTLP exporters, and a
+                // processor there would receive every prompt-bearing span.
+                //
+                // v5's smart default span filter needs no override here: this provider
+                // only ever creates spans through the Langfuse tracer, and
+                // `langfuse-sdk` spans are in the default allow-list.
+                const provider = new BasicTracerProvider({ spanProcessors: [processor] });
+                tracing.setLangfuseTracerProvider(provider);
+                return {
+                    processor,
+                    startObservation: tracing.startObservation,
+                    propagateAttributes: tracing.propagateAttributes,
+                };
+            }
+            catch (error) {
+                warn(error, { stage: "init" });
+                return null;
+            }
+        })();
+        return handle;
+    };
+    return {
+        emit: (emission) => {
+            void init()
+                .then((h) => {
+                if (!h)
+                    return;
+                const traceId = llmTraceIdForSeed(emission.traceSeed);
+                // propagateAttributes is scope-based in v5: the observation must be
+                // created INSIDE the callback to inherit userId/sessionId/tags.
+                h.propagateAttributes(emission.correlation, () => {
+                    // The kind is a union, so no single overload matches it. Every
+                    // overload returns an observation extending the same base, and the
+                    // only method used here is .end() — so resolving against the span
+                    // overload is safe while the real kind is passed at runtime.
+                    const observation = h.startObservation(emission.name, emission.attributes, {
+                        asType: emission.kind,
+                        startTime: emission.startTime,
+                        parentSpanContext: {
+                            traceId,
+                            spanId: rootSpanIdForSeed(emission.traceSeed),
+                            traceFlags: 1,
+                        },
+                    });
+                    observation.end(emission.endTime);
+                });
+            })
+                .catch((error) => warn(error, { stage: emission.kind }));
+        },
+        flush: () => init().then((h) => h?.processor.forceFlush() ?? Promise.resolve()),
+        shutdown: () => init().then((h) => h?.processor.shutdown() ?? Promise.resolve()),
+    };
+}
 /**
  * Construct a fail-open Langfuse client, or `null` when tracing is disabled or
  * misconfigured. Prefer the process-wide `getLlmTracingClient` in app code;
- * this direct factory exists for tests (inject `langfuseImpl`).
+ * this direct factory exists for tests (inject `emitterImpl`).
  */
 export function createLlmTracingClient(env = process.env, options) {
-    if (!options?.langfuseImpl && !isLlmTracingEnabled(env))
+    if (!options?.emitterImpl && !isLlmTracingEnabled(env))
         return null;
     let lastWarnAtMs = 0;
     const warn = (error, context) => {
@@ -117,30 +243,7 @@ export function createLlmTracingClient(env = process.env, options) {
             ...context,
         });
     };
-    let sdk;
-    try {
-        sdk =
-            options?.langfuseImpl ??
-                new Langfuse({
-                    publicKey: env.LANGFUSE_PUBLIC_KEY,
-                    secretKey: env.LANGFUSE_SECRET_KEY,
-                    ...(env.LANGFUSE_BASE_URL?.trim() ? { baseUrl: env.LANGFUSE_BASE_URL.trim() } : {}),
-                    environment: resolveLlmTracingEnvironment(env),
-                    sdkIntegration: "oxygen",
-                });
-    }
-    catch (error) {
-        warn(error, { stage: "construct" });
-        return null;
-    }
-    // The SDK surfaces async ingest failures on its emitter; unheard, they are
-    // unhandled rejections. Route them into the throttled warn.
-    try {
-        sdk.on?.("error", (error) => warn(error, { stage: "ingest" }));
-    }
-    catch {
-        // an emitter-less test double is fine
-    }
+    const emitter = options?.emitterImpl ?? createOtelEmitter(env, warn);
     const guarded = (fn, stage) => {
         try {
             fn();
@@ -149,13 +252,110 @@ export function createLlmTracingClient(env = process.env, options) {
             warn(error, { stage });
         }
     };
+    // propagateAttributes rejects non-string ids and anything over 200 chars, and
+    // drops the whole attribute with a warning rather than truncating. Normalize
+    // here so a stray null/oversized id degrades to "absent", never to a dropped
+    // correlation on every observation of the run.
+    const correlate = (input) => {
+        const bounded = (value) => {
+            if (typeof value !== "string")
+                return undefined;
+            const trimmed = value.trim();
+            if (trimmed === "" || trimmed.length > 200)
+                return undefined;
+            return trimmed;
+        };
+        return compact({
+            traceName: input.traceName,
+            sessionId: bounded(input.sessionId),
+            userId: bounded(input.userId),
+            tags: input.tags,
+        });
+    };
     return {
-        trace: (body) => guarded(() => void sdk.trace(compact(body)), "trace"),
-        span: (body) => guarded(() => void sdk.span(compact(body)), "span"),
-        generation: (body) => guarded(() => void sdk.generation(compact(body)), "generation"),
-        event: (body) => guarded(() => void sdk.event(compact(body)), "event"),
-        flush: () => boundedNever(sdk.flushAsync(), (error) => warn(error, { stage: "flush" })),
-        shutdown: () => boundedNever(sdk.shutdownAsync(), (error) => warn(error, { stage: "shutdown" })),
+        trace: (body) => guarded(() => {
+            const startTime = body.startTime ?? new Date();
+            emitter.emit({
+                kind: "span",
+                traceSeed: body.id,
+                name: body.name,
+                // Overall trace IO lives on this ROOT observation — v5 deprecates
+                // trace-level input/output, so it is deliberately not set separately.
+                attributes: compact({
+                    input: body.input,
+                    output: body.output,
+                    metadata: { ...(body.metadata ?? {}), oxygen_observation_id: body.id },
+                }),
+                correlation: correlate({
+                    traceName: body.name,
+                    sessionId: body.sessionId,
+                    userId: body.userId,
+                    ...(body.tags ? { tags: body.tags } : {}),
+                }),
+                startTime,
+                endTime: body.endTime ?? startTime,
+            });
+        }, "trace"),
+        span: (body) => guarded(() => {
+            emitter.emit({
+                kind: "span",
+                traceSeed: body.traceId,
+                name: body.name,
+                attributes: compact({
+                    input: body.input,
+                    output: body.output,
+                    level: body.level,
+                    statusMessage: body.statusMessage,
+                    metadata: { ...(body.metadata ?? {}), oxygen_observation_id: body.id },
+                }),
+                correlation: correlate({ sessionId: body.sessionId, userId: body.userId }),
+                startTime: body.startTime ?? new Date(),
+                ...(body.endTime ? { endTime: body.endTime } : {}),
+            });
+        }, "span"),
+        generation: (body) => guarded(() => {
+            emitter.emit({
+                kind: "generation",
+                traceSeed: body.traceId,
+                name: body.name,
+                attributes: compact({
+                    input: body.input,
+                    output: body.output,
+                    level: body.level,
+                    statusMessage: body.statusMessage,
+                    model: body.model,
+                    completionStartTime: body.completionStartTime,
+                    usageDetails: body.usageDetails,
+                    costDetails: body.costDetails,
+                    metadata: { ...(body.metadata ?? {}), oxygen_observation_id: body.id },
+                }),
+                // The cost-bearing observation: v5 session cost only rolls up when
+                // the generation itself carries the session.
+                correlation: correlate({ sessionId: body.sessionId, userId: body.userId }),
+                startTime: body.startTime ?? new Date(),
+                ...(body.endTime ? { endTime: body.endTime } : {}),
+            });
+        }, "generation"),
+        event: (body) => guarded(() => {
+            const startTime = body.startTime ?? new Date();
+            emitter.emit({
+                kind: "event",
+                traceSeed: body.traceId,
+                name: body.name,
+                attributes: compact({
+                    input: body.input,
+                    metadata: { ...(body.metadata ?? {}), oxygen_observation_id: body.id },
+                }),
+                correlation: correlate({ sessionId: body.sessionId, userId: body.userId }),
+                startTime,
+                endTime: startTime,
+            });
+        }, "event"),
+        // The "never rejects, bounded at ~5s" contract is the CLIENT's, so it is
+        // enforced here rather than inside one emitter — an emitter that throws
+        // synchronously or rejects must still not escape into product code.
+        flush: () => boundedNever((async () => emitter.flush())(), (error) => warn(error, { stage: "flush" })),
+        shutdown: () => boundedNever((async () => emitter.shutdown())(), (error) => warn(error, { stage: "shutdown" })),
     };
 }
 // --- Process-wide singleton (both runtimes construct at most one client) ------
@@ -188,7 +388,8 @@ export function flushLlmTracing(env = process.env) {
 // then call scheduleLlmTracingFlush() and the flush runs post-response instead
 // of adding latency inside the request. Off-web (worker, tests) there is no
 // scheduler and the flush degrades to fire-and-forget — the worker's cycle-end
-// awaited flush + SDK interval flush are the durability guarantee there.
+// awaited flush + the processor's own interval flush are the durability
+// guarantee there.
 //
 // The registration lives on globalThis, not in a module-local: Next.js gives
 // instrumentation.ts and each route handler their own copy of this module, so a

package/node_modules/@oxygen/shared/dist/product-briefing-rules.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The briefing contract: every behavioural rule the OXYGEN session briefing has
+ * to state, and which half of it owns that rule.
+ *
+ * WHY THIS FILE EXISTS. The briefing is one string an agent reads once per
+ * session, so its only failure mode is silent omission: nothing crashes, no
+ * type breaks, and the rule simply stops being said. That happened. Splitting
+ * the MCP `instructions` into shared doctrine plus an MCP remainder dropped
+ * sixteen rules — sender rotation, the webhook/event/wait triggers, "never
+ * sends raw provider messages", the Knowledge citation and near-duplicate
+ * discipline, `ui://`, Crustdata routing, and more — while every existing
+ * assertion stayed green, because those assertions pinned lengths, the derived
+ * roster, and a handful of literal phrases, none of which is the rule set.
+ *
+ * WHY THIS SHAPE. There is no way to derive "this prose still tells an agent to
+ * rotate senders" from code, so the rule set has to be written down. What the
+ * ledger adds over sixteen inline `toContain` calls is:
+ *
+ * - Each entry names the behaviour in `rule`, so a future editor deleting a
+ *   sentence sees what they are deleting rather than an opaque magic string.
+ * - `probes` is a disjunction: ANY match satisfies the rule. The briefing lives
+ *   under a hard character budget, so it gets compressed often; probes key on
+ *   the distinctive noun ("sender rotation") and accept alternate phrasings, so
+ *   honest rewording stays green while deletion goes red.
+ * - `home` makes the shared/MCP split testable in both directions: a doctrine
+ *   rule missing from the doctrine is red, an MCP-mechanics rule that leaks into
+ *   the surface-neutral doctrine is red, and a rule stated in both halves is red
+ *   (duplication is what the split was meant to end, and it is paid for twice in
+ *   every session's context).
+ *
+ * WHAT IT DOES NOT CATCH, stated plainly so nobody over-trusts it:
+ *
+ * - Truth. A probe proves a phrase is present, not that the surrounding
+ *   sentence is correct or still says the right thing.
+ * - Rules never entered here. New behaviour has to be added to this ledger by
+ *   hand; the file is only as complete as its last review. `MINIMUM_RULE_COUNT`
+ *   in the tests is a ratchet against quietly gutting the ledger itself, not a
+ *   proof of completeness.
+ * - Whether an agent obeys any of it at runtime. That is an eval, not a test.
+ */
+/** Which half of the composed briefing must state a rule. */
+export type BriefingHome = "doctrine" | "mcp";
+export interface BriefingRule {
+    /** Stable identifier. Rename the prose, never this. */
+    id: string;
+    /** The behaviour in plain English: what an agent loses if this goes missing. */
+    rule: string;
+    /**
+     * `doctrine` — surface-neutral product truth, equally valid for a Copilot
+     * turn, an Agent run, and an MCP session; lives in `product-doctrine.ts`.
+     * `mcp` — MCP mechanics or literal `oxygen_*` tool names; lives in the MCP
+     * server's remainder, and must stay out of the doctrine.
+     */
+    home: BriefingHome;
+    /** Accepted phrasings. Any one match satisfies the rule. */
+    probes: readonly RegExp[];
+}
+export declare const OXYGEN_BRIEFING_RULES: readonly BriefingRule[];