@senad-d/observme 0.1.4 → 0.1.6

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);
 }

package/src/commands/obs-status.ts

@@ -1,9 +1,21 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import type { LoadSessionConfigOptions, SessionConfigDiagnostics, SessionConfigEffectiveSource } from "../config/load-config.ts";
+import type {
+  LoadSessionConfigOptions,
+  SessionConfigDiagnostics,
+  SessionConfigEffectiveSource,
+  SessionConfigEnvFileStatus,
+  SessionConfigEnvironmentStatus,
+  SessionConfigProjectStatus,
+} from "../config/load-config.ts";
 import { loadSessionConfigWithDiagnostics } from "../config/load-config.ts";
 import type { CaptureConfig, ObservMeConfig } from "../config/schema.ts";
+import {
+  describeGrafanaTransportSecurity,
+  describeOtlpTransportSecurity,
+} from "../config/transport-security.ts";
 import { getGrafanaQueryReadiness } from "../query/grafana-readiness.ts";
 import { completeObsSubcommand, isExactObsSubcommandRequest } from "./obs-args.ts";
+import { notifyObsCommand } from "./obs-command-support.ts";
 import { sanitizeObsDiagnosticText } from "./obs-diagnostics.ts";
 
 export interface ObsStatusCommandContext {
@@ -93,15 +105,15 @@ export async function handleObsStatusCommand(
   options: RegisterObsStatusCommandOptions = {},
 ): Promise<void> {
   if (!isObsStatusRequest(args)) {
-    await notifyStatus(ctx, "Usage: /obs status", "warning");
+    await notifyObsCommand(ctx, "Usage: /obs status", "warning");
     return;
   }
 
   try {
     const snapshot = await resolveObsStatusSnapshot(ctx, options);
-    await notifyStatus(ctx, renderObsStatus(snapshot), "info");
+    await notifyObsCommand(ctx, renderObsStatus(snapshot), "info");
   } catch (error) {
-    await notifyStatus(ctx, `ObservMe status unavailable: ${sanitizeObsDiagnosticText(formatError(error))}`, "error");
+    await notifyObsCommand(ctx, `ObservMe status unavailable: ${sanitizeObsDiagnosticText(formatError(error))}`, "error");
   }
 }
 
@@ -129,8 +141,10 @@ export function renderObsStatus(snapshot: ObsStatusSnapshot): string {
   const lines = [
     `ObservMe: ${formatEnabled(config.enabled)}`,
     `OTLP endpoint: ${formatSafeConfiguredEndpoint(config.otlp.endpoint)}`,
+    `OTLP transport security: ${describeOtlpTransportSecurity(config)}`,
     ...formatConfigDiagnosticsLines(snapshot.configDiagnostics),
     `Grafana URL: ${formatSafeConfiguredUrl(config.query.grafana.url)}`,
+    `Grafana transport security: ${describeGrafanaTransportSecurity(config)}`,
     `Grafana query readiness: ${formatGrafanaQueryReadiness(config)}`,
     `Traces: ${formatEnabled(signalEnabled(config, config.traces.enabled))}`,
     `Metrics: ${formatEnabled(signalEnabled(config, config.metrics.enabled))}`,
@@ -237,10 +251,6 @@ function isObsStatusRequest(args: string): boolean {
   return isExactObsSubcommandRequest(args, OBS_STATUS_SUBCOMMAND, { allowEmpty: true });
 }
 
-async function notifyStatus(ctx: ObsStatusCommandContext, message: string, type: "info" | "warning" | "error"): Promise<void> {
-  await ctx.ui?.notify?.(message, type);
-}
-
 function formatCaptureLines(capture: CaptureConfig): string[] {
   return [
     `Prompt capture: ${formatEnabled(capture.prompts)}`,
@@ -259,7 +269,10 @@ function formatConfigDiagnosticsLines(diagnostics: SessionConfigDiagnostics | un
 
   return [
     `Config source: ${formatConfigEffectiveSource(diagnostics.effectiveSource)}`,
-    `Project config: ${formatProjectConfigStatus(diagnostics)}`,
+    ...formatGlobalConfigStatus(diagnostics),
+    `Project config: ${formatProjectConfigStatus(diagnostics.projectConfigStatus)}`,
+    ...formatEnvFileStatus(diagnostics.envFileStatus),
+    ...formatEnvironmentStatus(diagnostics.environmentStatus),
     ...formatConfigRejectionLines(diagnostics),
   ];
 }
@@ -281,13 +294,43 @@ function formatConfigEffectiveSource(source: SessionConfigEffectiveSource): stri
   return "defaults";
 }
 
-function formatProjectConfigStatus(diagnostics: SessionConfigDiagnostics): string {
-  if (diagnostics.projectConfigStatus === "loaded") return "loaded (trusted .pi/observme.yaml)";
-  if (diagnostics.projectConfigStatus === "skipped_untrusted") {
+function formatGlobalConfigStatus(diagnostics: SessionConfigDiagnostics): string[] {
+  if (!diagnostics.globalConfigStatus) return [];
+  return [`Global config: ${formatFileSourceStatus(diagnostics.globalConfigStatus, "global config")}`];
+}
+
+function formatProjectConfigStatus(status: SessionConfigProjectStatus): string {
+  if (status === "loaded") return "loaded (trusted .pi/observme.yaml)";
+  if (status === "skipped_untrusted") {
     return "skipped (project is untrusted; safe defaults/global/env only)";
   }
+  if (status === "missing") return "missing (trusted project has no .pi/observme.yaml)";
+  return formatFileSourceStatus(status, "trusted .pi/observme.yaml");
+}
+
+function formatEnvFileStatus(status: SessionConfigEnvFileStatus | undefined): string[] {
+  if (!status) return [];
+  if (status === "skipped_untrusted") return ["Project .env: skipped (project is untrusted)"];
+  if (status === "skipped_disabled") return ["Project .env: skipped (loading is disabled)"];
+  return [`Project .env: ${formatFileSourceStatus(status, "trusted project .env")}`];
+}
+
+function formatEnvironmentStatus(status: SessionConfigEnvironmentStatus | undefined): string[] {
+  if (!status) return [];
+  if (status === "loaded") return ["Process environment: loaded"];
+  if (status === "rejected") return ["Process environment: rejected (malformed supported override)"];
+  return ["Process environment: no ObservMe values"];
+}
 
-  return "missing (trusted project has no .pi/observme.yaml)";
+function formatFileSourceStatus(
+  status: Exclude<SessionConfigProjectStatus, "skipped_untrusted">,
+  label: string,
+): string {
+  if (status === "loaded") return "loaded";
+  if (status === "missing") return "missing";
+  if (status === "malformed") return `ignored (${label} is malformed)`;
+  if (status === "unreadable") return `ignored (${label} is unreadable)`;
+  return `ignored (${label} was structurally rejected)`;
 }
 
 function formatGrafanaQueryReadiness(config: ObservMeConfig): string {

package/src/commands/obs-tools.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, isExactObsSubcommandRequest } from "./obs-args.ts";
 import { loadObsCommandConfig, notifyObsCommand } from "./obs-command-support.ts";
 import { appendObsRecoveryHint, formatObsCommandFailure } from "./obs-diagnostics.ts";
@@ -126,22 +131,29 @@ export async function getObsToolsSnapshot(
 export function renderObsTools(snapshot: ObsToolsSnapshot): string {
   const calls = snapshot.calls.map(normalizeObsToolCallRow).filter(isObsToolCallRow);
   const failures = snapshot.failures.map(normalizeObsToolFailureRow).filter(isObsToolFailureRow);
-  const lines = [`Tool calls by tool (last ${snapshot.window})`];
+  const callSelection = selectObsCommandRows(calls);
+  const failureSelection = selectObsCommandRows(failures);
+  const window = normalizeObsBackendLabel(snapshot.window) ?? OBS_TOOLS_WINDOW;
+  const lines = [`Tool calls by tool (last ${window})`];
 
   if (calls.length === 0) {
     lines.push(appendObsRecoveryHint("No tool call metrics found.", OBS_TOOLS_NO_CALLS_NEXT_ACTION));
   } else {
-    lines.push(...calls.map(renderObsToolCallRow));
+    lines.push(...callSelection.rows.map(renderObsToolCallRow));
+    if (callSelection.omittedCount > 0) lines.push(`… ${callSelection.omittedCount} tool call row(s) omitted`);
   }
 
-  lines.push(`Tool failures by tool/error (last ${snapshot.window})`);
+  lines.push(`Tool failures by tool/error (last ${window})`);
   if (failures.length === 0) {
     lines.push(appendObsRecoveryHint("No tool failure metrics found.", OBS_TOOLS_NO_FAILURES_NEXT_ACTION));
   } else {
-    lines.push(...failures.map(renderObsToolFailureRow));
+    lines.push(...failureSelection.rows.map(renderObsToolFailureRow));
+    if (failureSelection.omittedCount > 0) {
+      lines.push(`… ${failureSelection.omittedCount} tool failure row(s) omitted`);
+    }
   }
 
-  return lines.join("\n");
+  return boundObsCommandOutput(lines.join("\n"));
 }
 
 class ObsToolsCommand {
@@ -231,12 +243,11 @@ function parseRatePerSecond(value: string | number | undefined): number | undefi
 }
 
 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 renderObsToolCallRow(row: ObsToolCallRow): string {

package/src/commands/obs-trace.ts

@@ -92,6 +92,8 @@ const OBS_COMMAND_NAME = "obs";
 const OBS_TRACE_SUBCOMMAND = "trace";
 const OBS_TRACE_USAGE = "Usage: /obs trace [--last-turn|--session <session-id>]";
 const OBS_TRACE_TEMPO_ERROR_NEXT_ACTION = "run /obs health and verify query.grafana.url, Grafana credentials, and the Tempo datasource UID.";
+const OBS_TRACE_LINK_CONFIG_ERROR_NEXT_ACTION =
+  "set query.links.traceUrlTemplate to a supported trace-id placeholder or the ellipsis fallback, then verify query.grafana.url.";
 const OBS_TRACE_SESSION_ERROR_NEXT_ACTION = "wait for a Pi turn or query a generated session id with /obs trace --session <session-id>.";
 const OBS_TRACE_NOT_FOUND_NEXT_ACTION = "check the session id, wait for trace export, then verify Tempo datasource with /obs health.";
 const OBS_TRACE_ACTIVE_SESSION_NOTE = "Trace visibility: active sessions may show ended child spans before the root pi.session span; the root is exported after session_shutdown.";
@@ -398,6 +400,9 @@ export function resolveObsTraceDiagnostic(error: unknown): ObsCommandRecoveryHin
   const message = readObsDiagnosticMessage(error);
 
   if (isObsTraceSessionErrorMessage(message)) return { subsystem: "Session trace", nextAction: OBS_TRACE_SESSION_ERROR_NEXT_ACTION };
+  if (isObsTraceLinkConfigErrorMessage(message)) {
+    return { subsystem: "Grafana trace link", nextAction: OBS_TRACE_LINK_CONFIG_ERROR_NEXT_ACTION };
+  }
   if (isObsTraceNotFoundMessage(message)) return { subsystem: "Tempo", nextAction: OBS_TRACE_NOT_FOUND_NEXT_ACTION };
   return { subsystem: "Tempo", nextAction: OBS_TRACE_TEMPO_ERROR_NEXT_ACTION };
 }
@@ -406,6 +411,10 @@ function isObsTraceSessionErrorMessage(message: string): boolean {
   return /No current ObservMe session trace|No last-turn ObservMe trace|Unsafe ObservMe session id/u.test(message);
 }
 
+function isObsTraceLinkConfigErrorMessage(message: string): boolean {
+  return /Grafana trace link configuration is invalid/u.test(message);
+}
+
 function isObsTraceNotFoundMessage(message: string): boolean {
   return /No trace was found/u.test(message);
 }

package/src/commands/obs.ts

@@ -22,6 +22,7 @@ import { handleObsToolsCommand } from "./obs-tools.ts";
 import type { ObsTraceCommandContext, RegisterObsTraceCommandOptions } from "./obs-trace.ts";
 import { handleObsTraceCommand } from "./obs-trace.ts";
 import { completeObsSubcommands, firstObsCommandToken, obsUsageWithError } from "./obs-args.ts";
+import { notifyObsCommand } from "./obs-command-support.ts";
 
 export interface ObsCommandContext
   extends ObsStatusCommandContext,
@@ -153,7 +154,11 @@ export async function handleObsCommand(
     return;
   }
 
-  await ctx.ui?.notify?.(obsUsageWithError(OBS_ROOT_USAGE, subcommand ? `Unknown subcommand: ${subcommand}.` : undefined), "warning");
+  await notifyObsCommand(
+    ctx,
+    obsUsageWithError(OBS_ROOT_USAGE, subcommand ? `Unknown subcommand: ${subcommand}.` : undefined),
+    "warning",
+  );
 }
 
 export function getObsRootCommandArgumentCompletions(prefix: string): Array<{ value: string; label: string }> | null {

package/src/config/bootstrap-project-config.ts

@@ -1,9 +1,18 @@
 import { CONFIG_DIR_NAME, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
-import { mkdir, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
+import type {
+  ExtensionContext,
+  SessionStartEvent,
+} from "@earendil-works/pi-coding-agent";
 import { readDiagnosticMessage, sanitizeDiagnosticText } from "../diagnostics/sanitize.ts";
 import { RESOURCE_ATTRIBUTES } from "../semconv/attributes.ts";
-import { resolveProjectLocalFilePath } from "./project-paths.ts";
+import {
+  createCanonicalProjectLocalFileExclusively,
+  resolveProjectLocalFilePath,
+} from "./project-paths.ts";
+import type {
+  ProjectLocalFileOperationHooks,
+  ProjectLocalFilePathOptions,
+} from "./project-paths.ts";
 
 export type ProjectConfigBootstrapStatus = "created" | "exists" | "skipped_untrusted";
 export type ProjectConfigNotifyLevel = "info" | "warning" | "error";
@@ -30,14 +39,15 @@ export interface EnsureProjectConfigOptions {
   readonly configDirName?: string;
   readonly cwd?: string;
   readonly isProjectTrusted?: boolean | (() => boolean | Promise<boolean>);
+  readonly projectFileOperationHooks?: ProjectLocalFileOperationHooks;
 }
 
 export type EnsureProjectConfig = (options: EnsureProjectConfigOptions) => Promise<ProjectConfigBootstrapResult>;
 
-type ProjectConfigBootstrapHandler = (event: unknown, ctx: ProjectConfigBootstrapContext) => Promise<void> | void;
+type ProjectConfigBootstrapHandler = (event: SessionStartEvent, ctx: ExtensionContext) => Promise<void> | void;
 
 interface ProjectConfigBootstrapPiApi {
-  on: (eventName: string, handler: ProjectConfigBootstrapHandler) => void;
+  on: (eventName: "session_start", handler: ProjectConfigBootstrapHandler) => void;
 }
 
 const observmeYamlFileName = "observme.yaml";
@@ -46,7 +56,6 @@ export const PROJECT_OBSERVME_YAML_TEMPLATE = `observme:
   enabled: true
   environment: development
   tenant: local-dev
-  replayOnStart: false
 
   otlp:
     endpoint: http://localhost:4318
@@ -54,7 +63,6 @@ export const PROJECT_OBSERVME_YAML_TEMPLATE = `observme:
     timeoutMs: 3000
     headers: {}
     tls:
-      enabled: false
       insecureSkipVerify: false
     signalEndpoints:
       traces: http://localhost:4318/v1/traces
@@ -86,6 +94,8 @@ export const PROJECT_OBSERVME_YAML_TEMPLATE = `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:
@@ -192,11 +202,16 @@ export function registerProjectConfigBootstrap(
 export async function ensureProjectObservMeConfig(
   options: EnsureProjectConfigOptions = {},
 ): Promise<ProjectConfigBootstrapResult> {
-  const configPath = resolveProjectObservMeConfigPath(options);
+  const pathOptions = createProjectObservMeConfigPathOptions(options);
+  const configPath = resolveProjectLocalFilePath(pathOptions);
   const projectTrusted = await resolveBootstrapProjectTrust(options.isProjectTrusted);
 
   if (!projectTrusted) return { path: configPath, status: "skipped_untrusted" };
-  return createProjectObservMeConfigFile(configPath);
+  return createProjectObservMeConfigFile(
+    configPath,
+    pathOptions,
+    options.projectFileOperationHooks,
+  );
 }
 
 function createProjectConfigBootstrapHandler(
@@ -254,30 +269,40 @@ async function notifyProjectConfigBootstrapFailed(ctx: ProjectConfigBootstrapCon
   await ctx.ui?.notify?.(`ObservMe could not create the project config file: ${formatError(error)}`, "warning");
 }
 
-async function createProjectObservMeConfigFile(configPath: string): Promise<ProjectConfigBootstrapResult> {
-  return withFileMutationQueue(configPath, createProjectObservMeConfigFileInQueue.bind(undefined, configPath));
+async function createProjectObservMeConfigFile(
+  configPath: string,
+  pathOptions: ProjectLocalFilePathOptions,
+  hooks: ProjectLocalFileOperationHooks | undefined,
+): Promise<ProjectConfigBootstrapResult> {
+  return withFileMutationQueue(
+    configPath,
+    createProjectObservMeConfigFileInQueue.bind(undefined, configPath, pathOptions, hooks),
+  );
 }
 
-async function createProjectObservMeConfigFileInQueue(configPath: string): Promise<ProjectConfigBootstrapResult> {
-  await mkdir(dirname(configPath), { recursive: true });
-
-  try {
-    await writeFile(configPath, PROJECT_OBSERVME_YAML_TEMPLATE, { encoding: "utf8", flag: "wx" });
-    return { path: configPath, status: "created" };
-  } catch (error) {
-    if (isFileAlreadyExistsError(error)) return { path: configPath, status: "exists" };
-    throw error;
-  }
+async function createProjectObservMeConfigFileInQueue(
+  configPath: string,
+  pathOptions: ProjectLocalFilePathOptions,
+  hooks: ProjectLocalFileOperationHooks | undefined,
+): Promise<ProjectConfigBootstrapResult> {
+  const status = await createCanonicalProjectLocalFileExclusively(
+    pathOptions,
+    PROJECT_OBSERVME_YAML_TEMPLATE,
+    hooks,
+  );
+  return { path: configPath, status };
 }
 
-function resolveProjectObservMeConfigPath(options: EnsureProjectConfigOptions): string {
-  return resolveProjectLocalFilePath({
+function createProjectObservMeConfigPathOptions(
+  options: EnsureProjectConfigOptions,
+): ProjectLocalFilePathOptions {
+  return {
     cwd: options.cwd,
     configDirName: options.configDirName,
     defaultConfigDirName: CONFIG_DIR_NAME,
     fileName: observmeYamlFileName,
     inputLabel: "project config path",
-  });
+  };
 }
 
 async function resolveBootstrapProjectTrust(
@@ -288,14 +313,6 @@ async function resolveBootstrapProjectTrust(
   return false;
 }
 
-function isFileAlreadyExistsError(error: unknown): boolean {
-  return isErrorWithCode(error) && error.code === "EEXIST";
-}
-
-function isErrorWithCode(error: unknown): error is NodeJS.ErrnoException {
-  return typeof error === "object" && error !== null && "code" in error;
-}
-
 function formatError(error: unknown): string {
   return sanitizeDiagnosticText(readDiagnosticMessage(error));
 }

package/src/config/defaults.ts

@@ -5,7 +5,6 @@ export const defaultObservMeConfig = {
   enabled: true,
   environment: "production",
   tenant: "platform",
-  replayOnStart: false,
   otlp: {
     endpoint: "https://otel-collector.example.com:4318",
     protocol: "http/protobuf",
@@ -14,7 +13,6 @@ export const defaultObservMeConfig = {
       Authorization: "Bearer ${OBSERVME_OTLP_TOKEN}",
     },
     tls: {
-      enabled: true,
       insecureSkipVerify: false,
     },
   },