@senad-d/observme 0.1.3 → 0.1.5

package/examples/integrations/subagent-runner.ts

@@ -1,13 +1,13 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
   requestObservMeIntegration,
-  type ObservMeChildStatus,
   type ObservMeIntegrationApi,
   type ObservMeJoinStatus,
   type ObservMeProcessEnvironment,
   type ObservMeSpawnReason,
   type ObservMeSpawnType,
   type ObservMeStartedSubagent,
+  type ObservMeTerminalChildStatus,
 } from "@senad-d/observme/integration";
 
 /**
@@ -70,7 +70,6 @@ export class ObservableSubagentRunner<Request, Handle, Value> {
 
     try {
       handle = await this.#transport.launch(options.request, context, options.signal);
-      completeObservMeLaunch(observme, started);
     } catch (error) {
       failObservMeLaunch(observme, started, error);
       throw error;
@@ -90,10 +89,12 @@ export class ObservableSubagentRunner<Request, Handle, Value> {
     try {
       const result = await this.#transport.wait(handle, signal);
       endObservMeWait(observme, started, wait, result);
+      completeObservMeChild(observme, started, childStatus(result.status));
       recordObservMeJoin(observme, started, result);
       return result;
     } catch (error) {
       endObservMeWaitFailure(observme, started, wait);
+      completeObservMeChild(observme, started, "failed");
       recordObservMeJoinFailure(observme, started);
       throw error;
     }
@@ -127,14 +128,16 @@ function createLaunchContext(
   };
 }
 
-function completeObservMeLaunch(
+function completeObservMeChild(
   observme: ObservMeIntegrationApi | undefined,
   started: ObservMeStartedSubagent | undefined,
+  status: ObservMeTerminalChildStatus,
 ): void {
   if (!observme || !started) return;
   observme.completeSubagent(started.spawnId, {
     childAgentId: started.childAgentId,
-    childStatus: "active",
+    childStatus: status,
+    outcome: status,
   });
 }
 
@@ -245,7 +248,7 @@ function recordObservMeJoinFailure(
   });
 }
 
-function childStatus(status: ChildRunResult<unknown>["status"]): ObservMeChildStatus {
+function childStatus(status: ChildRunResult<unknown>["status"]): ObservMeTerminalChildStatus {
   if (status === "completed") return "completed";
   if (status === "cancelled") return "cancelled";
   return "failed";

package/examples/observme.yaml

@@ -6,7 +6,6 @@ observme:
   enabled: true
   environment: development
   tenant: local-dev
-  replayOnStart: false
 
   otlp:
     endpoint: http://localhost:4318
@@ -14,7 +13,6 @@ observme:
     timeoutMs: 3000
     headers: {}
     tls:
-      enabled: false
       insecureSkipVerify: false
     signalEndpoints:
       traces: http://localhost:4318/v1/traces
@@ -46,6 +44,8 @@ observme:
     propagateTraceContext: true
     propagateToSubagents: true
     capabilityEnv: OBSERVME_AGENT_CAPABILITY
+    # Opt in to one validated, branch-local custom entry for reload/resume recovery.
+    # This entry never participates in LLM context.
     writeCorrelationEntry: false
 
   traces:
@@ -61,6 +61,7 @@ observme:
     enabled: true
     exportIntervalMillis: 15000
     exportTimeoutMillis: 3000
+    activeAgentLeaseDurationMillis: 60000
 
   logs:
     enabled: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@senad-d/observme",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "ObservMe: a Pi extension that instruments Pi agent sessions and exports OpenTelemetry traces, metrics, and logs to an external observability stack (OTel Collector, Grafana Tempo/Loki/Prometheus).",
   "license": "MIT",
@@ -57,7 +57,9 @@
     "lint:fix": "eslint . --fix",
     "format:check": "node scripts/check-format.mjs",
     "test": "node --test test/*.test.mjs test/*.test.ts",
+    "test:active-agent-lease:contracts": "node --test test/active-agent-lease.test.ts test/alerts.test.mjs test/cardinality.test.ts test/config-defaults.test.mjs test/config-loader.test.mjs test/config-validation.test.mjs test/dashboards.test.mjs test/metrics.test.ts test/pi-handlers.test.mjs test/semconv-metrics.test.mjs",
     "test:integration:collector": "node --test test/integration/collector-debug.test.mjs",
+    "test:integration:active-agent-lease": "node --test test/integration/active-agent-lease.test.mjs",
     "test:integration:grafana-stack": "node --test test/integration/grafana-stack.test.mjs",
     "test:coverage": "node scripts/test-coverage.mjs",
     "smoke:discover": "node scripts/smoke-observability.mjs",
@@ -65,12 +67,20 @@
     "smoke:handlers": "node scripts/smoke-handler-execution.mjs",
     "smoke:pi-lifecycle": "node scripts/smoke-pi-lifecycle.mjs",
     "smoke:pi-runtime": "node scripts/smoke-pi-runtime.mjs",
+    "validate:pi-compatibility": "npm run typecheck && npm run typecheck:test && node --test test/pi-compatibility.test.ts test/event-mapping.test.ts test/template.test.mjs && npm run smoke:packaged && npm run smoke:handlers && npm run smoke:pi-lifecycle && npm run smoke:pi-runtime",
     "validate:grafana-obs": "node scripts/validate-grafana-obs-flow.mjs",
     "check": "node --check scripts/check-package-contents.mjs && node --check scripts/test-coverage.mjs && node --check scripts/smoke-observability.mjs && node --check scripts/smoke-packaged-install.mjs && node --check scripts/smoke-handler-execution.mjs && node --check scripts/smoke-pi-lifecycle.mjs && node --check scripts/smoke-pi-runtime.mjs && node --check scripts/validate-grafana-obs-flow.mjs",
     "pack:dry-run": "npm pack --dry-run --json",
     "check:pack": "node scripts/check-package-contents.mjs",
     "validate": "npm run lint && npm run test && npm run check:pack && npm run smoke:packaged && npm run smoke:handlers && npm run smoke:pi-lifecycle && npm run smoke:pi-runtime"
   },
+  "observmeCompatibility": {
+    "pi": {
+      "minimumVersion": "0.80.5",
+      "releaseTestedVersion": "0.80.6",
+      "supportedRange": ">=0.80.5 <0.81.0"
+    }
+  },
   "pi": {
     "extensions": [
       "./src/extension.ts"
@@ -86,8 +96,8 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.80.2",
-    "@earendil-works/pi-coding-agent": "^0.80.2",
+    "@earendil-works/pi-ai": "0.80.6",
+    "@earendil-works/pi-coding-agent": "0.80.6",
     "@eslint/js": "^10.0.1",
     "@types/node": "^26.1.1",
     "c8": "^11.0.0",
@@ -95,7 +105,7 @@
     "globals": "^17.7.0",
     "typebox": "^1.3.6",
     "typescript": "6.0.3",
-    "typescript-eslint": "^8.63.0"
+    "typescript-eslint": "8.63.0"
   },
   "dependencies": {
     "@opentelemetry/api": "1.9.1",

package/src/commands/obs-agents.ts

@@ -6,6 +6,11 @@ import type { PrometheusFetch, PrometheusMetricSeries, QueryResult } from "../qu
 import { createPrometheusQueryClient } from "../query/prometheus.ts";
 import type { TimeRange, TraceSummary } from "../query/tempo.ts";
 import { createTempoQueryClient } from "../query/tempo.ts";
+import {
+  boundObsCommandOutput,
+  normalizeObsBackendLabel,
+  normalizeObsBackendLabelRecord,
+} from "../safety/display-bounds.ts";
 import { COMMON_SPAN_ATTRIBUTES } from "../semconv/attributes.ts";
 import { completeObsSubcommand, isExactObsSubcommandRequest } from "./obs-args.ts";
 import { loadObsCommandConfig, notifyObsCommand } from "./obs-command-support.ts";
@@ -187,8 +192,8 @@ export function renderObsAgents(snapshot: ObsAgentsSnapshot): string {
   const latestChild = readLatestChild(snapshot.children);
   const lines = [
     `Workflow: ${formatUnknown(snapshot.workflowId)} root=${formatUnknown(snapshot.workflowRootAgentId ?? snapshot.rootAgentId)}`,
-    `Agent: ${formatUnknown(snapshot.agentId)} (${snapshot.role} depth=${snapshot.depth})`,
-    `Session: ${formatUnknown(normalizeOptionalString(snapshot.sessionId))}`,
+    `Agent: ${formatUnknown(snapshot.agentId)} (${formatUnknown(snapshot.role)} depth=${snapshot.depth})`,
+    `Session: ${formatUnknown(snapshot.sessionId)}`,
     `Subagents spawned in current trace: ${snapshot.fanoutCount}`,
     `Current tree: depth=${snapshot.treeDepth} width=${snapshot.treeWidth} active=${snapshot.activeChildren} orphaned=${snapshot.orphanCount}`,
     `Recent children: ${renderRecentChildren(snapshot.children, snapshot.recentChildrenLimit)}`,
@@ -200,7 +205,7 @@ export function renderObsAgents(snapshot: ObsAgentsSnapshot): string {
     `Aggregate agent metrics (last ${OBS_AGENTS_WINDOW}): ${renderAggregateRows(snapshot.aggregateRows)}`,
     `Lineage drill-down: ${renderLineageDrilldown(snapshot)}`,
   );
-  return lines.join("\n");
+  return boundObsCommandOutput(lines.join("\n"));
 }
 
 class ObsAgentsCommand {
@@ -322,9 +327,9 @@ function toObsAgentAggregateRow(series: PrometheusMetricSeries): ObsAgentAggrega
   if (value === undefined) return undefined;
 
   return {
-    labels: { ...series.metric },
+    labels: normalizeObsBackendLabelRecord(series.metric),
     value,
-    timestampUnixSeconds: series.value?.timestampUnixSeconds,
+    timestampUnixSeconds: normalizeObsBackendLabel(series.value?.timestampUnixSeconds),
   };
 }
 
@@ -379,12 +384,12 @@ function selectRecentChildrenForRender(
 
 function renderRecentChild(child: ObsAgentChildRow): string {
   const orphan = child.orphaned ? " orphaned" : "";
-  return `${child.agentId} status=${child.status} depth=${child.depth}${orphan}`;
+  return `${formatUnknown(child.agentId)} status=${formatUnknown(child.status)} depth=${child.depth}${orphan}`;
 }
 
 function renderLatestChild(child: ObsAgentChildRow, hints: readonly ObsAgentWaitJoinHint[]): string {
   const joinHint = readLatestHintForChild(child.agentId, hints, "join");
-  return `${child.agentId} status=${child.status} active=${child.activeChildren} join=${formatDuration(joinHint?.durationMs)}`;
+  return `${formatUnknown(child.agentId)} status=${formatUnknown(child.status)} active=${child.activeChildren} join=${formatDuration(joinHint?.durationMs)}`;
 }
 
 function readLatestHintForChild(
@@ -408,7 +413,8 @@ function renderWaitJoinHint(hint: ObsAgentWaitJoinHint | undefined): string {
   if (!hint) return "none";
 
   const status = hint.joinStatus ?? hint.childStatus ?? (hint.active ? "waiting" : "complete");
-  return `${hint.kind}:${hint.childAgentId ?? hint.spawnId ?? hint.id} status=${status} duration=${formatDuration(hint.durationMs)}`;
+  const target = hint.childAgentId ?? hint.spawnId ?? hint.id;
+  return `${formatUnknown(hint.kind)}:${formatUnknown(target)} status=${formatUnknown(status)} duration=${formatDuration(hint.durationMs)}`;
 }
 
 function renderAggregateRows(rows: ObsAgentsAggregateRows): string {
@@ -416,7 +422,7 @@ function renderAggregateRows(rows: ObsAgentsAggregateRows): string {
 }
 
 function renderLineageDrilldown(snapshot: ObsAgentsSnapshot): string {
-  const attrs = Object.keys(snapshot.tempoSearchAttributes).join(", ") || "none";
+  const attrs = Object.keys(snapshot.tempoSearchAttributes).map(formatUnknown).join(", ") || "none";
   const traceCount = snapshot.traces.length;
   const latestTrace = normalizeOptionalString(snapshot.traces[0]?.traceId) ?? normalizeOptionalString(snapshot.traceId);
   const traceSuffix = latestTrace ? ` latest_trace=${latestTrace}` : "";
@@ -454,8 +460,7 @@ function normalizeRecentChildrenLimit(value: number | undefined): number {
 }
 
 function normalizeOptionalString(value: string | undefined): string | undefined {
-  const trimmed = value?.trim();
-  return trimmed || undefined;
+  return normalizeObsBackendLabel(value);
 }
 
 function isObsAgentsRequest(args: string): boolean {
@@ -463,7 +468,7 @@ function isObsAgentsRequest(args: string): boolean {
 }
 
 function formatUnknown(value: string | undefined): string {
-  return value ?? "unknown";
+  return normalizeObsBackendLabel(value) ?? "unknown";
 }
 
 function formatDuration(value: number | undefined): string {

package/src/commands/obs-backfill.ts

@@ -2,7 +2,7 @@ import { setTimeout as delay } from "node:timers/promises";
 import type { ExtensionAPI, SessionEntry, SessionHeader } from "@earendil-works/pi-coding-agent";
 import type { LoadSessionConfigOptions } from "../config/load-config.ts";
 import type { ObservMeConfig } from "../config/schema.ts";
-import { ObservMeLogSdk } from "../otel/logs.ts";
+import { type ObservMeLogSdk, createLogSessionScopedOtelSdk } from "../otel/logs.ts";
 import type { BoundedOtelOperationResult } from "../otel/shutdown.ts";
 import { flushOtelSdk, shutdownOtelSdk } from "../otel/shutdown.ts";
 import { applyContentCapturePolicy } from "../privacy/content-capture.ts";
@@ -308,7 +308,7 @@ export function createObsBackfillLogExporter(
   config: ObservMeConfig,
   options: ObsBackfillOperationOptions = {},
 ): ObsBackfillExporter {
-  const sdk = new ObservMeLogSdk({ config });
+  const sdk = createLogSessionScopedOtelSdk({ config });
   sdk.start();
   return new ObsBackfillLogExporter(sdk, resolveBackfillOperationTimeoutMs(options, OBS_BACKFILL_DEFAULT_OPERATION_TIMEOUT_MS));
 }

package/src/commands/obs-command-support.ts

@@ -1,6 +1,7 @@
 import type { LoadSessionConfigOptions } from "../config/load-config.ts";
 import { loadSessionConfig } from "../config/load-config.ts";
 import type { ObservMeConfig } from "../config/schema.ts";
+import { boundObsCommandOutput } from "../safety/display-bounds.ts";
 
 export type ObsCommandNotificationType = "info" | "warning" | "error";
 
@@ -33,7 +34,7 @@ export async function notifyObsCommand(
   message: string,
   type: ObsCommandNotificationType,
 ): Promise<void> {
-  await ctx.ui?.notify?.(message, type);
+  await ctx.ui?.notify?.(boundObsCommandOutput(message), type);
 }
 
 export function normalizeObsCommandTimeoutMs(value: number | undefined, fallback: number, invalidFallback = fallback): number {

package/src/commands/obs-cost.ts

@@ -3,6 +3,11 @@ import type { LoadSessionConfigOptions } from "../config/load-config.ts";
 import type { ObservMeConfig } from "../config/schema.ts";
 import type { PrometheusFetch, PrometheusMetricSeries, QueryResult } from "../query/prometheus.ts";
 import { createPrometheusQueryClient } from "../query/prometheus.ts";
+import {
+  boundObsCommandOutput,
+  normalizeObsBackendLabel,
+  selectObsCommandRows,
+} from "../safety/display-bounds.ts";
 import { completeObsSubcommand, parseObsSubcommandArgs } from "./obs-args.ts";
 import { loadObsCommandConfig, notifyObsCommand } from "./obs-command-support.ts";
 import { appendObsRecoveryHint, formatObsCommandFailure } from "./obs-diagnostics.ts";
@@ -114,15 +119,19 @@ export async function getObsCostSnapshot(
 
 export function renderObsCost(snapshot: ObsCostSnapshot): string {
   const rows = snapshot.rows.map(normalizeObsCostRow).filter(isObsCostRow);
-  const lines = [`Cost by model/provider (last ${snapshot.window})`];
+  const selection = selectObsCommandRows(rows);
+  const window = normalizeObsBackendLabel(snapshot.window) ?? OBS_COST_WINDOW;
+  const lines = [`Cost by model/provider (last ${window})`];
 
   if (rows.length === 0) {
     lines.push(appendObsRecoveryHint("No cost metrics found.", OBS_COST_NO_METRICS_NEXT_ACTION));
-    return lines.join("\n");
+    return boundObsCommandOutput(lines.join("\n"));
   }
 
-  lines.push(...rows.map(renderObsCostRow), `Total: ${formatUsd(sumObsCostRows(rows))}`);
-  return lines.join("\n");
+  lines.push(...selection.rows.map(renderObsCostRow));
+  if (selection.omittedCount > 0) lines.push(`… ${selection.omittedCount} cost row(s) omitted`);
+  lines.push(`Total: ${formatUsd(sumObsCostRows(rows))}`);
+  return boundObsCommandOutput(lines.join("\n"));
 }
 
 class ObsCostCommand {
@@ -187,12 +196,11 @@ function parseCostUsd(value: string | number | undefined): number | undefined {
 }
 
 function normalizeMetricLabel(value: string | undefined): string {
-  return normalizeOptionalString(value) ?? "unknown";
+  return normalizeObsBackendLabel(value) ?? "unknown";
 }
 
 function normalizeOptionalString(value: string | undefined): string | undefined {
-  const trimmed = value?.trim();
-  return trimmed || undefined;
+  return normalizeObsBackendLabel(value);
 }
 
 function renderObsCostRow(row: ObsCostRow): string {

package/src/commands/obs-health.ts

@@ -1,6 +1,10 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { LoadSessionConfigOptions } from "../config/load-config.ts";
 import type { ObservMeConfig } from "../config/schema.ts";
+import {
+  createObsTransportSecuritySnapshot,
+  type ObsTransportSecuritySnapshot,
+} from "../config/transport-security.ts";
 import { readDiagnosticMessage, sanitizeDiagnosticText } from "../diagnostics/sanitize.ts";
 import { getGrafanaHealth, type GrafanaFetch } from "../query/grafana.ts";
 import { completeObsSubcommand, isExactObsSubcommandRequest } from "./obs-args.ts";
@@ -31,6 +35,7 @@ export interface ObsHealthCheckResult {
 export interface ObsHealthSnapshot {
   readonly timeoutMs: number;
   readonly checks: readonly ObsHealthCheckResult[];
+  readonly transportSecurity?: ObsTransportSecuritySnapshot;
 }
 
 export interface ObsHealthSnapshotOptions {
@@ -112,11 +117,18 @@ export async function getObsHealthSnapshot(
     getGrafanaHealth(config, { fetch: options.fetch, timeoutMs }),
   ]);
 
-  return { timeoutMs, checks: [collectorCheck, ...grafanaHealth.checks] };
+  return {
+    timeoutMs,
+    checks: [collectorCheck, ...grafanaHealth.checks],
+    transportSecurity: createObsTransportSecuritySnapshot(config),
+  };
 }
 
 export function renderObsHealth(snapshot: ObsHealthSnapshot): string {
-  return snapshot.checks.map(renderObsHealthCheck).join("\n");
+  return [
+    ...formatObsHealthTransportSecurity(snapshot.transportSecurity),
+    ...snapshot.checks.map(renderObsHealthCheck),
+  ].join("\n");
 }
 
 class ObsHealthCommand {
@@ -229,6 +241,14 @@ function failedHealthResult(label: string, kind: ObsHealthCheckKind, error: unkn
   };
 }
 
+function formatObsHealthTransportSecurity(security: ObsTransportSecuritySnapshot | undefined): string[] {
+  if (!security) return [];
+  return [
+    `Collector transport security: ${security.collector}`,
+    `Grafana transport security: ${security.grafana}`,
+  ];
+}
+
 function renderObsHealthCheck(check: ObsHealthCheckResult): string {
   const status = formatObsHealthStatus(check);
   const detail = formatObsHealthDetail(check);

package/src/commands/obs-loki-summary.ts

@@ -1,4 +1,6 @@
+import { normalizeQueryResultCount } from "../config/query-limits.ts";
 import type { LogResult, TimeRange } from "../query/loki.ts";
+import { normalizeObsBackendLabel } from "../safety/display-bounds.ts";
 import { LOG_ATTRIBUTES } from "../semconv/attributes.ts";
 
 export interface ObsLokiLogSummaryRow {
@@ -25,10 +27,8 @@ export interface ObsLokiTimeRangeOptions {
 }
 
 const defaultRangeHours = 1;
-const minimumMaxLogs = 1;
 const millisecondsPerHour = 60 * 60 * 1000;
 const nanosecondsPerMillisecond = 1_000_000n;
-const maximumDisplayValueLength = 96;
 const safeEventBodyPattern = /^[A-Za-z0-9_.:-]{1,96}$/u;
 const integerNanosecondsPattern = /^-?\d+$/u;
 const unknownTimestamp = "unknown-time";
@@ -51,8 +51,7 @@ export function formatObsLokiWindow(options: ObsLokiTimeRangeOptions = {}): stri
 }
 
 export function normalizeObsLokiMaxLogs(value: number | undefined): number {
-  if (value === undefined || !Number.isFinite(value) || value < minimumMaxLogs) return minimumMaxLogs;
-  return Math.trunc(value);
+  return normalizeQueryResultCount(value);
 }
 
 export function toObsLokiLogSummaryRow(log: LogResult): ObsLokiLogSummaryRow {
@@ -140,10 +139,7 @@ function normalizeObsLokiLogSummaryRow(row: ObsLokiLogSummaryRow): ObsLokiLogSum
 }
 
 function normalizeDisplayValue(value: string | undefined): string | undefined {
-  const normalized = value?.replace(/\s+/gu, " ").trim();
-  if (!normalized) return undefined;
-  if (normalized.length <= maximumDisplayValueLength) return normalized;
-  return `${normalized.slice(0, maximumDisplayValueLength - 1)}…`;
+  return normalizeObsBackendLabel(value);
 }
 
 function renderObsLokiLogSummaryRow(row: ObsLokiLogSummaryRow): string {

package/src/commands/obs-session.ts

@@ -1,5 +1,9 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ObservMeConfig } from "../config/schema.ts";
+import { readDiagnosticMessage, sanitizeDiagnosticText } from "../diagnostics/sanitize.ts";
+import { buildGrafanaTraceLink } from "../query/trace-link.ts";
 import { completeObsSubcommand, isExactObsSubcommandRequest } from "./obs-args.ts";
+import { notifyObsCommand } from "./obs-command-support.ts";
 
 export interface ObsSessionCommandContext {
   readonly ui: {
@@ -15,6 +19,7 @@ export interface ObsSessionSnapshot {
   readonly toolCalls: number;
   readonly costUsd: number;
   readonly traceLink?: string;
+  readonly traceLinkError?: string;
 }
 
 export interface ObsSessionRuntimeStatePatch {
@@ -25,12 +30,13 @@ export interface ObsSessionRuntimeStatePatch {
   readonly toolCalls?: number;
   readonly costUsd?: number;
   readonly traceLink?: string;
+  readonly traceLinkError?: string;
 }
 
 export interface StartObsSessionRuntimeStateOptions {
   readonly sessionId?: string;
   readonly traceId?: string;
-  readonly traceUrlTemplate?: string;
+  readonly config?: ObservMeConfig;
 }
 
 export type ObsSessionProvider = (ctx: ObsSessionCommandContext) => Promise<ObsSessionSnapshot> | ObsSessionSnapshot;
@@ -47,6 +53,12 @@ interface MutableObsSessionRuntimeState {
   toolCalls: number;
   costUsd: number;
   traceLink?: string;
+  traceLinkError?: string;
+}
+
+interface ObsSessionTraceLinkState {
+  readonly traceLink?: string;
+  readonly traceLinkError?: string;
 }
 
 const OBS_COMMAND_NAME = "obs";
@@ -71,15 +83,15 @@ export async function handleObsSessionCommand(
   options: RegisterObsSessionCommandOptions = {},
 ): Promise<void> {
   if (!isObsSessionRequest(args)) {
-    await notifySession(ctx, "Usage: /obs session", "warning");
+    await notifyObsCommand(ctx, "Usage: /obs session", "warning");
     return;
   }
 
   try {
     const snapshot = await resolveObsSessionSnapshot(ctx, options);
-    await notifySession(ctx, renderObsSession(snapshot), "info");
+    await notifyObsCommand(ctx, renderObsSession(snapshot), snapshot.traceLinkError ? "warning" : "info");
   } catch (error) {
-    await notifySession(ctx, `ObservMe session unavailable: ${formatError(error)}`, "error");
+    await notifyObsCommand(ctx, `ObservMe session unavailable: ${formatError(error)}`, "error");
   }
 }
 
@@ -103,12 +115,13 @@ export function renderObsSession(snapshot: ObsSessionSnapshot): string {
   ];
 
   if (normalized.traceLink) lines.push(`Open trace: ${normalized.traceLink}`);
+  else if (normalized.traceLinkError) lines.push(`Trace link unavailable: ${normalized.traceLinkError}`);
   return lines.join("\n");
 }
 
 export function startObsSessionRuntimeState(options: StartObsSessionRuntimeStateOptions): void {
   const traceId = normalizeTraceId(options.traceId);
-  const traceLink = buildObsSessionTraceLink(traceId, options.traceUrlTemplate);
+  const traceLinkState = createObsSessionTraceLinkState(options.config, traceId);
 
   replaceObsSessionRuntimeState({
     sessionId: normalizeString(options.sessionId),
@@ -117,10 +130,23 @@ export function startObsSessionRuntimeState(options: StartObsSessionRuntimeState
     llmCalls: 0,
     toolCalls: 0,
     costUsd: 0,
-    traceLink,
+    ...traceLinkState,
   });
 }
 
+function createObsSessionTraceLinkState(
+  config: ObservMeConfig | undefined,
+  traceId: string | undefined,
+): ObsSessionTraceLinkState {
+  if (!config || !traceId) return {};
+
+  try {
+    return { traceLink: buildGrafanaTraceLink(config, traceId) };
+  } catch (error) {
+    return { traceLinkError: sanitizeDiagnosticText(readDiagnosticMessage(error)) };
+  }
+}
+
 export function updateObsSessionRuntimeState(patch: ObsSessionRuntimeStatePatch): void {
   if (patch.sessionId !== undefined) runtimeSessionState.sessionId = normalizeString(patch.sessionId);
   if (patch.traceId !== undefined) runtimeSessionState.traceId = normalizeTraceId(patch.traceId);
@@ -129,6 +155,7 @@ export function updateObsSessionRuntimeState(patch: ObsSessionRuntimeStatePatch)
   if (patch.toolCalls !== undefined) runtimeSessionState.toolCalls = normalizeCount(patch.toolCalls);
   if (patch.costUsd !== undefined) runtimeSessionState.costUsd = normalizeCost(patch.costUsd);
   if (patch.traceLink !== undefined) runtimeSessionState.traceLink = normalizeString(patch.traceLink);
+  if (patch.traceLinkError !== undefined) runtimeSessionState.traceLinkError = normalizeString(patch.traceLinkError);
 }
 
 export function recordObsSessionTurn(count = 1): void {
@@ -152,20 +179,6 @@ export function clearObsSessionRuntimeState(): void {
   replaceObsSessionRuntimeState(createEmptyObsSessionRuntimeState());
 }
 
-export function buildObsSessionTraceLink(traceId: string | undefined, traceUrlTemplate: string | undefined): string | undefined {
-  const template = normalizeString(traceUrlTemplate);
-  if (!traceId || !template) return undefined;
-
-  if (template.includes("{{traceId}}")) return template.replaceAll("{{traceId}}", encodeURIComponent(traceId));
-  if (template.includes("${traceId}")) return template.replaceAll("${traceId}", encodeURIComponent(traceId));
-  if (template.includes("{traceId}")) return template.replaceAll("{traceId}", encodeURIComponent(traceId));
-  if (template.includes("$traceId")) return template.replaceAll("$traceId", encodeURIComponent(traceId));
-  if (template.includes("%TRACE_ID%")) return template.replaceAll("%TRACE_ID%", encodeURIComponent(traceId));
-  if (template.includes("__TRACE_ID__")) return template.replaceAll("__TRACE_ID__", encodeURIComponent(traceId));
-  if (template.includes("...")) return template.replaceAll("...", encodeURIComponent(traceId));
-  return undefined;
-}
-
 class ObsSessionCommand {
   readonly #options: RegisterObsSessionCommandOptions;
 
@@ -194,6 +207,7 @@ function replaceObsSessionRuntimeState(state: MutableObsSessionRuntimeState): vo
   runtimeSessionState.toolCalls = state.toolCalls;
   runtimeSessionState.costUsd = state.costUsd;
   runtimeSessionState.traceLink = state.traceLink;
+  runtimeSessionState.traceLinkError = state.traceLinkError;
 }
 
 function createEmptyObsSessionRuntimeState(): MutableObsSessionRuntimeState {
@@ -214,6 +228,7 @@ function normalizeObsSessionSnapshot(snapshot: ObsSessionSnapshot): ObsSessionSn
     toolCalls: normalizeCount(snapshot.toolCalls),
     costUsd: normalizeCost(snapshot.costUsd),
     traceLink: normalizeString(snapshot.traceLink),
+    traceLinkError: normalizeString(snapshot.traceLinkError),
   };
 }
 
@@ -246,14 +261,6 @@ function isObsSessionRequest(args: string): boolean {
   return isExactObsSubcommandRequest(args, OBS_SESSION_SUBCOMMAND);
 }
 
-async function notifySession(
-  ctx: ObsSessionCommandContext,
-  message: string,
-  type: "info" | "warning" | "error",
-): Promise<void> {
-  await ctx.ui?.notify?.(message, type);
-}
-
 function formatError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }