@senad-d/observme 0.1.4 → 0.1.6

package/src/extension.ts

@@ -1,28 +1,18 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerObsCommand } from "./commands/obs.ts";
+import { assertObservMePiCapabilities } from "./pi/compatibility.ts";
 import { registerHandlers } from "./pi/handlers.ts";
-
-const extensionPiApiCompatibilityErrorMessage =
-  "ObservMe/Pi API compatibility error: expected Pi ExtensionAPI with on(eventName, handler) and registerCommand(name, options) before registering ObservMe.";
 const partialInitializationErrorMessage =
   "ObservMe extension initialization failed while registering /obs after Pi event handlers were already registered. Pi ExtensionAPI does not expose unregister hooks for event handlers or slash commands, so ObservMe cannot roll back partial registration; restart Pi after fixing command registration.";
 
 export default function observme(pi: ExtensionAPI): void {
-  assertRegistrationApiAvailable(pi);
+  assertObservMePiCapabilities(pi);
   // Only the Pi process environment is eligible for launcher-provided lineage.
   // Session config loading keeps trusted project .env values out of this boundary.
   registerHandlers(pi, { trustedParentContext: true });
   registerObsCommandWithPartialInitializationDiagnostic(pi);
 }
 
-function assertRegistrationApiAvailable(pi: ExtensionAPI): void {
-  const api = pi as Partial<ExtensionAPI> | null | undefined;
-
-  if (!api || typeof api.on !== "function" || typeof api.registerCommand !== "function") {
-    throw new TypeError(extensionPiApiCompatibilityErrorMessage);
-  }
-}
-
 function registerObsCommandWithPartialInitializationDiagnostic(pi: ExtensionAPI): void {
   try {
     registerObsCommand(pi);

package/src/integration.ts

@@ -7,14 +7,18 @@ export type ObservMeSpawnType = "command" | "tool" | "extension" | "unknown";
 export type ObservMeSpawnReason = "delegated_task" | "parallel_search" | "review" | "tool_wrapper" | "unknown";
 export type ObservMeAgentWaitReason = "dependency" | "rate_limit" | "child_running" | "unknown";
 export type ObservMeChildStatus = "starting" | "active" | "completed" | "failed" | "cancelled" | "orphaned";
+export type ObservMeTerminalChildStatus = Extract<ObservMeChildStatus, "completed" | "failed" | "cancelled">;
 export type ObservMeJoinStatus = "completed" | "failed" | "cancelled" | "timeout" | "unknown" | "waiting";
 export type ObservMeIntegrationFailureReason =
   | "session_unavailable"
   | "invalid_request"
   | "spawn_already_exists"
+  | "child_agent_already_exists"
   | "wait_already_exists"
   | "join_already_exists"
   | "spawn_not_found"
+  | "child_agent_mismatch"
+  | "invalid_terminal_transition"
   | "wait_not_found"
   | "join_not_found"
   | "operation_failed";
@@ -63,8 +67,8 @@ export interface ObservMeStartedSubagent {
 
 export interface ObservMeCompleteSubagentOptions {
   readonly childAgentId?: string;
-  readonly childStatus?: ObservMeChildStatus;
-  readonly outcome?: "completed" | "failed" | "cancelled";
+  readonly childStatus?: ObservMeTerminalChildStatus;
+  readonly outcome?: ObservMeTerminalChildStatus;
 }
 
 export interface ObservMeFailSubagentOptions {

package/src/otel/logs.ts

@@ -1,5 +1,5 @@
 import type { Logger } from "@opentelemetry/api-logs";
-import { createNoopLogger, logs } from "@opentelemetry/api-logs";
+import { createNoopLogger } from "@opentelemetry/api-logs";
 import type { Resource } from "@opentelemetry/resources";
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-proto";
@@ -7,6 +7,7 @@ import type { LogRecordExporter, LogRecordProcessor } from "@opentelemetry/sdk-l
 import { BatchLogRecordProcessor, LoggerProvider } from "@opentelemetry/sdk-logs";
 import type { LogsBatchConfig, ObservMeConfig } from "../config/schema.ts";
 import { appendOtlpSignalPath } from "./otlp-endpoint.ts";
+import { buildOtlpHttpAgentOptions, type OtlpHttpAgentOptions } from "./otlp-http-options.ts";
 import type { StartOtelSdkFactoryOptions } from "./sdk.ts";
 
 export const OBSERVME_LOGGER_NAME = "@senad-d/observme";
@@ -24,6 +25,7 @@ export interface OtlpLogExporterOptions {
   readonly url: string;
   readonly headers: Record<string, string>;
   readonly timeoutMillis: number;
+  readonly httpAgentOptions: OtlpHttpAgentOptions;
 }
 
 export interface LogProviderOptions {
@@ -45,7 +47,6 @@ export type LogProviderFactory = (options: LogProviderOptions) => LogProviderLik
 export interface ObservMeLogSdkOptions {
   readonly config: ObservMeConfig;
   readonly loggerName?: string;
-  readonly registerGlobal?: boolean;
   readonly exporterFactory?: LogExporterFactory;
   readonly processorFactory?: LogRecordProcessorFactory;
   readonly loggerProviderFactory?: LogProviderFactory;
@@ -62,10 +63,11 @@ const noopLogger = createNoopLogger();
 export class ObservMeLogSdk {
   readonly #config: ObservMeConfig;
   readonly #loggerName: string;
-  readonly #registerGlobal: boolean;
   readonly #exporterFactory: LogExporterFactory;
   readonly #processorFactory: LogRecordProcessorFactory;
   readonly #loggerProviderFactory: LogProviderFactory;
+  #exporter?: LogRecordExporter;
+  #processor?: LogRecordProcessor;
   #provider?: LogProviderLike;
   #logger: Logger = noopLogger;
   #state: LogPipelineState = "idle";
@@ -73,7 +75,6 @@ export class ObservMeLogSdk {
   constructor(options: ObservMeLogSdkOptions) {
     this.#config = options.config;
     this.#loggerName = options.loggerName ?? OBSERVME_LOGGER_NAME;
-    this.#registerGlobal = options.registerGlobal ?? true;
     this.#exporterFactory = options.exporterFactory ?? createOtlpLogExporter;
     this.#processorFactory = options.processorFactory ?? createBatchLogRecordProcessor;
     this.#loggerProviderFactory = options.loggerProviderFactory ?? createLogProvider;
@@ -89,21 +90,20 @@ export class ObservMeLogSdk {
 
   start(): void {
     if (this.#state === "started" || this.#state === "disabled") return;
-    if (!this.#config.logs.enabled) {
+    if (!this.#config.enabled || !this.#config.logs.enabled) {
       this.#state = "disabled";
       return;
     }
 
     const wiring = buildLogExporterWiring(this.#config);
-    const exporter = this.#exporterFactory(wiring.exporter);
-    const processor = this.#processorFactory(exporter, wiring.batch);
+    this.#exporter = this.#exporterFactory(wiring.exporter);
+    this.#processor = this.#processorFactory(this.#exporter, wiring.batch);
     this.#provider = this.#loggerProviderFactory({
       resource: createLogResource(this.#config),
-      processors: [processor],
+      processors: [this.#processor],
       forceFlushTimeoutMillis: this.#config.shutdown.flushTimeoutMs,
     });
 
-    if (this.#registerGlobal) logs.setGlobalLoggerProvider(this.#provider);
     this.#logger = this.#provider.getLogger(this.#loggerName);
     this.#state = "started";
   }
@@ -113,9 +113,19 @@ export class ObservMeLogSdk {
   }
 
   async shutdown(): Promise<void> {
-    await this.#provider?.shutdown?.();
-    this.#state = "shutdown";
-    this.#logger = noopLogger;
+    if (this.#state === "shutdown") return;
+
+    try {
+      if (this.#provider?.shutdown) await this.#provider.shutdown();
+      else if (this.#processor) await this.#processor.shutdown();
+      else await this.#exporter?.shutdown();
+    } finally {
+      this.#provider = undefined;
+      this.#processor = undefined;
+      this.#exporter = undefined;
+      this.#state = "shutdown";
+      this.#logger = noopLogger;
+    }
   }
 }
 
@@ -125,7 +135,7 @@ export function createLogSessionScopedOtelSdk(options: StartOtelSdkFactoryOption
 
 export function buildLogExporterWiring(config: ObservMeConfig): LogExporterWiring {
   return {
-    enabled: config.logs.enabled,
+    enabled: config.enabled && config.logs.enabled,
     exporter: buildOtlpLogExporterOptions(config),
     batch: { ...config.logs.batch },
   };
@@ -136,6 +146,7 @@ export function buildOtlpLogExporterOptions(config: ObservMeConfig): OtlpLogExpo
     url: resolveLogEndpoint(config),
     headers: { ...config.otlp.headers },
     timeoutMillis: config.otlp.timeoutMs,
+    httpAgentOptions: buildOtlpHttpAgentOptions(config),
   };
 }
 

package/src/otel/metrics.ts

@@ -1,5 +1,5 @@
 import type { Meter } from "@opentelemetry/api";
-import { createNoopMeter, metrics } from "@opentelemetry/api";
+import { createNoopMeter } from "@opentelemetry/api";
 import type { Resource } from "@opentelemetry/resources";
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-proto";
@@ -7,6 +7,7 @@ import type { IMetricReader, PushMetricExporter } from "@opentelemetry/sdk-metri
 import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
 import type { MetricsConfig, ObservMeConfig } from "../config/schema.ts";
 import { appendOtlpSignalPath } from "./otlp-endpoint.ts";
+import { buildOtlpHttpAgentOptions, type OtlpHttpAgentOptions } from "./otlp-http-options.ts";
 import type { StartOtelSdkFactoryOptions } from "./sdk.ts";
 
 export const OBSERVME_METER_NAME = "@senad-d/observme";
@@ -23,6 +24,7 @@ export interface OtlpMetricExporterOptions {
   readonly url: string;
   readonly headers: Record<string, string>;
   readonly timeoutMillis: number;
+  readonly httpAgentOptions: OtlpHttpAgentOptions;
 }
 
 export interface MetricReaderOptions {
@@ -48,7 +50,6 @@ export type MetricProviderFactory = (options: MetricProviderOptions) => MetricPr
 export interface ObservMeMetricSdkOptions {
   readonly config: ObservMeConfig;
   readonly meterName?: string;
-  readonly registerGlobal?: boolean;
   readonly exporterFactory?: MetricExporterFactory;
   readonly readerFactory?: MetricReaderFactory;
   readonly meterProviderFactory?: MetricProviderFactory;
@@ -65,10 +66,11 @@ const noopMeter = createNoopMeter();
 export class ObservMeMetricSdk {
   readonly #config: ObservMeConfig;
   readonly #meterName: string;
-  readonly #registerGlobal: boolean;
   readonly #exporterFactory: MetricExporterFactory;
   readonly #readerFactory: MetricReaderFactory;
   readonly #meterProviderFactory: MetricProviderFactory;
+  #exporter?: PushMetricExporter;
+  #reader?: IMetricReader;
   #provider?: MetricProviderLike;
   #meter: Meter = noopMeter;
   #state: MetricPipelineState = "idle";
@@ -76,7 +78,6 @@ export class ObservMeMetricSdk {
   constructor(options: ObservMeMetricSdkOptions) {
     this.#config = options.config;
     this.#meterName = options.meterName ?? OBSERVME_METER_NAME;
-    this.#registerGlobal = options.registerGlobal ?? true;
     this.#exporterFactory = options.exporterFactory ?? createOtlpMetricExporter;
     this.#readerFactory = options.readerFactory ?? createPeriodicMetricReader;
     this.#meterProviderFactory = options.meterProviderFactory ?? createMetricProvider;
@@ -92,20 +93,19 @@ export class ObservMeMetricSdk {
 
   start(): void {
     if (this.#state === "started" || this.#state === "disabled") return;
-    if (!this.#config.metrics.enabled) {
+    if (!this.#config.enabled || !this.#config.metrics.enabled) {
       this.#state = "disabled";
       return;
     }
 
     const wiring = buildMetricExporterWiring(this.#config);
-    const exporter = this.#exporterFactory(wiring.exporter);
-    const reader = this.#readerFactory(exporter, wiring.reader);
+    this.#exporter = this.#exporterFactory(wiring.exporter);
+    this.#reader = this.#readerFactory(this.#exporter, wiring.reader);
     this.#provider = this.#meterProviderFactory({
       resource: createMetricResource(this.#config),
-      readers: [reader],
+      readers: [this.#reader],
     });
 
-    if (this.#registerGlobal) metrics.setGlobalMeterProvider(this.#provider);
     this.#meter = this.#provider.getMeter(this.#meterName);
     this.#state = "started";
   }
@@ -115,9 +115,19 @@ export class ObservMeMetricSdk {
   }
 
   async shutdown(): Promise<void> {
-    await this.#provider?.shutdown?.();
-    this.#state = "shutdown";
-    this.#meter = noopMeter;
+    if (this.#state === "shutdown") return;
+
+    try {
+      if (this.#provider?.shutdown) await this.#provider.shutdown();
+      else if (this.#reader) await this.#reader.shutdown();
+      else await this.#exporter?.shutdown();
+    } finally {
+      this.#provider = undefined;
+      this.#reader = undefined;
+      this.#exporter = undefined;
+      this.#state = "shutdown";
+      this.#meter = noopMeter;
+    }
   }
 }
 
@@ -127,7 +137,7 @@ export function createMetricSessionScopedOtelSdk(options: StartOtelSdkFactoryOpt
 
 export function buildMetricExporterWiring(config: ObservMeConfig): MetricExporterWiring {
   return {
-    enabled: config.metrics.enabled,
+    enabled: config.enabled && config.metrics.enabled,
     exporter: buildOtlpMetricExporterOptions(config),
     reader: {
       exportIntervalMillis: config.metrics.exportIntervalMillis,
@@ -141,6 +151,7 @@ export function buildOtlpMetricExporterOptions(config: ObservMeConfig): OtlpMetr
     url: resolveMetricEndpoint(config),
     headers: { ...config.otlp.headers },
     timeoutMillis: config.otlp.timeoutMs,
+    httpAgentOptions: buildOtlpHttpAgentOptions(config),
   };
 }
 

package/src/otel/otlp-endpoint.ts

@@ -1,6 +1,45 @@
+export type OtlpEndpointFailureClass =
+  | "unresolved_placeholder"
+  | "malformed_url"
+  | "unsupported_protocol"
+  | "embedded_credentials"
+  | "query_not_supported"
+  | "fragment_not_supported";
+
+export function classifyOtlpEndpointFailure(endpoint: string): OtlpEndpointFailureClass | undefined {
+  if (endpoint.includes("${")) return "unresolved_placeholder";
+  if (/\s/u.test(endpoint)) return "malformed_url";
+
+  const parsedEndpoint = parseEndpoint(endpoint);
+  if (!parsedEndpoint) return "malformed_url";
+  if (parsedEndpoint.protocol !== "http:" && parsedEndpoint.protocol !== "https:") return "unsupported_protocol";
+  if (parsedEndpoint.username || parsedEndpoint.password) return "embedded_credentials";
+  if (endpoint.includes("?")) return "query_not_supported";
+  if (endpoint.includes("#")) return "fragment_not_supported";
+  return undefined;
+}
+
 export function appendOtlpSignalPath(baseEndpoint: string, signalPath: string): string {
-  const trimmedBaseEndpoint = removeTrailingSlashes(baseEndpoint);
-  return `${trimmedBaseEndpoint}${signalPath}`;
+  const failureClass = classifyOtlpEndpointFailure(baseEndpoint);
+  if (failureClass) throw new TypeError(`OTLP endpoint is invalid (${failureClass}).`);
+
+  const endpoint = new URL(baseEndpoint);
+  endpoint.pathname = `${removeTrailingSlashes(endpoint.pathname)}${normalizeSignalPath(signalPath)}`;
+  return endpoint.href;
+}
+
+function parseEndpoint(endpoint: string): URL | undefined {
+  try {
+    return new URL(endpoint);
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeSignalPath(signalPath: string): string {
+  let start = 0;
+  while (start < signalPath.length && signalPath[start] === "/") start += 1;
+  return `/${signalPath.slice(start)}`;
 }
 
 function removeTrailingSlashes(value: string): string {

package/src/otel/otlp-http-options.ts

@@ -0,0 +1,11 @@
+import type { ObservMeConfig } from "../config/schema.ts";
+
+export interface OtlpHttpAgentOptions {
+  readonly rejectUnauthorized: boolean;
+}
+
+export function buildOtlpHttpAgentOptions(config: ObservMeConfig): OtlpHttpAgentOptions {
+  return {
+    rejectUnauthorized: !config.otlp.tls.insecureSkipVerify,
+  };
+}

package/src/otel/sdk.ts

@@ -1,9 +1,24 @@
 import type { ObservMeConfig } from "../config/schema.ts";
+import { readDiagnosticMessage, sanitizeDiagnosticText } from "../diagnostics/sanitize.ts";
 import type { AgentLineageContext } from "../pi/agent-lineage.ts";
-import type { BoundedOtelOperationResult, OtelShutdownLogSink, ShutdownableOtelSdk } from "./shutdown.ts";
+import type {
+  BoundedOtelOperationResult,
+  OtelOperationSettlement,
+  OtelShutdownLogSink,
+  ShutdownableOtelSdk,
+} from "./shutdown.ts";
 import { flushOtelSdk, shutdownOtelSdk } from "./shutdown.ts";
 
-export type OtelSdkLifecycleState = "idle" | "starting" | "started" | "shutting_down" | "shutdown";
+// `failed` is terminal for startup; shutdown cleanup can remain owned for observation or retry.
+export type OtelSdkLifecycleState =
+  | "idle"
+  | "starting"
+  | "started"
+  | "failed"
+  | "shutting_down"
+  | "shutdown_pending"
+  | "shutdown_failed"
+  | "shutdown";
 
 export interface StartOtelSdkFactoryOptions {
   readonly config: ObservMeConfig;
@@ -35,6 +50,10 @@ export class ObservMeOtelSdkController {
   readonly #sdkFactory: SessionScopedOtelSdkFactory;
   readonly #logger?: OtelShutdownLogSink;
   #sdk?: SessionScopedOtelSdk;
+  #startPromise?: Promise<SessionScopedOtelSdk>;
+  #shutdownPromise?: Promise<BoundedOtelOperationResult>;
+  #pendingShutdown?: Promise<OtelOperationSettlement>;
+  #startupCleanupResult?: BoundedOtelOperationResult;
   #state: OtelSdkLifecycleState = "idle";
 
   constructor(options: ObservMeOtelSdkControllerOptions) {
@@ -62,13 +81,42 @@ export class ObservMeOtelSdkController {
 
   async start(): Promise<SessionScopedOtelSdk> {
     if (this.#state === "started" && this.#sdk) return this.#sdk;
+    if (this.#state === "starting" && this.#startPromise) return this.#startPromise;
+    if (this.#state === "failed") throw new Error("ObservMe OTEL SDK controller cannot be restarted after failed startup.");
     if (this.#state === "shutdown") throw new Error("ObservMe OTEL SDK controller cannot be restarted after shutdown.");
+    if (this.#state !== "idle") {
+      throw new Error(`ObservMe OTEL SDK controller cannot start while cleanup state is ${this.#state}.`);
+    }
 
     this.#state = "starting";
-    this.#sdk = this.#sdkFactory({ config: this.#config, agent: this.#agent });
-    await this.#sdk.start?.();
-    this.#state = "started";
-    return this.#sdk;
+    this.#startPromise = this.startOnce();
+    return this.#startPromise;
+  }
+
+  private async startOnce(): Promise<SessionScopedOtelSdk> {
+    try {
+      this.#sdk = this.#sdkFactory({ config: this.#config, agent: this.#agent });
+      await this.#sdk.start?.();
+      this.#state = "started";
+      return this.#sdk;
+    } catch (error) {
+      if (error instanceof ObservMeOtelStartupError) {
+        this.#startupCleanupResult = error.cleanup ?? completedShutdown();
+      } else {
+        this.#startupCleanupResult = sanitizeStartupCleanupResult(
+          await shutdownOtelSdk(
+            this.#sdk,
+            this.#config.shutdown.flushTimeoutMs,
+            this.#logger,
+          ),
+        );
+      }
+      this.#sdk = undefined;
+      this.#state = "failed";
+      throw toOtelStartupError(error, this.#startupCleanupResult);
+    } finally {
+      this.#startPromise = undefined;
+    }
   }
 
   async flush(timeoutMs: number = this.#config.shutdown.flushTimeoutMs): Promise<BoundedOtelOperationResult> {
@@ -76,12 +124,86 @@ export class ObservMeOtelSdkController {
   }
 
   async shutdown(timeoutMs: number = this.#config.shutdown.flushTimeoutMs): Promise<BoundedOtelOperationResult> {
-    if (this.#state === "shutdown") return { operation: "shutdown", completed: true, timedOut: false };
+    if (this.#state === "shutdown") return completedShutdown();
+    if (this.#state === "failed") return this.#startupCleanupResult ?? completedShutdown();
+    if (this.#state === "shutting_down" && this.#shutdownPromise) return this.#shutdownPromise;
+    if (this.#state === "shutdown_pending" && this.#pendingShutdown) {
+      return pendingShutdown(this.#pendingShutdown);
+    }
 
     this.#state = "shutting_down";
-    const result = await shutdownOtelSdk(this.#sdk, timeoutMs, this.#logger);
+    this.#shutdownPromise = this.shutdownOnce(timeoutMs);
+    return this.#shutdownPromise;
+  }
+
+  private async shutdownOnce(timeoutMs: number): Promise<BoundedOtelOperationResult> {
+    try {
+      const result = await shutdownOtelSdk(this.#sdk, timeoutMs, this.#logger);
+      this.applyShutdownResult(result);
+      return result;
+    } finally {
+      this.#shutdownPromise = undefined;
+    }
+  }
+
+  private applyShutdownResult(result: BoundedOtelOperationResult): void {
+    if (result.timedOut && result.settlement) {
+      this.#pendingShutdown = result.settlement;
+      this.#state = "shutdown_pending";
+      void result.settlement.then(this.observePendingShutdown.bind(this, result.settlement));
+      return;
+    }
+
+    if (result.error || !result.completed) {
+      this.#state = "shutdown_failed";
+      return;
+    }
+
+    this.releaseShutdownOwnership();
+  }
+
+  private observePendingShutdown(
+    pending: Promise<OtelOperationSettlement>,
+    settlement: OtelOperationSettlement,
+  ): void {
+    if (this.#pendingShutdown !== pending) return;
+
+    this.#pendingShutdown = undefined;
+    if (settlement.error || !settlement.completed) {
+      this.#state = "shutdown_failed";
+      return;
+    }
+
+    this.releaseShutdownOwnership();
+  }
+
+  private releaseShutdownOwnership(): void {
+    this.#sdk = undefined;
     this.#state = "shutdown";
-    return result;
+  }
+}
+
+export function toOtelStartupError(
+  error: unknown,
+  cleanup?: BoundedOtelOperationResult,
+): Error {
+  if (error instanceof ObservMeOtelStartupError) return error;
+
+  const detail = sanitizeDiagnosticText(readDiagnosticMessage(error));
+  const safeCleanup = cleanup ? sanitizeStartupCleanupResult(cleanup) : undefined;
+  return new ObservMeOtelStartupError(
+    `ObservMe OTEL startup failed: ${detail}. ${startupCleanupGuidance(safeCleanup)}`,
+    safeCleanup,
+  );
+}
+
+export class ObservMeOtelStartupError extends Error {
+  readonly cleanup?: BoundedOtelOperationResult;
+
+  constructor(message: string, cleanup?: BoundedOtelOperationResult) {
+    super(message);
+    this.name = "ObservMeOtelStartupError";
+    this.cleanup = cleanup;
   }
 }
 
@@ -99,6 +221,30 @@ export function createNoopSessionScopedOtelSdk(): SessionScopedOtelSdk {
   return new NoopSessionScopedOtelSdk();
 }
 
+function startupCleanupGuidance(cleanup: BoundedOtelOperationResult | undefined): string {
+  if (!cleanup) return "Check OTLP settings and Collector availability before retrying.";
+  if (cleanup.timedOut) return "Cleanup exceeded its timeout; restart Pi before retrying.";
+  if (cleanup.error) return "Cleanup also failed; restart Pi before retrying.";
+  return "Started providers were cleaned up; check OTLP settings and Collector availability before retrying.";
+}
+
+function completedShutdown(): BoundedOtelOperationResult {
+  return { operation: "shutdown", completed: true, timedOut: false };
+}
+
+function pendingShutdown(settlement: Promise<OtelOperationSettlement>): BoundedOtelOperationResult {
+  return { operation: "shutdown", completed: false, timedOut: true, settlement };
+}
+
+function sanitizeStartupCleanupResult(result: BoundedOtelOperationResult): BoundedOtelOperationResult {
+  if (!result.error) return result;
+
+  return {
+    ...result,
+    error: new Error(sanitizeDiagnosticText(readDiagnosticMessage(result.error))),
+  };
+}
+
 class NoopSessionScopedOtelSdk implements SessionScopedOtelSdk {
   async start(): Promise<void> {
     await Promise.resolve();

package/src/otel/shutdown.ts

@@ -9,11 +9,19 @@ export interface ShutdownableOtelSdk extends FlushableOtelSdk {
   shutdown?: () => Promise<void> | void;
 }
 
+export interface OtelOperationSettlement {
+  readonly operation: "flush" | "shutdown";
+  readonly completed: boolean;
+  readonly timedOut: false;
+  readonly error?: unknown;
+}
+
 export interface BoundedOtelOperationResult {
   readonly operation: "flush" | "shutdown";
   readonly completed: boolean;
   readonly timedOut: boolean;
   readonly error?: unknown;
+  readonly settlement?: Promise<OtelOperationSettlement>;
 }
 
 export interface OtelShutdownLogSink {
@@ -54,10 +62,10 @@ export async function runBoundedOtelOperation(
   const timeoutResult = timeoutOperation(operation, normalizedTimeoutMs, timeoutController.signal);
 
   try {
-    const completed = completeOperation(operation, action);
-    return await Promise.race([completed, timeoutResult]);
-  } catch (error) {
-    return { operation, completed: false, timedOut: false, error };
+    const settlement = settleOperation(operation, action);
+    const result = await Promise.race([settlement, timeoutResult]);
+    if (!result.timedOut) return result;
+    return { ...result, settlement };
   } finally {
     timeoutController.abort();
   }
@@ -68,12 +76,16 @@ function normalizeTimeoutMs(timeoutMs: number): number {
   return timeoutMs;
 }
 
-async function completeOperation(
+async function settleOperation(
   operation: "flush" | "shutdown",
   action: () => Promise<void> | void,
-): Promise<BoundedOtelOperationResult> {
-  await action();
-  return completedOperation(operation);
+): Promise<OtelOperationSettlement> {
+  try {
+    await action();
+    return completedOperation(operation);
+  } catch (error) {
+    return { operation, completed: false, timedOut: false, error };
+  }
 }
 
 async function timeoutOperation(
@@ -84,17 +96,33 @@ async function timeoutOperation(
   return delay(timeoutMs, { operation, completed: false, timedOut: true } as const, { signal });
 }
 
-function completedOperation(operation: "flush" | "shutdown"): BoundedOtelOperationResult {
+function completedOperation(operation: "flush" | "shutdown"): OtelOperationSettlement {
   return { operation, completed: true, timedOut: false };
 }
 
 function logBoundedOperationIssue(result: BoundedOtelOperationResult, logger: OtelShutdownLogSink | undefined): void {
   if (result.timedOut) {
-    logger?.warn?.(`ObservMe OTEL ${result.operation} exceeded timeout and was abandoned.`);
+    warnOtelOperation(logger, `ObservMe OTEL ${result.operation} exceeded timeout and remains pending.`);
+    void result.settlement?.then(logLateOperationIssue.bind(undefined, logger));
     return;
   }
 
-  if (result.error) logger?.warn?.(`ObservMe OTEL ${result.operation} failed: ${formatError(result.error)}`);
+  logLateOperationIssue(logger, result);
+}
+
+function logLateOperationIssue(
+  logger: OtelShutdownLogSink | undefined,
+  result: Pick<BoundedOtelOperationResult, "operation" | "error">,
+): void {
+  if (result.error) warnOtelOperation(logger, `ObservMe OTEL ${result.operation} failed: ${formatError(result.error)}`);
+}
+
+function warnOtelOperation(logger: OtelShutdownLogSink | undefined, message: string): void {
+  try {
+    logger?.warn?.(message);
+  } catch {
+    return;
+  }
 }
 
 function formatError(error: unknown): string {