@brunobracaioli/aibrain 0.2.0-beta.1 → 0.3.0-beta.7

package/dist/assets/codex-context-compaction.mjs

@@ -5,6 +5,9 @@ import { spawn } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
 import { dirname, relative, resolve } from 'node:path';
 import { StringDecoder } from 'node:string_decoder';
+import { pathToFileURL } from 'node:url';
+import { createTelemetryReporter, TELEMETRY_TIMEOUT_MS } from './context-telemetry-reporter.mjs';
+import { preflightSelectionState } from './context-selection-fitting.mjs';
 
 const DEFAULT_THRESHOLD = 85;
 const COOLDOWN_MS = 60_000;
@@ -14,11 +17,72 @@ const MAX_CAPTURE_BYTES = 1 * 1024 * 1024;
 const MAX_OWNED_REQUESTS = 1_000;
 const MAX_RETIRED_REQUESTS = 2_000;
 const MAX_RECOVERY_ITEMS = 128;
+const MAX_RECOVERY_SOURCE_INDEX = 4096;
 const MAX_NOTE_BYTES = 128 * 1024;
 const MAX_SELECTION_BYTES = 512 * 1024;
 const MAX_POLICY_BYTES = 8 * 1024;
 const MAX_NOTE_ITEM_CHARS = 16_384;
 const USAGE_FRESHNESS_MS = 60_000;
+const MAX_DIAGNOSTIC_STRING = 128;
+const MAX_BUDGET_SNAPSHOT_AGE_MS = 15_000;
+const CONTEXT_ERROR_CODES = new Set([
+  'INVALID_INPUT',
+  'FEATURE_DISABLED',
+  'PAID_PLAN_REQUIRED',
+  'ENTITLEMENT_UNAVAILABLE',
+  'RATE_LIMITED',
+  'PROVIDER_NOT_CONFIGURED',
+  'BUDGET_EXCEEDED',
+  'PROVIDER_TIMEOUT',
+  'PROVIDER_UNAVAILABLE',
+  'INVALID_PROVIDER_RESPONSE',
+]);
+const CONTEXT_FAILURE_DETAILS = new Set(['state_budget_exceeded', 'shared_admission_denied']);
+const CONTEXT_ADMISSION_REASONS = new Set([
+  'request_replayed',
+  'account_request_limit',
+  'account_token_limit',
+  'global_request_limit',
+  'global_token_limit',
+  'account_in_flight',
+  'database_unavailable',
+]);
+const SHARED_QUOTA_ADMISSION_REASONS = new Set([
+  'account_request_limit',
+  'account_token_limit',
+  'global_request_limit',
+  'global_token_limit',
+  'account_in_flight',
+]);
+const DIAGNOSTIC_STAGES = new Set([
+  'capture',
+  'budget',
+  'selection',
+  'notes',
+  'native',
+  'recovery',
+  'transport',
+]);
+const DIAGNOSTIC_REASONS = new Set([
+  'requested',
+  'completed',
+  'candidate_window_bounded',
+  'candidate_over_bound',
+  'protected_over_bound',
+  'history_unavailable',
+  'stale_snapshot',
+  'unavailable',
+  'admission_denied',
+  'invalid_response',
+  'request_failed',
+  'source_changed',
+  'timeout',
+  'thread_closed',
+  'protocol_error',
+  'attached',
+  'uncertain',
+  'disconnected',
+]);
 const FITTING_STAGES = new Set([
   'original',
   'inputs_1000',
@@ -233,10 +297,13 @@ function isValidUsage(value) {
     isRecord(value) &&
     isValidBreakdown(value.last) &&
     isValidBreakdown(value.total) &&
-    isSafeCounter(value.modelContextWindow) &&
-    value.modelContextWindow > 0
+    (value.modelContextWindow === null ||
+      (isSafeCounter(value.modelContextWindow) && value.modelContextWindow > 0))
   );
 }
+function hasKnownContextWindow(value) {
+  return isRecord(value) && isSafeCounter(value.modelContextWindow) && value.modelContextWindow > 0;
+}
 function redact(value, limit = 16_384) {
   return String(value)
     .replace(/(authorization\s*[:=]\s*bearer\s+)[^\s]+/gi, '$1[REDACTED]')
@@ -247,6 +314,187 @@ function redact(value, limit = 16_384) {
     .slice(0, limit);
 }
 
+function isUuid(value) {
+  return (
+    typeof value === 'string' &&
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(value)
+  );
+}
+
+function boundedDiagnosticValue(value) {
+  return typeof value === 'string' && value.length > 0 && value.length <= MAX_DIAGNOSTIC_STRING
+    ? value
+    : null;
+}
+
+function isSafeCorrelationId(value) {
+  return typeof value === 'string' && /^[A-Za-z0-9._:-]{1,128}$/u.test(value);
+}
+
+function boundedCorrelationValue(value) {
+  return typeof value === 'string' && value.length > 0 && value.length <= 256 ? value : null;
+}
+
+/**
+ * Closed private diagnostic contract consumed by the client sink. It contains
+ * stage/reason enums, pseudonymous session identity, operation/correlation
+ * identifiers and bounded counts only. It never accepts raw MCP/provider text,
+ * prompts, notes, paths or thread IDs.
+ */
+export function normalizeCodexDiagnostic(event, { threadId = null } = {}) {
+  if (!isRecord(event)) return null;
+  const stage = DIAGNOSTIC_STAGES.has(event.stage)
+    ? event.stage
+    : DIAGNOSTIC_STAGES.has(event.phase)
+      ? event.phase
+      : null;
+  const reason = DIAGNOSTIC_REASONS.has(event.reason)
+    ? event.reason
+    : event.reasonCode === 'candidate_window_bounded'
+      ? 'candidate_window_bounded'
+      : null;
+  if (stage === null || reason === null) return null;
+  const operationId = isUuid(event.operationId) ? event.operationId : undefined;
+  const correlationId = boundedDiagnosticValue(event.correlationId);
+  const counts = isRecord(event.counts)
+    ? Object.fromEntries(
+        Object.entries(event.counts).filter(
+          ([key, value]) =>
+            /^[a-z_]{1,48}$/u.test(key) && isSafeBoundedInteger(value, 0, 1_000_000),
+        ),
+      )
+    : undefined;
+  const result = {
+    schema_version: 1,
+    phase: boundedDiagnosticValue(event.phase) ?? `${stage}_${reason}`,
+    stage,
+    reason,
+    ...(operationId === undefined ? {} : { operation_id: operationId }),
+    ...(correlationId === null ? {} : { correlation_id: correlationId }),
+    ...(typeof threadId === 'string' && threadId.length > 0
+      ? { session_key: hashText(threadId) }
+      : {}),
+    ...(counts && Object.keys(counts).length > 0 ? { counts } : {}),
+  };
+  return result;
+}
+
+function parseJsonText(value) {
+  if (typeof value !== 'string' || Buffer.byteLength(value, 'utf8') > MAX_SELECTION_BYTES)
+    return null;
+  try {
+    const parsed = JSON.parse(value);
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function responseStructuredContent(response) {
+  if (!isRecord(response)) return null;
+  if (isRecord(response.structuredContent)) return response.structuredContent;
+  const content = Array.isArray(response.content) ? response.content : [];
+  const textPart = content.find((part) => isRecord(part) && part.type === 'text');
+  return textPart ? parseJsonText(textPart.text) : null;
+}
+
+/** Parse only the closed Context error envelope or known fixed-code text form. */
+export function parseContextError(response) {
+  const structured = responseStructuredContent(response);
+  let value = structured;
+  if (value === null) {
+    const content = Array.isArray(response?.content) ? response.content : [];
+    const textPart = content.find((part) => isRecord(part) && part.type === 'text');
+    const text = typeof textPart?.text === 'string' ? textPart.text : '';
+    const fixed =
+      /^(INVALID_INPUT|FEATURE_DISABLED|PAID_PLAN_REQUIRED|ENTITLEMENT_UNAVAILABLE|RATE_LIMITED|PROVIDER_NOT_CONFIGURED|BUDGET_EXCEEDED|PROVIDER_TIMEOUT|PROVIDER_UNAVAILABLE|INVALID_PROVIDER_RESPONSE)(?::|$)/u.exec(
+        text,
+      );
+    if (!fixed) return null;
+    value = { error_code: fixed[1] };
+  }
+  if (
+    !CONTEXT_ERROR_CODES.has(value.error_code) ||
+    (value.failure_detail !== undefined && !CONTEXT_FAILURE_DETAILS.has(value.failure_detail)) ||
+    (value.admission_reason !== undefined &&
+      !CONTEXT_ADMISSION_REASONS.has(value.admission_reason)) ||
+    (value.correlation_id !== undefined && !isSafeCorrelationId(value.correlation_id)) ||
+    (value.request_id !== undefined && !isUuid(value.request_id)) ||
+    (value.retry_after_ms !== undefined &&
+      !isSafeBoundedInteger(value.retry_after_ms, 0, 3_600_000))
+  )
+    return null;
+  return {
+    errorCode: value.error_code,
+    failureDetail: value.failure_detail ?? null,
+    admissionReason: value.admission_reason ?? null,
+    correlationId: boundedCorrelationValue(value.correlation_id),
+    requestId: isUuid(value.request_id) ? value.request_id : null,
+    retryAfterMs: value.retry_after_ms ?? null,
+    quota:
+      value.error_code === 'RATE_LIMITED' ||
+      value.failure_detail === 'shared_admission_denied' ||
+      SHARED_QUOTA_ADMISSION_REASONS.has(value.admission_reason),
+  };
+}
+
+export function parseBudgetSnapshot(value) {
+  if (
+    !isRecord(value) ||
+    !hasOnlyKeys(value, [
+      'schema_version',
+      'server_time',
+      'expires_at',
+      'window_end',
+      'available_requests',
+      'available_tokens',
+      'output_token_allowance',
+      'max_batches_per_operation',
+      'account_in_flight',
+      'retry_after_ms',
+      'provider_batches',
+      'provider_model',
+      'correlation_id',
+    ]) ||
+    value.schema_version !== 1 ||
+    !isTimestamp(value.server_time) ||
+    !isTimestamp(value.expires_at) ||
+    !isTimestamp(value.window_end) ||
+    Date.parse(value.expires_at) <= Date.parse(value.server_time) ||
+    Date.parse(value.expires_at) - Date.parse(value.server_time) > MAX_BUDGET_SNAPSHOT_AGE_MS ||
+    Date.parse(value.expires_at) > Date.parse(value.window_end) ||
+    !isSafeBoundedInteger(value.available_requests, 0, 1_000_000) ||
+    !isSafeBoundedInteger(value.available_tokens, 0, Number.MAX_SAFE_INTEGER) ||
+    !isSafeBoundedInteger(value.output_token_allowance, 0, Number.MAX_SAFE_INTEGER) ||
+    !isSafeBoundedInteger(value.max_batches_per_operation, 0, 4) ||
+    typeof value.account_in_flight !== 'boolean' ||
+    !isSafeBoundedInteger(value.retry_after_ms, 0, 3_600_000) ||
+    value.provider_batches !== 0 ||
+    value.provider_model !== null ||
+    !isSafeCorrelationId(value.correlation_id)
+  )
+    return null;
+  return value;
+}
+
+function budgetSnapshotFresh(snapshot, receivedAt, currentTime) {
+  if (!isRecord(snapshot) || !Number.isSafeInteger(receivedAt) || currentTime < receivedAt)
+    return false;
+  const lifetime = Date.parse(snapshot.expires_at) - Date.parse(snapshot.server_time);
+  return (
+    lifetime > 0 && lifetime <= MAX_BUDGET_SNAPSHOT_AGE_MS && currentTime - receivedAt <= lifetime
+  );
+}
+
+function diagnosticReasonForError(error) {
+  const message = error instanceof Error ? error.message : String(error ?? '');
+  if (/tim(?:e|ed)[ -]?out/iu.test(message)) return 'timeout';
+  if (/closed|deleted/iu.test(message)) return 'thread_closed';
+  if (/source changed|stale/iu.test(message)) return 'source_changed';
+  if (/candidate|history|thread\/read/iu.test(message)) return 'history_unavailable';
+  return 'request_failed';
+}
+
 async function ensurePrivateDirectory(directory) {
   const target = resolve(directory);
   await mkdir(target, { recursive: true, mode: 0o700 });
@@ -351,12 +599,23 @@ function validateThreadRead(value, threadId) {
   return value;
 }
 
-export function buildRecoveryCandidates(read, revision, policy = null) {
+export function buildRecoveryCandidates(read, revision, policy = null, options = {}) {
   const turns = read.thread.turns;
-  const rawItems = turns.flatMap((turn) => (Array.isArray(turn.items) ? turn.items : []));
-  if (rawItems.length > MAX_RECOVERY_ITEMS)
+  const rawItems = turns.flatMap((turn, turnIndex) =>
+    (Array.isArray(turn.items) ? turn.items : []).map((item, itemIndex) => ({
+      item,
+      turnIndex,
+      itemIndex,
+    })),
+  );
+  const maxItems = options.maxItems ?? MAX_RECOVERY_ITEMS;
+  if (!Number.isSafeInteger(maxItems) || maxItems < 1 || maxItems > MAX_RECOVERY_ITEMS)
+    throw new Error('recovery candidate bound is invalid');
+  if (rawItems.length > maxItems && options.allowWindow !== true)
     throw new Error('recovery candidate count exceeds bound');
-  const items = rawItems.map((rawItem, index) => {
+  if (rawItems.length > MAX_RECOVERY_SOURCE_INDEX)
+    throw new Error('recovery source index exceeds bound');
+  let items = rawItems.map(({ item: rawItem, turnIndex, itemIndex }, index) => {
     const item = isRecord(rawItem) ? rawItem : {};
     const type = typeof item.type === 'string' ? item.type : 'unknown';
     const commandOutput =
@@ -439,10 +698,58 @@ export function buildRecoveryCandidates(read, revision, policy = null) {
       pinReasons,
       source: rawItem,
       sourceItemId: typeof item.id === 'string' ? item.id : `item-${index + 1}`,
+      sourceLocation: { flatIndex: index, turnIndex, itemIndex },
+      sourceRefs: null,
       sourceBodyChars: commandOutput.length,
       kind,
     };
   });
+  if (items.length > maxItems) {
+    const protectedItems = items.filter((item) => item.protected);
+    const anchorIds = new Set();
+    const first = items[0];
+    if (first?.protected) anchorIds.add(first.id);
+    const currentGoal = items.findLast((item) => item.kind === 'user_message');
+    if (currentGoal?.protected) anchorIds.add(currentGoal.id);
+    const recentCount = policy?.preserveRecentMessages ?? 6;
+    for (const item of items.slice(-recentCount)) {
+      if (item.protected) anchorIds.add(item.id);
+    }
+    const individualProtected = protectedItems.filter((item) => anchorIds.has(item.id));
+    const bundledProtected = protectedItems.filter((item) => !anchorIds.has(item.id));
+    if (individualProtected.length >= maxItems)
+      throw new Error('recovery protected anchors exceed bound');
+    const selected = new Set(individualProtected.map((item) => item.id));
+    if (bundledProtected.length > 0) {
+      const bundle = {
+        id: 'recovery-protected-bundle-1',
+        text: `protected reference bundle: ${bundledProtected.length} items retained in the verified immutable capture`,
+        localText: '',
+        localChars: 0,
+        protected: true,
+        pinReasons: ['reference'],
+        source: null,
+        sourceItemId: null,
+        sourceLocation: null,
+        sourceRefs: bundledProtected.map((item) => ({
+          ...item.sourceLocation,
+          sourceItemId: item.sourceItemId,
+        })),
+        sourceBodyChars: 0,
+        kind: 'reference',
+      };
+      items = [...items, bundle];
+      selected.add(bundle.id);
+    }
+    for (const item of items
+      .filter((candidate) => !candidate.protected)
+      .slice()
+      .reverse()) {
+      if (selected.size >= maxItems) break;
+      selected.add(item.id);
+    }
+    items = items.filter((item) => selected.has(item.id));
+  }
   const projection = {
     goal:
       policy?.goal !== undefined
@@ -467,6 +774,104 @@ export function buildRecoveryCandidates(read, revision, policy = null) {
   return { items, projection, projectionHash: hashJson(projection), revision };
 }
 
+function selectionFittingProjection(candidates) {
+  return {
+    goal: candidates.projection.goal,
+    items: candidates.items.map(
+      ({ id, kind, text, localChars, protected: protectedItem, pinReasons }) => ({
+        id,
+        kind,
+        text,
+        localChars,
+        protected: protectedItem,
+        pinReasons,
+      }),
+    ),
+  };
+}
+
+function selectionWireProjection(goal, items) {
+  return {
+    goal,
+    items: items.map(({ id, kind, text, localChars, protected: protectedItem, pinReasons }) => ({
+      id,
+      kind,
+      text,
+      local_chars: localChars,
+      protected: protectedItem,
+      pin_reasons: pinReasons,
+    })),
+  };
+}
+
+function selectionFittingOptions(policy, maxRequestTokens) {
+  return {
+    preserveRecentItems: policy?.preserveRecentMessages ?? 6,
+    maxStateTokens: policy?.maxStateTokens ?? 25_000,
+    maxRequestTokens,
+  };
+}
+
+function fitWithinCapacity(fit, capacity) {
+  if (!fit.ok) return false;
+  const batchCount = fit.batches.length;
+  return (
+    batchCount <= capacity.requests &&
+    batchCount * (fit.requestTokens + capacity.outputTokenAllowance) <= capacity.tokens
+  );
+}
+
+export function boundCandidatesToBudget(candidates, availableTokens, policy = null) {
+  const capacity =
+    typeof availableTokens === 'number'
+      ? {
+          tokens: availableTokens,
+          requests: Number.MAX_SAFE_INTEGER,
+          maxRequestTokens: 30_000,
+          outputTokenAllowance: 0,
+        }
+      : { outputTokenAllowance: 0, ...availableTokens };
+  if (
+    !isRecord(capacity) ||
+    !isSafeBoundedInteger(capacity.tokens, 1, Number.MAX_SAFE_INTEGER) ||
+    !isSafeBoundedInteger(capacity.requests, 1, Number.MAX_SAFE_INTEGER) ||
+    !isSafeBoundedInteger(capacity.maxRequestTokens, 1_000, 30_000) ||
+    !isSafeBoundedInteger(capacity.outputTokenAllowance, 0, Number.MAX_SAFE_INTEGER)
+  )
+    throw new Error('recovery budget has no usable token capacity');
+  const protectedItems = candidates.items.filter((item) => item.protected);
+  if (protectedItems.length > MAX_RECOVERY_ITEMS)
+    throw new Error('recovery protected candidate count exceeds bound');
+  const eligibleItems = candidates.items.filter((item) => !item.protected);
+  const fitFor = (items) =>
+    preflightSelectionState({
+      projection: selectionFittingProjection({ ...candidates, items }),
+      options: selectionFittingOptions(policy, capacity.maxRequestTokens),
+    });
+  for (let keepCount = eligibleItems.length; keepCount >= 0; keepCount -= 1) {
+    const retainedEligible = new Set(
+      (keepCount === 0 ? [] : eligibleItems.slice(-keepCount)).map((item) => item.id),
+    );
+    const items = candidates.items.filter(
+      (item) => item.protected || retainedEligible.has(item.id),
+    );
+    const fit = fitFor(items);
+    if (!fitWithinCapacity(fit, capacity)) continue;
+    const projection = selectionFittingProjection({ ...candidates, items });
+    const wireProjection = selectionWireProjection(candidates.projection.goal, items);
+    return {
+      items,
+      projection: wireProjection,
+      projectionHash: hashJson(wireProjection),
+      revision: candidates.revision,
+      bounded: items.length !== candidates.items.length,
+      preflight: fit,
+      providerProjection: projection,
+    };
+  }
+  throw new Error('recovery protected candidate projection exceeds budget');
+}
+
 export function parseSelection(value, input, candidates, currentTime = Date.now()) {
   const v2 = isRecord(input) && input.schema_version === 2;
   const baseKeys = [
@@ -610,6 +1015,36 @@ export function recoveryNotesText(
   candidates,
   decisions,
 ) {
+  const formatSourceLocations = (refs) => {
+    const sorted = refs
+      .filter(
+        (ref) =>
+          isRecord(ref) &&
+          isSafeBoundedInteger(ref.flatIndex, 0, MAX_RECOVERY_SOURCE_INDEX) &&
+          isSafeBoundedInteger(ref.turnIndex, 0, MAX_RECOVERY_SOURCE_INDEX) &&
+          isSafeBoundedInteger(ref.itemIndex, 0, MAX_RECOVERY_SOURCE_INDEX),
+      )
+      .sort((left, right) => left.flatIndex - right.flatIndex);
+    const ranges = [];
+    for (const ref of sorted) {
+      const previous = ranges.at(-1);
+      if (previous && ref.flatIndex === previous.end + 1) previous.end = ref.flatIndex;
+      else ranges.push({ start: ref.flatIndex, end: ref.flatIndex });
+    }
+    return {
+      positions: ranges
+        .map((range) =>
+          range.start === range.end ? String(range.start) : `${range.start}-${range.end}`,
+        )
+        .join(','),
+      locations: sorted.map((ref) => `${ref.turnIndex}:${ref.itemIndex}`).join(','),
+      ids: sorted
+        .map((ref) =>
+          typeof ref.sourceItemId === 'string' ? escapeReference(ref.sourceItemId) : 'unknown',
+        )
+        .join(','),
+    };
+  };
   const selected = new Map(
     decisions.filter((decision) => decision.keep).map((decision) => [decision.id, decision]),
   );
@@ -623,6 +1058,7 @@ export function recoveryNotesText(
     `- capture_base: ${escapeReference(captureBase)}`,
     `- capture_file: ${escapeReference(captureFile)} (private checkpoint directory)`,
     `- capture_source_sha256: ${revision}`,
+    '- capture_verified: immutable private capture read and revision checked before native compaction',
     `- source: private local capture`,
     '',
     '## Selected context',
@@ -631,7 +1067,12 @@ export function recoveryNotesText(
   let inlineBudget = Math.floor(MAX_NOTE_BYTES / 2);
   for (const item of candidates.items) {
     if (!selected.has(item.id)) continue;
-    const reference = `[selected local content retained in ${escapeReference(captureFile)}; source_item=${escapeReference(item.sourceItemId)}; local_chars=${item.localChars}]`;
+    const reference = item.sourceRefs
+      ? (() => {
+          const source = formatSourceLocations(item.sourceRefs);
+          return `[protected reference bundle retained in verified capture ${escapeReference(captureFile)}; source_positions=${source.positions}; thread_locations=${source.locations}; source_ids=${source.ids}]`;
+        })()
+      : `[selected local content retained in ${escapeReference(captureFile)}; source_item=${escapeReference(item.sourceItemId)}; source_location=${item.sourceLocation?.turnIndex ?? 'unknown'}:${item.sourceLocation?.itemIndex ?? 'unknown'}; local_chars=${item.localChars}]`;
     const inline =
       item.kind !== 'tool_result' &&
       item.kind !== 'reference' &&
@@ -698,6 +1139,13 @@ export function createCodexContextProxy({
   },
   recoveryEnabled = process.env.CODEX_CONTEXT_RECOVERY_ENABLED === '1',
   recoveryDisclosed = process.env.CODEX_CONTEXT_RECOVERY_DISCLOSED === '1',
+  telemetryEnabled = process.env.CODEX_CONTEXT_TELEMETRY_ENABLED === '1',
+  telemetryDisclosed = process.env.CODEX_CONTEXT_TELEMETRY_DISCLOSED === '1',
+  telemetryTimeoutMs = TELEMETRY_TIMEOUT_MS,
+  telemetrySetTimer = setTimeout,
+  telemetryClearTimer = clearTimeout,
+  budgetEnabled = process.env.CODEX_CONTEXT_BUDGET_ENABLED !== '0',
+  createDiagnosticSink = null,
   brainServer = process.env.AI_BRAIN_MCP_SERVER ?? 'brain',
   clientVersion = process.env.CODEX_CLIENT_VERSION ?? '0.161.0',
 }) {
@@ -707,10 +1155,86 @@ export function createCodexContextProxy({
   const ownedRequests = new Map();
   const internalReads = new Map();
   const retiredRequests = new Set();
+  const telemetryByThread = new Map();
+  const diagnosticSinks = new Map();
   let stopped = false;
   function emitDiagnostic(event) {
     try {
-      onDiagnostic(event);
+      const phase = typeof event?.phase === 'string' ? event.phase : '';
+      const stage =
+        event?.stage ??
+        (phase === 'selection_accepted' || phase === 'select' ? 'selection' : null) ??
+        (phase === 'read' || phase === 'capture' ? 'capture' : null) ??
+        (phase === 'compact' || phase === 'native' || phase === 'thread_failure'
+          ? 'native'
+          : null) ??
+        (phase === 'inject' || phase === 'recovery' ? 'recovery' : null) ??
+        (phase === 'transport_end' || phase === 'transport_close' || phase === 'process_error'
+          ? 'transport'
+          : null);
+      const reason =
+        event?.reason ??
+        (DIAGNOSTIC_REASONS.has(event?.reasonCode) ? event.reasonCode : null) ??
+        (phase === 'selection_accepted' ? 'completed' : null) ??
+        (phase === 'transport_close' || phase === 'transport_end' ? 'disconnected' : null) ??
+        (phase === 'thread_failure' ? 'protocol_error' : null) ??
+        (event?.errorCode !== undefined ? 'protocol_error' : null);
+      const normalized = normalizeCodexDiagnostic(
+        {
+          ...event,
+          stage,
+          reason,
+          operationId: event?.operationId ?? threads.get(event?.threadId)?.pending?.operationId,
+        },
+        { threadId: event?.threadId },
+      );
+      if (normalized === null) return;
+      if (
+        typeof event?.schemaVersion === 'number' &&
+        isSafeBoundedInteger(event.schemaVersion, 1, 2)
+      )
+        normalized.schemaVersion = event.schemaVersion;
+      for (const [source, target] of [
+        ['optionsHash', 'options_hash'],
+        ['fittingStage', 'fitting_stage'],
+        ['batchCount', 'batch_count'],
+        ['providerModel', 'provider_model'],
+      ]) {
+        if (
+          (typeof event[source] === 'string' && event[source].length <= MAX_DIAGNOSTIC_STRING) ||
+          (source === 'batchCount' && isSafeBoundedInteger(event[source], 0, 4)) ||
+          (source === 'providerModel' && event[source] === null)
+        )
+          normalized[target] = event[source];
+        if (source === 'optionsHash' && typeof event[source] === 'string')
+          normalized.optionsHash = event[source];
+        if (source === 'fittingStage' && typeof event[source] === 'string')
+          normalized.fittingStage = event[source];
+        if (source === 'batchCount' && isSafeBoundedInteger(event[source], 0, 4))
+          normalized.batchCount = event[source];
+        if (
+          source === 'providerModel' &&
+          (typeof event[source] === 'string' || event[source] === null)
+        )
+          normalized.providerModel = event[source];
+      }
+      onDiagnostic(normalized);
+      if (typeof createDiagnosticSink === 'function' && typeof event?.threadId === 'string') {
+        let sink = diagnosticSinks.get(event.threadId);
+        if (!sink) {
+          try {
+            sink = createDiagnosticSink(event.threadId);
+            if (typeof sink === 'function') diagnosticSinks.set(event.threadId, sink);
+          } catch {
+            sink = null;
+          }
+        }
+        try {
+          sink?.(normalized);
+        } catch {
+          /* private diagnostics cannot affect compaction */
+        }
+      }
     } catch {
       /* diagnostics must never affect compaction */
     }
@@ -751,7 +1275,15 @@ export function createCodexContextProxy({
     cleanupRequest(pending.compactId);
     pending.deferred.reject(new Error(reason));
     state.pending = null;
-    emitDiagnostic({ phase: 'thread_failure', reasonCode: reason.replace(/[^a-z0-9]+/gi, '_') });
+    const operationId = pending.operationId;
+    if (operationId) telemetryFor(threadId).failed({ operationId, reason: 'native_error' });
+    emitDiagnostic({
+      phase: 'thread_failure',
+      stage: pending.stage ?? 'native',
+      reason: diagnosticReasonForError(new Error(reason)),
+      threadId,
+      operationId,
+    });
     stderr.write(`codex-context: native compaction preserved (${reason})\n`);
   }
   function failAll(reason) {
@@ -792,6 +1324,7 @@ export function createCodexContextProxy({
       recoveryLoaded: false,
       recoveryLoadPromise: null,
       recoveryAttach: null,
+      telemetryConnected: false,
     };
     threads.set(threadId, created);
     return created;
@@ -810,6 +1343,187 @@ export function createCodexContextProxy({
     }
     return id;
   }
+  function telemetryFor(threadId) {
+    const existing = telemetryByThread.get(threadId);
+    if (existing) return existing;
+    const reporter = createTelemetryReporter({
+      client: 'codex-cli',
+      clientVersion,
+      sessionId: threadId,
+      enabled: telemetryEnabled,
+      disclosed: telemetryDisclosed,
+      now,
+      timeoutMs: telemetryTimeoutMs,
+      setTimer: telemetrySetTimer,
+      clearTimer: telemetryClearTimer,
+      send: async (event) => {
+        const waiter = deferred();
+        void waiter.promise.catch(() => undefined);
+        let id;
+        try {
+          id = sendOwned(
+            'mcpServer/tool/call',
+            {
+              threadId,
+              server: brainServer,
+              tool: 'brain_context_report',
+              arguments: event,
+            },
+            'telemetry',
+            threadId,
+            waiter,
+          );
+          let timer;
+          try {
+            const result = await Promise.race([
+              waiter.promise,
+              new Promise((_, reject) => {
+                timer = telemetrySetTimer(
+                  () => reject(new Error('telemetry_timeout')),
+                  telemetryTimeoutMs,
+                );
+              }),
+            ]);
+            if (!isRecord(result) || result.isError === true)
+              throw new Error('telemetry_report_rejected');
+            const structured = isRecord(result.structuredContent)
+              ? result.structuredContent
+              : result;
+            if (!isRecord(structured) || structured.accepted !== true)
+              throw new Error('telemetry_report_rejected');
+            return result;
+          } finally {
+            if (timer !== undefined) telemetryClearTimer(timer);
+          }
+        } finally {
+          cleanupRequest(id);
+        }
+      },
+    });
+    telemetryByThread.set(threadId, reporter);
+    return reporter;
+  }
+  async function requestBudget(threadId, pending) {
+    const waiter = deferred();
+    void waiter.promise.catch(() => undefined);
+    const budgetRequestId = sendOwned(
+      'mcpServer/tool/call',
+      {
+        threadId,
+        server: brainServer,
+        tool: 'brain_context_budget',
+        arguments: { schema_version: 1 },
+      },
+      'budget',
+      threadId,
+      waiter,
+    );
+    pending.auxIds.push(budgetRequestId);
+    emitDiagnostic({
+      phase: 'budget',
+      stage: 'budget',
+      reason: 'requested',
+      threadId,
+      operationId: pending.operationId,
+    });
+    let response;
+    try {
+      response = await waiter.promise;
+    } catch {
+      emitDiagnostic({
+        phase: 'budget',
+        stage: 'budget',
+        reason: 'unavailable',
+        threadId,
+        operationId: pending.operationId,
+      });
+      return { snapshot: null, error: null };
+    }
+    const error = parseContextError(response);
+    if (error !== null && response?.isError === true) {
+      emitDiagnostic({
+        phase: 'budget',
+        stage: 'budget',
+        reason: error.quota ? 'admission_denied' : 'request_failed',
+        threadId,
+        operationId: pending.operationId,
+        correlationId: error.correlationId,
+      });
+      return { snapshot: null, error };
+    }
+    const receivedAt = now();
+    const snapshot = parseBudgetSnapshot(responseStructuredContent(response));
+    if (snapshot === null) {
+      emitDiagnostic({
+        phase: 'budget',
+        stage: 'budget',
+        reason: 'stale_snapshot',
+        threadId,
+        operationId: pending.operationId,
+      });
+      return { snapshot: null, error: null };
+    }
+    emitDiagnostic({
+      phase: 'budget',
+      stage: 'budget',
+      reason: 'completed',
+      threadId,
+      operationId: pending.operationId,
+      correlationId: snapshot.correlation_id,
+      counts: {
+        available_requests: snapshot.available_requests,
+        available_tokens: Math.min(snapshot.available_tokens, 1_000_000),
+      },
+    });
+    return { snapshot, error: null, receivedAt };
+  }
+  function emitNativeFallback(threadId, pending, reason, correlationId = null) {
+    telemetryFor(threadId).fallback({
+      operationId: pending.operationId,
+      reason:
+        reason === 'admission_denied'
+          ? 'rate_limited'
+          : reason === 'provider_unavailable'
+            ? 'provider_unavailable'
+            : 'recovery_pending',
+    });
+    emitDiagnostic({
+      phase: 'budget',
+      stage: 'budget',
+      reason: reason === 'provider_unavailable' ? 'request_failed' : reason,
+      threadId,
+      operationId: pending.operationId,
+      correlationId,
+    });
+  }
+  function emitOutcome(outcome) {
+    try {
+      onOutcome(outcome);
+    } catch {
+      /* lifecycle observers cannot affect compaction */
+    }
+    const reporter = telemetryFor(outcome.threadId);
+    const operationId =
+      outcome.operationId ??
+      threads.get(outcome.threadId)?.recovery?.operationId ??
+      threads.get(outcome.threadId)?.pending?.operationId;
+    if (
+      !outcome.telemetryAlreadyEmitted &&
+      (outcome.status === 'native_completed' || outcome.status === 'completed') &&
+      operationId
+    )
+      reporter.nativeCompleted({ operationId });
+    else if (outcome.status === 'recovery_attached' && operationId)
+      reporter.recoveryAttached({ operationId });
+    else if (outcome.status === 'recovery_uncertain' && operationId)
+      reporter.uncertain({ operationId, reason: 'recovery_uncertain' });
+    else if (outcome.status === 'recovery_pending' && operationId)
+      reporter.fallback({ operationId, reason: 'recovery_pending' });
+    else if (outcome.status === 'recovery_abandoned' && operationId)
+      reporter.fallback({ operationId, reason: 'stale_context' });
+    else if (outcome.status === 'failed' && operationId)
+      reporter.failed({ operationId, reason: 'native_error' });
+  }
   function assertCurrent(threadId, state, pending, revision) {
     if (pending.canceled || state.pending !== pending || !state.idle || state.revision !== revision)
       throw new Error('Codex state changed during compaction');
@@ -851,14 +1565,22 @@ export function createCodexContextProxy({
             /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
               value.requestId,
             ) &&
+            (value.operationId === undefined ||
+              (typeof value.operationId === 'string' &&
+                /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
+                  value.operationId,
+                ))) &&
             typeof value.itemId === 'string' &&
             value.itemId.length <= 128 &&
             (!['pending_attachment', 'injecting', 'recovery_uncertain'].includes(value.status) ||
               typeof value.turnId === 'string')
           )
-            return value.status === 'injecting'
-              ? { ...value, status: 'recovery_uncertain' }
-              : value;
+            return {
+              ...(value.status === 'injecting'
+                ? { ...value, status: 'recovery_uncertain' }
+                : value),
+              operationId: value.operationId ?? value.requestId,
+            };
         } catch (error) {
           if (error?.code !== 'ENOENT') stderr.write('codex-context: recovery state unavailable\n');
         }
@@ -962,7 +1684,14 @@ export function createCodexContextProxy({
         await persistRecoveryState(threadId, attached);
         if (attachment.invalidated || attachment.canceled) return;
         state.recovery = attached;
-        onOutcome({ threadId, status: 'recovery_attached', turnId: record.turnId });
+        emitDiagnostic({
+          phase: 'recovery_attached',
+          stage: 'recovery',
+          reason: 'attached',
+          threadId,
+          operationId: record.operationId,
+        });
+        emitOutcome({ threadId, status: 'recovery_attached', turnId: record.turnId });
         return;
       }
       if (record.status === 'recovery_uncertain') {
@@ -973,7 +1702,14 @@ export function createCodexContextProxy({
         };
         await persistRecoveryState(threadId, uncertain).catch(() => undefined);
         state.recovery = uncertain;
-        onOutcome({ threadId, status: 'recovery_uncertain', turnId: record.turnId });
+        emitDiagnostic({
+          phase: 'recovery_uncertain',
+          stage: 'recovery',
+          reason: 'uncertain',
+          threadId,
+          operationId: record.operationId,
+        });
+        emitOutcome({ threadId, status: 'recovery_uncertain', turnId: record.turnId });
         return;
       }
       if (!state.idle) throw new Error('thread became active before recovery attachment');
@@ -1015,7 +1751,7 @@ export function createCodexContextProxy({
       };
       await persistRecoveryState(threadId, attached);
       state.recovery = attached;
-      onOutcome({ threadId, status: 'recovery_attached', turnId: record.turnId });
+      emitOutcome({ threadId, status: 'recovery_attached', turnId: record.turnId });
     } catch {
       if (attachment.injectSent) {
         const uncertain = {
@@ -1025,7 +1761,14 @@ export function createCodexContextProxy({
         };
         await persistRecoveryState(threadId, uncertain).catch(() => undefined);
         state.recovery = uncertain;
-        onOutcome({ threadId, status: 'recovery_uncertain', turnId: record.turnId });
+        emitDiagnostic({
+          phase: 'recovery_uncertain',
+          stage: 'recovery',
+          reason: 'uncertain',
+          threadId,
+          operationId: record.operationId,
+        });
+        emitOutcome({ threadId, status: 'recovery_uncertain', turnId: record.turnId });
       } else if (!attachment.canceled) {
         if (attachment.stale) {
           state.recovery = {
@@ -1034,8 +1777,8 @@ export function createCodexContextProxy({
             abandonedAt: new Date(now()).toISOString(),
           };
           await persistRecoveryState(threadId, state.recovery).catch(() => undefined);
-          onOutcome({ threadId, status: 'recovery_abandoned', turnId: record.turnId });
-        } else onOutcome({ threadId, status: 'recovery_pending', turnId: record.turnId });
+          emitOutcome({ threadId, status: 'recovery_abandoned', turnId: record.turnId });
+        } else emitOutcome({ threadId, status: 'recovery_pending', turnId: record.turnId });
       }
     } finally {
       if (attachment.timer) attachment.timer();
@@ -1060,6 +1803,7 @@ export function createCodexContextProxy({
       state.pending ||
       !state.usage ||
       !isValidUsage(state.usage) ||
+      !hasKnownContextWindow(state.usage) ||
       !Number.isFinite(state.usageReceivedAt) ||
       currentTime < state.usageReceivedAt ||
       currentTime - state.usageReceivedAt > USAGE_FRESHNESS_MS ||
@@ -1092,12 +1836,15 @@ export function createCodexContextProxy({
       itemCompleted: false,
       turnCompleted: false,
       canceled: false,
+      stage: 'capture',
+      operationId: randomUUID(),
       deferred: completion,
       timer: null,
     };
     state.pending = pending;
     pending.timer = scheduleTimeout(() => fail(threadId, 'native compaction timed out'), timeoutMs);
     try {
+      pending.stage = 'capture';
       pending.readId = sendOwned(
         'thread/read',
         { threadId, includeTurns: true },
@@ -1136,8 +1883,23 @@ export function createCodexContextProxy({
         `${safeThreadName(threadId)}.${sourceRevision}.json`,
       );
       await atomicWriteImmutablePrivate(immutableCapturePath, snapshot, sourceRevision);
+      emitDiagnostic({
+        phase: 'capture',
+        stage: 'capture',
+        reason: 'completed',
+        threadId,
+        operationId: pending.operationId,
+        counts: {
+          item_count: read.thread.turns.reduce(
+            (count, turn) => count + (turn.items?.length ?? 0),
+            0,
+          ),
+        },
+      });
       assertCurrent(threadId, state, pending, revision);
       let recoveryNotes;
+      let nativeFallback = false;
+      let budgetReceipt = null;
       if (recoveryEnabled && recoveryDisclosed) {
         strictThreadName(threadId);
         if (
@@ -1155,127 +1917,317 @@ export function createCodexContextProxy({
           await persistRecoveryState(threadId, state.recovery).catch(() => undefined);
           throw new Error('saved recovery selection is stale');
         } else {
-          const candidates = buildRecoveryCandidates(read, sourceRevision, contextPolicy);
-          const selectionInput = contextPolicy
-            ? {
-                schema_version: 2,
-                client: 'codex_app_server',
-                client_version: clientVersion,
-                session_ref: threadId,
-                revision: sourceRevision,
-                observed_at: new Date(now()).toISOString(),
-                request_id: randomUUID(),
-                policy_version: 'context-recovery-v2',
-                options: selectionOptions(contextPolicy),
-                projection: candidates.projection,
+          let candidates;
+          if (budgetEnabled) {
+            pending.stage = 'budget';
+            const budget = await requestBudget(threadId, pending);
+            budgetReceipt = budget;
+            if (budget.error?.quota === true) {
+              nativeFallback = true;
+              emitNativeFallback(threadId, pending, 'admission_denied', budget.error.correlationId);
+            } else if (budget.snapshot === null) {
+              nativeFallback = true;
+              emitNativeFallback(threadId, pending, 'unavailable', null);
+            } else if (!budgetSnapshotFresh(budget.snapshot, budget.receivedAt, now())) {
+              nativeFallback = true;
+              emitNativeFallback(
+                threadId,
+                pending,
+                'stale_snapshot',
+                budget.snapshot.correlation_id,
+              );
+            } else if (
+              budget.snapshot.account_in_flight === true ||
+              budget.snapshot.available_requests < 1 ||
+              budget.snapshot.available_tokens < 1 ||
+              budget.snapshot.max_batches_per_operation < 1
+            ) {
+              nativeFallback = true;
+              emitNativeFallback(
+                threadId,
+                pending,
+                'admission_denied',
+                budget.snapshot.correlation_id,
+              );
+            } else {
+              try {
+                candidates = buildRecoveryCandidates(read, sourceRevision, contextPolicy, {
+                  allowWindow: true,
+                });
+                const bounded = boundCandidatesToBudget(
+                  candidates,
+                  {
+                    tokens: budget.snapshot.available_tokens,
+                    requests: Math.min(
+                      budget.snapshot.available_requests,
+                      budget.snapshot.max_batches_per_operation,
+                    ),
+                    maxRequestTokens: contextPolicy?.maxRequestTokens ?? 30_000,
+                    outputTokenAllowance: budget.snapshot.output_token_allowance,
+                  },
+                  contextPolicy,
+                );
+                if (bounded.bounded) {
+                  emitDiagnostic({
+                    phase: 'candidate_window_bounded',
+                    stage: 'selection',
+                    reason: 'candidate_window_bounded',
+                    threadId,
+                    operationId: pending.operationId,
+                    correlationId: budget.snapshot.correlation_id,
+                    counts: {
+                      candidate_count: bounded.items.length,
+                      deferred_count: Math.max(0, candidates.items.length - bounded.items.length),
+                      provider_batch_count: bounded.preflight.batches.length,
+                      provider_request_tokens: bounded.preflight.requestTokens,
+                    },
+                  });
+                }
+                candidates = bounded;
+              } catch (error) {
+                nativeFallback = true;
+                emitNativeFallback(
+                  threadId,
+                  pending,
+                  error?.message?.includes('protected')
+                    ? 'protected_over_bound'
+                    : 'candidate_over_bound',
+                  budget.snapshot.correlation_id,
+                );
               }
-            : {
-                schema_version: 1,
-                client: 'codex_app_server',
-                client_version: clientVersion,
-                session_ref: threadId,
-                revision: sourceRevision,
-                observed_at: new Date(now()).toISOString(),
-                request_id: randomUUID(),
-                policy_version: 'context-recovery-v1',
-                projection: candidates.projection,
-              };
+            }
+          } else {
+            pending.stage = 'selection';
+            try {
+              candidates = buildRecoveryCandidates(read, sourceRevision, contextPolicy);
+            } catch {
+              nativeFallback = true;
+              emitNativeFallback(threadId, pending, 'candidate_over_bound');
+            }
+          }
           if (
-            typeof clientVersion !== 'string' ||
-            clientVersion.length < 1 ||
-            clientVersion.length > 64 ||
-            Buffer.byteLength(JSON.stringify(selectionInput), 'utf8') > MAX_SELECTION_BYTES
-          )
-            throw new Error('recovery selection input exceeds the contract bound');
-          const selectionWaiter = deferred();
-          pending.auxIds.push(
-            sendOwned(
-              'mcpServer/tool/call',
-              {
-                threadId,
-                server: brainServer,
-                tool: 'brain_context_select',
-                arguments: selectionInput,
-              },
-              'select',
+            !nativeFallback &&
+            budgetReceipt?.snapshot !== null &&
+            budgetReceipt?.snapshot !== undefined &&
+            !budgetSnapshotFresh(budgetReceipt.snapshot, budgetReceipt.receivedAt, now())
+          ) {
+            nativeFallback = true;
+            emitNativeFallback(
               threadId,
-              selectionWaiter,
-            ),
-          );
-          const selectionResponse = await selectionWaiter.promise;
-          if (!isRecord(selectionResponse) || selectionResponse.isError === true)
-            throw new Error('recovery selection MCP call failed');
-          const selectionPayload = selectionResponse.structuredContent;
-          const decisions = parseSelection(selectionPayload, selectionInput, candidates, now());
-          if (selectionInput.schema_version === 2) {
+              pending,
+              'stale_snapshot',
+              budgetReceipt.snapshot.correlation_id,
+            );
+          }
+          if (nativeFallback) candidates = null;
+          if (candidates === null || candidates === undefined) {
             emitDiagnostic({
-              phase: 'selection_accepted',
-              schemaVersion: 2,
-              optionsHash:
-                isRecord(selectionPayload) && typeof selectionPayload.options_hash === 'string'
-                  ? selectionPayload.options_hash
-                  : null,
-              fittingStage:
-                isRecord(selectionPayload) && isRecord(selectionPayload.fitting)
-                  ? selectionPayload.fitting.stage
-                  : null,
-              batchCount:
-                isRecord(selectionPayload) && isRecord(selectionPayload.stats)
-                  ? selectionPayload.stats.batch_count
-                  : null,
-              providerModel:
-                isRecord(selectionPayload) &&
-                (typeof selectionPayload.provider_model === 'string' ||
-                  selectionPayload.provider_model === null)
-                  ? selectionPayload.provider_model
-                  : null,
+              phase: 'selection',
+              stage: 'selection',
+              reason: 'unavailable',
+              threadId,
+              operationId: pending.operationId,
             });
+          } else {
+            pending.stage = 'selection';
+            const selectionInput = contextPolicy
+              ? {
+                  schema_version: 2,
+                  client: 'codex_app_server',
+                  client_version: clientVersion,
+                  session_ref: threadId,
+                  revision: sourceRevision,
+                  observed_at: new Date(now()).toISOString(),
+                  request_id: pending.operationId,
+                  policy_version: 'context-recovery-v2',
+                  options: selectionOptions(contextPolicy),
+                  projection: candidates.projection,
+                }
+              : {
+                  schema_version: 1,
+                  client: 'codex_app_server',
+                  client_version: clientVersion,
+                  session_ref: threadId,
+                  revision: sourceRevision,
+                  observed_at: new Date(now()).toISOString(),
+                  request_id: pending.operationId,
+                  policy_version: 'context-recovery-v1',
+                  projection: candidates.projection,
+                };
+            if (
+              typeof clientVersion !== 'string' ||
+              clientVersion.length < 1 ||
+              clientVersion.length > 64 ||
+              Buffer.byteLength(JSON.stringify(selectionInput), 'utf8') > MAX_SELECTION_BYTES
+            )
+              throw new Error('recovery selection input exceeds the contract bound');
+            const selectionWaiter = deferred();
+            pending.auxIds.push(
+              sendOwned(
+                'mcpServer/tool/call',
+                {
+                  threadId,
+                  server: brainServer,
+                  tool: 'brain_context_select',
+                  arguments: selectionInput,
+                },
+                'select',
+                threadId,
+                selectionWaiter,
+              ),
+            );
+            const selectionResponse = await selectionWaiter.promise;
+            const selectionError = parseContextError(selectionResponse);
+            if (!isRecord(selectionResponse) || selectionResponse.isError === true) {
+              if (selectionError?.quota === true) {
+                emitNativeFallback(
+                  threadId,
+                  pending,
+                  'admission_denied',
+                  selectionError.correlationId,
+                );
+                nativeFallback = true;
+              } else if (selectionError !== null) {
+                emitNativeFallback(
+                  threadId,
+                  pending,
+                  'provider_unavailable',
+                  selectionError.correlationId,
+                );
+                nativeFallback = true;
+              } else {
+                emitDiagnostic({
+                  phase: 'selection',
+                  stage: 'selection',
+                  reason: 'request_failed',
+                  threadId,
+                  operationId: pending.operationId,
+                  correlationId: selectionError?.correlationId,
+                });
+                throw new Error('recovery selection MCP call failed');
+              }
+            }
+            if (nativeFallback) {
+              emitDiagnostic({
+                phase: 'selection',
+                stage: 'selection',
+                reason: 'admission_denied',
+                threadId,
+                operationId: pending.operationId,
+              });
+            } else {
+              const selectionPayload = responseStructuredContent(selectionResponse);
+              const decisions = parseSelection(selectionPayload, selectionInput, candidates, now());
+              const selectionStats =
+                isRecord(selectionPayload) && isRecord(selectionPayload.stats)
+                  ? selectionPayload.stats
+                  : {};
+              telemetryFor(threadId).selectionCompleted({
+                operationId: pending.operationId,
+                counts: {
+                  eligible: Number.isSafeInteger(selectionStats.eligible_count)
+                    ? selectionStats.eligible_count
+                    : candidates.items.filter((item) => !item.protected).length,
+                  protected: Number.isSafeInteger(selectionStats.protected_count)
+                    ? selectionStats.protected_count
+                    : candidates.items.filter((item) => item.protected).length,
+                  selected: Number.isSafeInteger(selectionStats.selected_count)
+                    ? selectionStats.selected_count
+                    : decisions.filter((item) => item.keep).length,
+                },
+              });
+              if (selectionInput.schema_version === 2) {
+                emitDiagnostic({
+                  phase: 'selection_accepted',
+                  schemaVersion: 2,
+                  optionsHash:
+                    isRecord(selectionPayload) && typeof selectionPayload.options_hash === 'string'
+                      ? selectionPayload.options_hash
+                      : null,
+                  fittingStage:
+                    isRecord(selectionPayload) && isRecord(selectionPayload.fitting)
+                      ? selectionPayload.fitting.stage
+                      : null,
+                  batchCount:
+                    isRecord(selectionPayload) && isRecord(selectionPayload.stats)
+                      ? selectionPayload.stats.batch_count
+                      : null,
+                  providerModel:
+                    isRecord(selectionPayload) &&
+                    (typeof selectionPayload.provider_model === 'string' ||
+                      selectionPayload.provider_model === null)
+                      ? selectionPayload.provider_model
+                      : null,
+                  counts: {
+                    provider_eligible_count: candidates.items.filter((item) => !item.protected)
+                      .length,
+                    protected_candidate_count: candidates.items.filter((item) => item.protected)
+                      .length,
+                    protected_bundle_source_count: candidates.items
+                      .filter((item) => Array.isArray(item.sourceRefs))
+                      .reduce((count, item) => count + item.sourceRefs.length, 0),
+                  },
+                });
+              }
+              const rereadWaiter = deferred();
+              const rereadId = sendOwned(
+                'thread/read',
+                { threadId, includeTurns: true },
+                'read',
+                threadId,
+                rereadWaiter,
+              );
+              pending.auxIds.push(rereadId);
+              const reread = validateThreadRead(await rereadWaiter.promise, threadId);
+              if (hashJson(reread) !== sourceRevision)
+                throw new Error('recovery source changed during selection');
+              assertCurrent(threadId, state, pending, revision);
+              recoveryNotes = recoveryNotesText(
+                threadId,
+                sourceRevision,
+                selectionInput.request_id,
+                snapshot.capturedAt,
+                relative(recoveryDir, immutableCapturePath).replaceAll('\\', '/'),
+                resolve(recoveryDir),
+                candidates,
+                decisions,
+              );
+              pending.stage = 'notes';
+              await atomicWriteTextPrivate(
+                resolve(recoveryDir, `NOTES.${strictThreadName(threadId)}.md`),
+                recoveryNotes,
+              );
+              telemetryFor(threadId).notesWritten({ operationId: pending.operationId });
+              state.recovery = {
+                version: 1,
+                status: 'awaiting_native',
+                threadId,
+                sourceTurnId,
+                sourceRevision,
+                requestId: selectionInput.request_id,
+                notes: recoveryNotes,
+                notesHash: hashText(recoveryNotes),
+                notesFile: `NOTES.${strictThreadName(threadId)}.md`,
+                itemId: `recovery-${sourceRevision}`,
+                operationId: pending.operationId,
+                createdAt: new Date(now()).toISOString(),
+              };
+              state.recoveryLoaded = true;
+              await persistRecoveryState(threadId, state.recovery);
+              emitDiagnostic({
+                phase: 'selection',
+                stage: 'selection',
+                reason: 'completed',
+                threadId,
+                operationId: pending.operationId,
+                correlationId: selectionPayload.correlation_id,
+              });
+            }
           }
-          const rereadWaiter = deferred();
-          const rereadId = sendOwned(
-            'thread/read',
-            { threadId, includeTurns: true },
-            'read',
-            threadId,
-            rereadWaiter,
-          );
-          pending.auxIds.push(rereadId);
-          const reread = validateThreadRead(await rereadWaiter.promise, threadId);
-          if (hashJson(reread) !== sourceRevision)
-            throw new Error('recovery source changed during selection');
-          assertCurrent(threadId, state, pending, revision);
-          recoveryNotes = recoveryNotesText(
-            threadId,
-            sourceRevision,
-            selectionInput.request_id,
-            snapshot.capturedAt,
-            relative(recoveryDir, immutableCapturePath).replaceAll('\\', '/'),
-            resolve(recoveryDir),
-            candidates,
-            decisions,
-          );
-          await atomicWriteTextPrivate(
-            resolve(recoveryDir, `NOTES.${strictThreadName(threadId)}.md`),
-            recoveryNotes,
-          );
-          state.recovery = {
-            version: 1,
-            status: 'awaiting_native',
-            threadId,
-            sourceTurnId,
-            sourceRevision,
-            requestId: selectionInput.request_id,
-            notes: recoveryNotes,
-            notesHash: hashText(recoveryNotes),
-            notesFile: `NOTES.${strictThreadName(threadId)}.md`,
-            itemId: `recovery-${sourceRevision}`,
-            createdAt: new Date(now()).toISOString(),
-          };
-          state.recoveryLoaded = true;
-          await persistRecoveryState(threadId, state.recovery);
         }
         assertCurrent(threadId, state, pending, revision);
       }
+      pending.stage = 'native';
       pending.compactId = sendOwned('thread/compact/start', { threadId }, 'compact', threadId);
       pending.lifecycleArmed = true;
       await completion.promise;
@@ -1297,17 +2249,32 @@ export function createCodexContextProxy({
           completedAt: new Date(now()).toISOString(),
         };
         await persistRecoveryState(threadId, state.recovery);
+        telemetryFor(threadId).nativeCompleted({ operationId: pending.operationId });
         await attachRecovery(threadId, state);
-        onOutcome({
+        emitOutcome({
           threadId,
           status: 'native_completed',
           turnId: pending.turnId,
-          recoveryStatus: state.recovery?.status ?? 'pending_attachment',
+          operationId: pending.operationId,
+          recoveryStatus: 'pending_attachment',
+          telemetryAlreadyEmitted: true,
         });
       } else {
-        onOutcome({ threadId, status: 'completed', turnId: pending.turnId });
+        emitOutcome({
+          threadId,
+          status: 'completed',
+          operationId: pending.operationId,
+          turnId: pending.turnId,
+        });
       }
-    } catch {
+    } catch (error) {
+      emitDiagnostic({
+        phase: 'operation_failed',
+        stage: pending.stage ?? 'native',
+        reason: diagnosticReasonForError(error),
+        threadId,
+        operationId: pending.operationId,
+      });
       fail(threadId, 'checkpoint, request, or native completion failed');
     } finally {
       if (pending.timer) pending.timer();
@@ -1328,7 +2295,13 @@ export function createCodexContextProxy({
       const owned = ownedRequests.get(message.id);
       ownedRequests.delete(message.id);
       retire(message.id);
-      if (owned.kind === 'read' || owned.kind === 'select' || owned.kind === 'inject') {
+      if (
+        owned.kind === 'read' ||
+        owned.kind === 'select' ||
+        owned.kind === 'budget' ||
+        owned.kind === 'inject' ||
+        owned.kind === 'telemetry'
+      ) {
         const waiter = internalReads.get(message.id);
         internalReads.delete(message.id);
         if (waiter) {
@@ -1359,6 +2332,12 @@ export function createCodexContextProxy({
       const state = threadState(message.params.threadId);
       state.status =
         typeof message.params.status.type === 'string' ? message.params.status.type : 'unknown';
+      if (!state.telemetryConnected) {
+        state.telemetryConnected = true;
+        telemetryFor(message.params.threadId).connected({
+          triggerPercent: effectiveThreshold,
+        });
+      }
       state.idle = state.status === 'idle';
       if (!state.idle) invalidateAttachment(state);
       if (state.idle) void requestCompaction(message.params.threadId, state);
@@ -1384,6 +2363,16 @@ export function createCodexContextProxy({
       const state = threadState(params.threadId);
       state.usage = params.tokenUsage;
       state.usageReceivedAt = now();
+      telemetryFor(params.threadId).usage({
+        measurement: {
+          unit: 'tokens',
+          used: params.tokenUsage.last.totalTokens,
+          ...(hasKnownContextWindow(params.tokenUsage)
+            ? { capacity: params.tokenUsage.modelContextWindow }
+            : {}),
+        },
+        triggerPercent: effectiveThreshold,
+      });
       state.turnId = params.turnId;
       state.revision = `${state.turnId ?? 'unknown'}:${String(params.tokenUsage.last?.totalTokens ?? '')}:${String(params.tokenUsage.modelContextWindow ?? '')}`;
       if (
@@ -1427,6 +2416,13 @@ export function createCodexContextProxy({
         pending.turnId = typeof p.turnId === 'string' ? p.turnId : null;
         pending.started = true;
         pending.itemId = p.item.id ?? null;
+        emitDiagnostic({
+          phase: 'native_started',
+          stage: 'native',
+          reason: 'requested',
+          threadId: p.threadId,
+          operationId: pending.operationId,
+        });
       }
     }
     if (
@@ -1445,6 +2441,13 @@ export function createCodexContextProxy({
         pending.itemId === (p.item.id ?? null)
       ) {
         pending.itemCompleted = true;
+        emitDiagnostic({
+          phase: 'native_item_completed',
+          stage: 'native',
+          reason: 'completed',
+          threadId: p.threadId,
+          operationId: pending.operationId,
+        });
         if (pending.turnCompleted) pending.deferred.resolve();
       }
     }
@@ -1460,7 +2463,16 @@ export function createCodexContextProxy({
       if (pending?.lifecycleArmed && pending.turnId === turn.id) {
         if (turn.status === 'completed') pending.turnCompleted = true;
         else fail(message.params.threadId, 'native compaction turn failed');
-        if (pending.itemCompleted && pending.turnCompleted) pending.deferred.resolve();
+        if (pending.itemCompleted && pending.turnCompleted) {
+          emitDiagnostic({
+            phase: 'native_completed',
+            stage: 'native',
+            reason: 'completed',
+            threadId: message.params.threadId,
+            operationId: pending.operationId,
+          });
+          pending.deferred.resolve();
+        }
       }
     }
     if (
@@ -1497,9 +2509,10 @@ export function createCodexContextProxy({
   };
   const processLine = (line) => {
     if (Buffer.byteLength(line) > MAX_LINE_BYTES) {
-      if (line.includes('"id":"ai-brain-context-')) {
+      const ownedId = internalRequestId(line);
+      if (ownedId !== null) {
         stderr.write('codex-context: oversized internal response rejected\n');
-        failAll('oversized internal response');
+        failOversizedInternal(ownedId);
       } else forward(`${line}\n`);
       return;
     }
@@ -1511,29 +2524,63 @@ export function createCodexContextProxy({
     }
     if (forwardLine) forward(`${line}\n`);
   };
+  function internalRequestId(line) {
+    const match =
+      /^\s*\{\s*(?:"id"\s*:\s*"(ai-brain-context-[A-Za-z0-9._:-]{1,128})"|"jsonrpc"\s*:\s*"2\.0"\s*,\s*"id"\s*:\s*"(ai-brain-context-[A-Za-z0-9._:-]{1,128})")/u.exec(
+        line,
+      );
+    return match?.[1] ?? match?.[2] ?? null;
+  }
+  function failCompactions(reason) {
+    for (const [threadId, state] of threads) {
+      if (state.pending) fail(threadId, reason);
+    }
+  }
+  function failOversizedInternal(id) {
+    const owned = ownedRequests.get(id);
+    if (!owned) {
+      failCompactions('oversized internal response');
+      return;
+    }
+    cleanupRequest(id);
+    if (owned.kind === 'telemetry') return;
+    fail(owned.threadId, 'oversized internal response');
+  }
   child.stdout.on('data', (chunk) => {
     if (stopped) return;
-    inputBuffer += decoder.write(chunk);
+    const decoded = decoder.write(chunk);
+    if (discardOversized) {
+      const newline = decoded.indexOf('\n');
+      if (newline < 0) return;
+      discardOversized = false;
+      inputBuffer = decoded.slice(newline + 1);
+    } else inputBuffer += decoded;
     while (true) {
       const newline = inputBuffer.indexOf('\n');
       if (newline < 0) break;
       const line = inputBuffer.slice(0, newline);
       inputBuffer = inputBuffer.slice(newline + 1);
-      if (passthrough) {
+      if (discardOversized) {
+        discardOversized = false;
+      } else if (passthrough) {
         forward(`${line}\n`);
         passthrough = false;
-      } else if (discardOversized) {
-        discardOversized = false;
       } else processLine(line);
     }
     if (Buffer.byteLength(inputBuffer) > MAX_LINE_BYTES) {
-      if (inputBuffer.includes('"id":"ai-brain-context-')) {
+      if (passthrough) {
+        forward(inputBuffer);
+        inputBuffer = '';
+      } else if (internalRequestId(inputBuffer) !== null) {
         stderr.write('codex-context: oversized internal response rejected\n');
-        failAll('oversized internal response');
+        failOversizedInternal(internalRequestId(inputBuffer));
         discardOversized = true;
-      } else forward(inputBuffer);
-      inputBuffer = '';
-      if (!passthrough) passthrough = true;
+        inputBuffer = '';
+      } else {
+        forward(inputBuffer);
+        inputBuffer = '';
+        passthrough = true;
+      }
     }
   });
   child.stdout.on('end', () => {
@@ -1553,17 +2600,45 @@ export function createCodexContextProxy({
     failAll('app-server disconnected');
     emitDiagnostic({ phase: 'transport_close' });
   });
+  // Native app-server stderr is operational logging and may contain private
+  // paths, prompts or tool output. Drain the owned pipe without forwarding or
+  // persisting its contents; protocol errors remain on stdout and process exit
+  // status is still propagated by the launcher.
+  if (child.stderr && typeof child.stderr.on === 'function') {
+    child.stderr.on('data', () => undefined);
+    child.stderr.resume?.();
+  }
   return {
     threads,
-    stop() {
-      if (stopped) return;
+    async stop() {
+      if (stopped) {
+        await Promise.all(
+          [...diagnosticSinks.values()].map((sink) =>
+            typeof sink.flush === 'function'
+              ? Promise.resolve(sink.flush()).catch(() => undefined)
+              : undefined,
+          ),
+        );
+        return;
+      }
+      for (const reporter of telemetryByThread.values()) {
+        reporter.disconnected();
+        void reporter.flush();
+      }
       stopped = true;
       failAll('adapter stopped');
+      await Promise.all(
+        [...diagnosticSinks.values()].map((sink) =>
+          typeof sink.flush === 'function'
+            ? Promise.resolve(sink.flush()).catch(() => undefined)
+            : undefined,
+        ),
+      );
     },
   };
 }
 
-function main() {
+async function main() {
   if (process.argv.includes('--help')) {
     process.stderr.write(
       'Usage: node scripts/codex-context-compaction.mjs [app-server arguments...]\nStarts an owned Codex app-server and requests native compaction at CODEX_CONTEXT_COMPACT_AT (default 85).\n',
@@ -1572,19 +2647,58 @@ function main() {
   }
   const policy = parseContextPolicy();
   const command = process.env.CODEX_BIN ?? 'codex';
-  const child = spawn(command, ['app-server', ...process.argv.slice(2)], {
-    stdio: ['pipe', 'pipe', 'inherit'],
-    env: codexChildEnvironment(),
-  });
-  createCodexContextProxy({
+  const profile = process.env.CODEX_APP_SERVER_PROFILE;
+  if (profile !== undefined && !/^[A-Za-z0-9._-]{1,64}$/u.test(profile)) {
+    throw new Error('CODEX_APP_SERVER_PROFILE is invalid');
+  }
+  const child = spawn(
+    command,
+    [
+      ...(profile === undefined ? [] : ['--profile', profile]),
+      'app-server',
+      ...process.argv.slice(2),
+    ],
+    {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: codexChildEnvironment(),
+    },
+  );
+  let diagnosticFactory = null;
+  const diagnosticModule = process.env.CODEX_CONTEXT_DIAGNOSTICS_MODULE;
+  if (
+    process.env.CODEX_CONTEXT_DIAGNOSTICS_ENABLED === '1' &&
+    typeof diagnosticModule === 'string' &&
+    diagnosticModule.length > 0
+  ) {
+    try {
+      const module = await import(pathToFileURL(resolve(diagnosticModule)).href);
+      if (typeof module.createCodexDiagnosticSink === 'function') {
+        const stateDir = process.env.CODEX_CONTEXT_DIAGNOSTICS_DIR ?? process.cwd();
+        diagnosticFactory = (threadId) =>
+          module.createCodexDiagnosticSink({
+            stateDir,
+            sessionId: threadId,
+            clientVersion: process.env.CODEX_CLIENT_VERSION ?? '0.161.0',
+            enabled: true,
+          });
+      }
+    } catch {
+      diagnosticFactory = null;
+    }
+  }
+  const proxy = createCodexContextProxy({
     child,
     threshold: numberEnv('CODEX_CONTEXT_COMPACT_AT', DEFAULT_THRESHOLD),
     timeoutMs: numberEnv('CODEX_CONTEXT_COMPACT_TIMEOUT_MS', DEFAULT_TIMEOUT_MS),
     policy,
+    createDiagnosticSink: diagnosticFactory,
   });
   process.stdin.pipe(child.stdin);
   process.stdin.on('end', () => child.stdin.end());
-  child.on('exit', (code, signal) => (process.exitCode = code ?? (signal ? 1 : 0)));
+  child.on('exit', async (code, signal) => {
+    await proxy.stop();
+    process.exitCode = code ?? (signal ? 1 : 0);
+  });
 }
 if (process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname))
-  main();
+  void main();