@brunobracaioli/aibrain 0.1.0-beta.1 → 0.3.0-beta.13

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

@@ -1,23 +1,256 @@
 #!/usr/bin/env node
 
-import { chmod, lstat, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import {
+  chmod,
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  readdir,
+  rename,
+  unlink,
+  writeFile,
+} from 'node:fs/promises';
 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 captureFs = {
+  chmod,
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  readdir,
+  rename,
+  unlink,
+  writeFile,
+};
 
 const DEFAULT_THRESHOLD = 85;
 const COOLDOWN_MS = 60_000;
 const DEFAULT_TIMEOUT_MS = 120_000;
-const MAX_LINE_BYTES = 2 * 1024 * 1024;
-const MAX_CAPTURE_BYTES = 1 * 1024 * 1024;
+const MAX_LINE_BYTES = 8 * 1024 * 1024;
+const MAX_CAPTURE_BYTES = 8 * 1024 * 1024;
+const MAX_CAPTURE_PAGE_BYTES = 8 * 1024 * 1024;
+const MAX_CAPTURE_TOTAL_BYTES = 128 * 1024 * 1024;
+const MAX_CAPTURE_PAGES = 32;
+const MAX_CAPTURE_ITEMS = 65_536;
+const MAX_CAPTURE_DIRECTORY_BYTES = 256 * 1024 * 1024;
+const MAX_CAPTURE_STAGING_HEADROOM_BYTES = 16 * 1024 * 1024;
+const MAX_CAPTURE_FILES = 128;
+const CAPTURE_LOCK_WAIT_MS = 1_000;
 const MAX_OWNED_REQUESTS = 1_000;
 const MAX_RETIRED_REQUESTS = 2_000;
+const MAX_CLIENT_REQUEST_BINDINGS = 128;
+const MAX_OWNED_THREAD_IDS = 256;
 const MAX_RECOVERY_ITEMS = 128;
+const MAX_RECOVERY_SOURCE_INDEX = 65_536;
 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_DIAGNOSTIC_BYTES = MAX_CAPTURE_DIRECTORY_BYTES;
+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',
+  'capture_size_exceeded',
+  'capture_item_count_exceeded',
+  'private_storage_failed',
+  'storage_capacity_exceeded',
+  'attached',
+  'uncertain',
+  'disconnected',
+]);
+const FITTING_STAGES = new Set([
+  'original',
+  'inputs_1000',
+  'inputs_200',
+  'inputs_60',
+  'text_head_tail',
+  'text_omitted',
+  'compact_calls',
+  'callless_omitted',
+  'runs_folded',
+]);
+
+function isFiniteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+function isSafeBoundedInteger(value, minimum, maximum) {
+  return Number.isSafeInteger(value) && value >= minimum && value <= maximum;
+}
+
+/**
+ * Parse the optional v2 policy without allowing partial or unknown settings.
+ * @param {string|undefined} [raw]
+ */
+export function parseContextPolicy(raw = process.env.CODEX_CONTEXT_POLICY_JSON) {
+  if (raw === undefined || raw.trim() === '') return null;
+  if (Buffer.byteLength(raw, 'utf8') > MAX_POLICY_BYTES)
+    throw new Error('context policy exceeds 8KiB');
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw new Error('context policy is not valid JSON');
+  }
+  if (
+    !isRecord(value) ||
+    !hasOnlyKeys(value, [
+      'schemaVersion',
+      'compactAtPercent',
+      'keepThreshold',
+      'preserveRecentMessages',
+      'maxStateTokens',
+      'maxRequestTokens',
+      'goal',
+    ]) ||
+    value.schemaVersion !== 2 ||
+    !isFiniteNumber(value.compactAtPercent) ||
+    value.compactAtPercent < 1 ||
+    value.compactAtPercent > 95 ||
+    !isFiniteNumber(value.keepThreshold) ||
+    value.keepThreshold < 0 ||
+    value.keepThreshold > 1 ||
+    !isSafeBoundedInteger(value.preserveRecentMessages, 1, 100) ||
+    !isSafeBoundedInteger(value.maxStateTokens, 1_000, 25_000) ||
+    !isSafeBoundedInteger(value.maxRequestTokens, 1_000, 30_000) ||
+    value.maxRequestTokens <= value.maxStateTokens + 256 ||
+    (value.goal !== undefined &&
+      (typeof value.goal !== 'string' || value.goal.length > 4_000 || value.goal.length === 0))
+  )
+    throw new Error('context policy v2 is invalid');
+  return Object.freeze({
+    schemaVersion: 2,
+    compactAtPercent: value.compactAtPercent,
+    keepThreshold: value.keepThreshold,
+    preserveRecentMessages: value.preserveRecentMessages,
+    maxStateTokens: value.maxStateTokens,
+    maxRequestTokens: value.maxRequestTokens,
+    ...(value.goal === undefined ? {} : { goal: value.goal }),
+  });
+}
+
+function normalizeContextPolicy(policy) {
+  if (policy === undefined) return parseContextPolicy();
+  if (policy === null) return null;
+  try {
+    const serialized = JSON.stringify(policy);
+    if (typeof serialized !== 'string') throw new Error('policy is not serializable');
+    return parseContextPolicy(serialized);
+  } catch {
+    throw new Error('context policy v2 is invalid');
+  }
+}
+
+function selectionOptions(policy) {
+  return {
+    keep_threshold: policy.keepThreshold,
+    preserve_recent_items: policy.preserveRecentMessages,
+    max_state_tokens: policy.maxStateTokens,
+    max_request_tokens: policy.maxRequestTokens,
+  };
+}
+
+function validSelectionOptions(value) {
+  return (
+    isRecord(value) &&
+    hasOnlyKeys(value, [
+      'keep_threshold',
+      'preserve_recent_items',
+      'max_state_tokens',
+      'max_request_tokens',
+    ]) &&
+    isFiniteNumber(value.keep_threshold) &&
+    value.keep_threshold >= 0 &&
+    value.keep_threshold <= 1 &&
+    isSafeBoundedInteger(value.preserve_recent_items, 1, 100) &&
+    isSafeBoundedInteger(value.max_state_tokens, 1_000, 25_000) &&
+    isSafeBoundedInteger(value.max_request_tokens, 1_000, 30_000) &&
+    value.max_request_tokens > value.max_state_tokens + 256
+  );
+}
+
+function validateFitting(value, maxStateTokens = 25_000) {
+  if (value === null) return;
+  if (
+    !isRecord(value) ||
+    !hasOnlyKeys(value, [
+      'version',
+      'stage',
+      'estimator',
+      'before_estimated_state_tokens',
+      'after_estimated_state_tokens',
+    ]) ||
+    value.version !== 'state-fit-v1' ||
+    !FITTING_STAGES.has(value.stage) ||
+    value.estimator !== 'utf8-bytes-v1' ||
+    !isSafeBoundedInteger(value.before_estimated_state_tokens, 0, MAX_SELECTION_BYTES) ||
+    !isSafeBoundedInteger(value.after_estimated_state_tokens, 0, maxStateTokens) ||
+    value.after_estimated_state_tokens > value.before_estimated_state_tokens
+  )
+    throw new Error('invalid v2 fitting metadata');
+}
 
 function numberEnv(name, fallback) {
   const value = Number(process.env[name]);
@@ -101,10 +334,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]')
@@ -115,69 +351,978 @@ function redact(value, limit = 16_384) {
     .slice(0, limit);
 }
 
-async function ensurePrivateDirectory(directory) {
+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;
+}
+
+function safeRpcCode(value) {
+  return Number.isSafeInteger(value) && value >= -32_768 && value <= 32_767 ? value : null;
+}
+
+function clientRequestKey(value) {
+  if (typeof value === 'string' && value.length > 0 && value.length <= 128) return `s:${value}`;
+  if (Number.isSafeInteger(value)) return `n:${value}`;
+  return 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 = isSafeCorrelationId(event.correlationId) ? event.correlationId : null;
+  const rpcCode = safeRpcCode(event.rpcCode ?? event.rpc_code);
+  const counts = isRecord(event.counts)
+    ? Object.fromEntries(
+        Object.entries(event.counts).filter(
+          ([key, value]) =>
+            /^[a-z_]{1,48}$/u.test(key) &&
+            isSafeBoundedInteger(value, 0, /_bytes$/u.test(key) ? MAX_DIAGNOSTIC_BYTES : 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 }),
+    ...(rpcCode === null ? {} : { rpc_code: rpcCode }),
+    ...(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) {
+  if (DIAGNOSTIC_REASONS.has(error?.diagnosticReason)) return error.diagnosticReason;
+  if (safeRpcCode(error?.rpcCode) !== null) return 'protocol_error';
+  const message = error instanceof Error ? error.message : String(error ?? '');
+  if (
+    /snapshot exceeds bound|capture exceeds|capture size|oversized internal response/iu.test(
+      message,
+    )
+  )
+    return 'capture_size_exceeded';
+  if (/capture item count|source index exceeds bound/iu.test(message))
+    return 'capture_item_count_exceeded';
+  if (/capture storage capacity|storage capacity|capture directory/iu.test(message))
+    return 'storage_capacity_exceeded';
+  if (/capture source identity validation/iu.test(message)) return 'source_changed';
+  if (/capture candidate|checkpoint target/iu.test(message)) return 'private_storage_failed';
+  if (/thread\/(?:read|turns\/list)|capture history|page unavailable/iu.test(message))
+    return 'history_unavailable';
+  if (/checkpoint|recovery notes|private (?:file|storage)|storage|EACCES|ENOSPC/iu.test(message))
+    return 'private_storage_failed';
+  if (/tim(?:e|ed)[ -]?out/iu.test(message)) return 'timeout';
+  if (/closed|deleted/iu.test(message)) return 'thread_closed';
+  if (/source changed|state changed|stale/iu.test(message)) return 'source_changed';
+  if (/candidate|history|thread\/read/iu.test(message)) return 'history_unavailable';
+  return 'request_failed';
+}
+
+function rpcFailure(kind, error) {
+  const failure = new Error(`${kind} request rejected by the app-server`);
+  failure.name = 'CodexProtocolError';
+  failure.diagnosticReason = 'protocol_error';
+  failure.rpcCode = safeRpcCode(error?.code);
+  return failure;
+}
+
+function boundedFailureCounts(error) {
+  if (!isRecord(error)) return undefined;
+  const counts = {};
+  for (const [source, target] of [
+    ['captureItemCount', 'capture_item_count'],
+    ['captureItemLimit', 'capture_item_limit'],
+    ['captureBytes', 'capture_bytes'],
+    ['captureLimitBytes', 'capture_limit_bytes'],
+    ['responseBytes', 'response_bytes'],
+    ['responseLimitBytes', 'response_limit_bytes'],
+    ['captureDirectoryBytes', 'capture_directory_bytes'],
+    ['captureDirectoryLimitBytes', 'capture_directory_limit_bytes'],
+    ['captureFileCount', 'capture_file_count'],
+    ['captureFileLimit', 'capture_file_limit'],
+  ]) {
+    const maximum = target.includes('directory_bytes')
+      ? MAX_CAPTURE_DIRECTORY_BYTES
+      : target.includes('bytes')
+        ? MAX_DIAGNOSTIC_BYTES
+        : 1_000_000;
+    if (isSafeBoundedInteger(error[source], 0, maximum)) counts[target] = error[source];
+  }
+  return Object.keys(counts).length > 0 ? counts : undefined;
+}
+
+async function ensurePrivateDirectory(directory, fsOps = captureFs) {
   const target = resolve(directory);
-  await mkdir(target, { recursive: true, mode: 0o700 });
+  await fsOps.mkdir(target, { recursive: true, mode: 0o700 });
   const parts = target.split('/');
   let current = parts[0] === '' ? '/' : parts[0];
   for (const part of parts.slice(parts[0] === '' ? 1 : 1)) {
     if (!part) continue;
     current = current === '/' ? `/${part}` : `${current}/${part}`;
-    const info = await lstat(current);
+    const info = await fsOps.lstat(current);
     if (info.isSymbolicLink() || !info.isDirectory())
       throw new Error('checkpoint directory is unsafe');
   }
-  await chmod(target, 0o700);
+  await fsOps.chmod(target, 0o700);
   return target;
 }
-async function assertPrivateFile(file, label) {
-  const info = await lstat(file);
+async function assertPrivateFile(file, label, fsOps = captureFs) {
+  const info = await fsOps.lstat(file);
   if (info.isSymbolicLink() || !info.isFile() || (info.mode & 0o077) !== 0)
     throw new Error(`${label} is not a private regular file`);
   return info;
 }
-async function readPrivateFile(file, label, maxBytes = null) {
-  const info = await assertPrivateFile(file, label);
+async function readPrivateFile(file, label, maxBytes = null, fsOps = captureFs) {
+  const info = await assertPrivateFile(file, label, fsOps);
   if (maxBytes !== null && info.size > maxBytes) throw new Error(`${label} exceeds its bound`);
-  return readFile(file, 'utf8');
+  return fsOps.readFile(file, 'utf8');
 }
 
-async function atomicWritePrivate(file, value) {
-  const directory = await ensurePrivateDirectory(dirname(file));
+function captureCapacityError(state) {
+  const error = new Error('capture storage capacity exceeded');
+  error.diagnosticReason = 'storage_capacity_exceeded';
+  error.captureDirectoryBytes = state?.totalBytes ?? MAX_CAPTURE_DIRECTORY_BYTES;
+  error.captureDirectoryLimitBytes = MAX_CAPTURE_DIRECTORY_BYTES;
+  error.captureFileCount = state?.managedFiles?.length ?? MAX_CAPTURE_FILES;
+  error.captureFileLimit = MAX_CAPTURE_FILES;
+  return error;
+}
+
+function validateCaptureSnapshot(value, expectedSourceRevision = null) {
+  if (
+    !isRecord(value) ||
+    ![1, 2].includes(value.version) ||
+    typeof value.threadId !== 'string' ||
+    typeof value.sourceRevision !== 'string' ||
+    !/^[a-f0-9]{64}$/u.test(value.sourceRevision) ||
+    !isRecord(value.threadRead) ||
+    value.threadRead.thread?.id !== value.threadId ||
+    (value.version === 1 && hashJson(value.threadRead) !== value.sourceRevision) ||
+    (value.version === 2 &&
+      (!isRecord(value.captureManifest) ||
+        value.captureManifest.version !== 'codex-capture-manifest-v1' ||
+        value.captureManifest.sourceRevision !== value.sourceRevision ||
+        value.captureManifest.threadId !== value.threadId ||
+        !isSafeBoundedInteger(value.captureManifest.pageCount, 1, MAX_CAPTURE_PAGES) ||
+        !isSafeBoundedInteger(value.captureManifest.itemCount, 0, MAX_CAPTURE_ITEMS) ||
+        !isSafeBoundedInteger(value.captureManifest.totalBytes, 1, MAX_CAPTURE_TOTAL_BYTES) ||
+        !Array.isArray(value.captureManifest.segments) ||
+        value.captureManifest.segments.length !== value.captureManifest.pageCount ||
+        !Array.isArray(value.captureManifest.pageHashes) ||
+        value.captureManifest.pageHashes.length !== value.captureManifest.pageCount ||
+        value.captureManifest.pageHashes.some((hash) => !/^[a-f0-9]{64}$/u.test(hash)) ||
+        captureManifestRevision(value.threadRead.thread, value.captureManifest.pageHashes) !==
+          value.sourceRevision ||
+        value.captureManifest.segments.some(
+          (segment, index) =>
+            segment !== captureSegmentName(value.threadId, value.sourceRevision, index),
+        ))) ||
+    (expectedSourceRevision !== null && value.sourceRevision !== expectedSourceRevision)
+  )
+    throw new Error('capture source identity validation failed');
+  strictThreadName(value.threadId);
+  return value;
+}
+
+function validateCaptureSegment(value, expectedThreadId = null, expectedSourceRevision = null) {
+  if (
+    !isRecord(value) ||
+    value.version !== 'codex-capture-segment-v1' ||
+    typeof value.threadId !== 'string' ||
+    (expectedThreadId !== null && value.threadId !== expectedThreadId) ||
+    typeof value.sourceRevision !== 'string' ||
+    !/^[a-f0-9]{64}$/u.test(value.sourceRevision) ||
+    (expectedSourceRevision !== null && value.sourceRevision !== expectedSourceRevision) ||
+    !isSafeBoundedInteger(value.pageIndex, 0, MAX_CAPTURE_PAGES - 1) ||
+    !isRecord(value.page) ||
+    value.page.threadId !== value.threadId ||
+    !Array.isArray(value.page.turns) ||
+    typeof value.pageHash !== 'string' ||
+    !/^[a-f0-9]{64}$/u.test(value.pageHash) ||
+    hashJson(value.page) !== value.pageHash ||
+    !isSafeBoundedInteger(value.itemCount, 0, MAX_CAPTURE_ITEMS)
+  )
+    throw new Error('capture segment identity validation failed');
+  return value;
+}
+
+function captureSegmentName(threadId, sourceRevision, pageIndex) {
+  return `${strictThreadName(threadId)}.${sourceRevision}.segment-${String(pageIndex).padStart(4, '0')}.json`;
+}
+
+function captureManifestRevision(metadataThread, pageHashes) {
+  const thread = Object.fromEntries(
+    Object.entries(metadataThread).filter(([key]) => key !== 'turns'),
+  );
+  return hashJson({ thread, pages: pageHashes });
+}
+
+function captureNameForSnapshot(value, suffix = '') {
+  return `${strictThreadName(value.threadId)}${suffix}.json`;
+}
+
+async function readCaptureDirectoryState(directory, fsOps = captureFs) {
+  const entries = await fsOps.readdir(directory, { withFileTypes: true });
+  if (entries.length > MAX_CAPTURE_FILES * 4)
+    throw captureCapacityError({ totalBytes: MAX_CAPTURE_DIRECTORY_BYTES, managedFiles: [] });
+  const state = {
+    entryCount: entries.length,
+    totalBytes: 0,
+    managedFiles: [],
+    referencedImmutableNames: new Set(),
+    protectedGroups: new Set(),
+    manifestRefs: [],
+    blockedEntries: false,
+    unsafeRecovery: false,
+  };
+  for (const entry of entries) {
+    if (entry.name === '.capture.lock') continue;
+    const file = resolve(directory, entry.name);
+    const info = await fsOps.lstat(file);
+    state.totalBytes += info.size;
+    if (
+      info.isSymbolicLink() ||
+      !info.isFile() ||
+      (typeof process.getuid === 'function' && info.uid !== process.getuid()) ||
+      (info.mode & 0o077) !== 0
+    ) {
+      state.blockedEntries = true;
+      continue;
+    }
+    if (!entry.name.endsWith('.json')) continue;
+    let value;
+    try {
+      if (info.size > MAX_CAPTURE_BYTES) {
+        if (entry.name.endsWith('.recovery.json')) state.unsafeRecovery = true;
+        continue;
+      }
+      value = JSON.parse(await fsOps.readFile(file, 'utf8'));
+    } catch {
+      if (entry.name.endsWith('.recovery.json')) state.unsafeRecovery = true;
+      continue;
+    }
+    if (entry.name.endsWith('.recovery.json')) {
+      if (
+        isRecord(value) &&
+        typeof value.threadId === 'string' &&
+        /^[a-f0-9]{64}$/u.test(value.sourceRevision) &&
+        typeof value.notes === 'string' &&
+        typeof value.notesHash === 'string' &&
+        value.notesHash === hashText(value.notes)
+      ) {
+        try {
+          state.referencedImmutableNames.add(
+            `${strictThreadName(value.threadId)}.${value.sourceRevision}.json`,
+          );
+          state.protectedGroups.add(`${strictThreadName(value.threadId)}.${value.sourceRevision}`);
+        } catch {
+          state.unsafeRecovery = true;
+        }
+      } else state.unsafeRecovery = true;
+      if (isRecord(value) && typeof value.notes === 'string') {
+        const references = [
+          ...value.notes.matchAll(/capture_file:\s+.*?([A-Za-z0-9._-]+\.[a-f0-9]{64}\.json)/gu),
+        ];
+        for (const match of references) state.referencedImmutableNames.add(match[1]);
+      }
+      continue;
+    }
+    if (isRecord(value) && value.version === 'codex-capture-segment-v1') {
+      try {
+        validateCaptureSegment(value);
+        const expectedName = captureSegmentName(
+          value.threadId,
+          value.sourceRevision,
+          value.pageIndex,
+        );
+        if (entry.name !== expectedName) continue;
+        state.managedFiles.push({
+          file,
+          name: entry.name,
+          size: info.size,
+          mtimeMs: info.mtimeMs,
+          immutable: true,
+          group: `${value.threadId}.${value.sourceRevision}`,
+        });
+      } catch {
+        state.blockedEntries = true;
+      }
+      continue;
+    }
+    try {
+      validateCaptureSnapshot(value);
+    } catch {
+      continue;
+    }
+    const sourceName = `${strictThreadName(value.threadId)}.${value.sourceRevision}.json`;
+    if (
+      !new Set([
+        captureNameForSnapshot(value),
+        captureNameForSnapshot(value, '.completed'),
+        sourceName,
+      ]).has(entry.name)
+    )
+      continue;
+    state.managedFiles.push({
+      file,
+      name: entry.name,
+      size: info.size,
+      mtimeMs: info.mtimeMs,
+      immutable: entry.name === sourceName,
+      group: `${value.threadId}.${value.sourceRevision}`,
+    });
+    if (!entry.name.endsWith('.' + value.sourceRevision + '.json'))
+      state.referencedImmutableNames.add(sourceName);
+    if (value.version === 2 && entry.name !== sourceName) {
+      for (const segment of value.captureManifest.segments) {
+        if (typeof segment === 'string') state.referencedImmutableNames.add(segment);
+      }
+    }
+    if (value.version === 2) state.manifestRefs.push(value.captureManifest);
+    if (
+      value.version === 2 &&
+      state.protectedGroups.has(`${value.threadId}.${value.sourceRevision}`)
+    ) {
+      for (const segment of value.captureManifest.segments)
+        state.referencedImmutableNames.add(segment);
+    }
+  }
+  const managedNames = new Set(state.managedFiles.map((entry) => entry.name));
+  for (const manifest of state.manifestRefs) {
+    if (manifest.segments.some((segment) => !managedNames.has(segment)))
+      state.blockedEntries = true;
+  }
+  for (const entry of state.managedFiles) {
+    if (entry.group && state.referencedImmutableNames.has(entry.name))
+      state.protectedGroups.add(entry.group);
+  }
+  return state;
+}
+
+async function withCaptureStoreLock(
+  directory,
+  task,
+  fsOps = captureFs,
+  {
+    now = Date.now,
+    sleep = (milliseconds) =>
+      new Promise((resolvePromise) => setTimeout(resolvePromise, milliseconds)),
+  } = {},
+) {
+  const lockPath = resolve(directory, '.capture.lock');
+  const started = now();
+  while (true) {
+    let handle;
+    try {
+      handle = await fsOps.open(lockPath, 'wx', 0o600);
+      try {
+        return await task();
+      } finally {
+        await handle.close();
+        await fsOps.unlink(lockPath).catch(() => undefined);
+      }
+    } catch (error) {
+      if (handle) throw error;
+      if (error?.code !== 'EEXIST') throw error;
+      if (now() - started >= CAPTURE_LOCK_WAIT_MS)
+        throw captureCapacityError({ totalBytes: 0, managedFiles: [] });
+      await sleep(10);
+    }
+  }
+}
+
+async function writePrivateFile(file, serialized, fsOps = captureFs) {
+  const directory = await ensurePrivateDirectory(dirname(file), fsOps);
   const target = resolve(
     directory,
     file.startsWith(directory) ? file.slice(directory.length + 1) : file,
   );
   try {
-    await assertPrivateFile(target, 'checkpoint target');
+    await assertPrivateFile(target, 'checkpoint target', fsOps);
   } catch (error) {
     if (error?.code !== 'ENOENT') throw error;
   }
   const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
   try {
-    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
-    await rename(temporary, target);
+    await fsOps.writeFile(temporary, serialized, { flag: 'wx', mode: 0o600 });
+    await fsOps.rename(temporary, target);
   } catch (error) {
+    await fsOps.unlink(temporary).catch(() => undefined);
+    throw error;
+  }
+}
+
+async function writeBoundedCapture(file, serialized, value, fsOps = captureFs, lockOptions = {}) {
+  const directory = await ensurePrivateDirectory(dirname(file), fsOps);
+  const target = resolve(
+    directory,
+    file.startsWith(directory) ? file.slice(directory.length + 1) : file,
+  );
+  const targetName = target.slice(directory.length + 1);
+  const operation = async () => {
+    const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
+    const sourceName = `${strictThreadName(value.threadId)}.${value.sourceRevision}.json`;
+    const expectedNames = new Set([
+      captureNameForSnapshot(value),
+      captureNameForSnapshot(value, '.completed'),
+      sourceName,
+    ]);
+    let existingTarget = null;
     try {
-      await unlink(temporary);
-    } catch {
-      /* preserve the original failure */
+      existingTarget = await assertPrivateFile(target, 'capture target', fsOps);
+      const existing = JSON.parse(
+        await readPrivateFile(target, 'capture target', MAX_CAPTURE_BYTES, fsOps),
+      );
+      validateCaptureSnapshot(existing);
+      if (!expectedNames.has(targetName) || existing.threadId !== value.threadId)
+        throw new Error('capture target identity validation failed');
+      if (targetName === sourceName && existing.sourceRevision === value.sourceRevision) return;
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+    try {
+      await fsOps.writeFile(temporary, serialized, { flag: 'wx', mode: 0o600 });
+      const written = await assertPrivateFile(temporary, 'capture candidate', fsOps);
+      if (written.size !== Buffer.byteLength(serialized, 'utf8'))
+        throw new Error('capture candidate read-back size mismatch');
+      validateCaptureSnapshot(
+        JSON.parse(await fsOps.readFile(temporary, 'utf8')),
+        value.sourceRevision,
+      );
+      const state = await readCaptureDirectoryState(directory, fsOps);
+      if (state.unsafeRecovery || state.blockedEntries) throw captureCapacityError(state);
+      const protectedNames = new Set([targetName, sourceName]);
+      if (value.version === 2 && Array.isArray(value.captureManifest?.segments)) {
+        for (const segment of value.captureManifest.segments) protectedNames.add(segment);
+      }
+      const targetWasManaged = state.managedFiles.some((entry) => entry.name === targetName);
+      const eligibleGroups = new Map();
+      if (!state.blockedEntries) {
+        for (const entry of state.managedFiles) {
+          if (
+            !entry.immutable ||
+            protectedNames.has(entry.name) ||
+            state.referencedImmutableNames.has(entry.name) ||
+            state.protectedGroups.has(entry.group)
+          )
+            continue;
+          const group = entry.group ?? entry.name;
+          const members = eligibleGroups.get(group) ?? [];
+          members.push(entry);
+          eligibleGroups.set(group, members);
+        }
+      }
+      const eligible = [...eligibleGroups.values()].sort(
+        (left, right) =>
+          Math.min(...left.map((entry) => entry.mtimeMs)) -
+          Math.min(...right.map((entry) => entry.mtimeMs)),
+      );
+      const targetEntry = state.managedFiles.find((entry) => entry.name === targetName);
+      const replacedBytes = targetEntry?.size ?? 0;
+      const temporaryHeadroom = 2 * MAX_CAPTURE_BYTES;
+      let projectedPeakBytes = state.totalBytes;
+      let projectedSteadyBytes = state.totalBytes - replacedBytes;
+      let projectedFiles = state.managedFiles.length + (targetWasManaged ? 0 : 1);
+      const retire = [];
+      for (const group of eligible) {
+        if (
+          projectedPeakBytes <= MAX_CAPTURE_DIRECTORY_BYTES + temporaryHeadroom &&
+          projectedSteadyBytes <= MAX_CAPTURE_DIRECTORY_BYTES &&
+          projectedFiles <= MAX_CAPTURE_FILES
+        )
+          break;
+        const groupBytes = group.reduce((sum, entry) => sum + entry.size, 0);
+        projectedPeakBytes -= groupBytes;
+        projectedSteadyBytes -= groupBytes;
+        projectedFiles -= group.length;
+        retire.push(...group);
+      }
+      if (
+        projectedPeakBytes > MAX_CAPTURE_DIRECTORY_BYTES + temporaryHeadroom ||
+        projectedSteadyBytes > MAX_CAPTURE_DIRECTORY_BYTES ||
+        projectedFiles > MAX_CAPTURE_FILES
+      )
+        throw captureCapacityError(state);
+      const backup = existingTarget
+        ? `${target}.${process.pid}.${randomUUID()}.capture-backup`
+        : null;
+      const staged = [];
+      let backupCreated = false;
+      let candidatePublished = false;
+      try {
+        if (backup !== null) {
+          await fsOps.rename(target, backup);
+          backupCreated = true;
+        }
+        await fsOps.rename(temporary, target);
+        candidatePublished = true;
+        for (const candidate of retire) {
+          const stagedPath = `${candidate.file}.${process.pid}.${randomUUID()}.capture-retire`;
+          await fsOps.rename(candidate.file, stagedPath);
+          staged.push({ original: candidate.file, staged: stagedPath });
+        }
+        if (backup !== null) await fsOps.unlink(backup).catch(() => undefined);
+        for (const item of staged) await fsOps.unlink(item.staged).catch(() => undefined);
+      } catch (error) {
+        if (candidatePublished) await fsOps.unlink(target).catch(() => undefined);
+        for (const item of staged)
+          await fsOps.rename(item.staged, item.original).catch(() => undefined);
+        if (backupCreated && backup !== null)
+          await fsOps.rename(backup, target).catch(() => undefined);
+        throw error;
+      }
+    } catch (error) {
+      await fsOps.unlink(temporary).catch(() => undefined);
+      throw error;
     }
+  };
+  return lockOptions.lockHeld
+    ? operation()
+    : withCaptureStoreLock(directory, operation, fsOps, lockOptions);
+}
+
+async function atomicWritePrivate(
+  file,
+  value,
+  {
+    maxBytes = null,
+    compact = false,
+    capture = false,
+    captureLock = false,
+    captureLockHeld = false,
+  } = {},
+) {
+  const serialized = `${compact ? JSON.stringify(value) : JSON.stringify(value, null, 2)}\n`;
+  if (maxBytes !== null && Buffer.byteLength(serialized, 'utf8') > maxBytes) {
+    const error = new Error('capture snapshot exceeds bound');
+    error.diagnosticReason = 'capture_size_exceeded';
+    error.captureBytes = Buffer.byteLength(serialized, 'utf8');
+    error.captureLimitBytes = maxBytes;
     throw error;
   }
+  if (capture) {
+    const result = await writeBoundedCapture(file, serialized, value, captureFs, {
+      lockHeld: captureLockHeld,
+    });
+    return result;
+  }
+  const directory = await ensurePrivateDirectory(dirname(file));
+  if (captureLock) return withCaptureStoreLock(directory, () => writePrivateFile(file, serialized));
+  return writePrivateFile(file, serialized);
 }
-async function atomicWriteImmutablePrivate(file, value, sourceRevision) {
-  await ensurePrivateDirectory(dirname(file));
+async function atomicWriteImmutablePrivate(file, value, sourceRevision, captureLockHeld = false) {
+  validateCaptureSnapshot(value, sourceRevision);
+  await atomicWritePrivate(file, value, {
+    maxBytes: MAX_CAPTURE_BYTES,
+    compact: true,
+    capture: true,
+    captureLockHeld,
+  });
+}
+
+async function writeSegmentedCapture(
+  directory,
+  { threadId, sourceRevision, metadata, pages, lockHeld = false, fs = captureFs },
+) {
+  if (!Array.isArray(pages) || pages.length < 1 || pages.length > MAX_CAPTURE_PAGES)
+    throw new Error('capture page count exceeds bound');
+  const segments = [];
+  const prepared = [];
+  const cleanupSource = async () => {
+    for (const descriptor of pages) {
+      if (descriptor?.stagedPath) await fs.unlink(descriptor.stagedPath).catch(() => undefined);
+    }
+  };
   try {
-    const existing = JSON.parse(
-      await readPrivateFile(file, 'immutable capture', MAX_CAPTURE_BYTES),
-    );
-    if (existing?.sourceRevision === sourceRevision) return;
-    throw new Error('immutable capture already belongs to another source');
+    for (const [descriptorPosition, descriptor] of pages.entries()) {
+      if (
+        !isRecord(descriptor) ||
+        !isSafeBoundedInteger(descriptor.pageIndex, 0, MAX_CAPTURE_PAGES - 1) ||
+        descriptor.pageIndex !== descriptorPosition ||
+        typeof descriptor.stagedPath !== 'string' ||
+        typeof descriptor.pageHash !== 'string' ||
+        !/^[a-f0-9]{64}$/u.test(descriptor.pageHash)
+      )
+        throw new Error('capture staged page identity validation failed');
+      const page = JSON.parse(
+        await readPrivateFile(
+          descriptor.stagedPath,
+          'capture staged page',
+          MAX_CAPTURE_PAGE_BYTES,
+          fs,
+        ),
+      );
+      if (
+        !isRecord(page) ||
+        page.threadId !== threadId ||
+        !Array.isArray(page.turns) ||
+        hashJson(page) !== descriptor.pageHash
+      )
+        throw new Error('capture staged page integrity validation failed');
+      const payload = {
+        version: 'codex-capture-segment-v1',
+        threadId,
+        sourceRevision,
+        pageIndex: descriptor.pageIndex,
+        pageHash: descriptor.pageHash,
+        itemCount: page.turns.reduce(
+          (count, turn) => count + (Array.isArray(turn.items) ? turn.items.length : 0),
+          0,
+        ),
+        page,
+      };
+      validateCaptureSegment(payload, threadId, sourceRevision);
+      const serialized = `${JSON.stringify(payload)}\n`;
+      if (Buffer.byteLength(serialized, 'utf8') > MAX_CAPTURE_PAGE_BYTES)
+        throw new Error('capture page exceeds bound');
+      const stagedState = await readCaptureDirectoryState(directory, fs);
+      if (
+        stagedState.totalBytes + Buffer.byteLength(serialized, 'utf8') >
+        MAX_CAPTURE_DIRECTORY_BYTES + MAX_CAPTURE_STAGING_HEADROOM_BYTES
+      )
+        throw captureCapacityError(stagedState);
+      const stagedFinalPath = resolve(
+        directory,
+        `.capture-segment-stage.${safeThreadName(threadId)}.${randomUUID()}.${descriptor.pageIndex}.tmp`,
+      );
+      await fs.writeFile(stagedFinalPath, serialized, { flag: 'wx', mode: 0o600 });
+      prepared.push(stagedFinalPath);
+      segments.push({
+        name: captureSegmentName(threadId, sourceRevision, descriptor.pageIndex),
+        pageHash: descriptor.pageHash,
+        itemCount: payload.itemCount,
+        bytes: Buffer.byteLength(serialized, 'utf8'),
+        stagedPath: descriptor.stagedPath,
+        stagedFinalPath,
+      });
+    }
   } catch (error) {
-    if (error?.code !== 'ENOENT') throw error;
+    for (const file of prepared) await fs.unlink(file).catch(() => undefined);
+    await cleanupSource();
+    throw error;
+  }
+  const manifest = {
+    version: 'codex-capture-manifest-v1',
+    threadId,
+    sourceRevision,
+    pageCount: segments.length,
+    itemCount: segments.reduce((count, segment) => count + segment.itemCount, 0),
+    totalBytes: segments.reduce((count, segment) => count + segment.bytes, 0),
+    segments: segments.map((segment) => segment.name),
+    pageHashes: segments.map((segment) => segment.pageHash),
+  };
+  if (
+    isRecord(metadata?.thread) &&
+    captureManifestRevision(metadata.thread, manifest.pageHashes) !== sourceRevision
+  ) {
+    await cleanupSource();
+    for (const file of prepared) await fs.unlink(file).catch(() => undefined);
+    throw new Error('capture manifest revision does not match page hashes');
+  }
+  if (manifest.totalBytes > MAX_CAPTURE_TOTAL_BYTES || manifest.itemCount > MAX_CAPTURE_ITEMS) {
+    await cleanupSource();
+    for (const file of prepared) await fs.unlink(file).catch(() => undefined);
+    throw new Error('capture exceeds segmented bound');
+  }
+  const operation = async () => {
+    const state = await readCaptureDirectoryState(directory, fs);
+    if (state.unsafeRecovery || state.blockedEntries) {
+      await cleanupSource();
+      for (const file of prepared) await fs.unlink(file).catch(() => undefined);
+      throw captureCapacityError(state);
+    }
+    const staged = [];
+    const publishedTargets = [];
+    try {
+      for (const segment of segments) {
+        const target = resolve(directory, segment.name);
+        try {
+          await assertPrivateFile(target, 'capture segment', fs);
+          const existing = JSON.parse(
+            await readPrivateFile(target, 'capture segment', MAX_CAPTURE_PAGE_BYTES, fs),
+          );
+          validateCaptureSegment(existing, threadId, sourceRevision);
+          if (existing.pageHash !== segment.pageHash) throw new Error('capture segment collision');
+          await fs.unlink(segment.stagedFinalPath).catch(() => undefined);
+          continue;
+        } catch (error) {
+          if (error?.code !== 'ENOENT') throw error;
+        }
+        staged.push({ temporary: segment.stagedFinalPath, target, bytes: segment.bytes });
+      }
+      const protectedNames = new Set(segments.map((segment) => segment.name));
+      const groups = new Map();
+      for (const entry of state.managedFiles) {
+        if (
+          !entry.immutable ||
+          protectedNames.has(entry.name) ||
+          state.referencedImmutableNames.has(entry.name) ||
+          state.protectedGroups.has(entry.group)
+        )
+          continue;
+        const members = groups.get(entry.group ?? entry.name) ?? [];
+        members.push(entry);
+        groups.set(entry.group ?? entry.name, members);
+      }
+      const retired = [];
+      let projected = state.totalBytes;
+      let projectedFiles = state.managedFiles.length + staged.length;
+      for (const members of [...groups.values()].sort(
+        (left, right) =>
+          Math.min(...left.map((entry) => entry.mtimeMs)) -
+          Math.min(...right.map((entry) => entry.mtimeMs)),
+      )) {
+        if (projected <= MAX_CAPTURE_DIRECTORY_BYTES && projectedFiles <= MAX_CAPTURE_FILES) break;
+        const bytes = members.reduce((sum, entry) => sum + entry.size, 0);
+        projected -= bytes;
+        projectedFiles -= members.length;
+        retired.push(...members);
+      }
+      if (projected > MAX_CAPTURE_DIRECTORY_BYTES || projectedFiles > MAX_CAPTURE_FILES)
+        throw captureCapacityError({ totalBytes: projected, managedFiles: state.managedFiles });
+      const retiredPaths = [];
+      try {
+        for (const entry of retired) {
+          const stagedPath = `${entry.file}.${process.pid}.${randomUUID()}.capture-retire`;
+          await fs.rename(entry.file, stagedPath);
+          retiredPaths.push({ original: entry.file, staged: stagedPath });
+        }
+        for (const item of staged) await fs.rename(item.temporary, item.target);
+        publishedTargets.push(...staged.map((item) => item.target));
+        for (const segment of segments) {
+          const verify = JSON.parse(
+            await readPrivateFile(
+              resolve(directory, segment.name),
+              'capture segment',
+              MAX_CAPTURE_PAGE_BYTES,
+              fs,
+            ),
+          );
+          validateCaptureSegment(verify, threadId, sourceRevision);
+        }
+        for (const segment of segments) await fs.unlink(segment.stagedPath).catch(() => undefined);
+        for (const file of prepared) await fs.unlink(file).catch(() => undefined);
+        for (const item of retiredPaths) await fs.unlink(item.staged).catch(() => undefined);
+        return manifest;
+      } catch (error) {
+        for (const item of retiredPaths)
+          await fs.rename(item.staged, item.original).catch(() => undefined);
+        if (error?.code === 'ENOENT') throw captureCapacityError(state);
+        throw error;
+      }
+    } catch (error) {
+      for (const item of staged) {
+        await fs.unlink(item.temporary).catch(() => undefined);
+        await fs.unlink(item.target).catch(() => undefined);
+      }
+      for (const target of publishedTargets) await fs.unlink(target).catch(() => undefined);
+      for (const segment of segments) await fs.unlink(segment.stagedPath).catch(() => undefined);
+      for (const file of prepared) await fs.unlink(file).catch(() => undefined);
+      throw error;
+    }
+  };
+  return lockHeld ? operation() : withCaptureStoreLock(directory, operation, fs);
+}
+
+/**
+ * Test seam for the segmented capture store. Pages are written as private
+ * staging files first, then published as one lock-bound capture group.
+ */
+export async function __testWriteSegmentedCapture(
+  directory,
+  { threadId, sourceRevision, metadata = { thread: { id: threadId } }, pages },
+  { fs = captureFs } = {},
+) {
+  await ensurePrivateDirectory(directory, fs);
+  const staged = [];
+  try {
+    for (const [pageIndex, page] of pages.entries()) {
+      const serialized = `${JSON.stringify(page)}\n`;
+      const state = await readCaptureDirectoryState(directory, fs);
+      if (state.totalBytes + Buffer.byteLength(serialized, 'utf8') > MAX_CAPTURE_DIRECTORY_BYTES)
+        throw captureCapacityError(state);
+      const stagedPath = resolve(
+        directory,
+        `.capture-stage.test.${safeThreadName(threadId)}.${randomUUID()}.${pageIndex}.tmp`,
+      );
+      await fs.writeFile(stagedPath, serialized, { flag: 'wx', mode: 0o600 });
+      staged.push({
+        pageIndex,
+        stagedPath,
+        pageHash: hashJson(page),
+        bytes: Buffer.byteLength(serialized, 'utf8'),
+      });
+    }
+    return await writeSegmentedCapture(directory, {
+      threadId,
+      sourceRevision,
+      metadata,
+      pages: staged,
+      fs,
+    });
+  } catch (error) {
+    for (const page of staged) await fs.unlink(page.stagedPath).catch(() => undefined);
+    throw error;
   }
-  await atomicWritePrivate(file, value);
+}
+
+// Test-only seam for deterministic capture-store fault injection. Production
+// code continues to use the immutable writer above with the real filesystem.
+export async function __testWriteBoundedCapture(
+  file,
+  value,
+  { fs = captureFs, now = Date.now, sleep } = {},
+) {
+  const serialized = `${JSON.stringify(value)}\n`;
+  if (Buffer.byteLength(serialized, 'utf8') > MAX_CAPTURE_BYTES)
+    throw new Error('capture snapshot exceeds bound');
+  validateCaptureSnapshot(value, value.sourceRevision);
+  return writeBoundedCapture(file, serialized, value, fs, { now, sleep });
 }
 async function atomicWriteTextPrivate(file, text) {
   if (Buffer.byteLength(text) > MAX_NOTE_BYTES) throw new Error('recovery notes exceed bound');
@@ -219,17 +1364,156 @@ function validateThreadRead(value, threadId) {
   return value;
 }
 
-export function buildRecoveryCandidates(read, revision) {
+function validateThreadMetadata(value, threadId) {
+  if (!isRecord(value) || !isRecord(value.thread) || value.thread.id !== threadId)
+    throw new Error('thread/read returned invalid thread metadata');
+  return value;
+}
+
+export function parseTurnsPage(value, threadId, pageIndex) {
+  if (!isRecord(value)) throw new Error('thread/turns/list returned invalid page');
+  const data = Array.isArray(value.data)
+    ? value.data
+    : Array.isArray(value.turns)
+      ? value.turns
+      : null;
+  if (data === null || data.some((turn) => !isRecord(turn) || typeof turn.id !== 'string'))
+    throw new Error('thread/turns/list returned invalid turns');
+  const page = { threadId, turns: data };
+  const serializedBytes = Buffer.byteLength(JSON.stringify(page), 'utf8');
+  if (serializedBytes > MAX_CAPTURE_PAGE_BYTES) {
+    const error = new Error('capture page exceeds bound');
+    error.diagnosticReason = 'capture_size_exceeded';
+    error.captureBytes = serializedBytes;
+    error.captureLimitBytes = MAX_CAPTURE_PAGE_BYTES;
+    throw error;
+  }
+  const cursor = value.nextCursor ?? value.next_cursor ?? null;
+  if (cursor !== null && (typeof cursor !== 'string' || cursor.length > 512))
+    throw new Error('thread/turns/list returned invalid cursor');
+  return { page, pageIndex, cursor };
+}
+
+function summarizeCaptureItem(item) {
+  if (!isRecord(item)) return { type: 'unknown' };
+  const summary = { type: typeof item.type === 'string' ? item.type : 'unknown' };
+  if (typeof item.id === 'string') summary.id = item.id;
+  if (summary.type === 'userMessage') {
+    const parts = Array.isArray(item.content)
+      ? item.content.filter((part) => isRecord(part) && typeof part.text === 'string')
+      : [];
+    const contentChars = parts.reduce((total, part) => total + part.text.length, 0);
+    summary.content = parts.slice(0, 64).map((part) => ({
+      type: part.type,
+      text: part.text.slice(0, MAX_NOTE_ITEM_CHARS),
+    }));
+    summary.contentChars = contentChars;
+    summary.bodyComplete =
+      parts.length <= 64 && parts.every((part) => part.text.length <= MAX_NOTE_ITEM_CHARS);
+  } else if (summary.type === 'agentMessage' || summary.type === 'plan') {
+    const text = typeof item.text === 'string' ? item.text : '';
+    summary.text = text.slice(0, MAX_NOTE_ITEM_CHARS);
+    summary.textChars = text.length;
+    summary.bodyComplete = text.length <= MAX_NOTE_ITEM_CHARS;
+  } else if (summary.type === 'commandExecution') {
+    const command = typeof item.command === 'string' ? item.command : '';
+    summary.command = command.slice(0, MAX_NOTE_ITEM_CHARS);
+    summary.commandComplete = command.length <= MAX_NOTE_ITEM_CHARS;
+    for (const key of ['status', 'exitCode']) {
+      if (key in item && (typeof item[key] === 'string' || typeof item[key] === 'number'))
+        summary[key] = item[key];
+    }
+    summary.aggregatedOutput = String(item.aggregatedOutput ?? item.output ?? '').slice(0, 1024);
+    summary.outputChars = String(item.aggregatedOutput ?? item.output ?? '').length;
+  }
+  return summary;
+}
+
+function summarizeCaptureTurn(turn) {
+  return {
+    ...(typeof turn.id === 'string' ? { id: turn.id } : {}),
+    ...(typeof turn.status === 'string' ? { status: turn.status } : {}),
+    items: turn.items.map(summarizeCaptureItem),
+  };
+}
+
+export function mergePaginatedTurns(metadata, pages, threadId) {
+  validateThreadMetadata(metadata, threadId);
+  if (!Array.isArray(pages) || pages.length < 1 || pages.length > MAX_CAPTURE_PAGES)
+    throw new Error('capture page count exceeds bound');
+  const turns = [];
+  const ids = new Set();
+  const itemIds = new Set();
+  let itemCount = 0;
+  for (const [pagePosition, entry] of pages.entries()) {
+    const page = entry?.page;
+    if (!isRecord(page) || page.threadId !== threadId || !Array.isArray(page.turns))
+      throw new Error('capture page identity validation failed');
+    if (entry.pageIndex !== pagePosition) throw new Error('capture pages are out of order');
+    for (const turn of page.turns) {
+      if (!isRecord(turn) || typeof turn.id !== 'string' || ids.has(turn.id))
+        throw new Error('capture history contains duplicate turn');
+      ids.add(turn.id);
+      if (!Array.isArray(turn.items)) throw new Error('capture turn items are unavailable');
+      for (const item of turn.items) {
+        if (isRecord(item) && typeof item.id === 'string') {
+          if (itemIds.has(item.id)) throw new Error('capture history contains duplicate item');
+          itemIds.add(item.id);
+        }
+      }
+      itemCount += turn.items.length;
+      if (itemCount > MAX_CAPTURE_ITEMS) {
+        const error = new Error('capture item count exceeds bound');
+        error.captureItemCount = itemCount;
+        error.captureItemLimit = MAX_CAPTURE_ITEMS;
+        throw error;
+      }
+      turns.push(turn);
+    }
+  }
+  if (turns.length === 0) throw new Error('thread/turns/list returned no recoverable turns');
+  return { thread: { ...metadata.thread, turns } };
+}
+
+function captureSourceRevision(capture) {
+  if (capture.pages === null) return hashJson(capture.read);
+  return captureManifestRevision(
+    capture.metadata.thread,
+    capture.pages.map(({ pageHash }) => pageHash),
+  );
+}
+
+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) {
+    const error = new Error('recovery source index exceeds bound');
+    error.captureItemCount = rawItems.length;
+    error.captureItemLimit = MAX_RECOVERY_SOURCE_INDEX;
+    throw error;
+  }
+  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 =
       type === 'commandExecution' ? String(item.aggregatedOutput ?? item.output ?? '') : '';
+    const sourceOutputChars =
+      type === 'commandExecution' && isSafeCounter(item.outputChars)
+        ? item.outputChars
+        : commandOutput.length;
     const command = typeof item.command === 'string' ? item.command : 'unknown';
+    const bodyComplete = item.bodyComplete !== false;
     const status = typeof item.status === 'string' ? item.status : 'unknown';
     const exitCode = typeof item.exitCode === 'number' ? item.exitCode : null;
     const localText =
@@ -275,9 +1559,11 @@ export function buildRecoveryCandidates(read, revision) {
         ) &&
         (commandName !== 'git' ||
           ['status', 'diff', 'log', 'show', 'rev-parse'].includes(commandWords[1])));
-    const unknownCommand = type === 'commandExecution' && !readOnlyCommand;
+    const unknownCommand =
+      type === 'commandExecution' && (!readOnlyCommand || item.commandComplete === false);
     const unknown = !['userMessage', 'agentMessage', 'plan', 'commandExecution'].includes(type);
-    const recent = index >= Math.max(0, rawItems.length - 6);
+    const recentCount = policy?.preserveRecentMessages ?? 6;
+    const recent = index >= Math.max(0, rawItems.length - recentCount);
     const protectedItem =
       kind === 'user_message' ||
       kind === 'plan' ||
@@ -296,7 +1582,14 @@ export function buildRecoveryCandidates(read, revision) {
     if (unknownCommand) pinReasons.push('unknown');
     if (unknown) pinReasons.push('unknown');
     if (recent && pinReasons.length === 0) pinReasons.push('recent');
-    const localChars = type === 'commandExecution' ? commandOutput.length : localText.length;
+    const localChars =
+      type === 'commandExecution'
+        ? sourceOutputChars
+        : type === 'userMessage' && isSafeCounter(item.contentChars)
+          ? item.contentChars
+          : (type === 'agentMessage' || type === 'plan') && isSafeCounter(item.textChars)
+            ? item.textChars
+            : localText.length;
     return {
       id: `recovery-${index + 1}`,
       text: redact(localText, 16_384),
@@ -306,19 +1599,102 @@ export function buildRecoveryCandidates(read, revision) {
       pinReasons,
       source: rawItem,
       sourceItemId: typeof item.id === 'string' ? item.id : `item-${index + 1}`,
-      sourceBodyChars: commandOutput.length,
+      sourceLocation: { flatIndex: index, turnIndex, itemIndex },
+      sourceRefs: null,
+      sourceBodyChars: sourceOutputChars,
+      bodyComplete,
       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: redact(
-      items
-        .filter((item) => item.kind === 'user_message')
-        .slice(-3)
-        .map((item) => item.text)
-        .join('\n'),
-      4_000,
+    goal:
+      policy?.goal !== undefined
+        ? redact(policy.goal, 4_000)
+        : redact(
+            items
+              .filter((item) => item.kind === 'user_message')
+              .slice(-3)
+              .map((item) => item.text)
+              .join('\n'),
+            4_000,
+          ),
+    items: items.map(({ id, kind, text, localChars, protected: protectedItem, pinReasons }) => ({
+      id,
+      kind,
+      text,
+      local_chars: localChars,
+      protected: protectedItem,
+      pin_reasons: pinReasons,
+    })),
+  };
+  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,
@@ -328,34 +1704,105 @@ export function buildRecoveryCandidates(read, revision) {
       pin_reasons: pinReasons,
     })),
   };
-  return { items, projection, projectionHash: hashJson(projection), revision };
+}
+
+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 = [
+    'schema_version',
+    'status',
+    'applied',
+    'persisted',
+    'request_id',
+    'correlation_id',
+    'session_ref',
+    'revision',
+    'projection_hash',
+    'policy_version',
+    'provider_model',
+    'created_at',
+    'expires_at',
+    'decisions',
+    'stats',
+  ];
+  const expectedOptionsHash =
+    v2 && validSelectionOptions(input.options) ? hashJson(input.options) : null;
   const expiresAt =
     isRecord(value) && isTimestamp(value.expires_at) ? Date.parse(value.expires_at) : Number.NaN;
   const createdAt =
     isRecord(value) && isTimestamp(value.created_at) ? Date.parse(value.created_at) : Number.NaN;
   if (
     !isRecord(value) ||
-    !hasOnlyKeys(value, [
-      'schema_version',
-      'status',
-      'applied',
-      'persisted',
-      'request_id',
-      'correlation_id',
-      'session_ref',
-      'revision',
-      'projection_hash',
-      'policy_version',
-      'provider_model',
-      'created_at',
-      'expires_at',
-      'decisions',
-      'stats',
-    ]) ||
-    value.schema_version !== 1 ||
+    !hasOnlyKeys(value, v2 ? [...baseKeys, 'options_hash', 'fitting'] : baseKeys) ||
+    value.schema_version !== (v2 ? 2 : 1) ||
     !['planned', 'noop'].includes(value.status) ||
     value.applied !== false ||
     value.persisted !== false ||
@@ -363,7 +1810,11 @@ export function parseSelection(value, input, candidates, currentTime = Date.now(
     value.session_ref !== input.session_ref ||
     value.revision !== input.revision ||
     value.projection_hash !== candidates.projectionHash ||
-    value.policy_version !== 'context-recovery-v1' ||
+    value.policy_version !== (v2 ? 'context-recovery-v2' : 'context-recovery-v1') ||
+    (v2 &&
+      (!validSelectionOptions(input.options) ||
+        typeof value.options_hash !== 'string' ||
+        value.options_hash !== expectedOptionsHash)) ||
     typeof value.correlation_id !== 'string' ||
     value.correlation_id.length === 0 ||
     value.correlation_id.length > 128 ||
@@ -401,6 +1852,8 @@ export function parseSelection(value, input, candidates, currentTime = Date.now(
     !Array.isArray(value.decisions)
   )
     throw new Error('invalid recovery selection binding');
+  if (v2) validateFitting(value.fitting, input.options.max_state_tokens);
+  const keepThreshold = v2 ? input.options.keep_threshold : 0.2;
   const byId = new Map(candidates.items.map((item) => [item.id, item]));
   if (value.decisions.length !== candidates.items.length)
     throw new Error('incomplete recovery selection');
@@ -437,7 +1890,7 @@ export function parseSelection(value, input, candidates, currentTime = Date.now(
       (!candidate.protected && decision.reason === 'protected') ||
       (decision.reason === 'relevant' && decision.keep !== true) ||
       (decision.reason === 'below_threshold' && decision.keep !== false) ||
-      (!candidate.protected && decision.keep !== decision.probability >= 0.2)
+      (!candidate.protected && decision.keep !== decision.probability >= keepThreshold)
     )
       throw new Error('recovery decision semantics do not match the selection contract');
     decisions.push(decision);
@@ -464,6 +1917,44 @@ 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 unique = [];
+    const seen = new Set();
+    for (const ref of sorted) {
+      const key = `${ref.flatIndex}:${ref.turnIndex}:${ref.itemIndex}:${String(ref.sourceItemId ?? '')}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      unique.push(ref);
+    }
+    const ranges = [];
+    for (const ref of unique) {
+      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: unique.map((ref) => `${ref.turnIndex}:${ref.itemIndex}`).join(','),
+      ids: unique
+        .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]),
   );
@@ -477,6 +1968,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',
@@ -485,10 +1977,16 @@ 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' &&
+      item.bodyComplete !== false &&
       item.localText.length > 0 &&
       item.localText.length <= MAX_NOTE_ITEM_CHARS &&
       Buffer.byteLength(item.localText, 'utf8') <= inlineBudget;
@@ -512,27 +2010,6 @@ export function recoveryNotesText(
   return `${lines.join('\n')}`;
 }
 
-function recoveryInjectionState(read, notes) {
-  const matches = read.thread.turns
-    .flatMap((turn) => (Array.isArray(turn.items) ? turn.items : []))
-    .filter(
-      (item) =>
-        isRecord(item) &&
-        ((item.type === 'message' &&
-          item.role === 'user' &&
-          Array.isArray(item.content) &&
-          item.content.some(
-            (part) => isRecord(part) && part.type === 'input_text' && part.text === notes,
-          )) ||
-          (item.type === 'userMessage' &&
-            Array.isArray(item.content) &&
-            item.content.some(
-              (part) => isRecord(part) && part.type === 'text' && part.text === notes,
-            ))),
-    );
-  return matches.length === 0 ? 'absent' : matches.length === 1 ? 'present' : 'ambiguous';
-}
-
 /** Own a Codex app-server process and request native compaction after a fresh usage event. */
 export function createCodexContextProxy({
   child,
@@ -540,6 +2017,7 @@ export function createCodexContextProxy({
   stderr = process.stderr,
   now = () => Date.now(),
   threshold = DEFAULT_THRESHOLD,
+  policy = undefined,
   timeoutMs = DEFAULT_TIMEOUT_MS,
   checkpointDir = process.env.CODEX_CONTEXT_CHECKPOINT_DIR ?? '.codex/context-checkpoints',
   recoveryDir = process.env.CODEX_CONTEXT_RECOVERY_DIR ?? '.notes/context',
@@ -551,17 +2029,104 @@ 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',
 }) {
+  const contextPolicy = normalizeContextPolicy(policy);
+  const effectiveThreshold = contextPolicy?.compactAtPercent ?? threshold;
   const threads = new Map();
   const ownedRequests = new Map();
+  const ownedThreadIds = new Set();
+  const clientRequestBindings = 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 */
     }
@@ -589,9 +2154,10 @@ export function createCodexContextProxy({
     attachment.invalidated = true;
     cleanupRequest(attachment.readId);
     cleanupRequest(attachment.injectId);
+    for (const id of attachment.auxIds ?? []) cleanupRequest(id);
   }
 
-  function fail(threadId, reason) {
+  function fail(threadId, reason, cause = null) {
     const state = threads.get(threadId);
     const pending = state?.pending;
     invalidateAttachment(state);
@@ -602,7 +2168,17 @@ 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(cause ?? new Error(reason)),
+      threadId,
+      operationId,
+      ...(boundedFailureCounts(cause) === undefined ? {} : { counts: boundedFailureCounts(cause) }),
+      ...(safeRpcCode(cause?.rpcCode) === null ? {} : { rpcCode: cause.rpcCode }),
+    });
     stderr.write(`codex-context: native compaction preserved (${reason})\n`);
   }
   function failAll(reason) {
@@ -643,10 +2219,28 @@ export function createCodexContextProxy({
       recoveryLoaded: false,
       recoveryLoadPromise: null,
       recoveryAttach: null,
+      telemetryConnected: false,
+      owned: false,
+      // Codex can publish an idle/usage snapshot before a resumed thread has
+      // finished loading. Native MCP and compact requests sent in that gap
+      // are rejected as invalid requests by the 0.163 app-server.
+      resumePending: false,
+      resumeRetryRequested: false,
+      resumeRequests: new Set(),
     };
     threads.set(threadId, created);
     return created;
   }
+  function claimOwnedThread(threadId) {
+    const existing = threads.get(threadId);
+    if (!existing && ownedThreadIds.size >= MAX_OWNED_THREAD_IDS) return null;
+    const state = existing ?? threadState(threadId);
+    if (state.owned) return state;
+    if (ownedThreadIds.size >= MAX_OWNED_THREAD_IDS) return null;
+    state.owned = true;
+    ownedThreadIds.add(threadId);
+    return state;
+  }
   function sendOwned(method, params, kind, threadId, waiter) {
     if (ownedRequests.size >= MAX_OWNED_REQUESTS)
       throw new Error('too many pending adapter requests');
@@ -661,10 +2255,345 @@ 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');
   }
+  async function readThreadCapture(
+    threadId,
+    pending,
+    firstWaiter = null,
+    { onPage = null, readId: existingReadId = null, verifyOnly = false } = {},
+  ) {
+    const waiter = firstWaiter ?? deferred();
+    const readId =
+      existingReadId ??
+      sendOwned('thread/read', { threadId, includeTurns: false }, 'read', threadId, waiter);
+    if (pending) {
+      pending.readId = readId;
+      pending.auxIds.push(readId);
+    }
+    const metadata = validateThreadMetadata(await waiter.promise, threadId);
+    if (Array.isArray(metadata.thread.turns) && metadata.thread.turns.length > 0) {
+      const legacy = validateThreadRead(metadata, threadId);
+      await onPage?.(metadata.thread);
+      return { read: legacy, metadata, pages: null };
+    }
+    const pages = [];
+    const seenTurnIds = new Set();
+    const seenItemIds = new Set();
+    let totalItems = 0;
+    if (!verifyOnly) await ensurePrivateDirectory(checkpointDir);
+    const summaryTurns = [];
+    const stagedFiles = [];
+    let stagedBytes = 0;
+    const cleanupStaged = async () => {
+      for (const file of stagedFiles) await unlink(file).catch(() => undefined);
+    };
+    const seenCursors = new Set();
+    let cursor = null;
+    for (let pageIndex = 0; pageIndex < MAX_CAPTURE_PAGES; pageIndex += 1) {
+      let pageResponse;
+      let pageLimit = 16;
+      for (let attempt = 0; attempt < 5; attempt += 1) {
+        const pageWaiter = deferred();
+        const params = {
+          threadId,
+          itemsView: 'full',
+          sortDirection: 'asc',
+          limit: pageLimit,
+        };
+        if (cursor !== null) params.cursor = cursor;
+        const pageId = sendOwned('thread/turns/list', params, 'page', threadId, pageWaiter);
+        if (pending) pending.auxIds.push(pageId);
+        try {
+          pageResponse = await pageWaiter.promise;
+          break;
+        } catch (error) {
+          if (error?.diagnosticReason === 'capture_size_exceeded' && attempt < 4) {
+            pageLimit = Math.max(1, Math.floor(pageLimit / 2));
+            continue;
+          }
+          await cleanupStaged();
+          if (error?.rpcCode === -32601 && pages.length === 0) {
+            const legacyWaiter = deferred();
+            const legacyId = sendOwned(
+              'thread/read',
+              { threadId, includeTurns: true },
+              'read',
+              threadId,
+              legacyWaiter,
+            );
+            if (pending) pending.auxIds.push(legacyId);
+            const legacy = validateThreadRead(await legacyWaiter.promise, threadId);
+            return { read: legacy, metadata, pages: null };
+          }
+          throw error;
+        }
+      }
+      if (pageResponse === undefined) throw new Error('thread/turns/list page unavailable');
+      try {
+        const parsed = parseTurnsPage(pageResponse, threadId, pageIndex);
+        if (parsed.page.turns.length === 0 && parsed.cursor !== null)
+          throw new Error('thread/turns/list returned empty page with cursor');
+        for (const turn of parsed.page.turns) {
+          if (seenTurnIds.has(turn.id)) throw new Error('capture history contains duplicate turn');
+          seenTurnIds.add(turn.id);
+          if (!Array.isArray(turn.items)) throw new Error('capture turn items are unavailable');
+          totalItems += turn.items.length;
+          if (totalItems > MAX_CAPTURE_ITEMS) {
+            const error = new Error('capture item count exceeds bound');
+            error.captureItemCount = totalItems;
+            error.captureItemLimit = MAX_CAPTURE_ITEMS;
+            throw error;
+          }
+          for (const item of turn.items) {
+            if (isRecord(item) && typeof item.id === 'string') {
+              if (seenItemIds.has(item.id))
+                throw new Error('capture history contains duplicate item');
+              seenItemIds.add(item.id);
+            }
+          }
+        }
+        const serializedPage = `${JSON.stringify(parsed.page)}\n`;
+        await onPage?.(parsed.page);
+        const pageBytes = Buffer.byteLength(serializedPage, 'utf8');
+        stagedBytes += pageBytes;
+        if (stagedBytes > MAX_CAPTURE_TOTAL_BYTES)
+          throw new Error('capture exceeds segmented bound');
+        let stagedPath = null;
+        if (!verifyOnly) {
+          const storageState = await readCaptureDirectoryState(checkpointDir);
+          if (
+            storageState.totalBytes + pageBytes >
+            MAX_CAPTURE_DIRECTORY_BYTES + MAX_CAPTURE_STAGING_HEADROOM_BYTES
+          )
+            throw captureCapacityError(storageState);
+          stagedPath = resolve(
+            checkpointDir,
+            `.capture-stage.${safeThreadName(threadId)}.${randomUUID()}.${pageIndex}.tmp`,
+          );
+          await writeFile(stagedPath, serializedPage, { flag: 'wx', mode: 0o600 });
+          stagedFiles.push(stagedPath);
+        }
+        pages.push({
+          pageIndex,
+          stagedPath,
+          pageHash: hashJson(parsed.page),
+          itemCount: parsed.page.turns.reduce(
+            (count, turn) => count + (Array.isArray(turn.items) ? turn.items.length : 0),
+            0,
+          ),
+          bytes: pageBytes,
+          cursor: parsed.cursor,
+        });
+        summaryTurns.push(...parsed.page.turns.map(summarizeCaptureTurn));
+        if (parsed.cursor === null)
+          return {
+            read: {
+              thread: {
+                ...metadata.thread,
+                turns: summaryTurns,
+              },
+            },
+            metadata,
+            pages,
+            stagedFiles,
+          };
+        if (seenCursors.has(parsed.cursor)) throw new Error('thread/turns/list cursor repeated');
+        seenCursors.add(parsed.cursor);
+        cursor = parsed.cursor;
+        if (pageIndex === MAX_CAPTURE_PAGES - 1)
+          throw new Error('thread/turns/list page count exceeds bound');
+      } catch (error) {
+        await cleanupStaged();
+        throw error;
+      }
+    }
+    await cleanupStaged();
+    throw new Error('thread/turns/list page count exceeds bound');
+  }
   async function loadRecoveryState(threadId, state) {
     if (state.recoveryLoaded) return state.recovery;
     if (!state.recoveryLoadPromise) {
@@ -702,14 +2631,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');
         }
@@ -725,6 +2662,7 @@ export function createCodexContextProxy({
     await atomicWritePrivate(
       resolve(checkpointDir, `${safeThreadName(threadId)}.recovery.json`),
       record,
+      { captureLock: true },
     );
   }
   async function readRecoveryNotes(threadId, record) {
@@ -763,6 +2701,7 @@ export function createCodexContextProxy({
       injectSent: false,
       readId: null,
       injectId: null,
+      auxIds: [],
       deferred: injectWaiter,
       timer: null,
     };
@@ -772,23 +2711,44 @@ export function createCodexContextProxy({
       attachment.canceled = true;
       cleanupRequest(attachment.readId);
       cleanupRequest(attachment.injectId);
+      for (const id of attachment.auxIds) cleanupRequest(id);
       injectWaiter.reject(new Error('recovery attachment timed out'));
     }, timeoutMs);
     try {
       const notes = await readRecoveryNotes(threadId, record);
       if (attachment.invalidated || attachment.canceled)
         throw new Error('recovery attachment was invalidated before read');
-      attachment.readId = sendOwned(
-        'thread/read',
-        { threadId, includeTurns: true },
-        'read',
-        threadId,
-        readWaiter,
-      );
-      const read = validateThreadRead(await readWaiter.promise, threadId);
+      let latest = null;
+      let injection = 'absent';
+      const capture = await readThreadCapture(threadId, attachment, readWaiter, {
+        verifyOnly: true,
+        onPage: async (page) => {
+          const pageLatest = page.turns?.at(-1);
+          if (pageLatest) latest = pageLatest;
+          const found = page.turns
+            ?.flatMap((turn) => (Array.isArray(turn.items) ? turn.items : []))
+            .some(
+              (item) =>
+                isRecord(item) &&
+                ((item.type === 'message' &&
+                  item.role === 'user' &&
+                  Array.isArray(item.content) &&
+                  item.content.some(
+                    (part) => isRecord(part) && part.type === 'input_text' && part.text === notes,
+                  )) ||
+                  (item.type === 'userMessage' &&
+                    Array.isArray(item.content) &&
+                    item.content.some(
+                      (part) => isRecord(part) && part.type === 'text' && part.text === notes,
+                    ))),
+            );
+          if (found) injection = injection === 'present' ? 'ambiguous' : 'present';
+        },
+      });
+      for (const descriptor of capture.pages ?? [])
+        if (descriptor.stagedPath) await unlink(descriptor.stagedPath).catch(() => undefined);
       if (attachment.invalidated || attachment.canceled)
         throw new Error('recovery attachment was invalidated during read');
-      const latest = read.thread.turns.at(-1);
       if (!latest || latest.id !== record.turnId || latest.status !== 'completed') {
         attachment.stale = true;
         throw new Error('recovery compaction turn is no longer current');
@@ -797,7 +2757,6 @@ export function createCodexContextProxy({
         attachment.stale = true;
         throw new Error('recovery attachment encountered a newer turn');
       }
-      const injection = recoveryInjectionState(read, notes);
       if (injection === 'ambiguous') {
         attachment.stale = true;
         throw new Error('recovery attachment has ambiguous prior injections');
@@ -813,7 +2772,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') {
@@ -824,7 +2790,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');
@@ -866,7 +2839,14 @@ export function createCodexContextProxy({
       };
       await persistRecoveryState(threadId, attached);
       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 });
     } catch {
       if (attachment.injectSent) {
         const uncertain = {
@@ -876,7 +2856,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 = {
@@ -885,18 +2872,24 @@ 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();
       cleanupRequest(attachment.readId);
       cleanupRequest(attachment.injectId);
+      for (const id of attachment.auxIds) cleanupRequest(id);
       if (state.recoveryAttach === attachment) state.recoveryAttach = null;
     }
   }
   async function requestCompaction(threadId, state) {
-    await loadRecoveryState(threadId, state);
+    if (!state.owned) return;
+    if (state.resumePending) {
+      state.resumeRetryRequested = true;
+      return;
+    }
+    if (recoveryEnabled && recoveryDisclosed) await loadRecoveryState(threadId, state);
     if (
       state.recovery &&
       ['pending_attachment', 'recovery_uncertain'].includes(state.recovery.status)
@@ -911,11 +2904,12 @@ 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 ||
       state.revision === null ||
-      (state.usage.last.totalTokens / state.usage.modelContextWindow) * 100 < threshold
+      (state.usage.last.totalTokens / state.usage.modelContextWindow) * 100 < effectiveThreshold
     )
       return;
     if (
@@ -943,52 +2937,126 @@ 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 },
+        { threadId, includeTurns: false },
         'read',
         threadId,
         readWaiter,
       );
-      const read = validateThreadRead(await readWaiter.promise, threadId);
-      assertCurrent(threadId, state, pending, revision);
-      const sourceRevision = hashJson(read);
-      const snapshot = {
-        version: 1,
-        status: 'requested',
-        capturedAt: new Date(now()).toISOString(),
+      await ensurePrivateDirectory(checkpointDir);
+      const publication = await withCaptureStoreLock(checkpointDir, async () => {
+        const capture = await readThreadCapture(threadId, pending, readWaiter, {
+          readId: pending.readId,
+        });
+        const read = capture.read;
+        assertCurrent(threadId, state, pending, revision);
+        const sourceRevision = captureSourceRevision(capture);
+        const compactSnapshot = {
+          version: 1,
+          status: 'requested',
+          capturedAt: new Date(now()).toISOString(),
+          threadId,
+          sourceTurnId,
+          revision,
+          sourceRevision,
+          statusAtCheckpoint: state.status,
+          usage: state.usage,
+          threadRead: read,
+          recovery: {
+            mode: 'codex-native-compaction',
+            action: 'resume-the-owned-app-server-session',
+            historyMutation: false,
+          },
+        };
+        let snapshot = compactSnapshot;
+        if (capture.pages !== null) {
+          const manifest = await writeSegmentedCapture(checkpointDir, {
+            threadId,
+            sourceRevision,
+            metadata: capture.metadata,
+            pages: capture.pages,
+            lockHeld: true,
+          });
+          snapshot = {
+            ...compactSnapshot,
+            version: 2,
+            threadRead: capture.metadata,
+            captureManifest: manifest,
+          };
+        } else if (Buffer.byteLength(JSON.stringify(compactSnapshot), 'utf8') > MAX_CAPTURE_BYTES) {
+          throw new Error('capture snapshot exceeds bound');
+        }
+        const manifestForRollback = snapshot.version === 2 ? snapshot.captureManifest : null;
+        const immutableCapturePath = resolve(
+          checkpointDir,
+          `${safeThreadName(threadId)}.${sourceRevision}.json`,
+        );
+        try {
+          await atomicWriteImmutablePrivate(immutableCapturePath, snapshot, sourceRevision, true);
+        } catch (error) {
+          if (manifestForRollback?.segments) {
+            for (const segment of manifestForRollback.segments)
+              await unlink(resolve(checkpointDir, segment)).catch(() => undefined);
+          }
+          throw error;
+        }
+        await atomicWritePrivate(
+          resolve(checkpointDir, `${safeThreadName(threadId)}.json`),
+          snapshot,
+          { maxBytes: MAX_CAPTURE_BYTES, compact: true, capture: true, captureLockHeld: true },
+        );
+        return { capture, read, sourceRevision, snapshot, immutableCapturePath };
+      });
+      const { capture, read, sourceRevision, snapshot, immutableCapturePath } = publication;
+      if (capture.pages !== null && recoveryEnabled && recoveryDisclosed) {
+        const verificationWaiter = deferred();
+        const verificationCapture = await readThreadCapture(threadId, pending, verificationWaiter, {
+          verifyOnly: true,
+        });
+        try {
+          if (captureSourceRevision(verificationCapture) !== sourceRevision)
+            throw new Error('recovery source changed before provider admission');
+        } finally {
+          for (const descriptor of verificationCapture.pages ?? [])
+            if (descriptor.stagedPath) await unlink(descriptor.stagedPath).catch(() => undefined);
+        }
+      }
+      emitDiagnostic({
+        phase: 'capture',
+        stage: 'capture',
+        reason: 'completed',
         threadId,
-        sourceTurnId,
-        revision,
-        sourceRevision,
-        statusAtCheckpoint: state.status,
-        usage: state.usage,
-        threadRead: read,
-        recovery: {
-          mode: 'codex-native-compaction',
-          action: 'resume-the-owned-app-server-session',
-          historyMutation: false,
+        operationId: pending.operationId,
+        counts: {
+          item_count: read.thread.turns.reduce(
+            (count, turn) => count + (turn.items?.length ?? 0),
+            0,
+          ),
+          ...(capture.pages === null
+            ? {}
+            : {
+                page_count: capture.pages.length,
+                capture_bytes: capture.pages.reduce(
+                  (count, descriptor) => count + descriptor.bytes,
+                  0,
+                ),
+              }),
         },
-      };
-      if (Buffer.byteLength(JSON.stringify(snapshot)) > MAX_CAPTURE_BYTES)
-        throw new Error('thread snapshot exceeds bound');
-      await atomicWritePrivate(
-        resolve(checkpointDir, `${safeThreadName(threadId)}.json`),
-        snapshot,
-      );
-      const immutableCapturePath = resolve(
-        checkpointDir,
-        `${safeThreadName(threadId)}.${sourceRevision}.json`,
-      );
-      await atomicWriteImmutablePrivate(immutableCapturePath, snapshot, sourceRevision);
+      });
       assertCurrent(threadId, state, pending, revision);
       let recoveryNotes;
+      let nativeFallback = false;
+      let budgetReceipt = null;
       if (recoveryEnabled && recoveryDisclosed) {
         strictThreadName(threadId);
         if (
@@ -1006,90 +3074,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);
-          const selectionInput = {
-            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,
-          };
-          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',
-              {
+          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,
-                server: brainServer,
-                tool: 'brain_context_select',
-                arguments: selectionInput,
-              },
-              'select',
+                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,
+                );
+              }
+            }
+          } else {
+            pending.stage = 'selection';
+            try {
+              candidates = buildRecoveryCandidates(read, sourceRevision, contextPolicy);
+            } catch {
+              nativeFallback = true;
+              emitNativeFallback(threadId, pending, 'candidate_over_bound');
+            }
+          }
+          if (
+            !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());
-          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);
+              pending,
+              'stale_snapshot',
+              budgetReceipt.snapshot.correlation_id,
+            );
+          }
+          if (nativeFallback) candidates = null;
+          if (candidates === null || candidates === undefined) {
+            emitDiagnostic({
+              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 rereadCapture = await readThreadCapture(threadId, pending, rereadWaiter, {
+                verifyOnly: true,
+              });
+              try {
+                if (captureSourceRevision(rereadCapture) !== sourceRevision)
+                  throw new Error('recovery source changed during selection');
+                assertCurrent(threadId, state, pending, revision);
+              } finally {
+                for (const descriptor of rereadCapture.pages ?? [])
+                  if (descriptor.stagedPath)
+                    await unlink(descriptor.stagedPath).catch(() => undefined);
+              }
+              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,
+              });
+            }
+          }
         }
         assertCurrent(threadId, state, pending, revision);
       }
+      pending.stage = 'native';
       pending.compactId = sendOwned('thread/compact/start', { threadId }, 'compact', threadId);
       pending.lifecycleArmed = true;
       await completion.promise;
@@ -1102,6 +3397,7 @@ export function createCodexContextProxy({
       await atomicWritePrivate(
         resolve(checkpointDir, `${safeThreadName(threadId)}.completed.json`),
         completed,
+        { maxBytes: MAX_CAPTURE_BYTES, compact: true, capture: true },
       );
       if (recoveryNotes !== undefined) {
         state.recovery = {
@@ -1111,18 +3407,36 @@ 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 {
-      fail(threadId, 'checkpoint, request, or native completion failed');
+    } catch (error) {
+      emitDiagnostic({
+        phase: 'operation_failed',
+        stage: pending.stage ?? 'native',
+        reason: diagnosticReasonForError(error),
+        threadId,
+        operationId: pending.operationId,
+        ...(boundedFailureCounts(error) === undefined
+          ? {}
+          : { counts: boundedFailureCounts(error) }),
+      });
+      fail(threadId, 'checkpoint, request, or native completion failed', error);
     } finally {
       if (pending.timer) pending.timer();
       cleanupRequest(pending.readId);
@@ -1142,22 +3456,44 @@ 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 === 'page' ||
+        owned.kind === 'select' ||
+        owned.kind === 'budget' ||
+        owned.kind === 'inject' ||
+        owned.kind === 'telemetry'
+      ) {
         const waiter = internalReads.get(message.id);
         internalReads.delete(message.id);
         if (waiter) {
-          if ('error' in message) waiter.reject(new Error('thread/read failed'));
+          if ('error' in message) waiter.reject(rpcFailure(owned.kind, message.error));
           else waiter.resolve(message.result);
         }
-      } else if ('error' in message) fail(owned.threadId, 'compact request rejected');
-      if ('error' in message)
+      } else if ('error' in message) {
+        const failure = rpcFailure(owned.kind, message.error);
+        fail(owned.threadId, 'app-server request rejected', failure);
+      }
+      if ('error' in message) {
+        const failure = rpcFailure(owned.kind, message.error);
         emitDiagnostic({
           phase: owned.kind,
-          errorCode:
-            typeof message.error?.code === 'number' || typeof message.error?.code === 'string'
-              ? message.error.code
-              : 'rpc_error',
+          stage:
+            owned.kind === 'read' || owned.kind === 'page'
+              ? 'capture'
+              : owned.kind === 'budget'
+                ? 'budget'
+                : owned.kind === 'select'
+                  ? 'selection'
+                  : owned.kind === 'inject'
+                    ? 'recovery'
+                    : 'transport',
+          reason: 'protocol_error',
+          threadId: owned.threadId,
+          operationId: threads.get(owned.threadId)?.pending?.operationId,
+          ...(safeRpcCode(failure.rpcCode) === null ? {} : { rpcCode: failure.rpcCode }),
         });
+      }
       if (owned.kind === 'compact') {
         const state = threads.get(owned.threadId);
         if (state?.pending) state.pending.compactId = null;
@@ -1170,11 +3506,19 @@ export function createCodexContextProxy({
       typeof message.params.threadId === 'string' &&
       isRecord(message.params.status)
     ) {
-      const state = threadState(message.params.threadId);
+      const state = threads.get(message.params.threadId);
+      if (!state) return true;
       state.status =
         typeof message.params.status.type === 'string' ? message.params.status.type : 'unknown';
       state.idle = state.status === 'idle';
       if (!state.idle) invalidateAttachment(state);
+      if (!state.owned) return true;
+      if (!state.telemetryConnected) {
+        state.telemetryConnected = true;
+        telemetryFor(message.params.threadId).connected({
+          triggerPercent: effectiveThreshold,
+        });
+      }
       if (state.idle) void requestCompaction(message.params.threadId, state);
     }
     if (
@@ -1195,7 +3539,8 @@ export function createCodexContextProxy({
         stderr.write('codex-context: invalid usage sample skipped\n');
         return true;
       }
-      const state = threadState(params.threadId);
+      const state = threads.get(params.threadId);
+      if (!state) return true;
       state.usage = params.tokenUsage;
       state.usageReceivedAt = now();
       state.turnId = params.turnId;
@@ -1209,6 +3554,17 @@ export function createCodexContextProxy({
         state.turnId !== state.recovery.sourceTurnId
       )
         invalidateAttachment(state);
+      if (!state.owned) return true;
+      telemetryFor(params.threadId).usage({
+        measurement: {
+          unit: 'tokens',
+          used: params.tokenUsage.last.totalTokens,
+          ...(hasKnownContextWindow(params.tokenUsage)
+            ? { capacity: params.tokenUsage.modelContextWindow }
+            : {}),
+        },
+        triggerPercent: effectiveThreshold,
+      });
       if (state.idle) void requestCompaction(params.threadId, state);
     }
     if (
@@ -1241,6 +3597,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 (
@@ -1259,6 +3622,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();
       }
     }
@@ -1274,7 +3644,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 (
@@ -1289,11 +3668,86 @@ export function createCodexContextProxy({
       typeof message.params.threadId === 'string'
     ) {
       fail(message.params.threadId, 'thread closed');
+      ownedThreadIds.delete(message.params.threadId);
       threads.delete(message.params.threadId);
     }
     return true;
   }
 
+  /**
+   * Observe TUI-owned requests without changing their wire representation.
+   * The app-server may emit status/usage events before a resumed thread's
+   * response arrives, so the adapter must defer owned work until that response
+   * confirms that the thread is loaded.
+   */
+  function observeClientRequest(message) {
+    if (!isRecord(message)) return;
+    const requestId = message.id;
+    const validRequestId =
+      (typeof requestId === 'string' && requestId.length > 0 && requestId.length <= 128) ||
+      Number.isSafeInteger(requestId);
+    if (!validRequestId) return;
+    const requestKey = clientRequestKey(requestId);
+    if (requestKey === null) return;
+    if (['thread/start', 'thread/resume', 'thread/fork'].includes(message.method)) {
+      const threadId =
+        isRecord(message.params) && typeof message.params.threadId === 'string'
+          ? message.params.threadId
+          : null;
+      if (
+        clientRequestBindings.has(requestKey) ||
+        clientRequestBindings.size >= MAX_CLIENT_REQUEST_BINDINGS
+      )
+        return;
+      clientRequestBindings.set(requestKey, { method: message.method, threadId });
+      if (message.method === 'thread/resume') {
+        if (threadId === null || threadId.length === 0 || threadId.length > 256) {
+          clientRequestBindings.delete(requestKey);
+          return;
+        }
+        const state = threadState(threadId);
+        state.resumePending = true;
+        state.resumeRetryRequested = false;
+        state.resumeRequests.add(requestKey);
+      }
+    }
+  }
+
+  function observeClientResponse(message) {
+    if (!isRecord(message) || message.id === undefined) return;
+    const requestKey = clientRequestKey(message.id);
+    if (requestKey === null) return;
+    const binding = clientRequestBindings.get(requestKey);
+    if (binding) {
+      clientRequestBindings.delete(requestKey);
+      if (binding.method === 'thread/resume' && binding.threadId !== null) {
+        const state = threadState(binding.threadId);
+        state.resumeRequests.delete(requestKey);
+        state.resumePending = state.resumeRequests.size > 0;
+        state.resumeRetryRequested = false;
+        const responseThreadId = message.result?.thread?.id;
+        if (
+          message.error === undefined &&
+          typeof responseThreadId === 'string' &&
+          responseThreadId === binding.threadId
+        ) {
+          const claimed = claimOwnedThread(binding.threadId);
+          if (claimed && !state.resumePending && claimed.idle)
+            void requestCompaction(binding.threadId, claimed);
+        } else if (!state.owned && state.resumeRequests.size === 0 && state.pending === null) {
+          threads.delete(binding.threadId);
+        }
+      } else if (message.error === undefined) {
+        const selectedId = message.result?.thread?.id;
+        if (typeof selectedId === 'string' && selectedId.length > 0 && selectedId.length <= 256) {
+          const selected = claimOwnedThread(selectedId);
+          if (!selected) return;
+          if (selected.idle) void requestCompaction(selectedId, selected);
+        }
+      }
+    }
+  }
+
   const decoder = new StringDecoder('utf8');
   let inputBuffer = '';
   let passthrough = false;
@@ -1310,44 +3764,100 @@ export function createCodexContextProxy({
     }
   };
   const processLine = (line) => {
-    if (Buffer.byteLength(line) > MAX_LINE_BYTES) {
-      if (line.includes('"id":"ai-brain-context-')) {
+    if (Buffer.byteLength(line, 'utf8') + 1 > MAX_LINE_BYTES) {
+      const ownedId = internalRequestId(line);
+      if (ownedId !== null) {
         stderr.write('codex-context: oversized internal response rejected\n');
-        failAll('oversized internal response');
+        failOversizedInternal(ownedId, Buffer.byteLength(line, 'utf8') + 1);
       } else forward(`${line}\n`);
       return;
     }
     let forwardLine = true;
     try {
-      forwardLine = handle(JSON.parse(line.endsWith('\r') ? line.slice(0, -1) : line));
+      const message = JSON.parse(line.endsWith('\r') ? line.slice(0, -1) : line);
+      observeClientResponse(message);
+      forwardLine = handle(message);
     } catch {
       /* preserve malformed external protocol lines */
     }
     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, responseBytes) {
+    const owned = ownedRequests.get(id);
+    if (!owned) {
+      failCompactions('oversized internal response');
+      return;
+    }
+    if (owned.kind === 'page') {
+      ownedRequests.delete(id);
+      const waiter = internalReads.get(id);
+      internalReads.delete(id);
+      retire(id);
+      const failure = new Error('oversized internal page response');
+      failure.diagnosticReason = 'capture_size_exceeded';
+      failure.responseBytes = responseBytes;
+      failure.responseLimitBytes = MAX_LINE_BYTES;
+      waiter?.reject(failure);
+      return;
+    }
+    cleanupRequest(id);
+    if (owned.kind === 'telemetry') return;
+    const failure = new Error('oversized internal response');
+    failure.diagnosticReason = 'capture_size_exceeded';
+    failure.responseBytes = responseBytes;
+    failure.responseLimitBytes = MAX_LINE_BYTES;
+    fail(owned.threadId, 'oversized internal response', failure);
+  }
   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 (Buffer.byteLength(inputBuffer, 'utf8') + 1 > MAX_LINE_BYTES) {
+      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),
+          Buffer.byteLength(inputBuffer, 'utf8') + 1,
+        );
         discardOversized = true;
-      } else forward(inputBuffer);
-      inputBuffer = '';
-      if (!passthrough) passthrough = true;
+        inputBuffer = '';
+      } else {
+        forward(inputBuffer);
+        inputBuffer = '';
+        passthrough = true;
+      }
     }
   });
   child.stdout.on('end', () => {
@@ -1367,36 +3877,138 @@ 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;
+    observeClientRequest,
+    observeClientResponse,
+    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;
+      clientRequestBindings.clear();
+      ownedThreadIds.clear();
       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',
     );
     return;
   }
+  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,
+  });
+  const clientDecoder = new StringDecoder('utf8');
+  let clientInputBuffer = '';
+  let discardOversizedClientFrame = false;
+  process.stdin.on('data', (chunk) => {
+    const decoded = clientDecoder.write(chunk);
+    if (discardOversizedClientFrame) {
+      const newline = decoded.indexOf('\n');
+      if (newline < 0) return;
+      discardOversizedClientFrame = false;
+      clientInputBuffer = decoded.slice(newline + 1);
+    } else clientInputBuffer += decoded;
+    while (true) {
+      const newline = clientInputBuffer.indexOf('\n');
+      if (newline < 0) break;
+      const line = clientInputBuffer.slice(0, newline).replace(/\r$/u, '');
+      clientInputBuffer = clientInputBuffer.slice(newline + 1);
+      if (!line) continue;
+      if (Buffer.byteLength(line, 'utf8') + 1 > MAX_LINE_BYTES) continue;
+      try {
+        proxy.observeClientRequest(JSON.parse(line));
+      } catch {
+        /* Preserve malformed/native frames unchanged; the app-server owns validation. */
+      }
+    }
+    if (Buffer.byteLength(clientInputBuffer, 'utf8') + 1 > MAX_LINE_BYTES) {
+      clientInputBuffer = '';
+      discardOversizedClientFrame = true;
+    }
   });
   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();