@brunobracaioli/aibrain 0.3.0-beta.7 → 0.4.0-beta.2

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

@@ -1,29 +1,68 @@
 #!/usr/bin/env node
 
-import { chmod, lstat, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import {
+  chmod,
+  link as hardlink,
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  readlink,
+  readdir,
+  rename,
+  unlink,
+  writeFile,
+} from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
-import { dirname, relative, resolve } from 'node:path';
+import { basename, 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,
+  hardlink,
+  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 MAX_CAPTURE_PUBLICATION_FILE_HEADROOM = MAX_CAPTURE_PAGES + 2;
+const MAX_CAPTURE_PUBLICATION_FILES = MAX_CAPTURE_FILES + MAX_CAPTURE_PUBLICATION_FILE_HEADROOM;
+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 = 4096;
+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',
@@ -79,6 +118,14 @@ const DIAGNOSTIC_REASONS = new Set([
   'timeout',
   'thread_closed',
   'protocol_error',
+  'capture_size_exceeded',
+  'capture_item_count_exceeded',
+  'private_storage_failed',
+  'storage_capacity_exceeded',
+  'capture_lock_timeout',
+  'capture_lock_legacy',
+  'capture_lock_owner_unverifiable',
+  'capture_lock_backend_unavailable',
   'attached',
   'uncertain',
   'disconnected',
@@ -335,6 +382,16 @@ 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
@@ -355,12 +412,14 @@ export function normalizeCodexDiagnostic(event, { threadId = null } = {}) {
       : null;
   if (stage === null || reason === null) return null;
   const operationId = isUuid(event.operationId) ? event.operationId : undefined;
-  const correlationId = boundedDiagnosticValue(event.correlationId);
+  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, 1_000_000),
+            /^[a-z_]{1,48}$/u.test(key) &&
+            isSafeBoundedInteger(value, 0, /_bytes$/u.test(key) ? MAX_DIAGNOSTIC_BYTES : 1_000_000),
         ),
       )
     : undefined;
@@ -371,6 +430,7 @@ export function normalizeCodexDiagnostic(event, { threadId = null } = {}) {
     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) }
       : {}),
@@ -477,87 +537,1461 @@ export function parseBudgetSnapshot(value) {
   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 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 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 fsOps.lstat(current);
+    if (info.isSymbolicLink() || !info.isDirectory())
+      throw new Error('checkpoint directory is unsafe');
+  }
+  await fsOps.chmod(target, 0o700);
+  return target;
+}
+async function validatePrivateDirectoryPath(directory, fsOps = captureFs) {
+  const target = resolve(directory);
+  const parts = target.split('/');
+  let current = parts[0] === '' ? '/' : parts[0];
+  for (const part of parts.slice(1)) {
+    if (!part) continue;
+    current = current === '/' ? `/${part}` : `${current}/${part}`;
+    const info = await fsOps.lstat(current);
+    if (info.isSymbolicLink() || !info.isDirectory())
+      throw new Error('checkpoint directory is unsafe');
+    if (
+      current === target &&
+      ((typeof process.getuid === 'function' && info.uid !== process.getuid()) ||
+        (info.mode & 0o077) !== 0)
+    )
+      throw new Error('capture directory is not private');
+  }
+  return target;
+}
+async function assertPrivateFile(file, label, fsOps = captureFs) {
+  const info = await fsOps.lstat(file);
+  if (
+    info.isSymbolicLink() ||
+    !info.isFile() ||
+    (info.mode & 0o077) !== 0 ||
+    (typeof process.getuid === 'function' && info.uid !== process.getuid())
+  )
+    throw new Error(`${label} is not a private regular file`);
+  return info;
+}
+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 fsOps.readFile(file, 'utf8');
+}
+
+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?.managedFileCount ?? state?.managedFiles?.length ?? MAX_CAPTURE_FILES;
+  error.captureFileLimit = MAX_CAPTURE_FILES;
+  return error;
+}
+
+function captureStorageCleanupError(state) {
+  const error = new Error('capture storage cleanup remains incomplete');
+  error.diagnosticReason = 'private_storage_failed';
+  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,
+  { replacedCurrentName = null } = {},
+) {
+  const entries = await fsOps.readdir(directory, { withFileTypes: true });
+  if (entries.length > MAX_CAPTURE_FILES * 4)
+    throw captureCapacityError({ totalBytes: MAX_CAPTURE_DIRECTORY_BYTES, managedFiles: [] });
+  let activeSentinelInfo = null;
+  try {
+    activeSentinelInfo = await fsOps.lstat(resolve(directory, '.capture.lock'));
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+  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);
+    if (
+      activeSentinelInfo !== null &&
+      Number.isInteger(activeSentinelInfo.dev) &&
+      Number.isInteger(activeSentinelInfo.ino) &&
+      info.dev === activeSentinelInfo.dev &&
+      info.ino === activeSentinelInfo.ino
+    )
+      continue;
+    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}`,
+    });
+    const replacedCurrent = entry.name === replacedCurrentName;
+    if (!replacedCurrent && !entry.name.endsWith('.' + value.sourceRevision + '.json'))
+      state.referencedImmutableNames.add(sourceName);
+    if (value.version === 2 && entry.name !== sourceName && !replacedCurrent) {
+      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;
+}
+
+function captureLockError(reason) {
+  const messages = {
+    capture_lock_timeout: 'capture lock is held by a live or unverified owner',
+    capture_lock_legacy: 'capture lock uses an unidentifiable legacy sentinel',
+    capture_lock_owner_unverifiable: 'capture lock owner identity is unavailable',
+    capture_lock_backend_unavailable: 'capture lock backend is unavailable',
+  };
+  const error = new Error(messages[reason] ?? 'capture lock unavailable');
+  error.diagnosticReason = reason;
+  return error;
+}
+
+const CAPTURE_LOCK_MARKER = `${JSON.stringify({ backend: 'flock', schema: 2 })}\n`;
+const CAPTURE_GUARD_NAME = '.capture.guard';
+const CAPTURE_PAGE_STAGE_NAME =
+  /^\.capture-(?:segment-)?stage\.[A-Za-z0-9._-]{1,128}\.[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\.(?:[0-9]|[12][0-9]|3[01])\.tmp$/iu;
+const CAPTURE_SOURCE_STAGE_NAME =
+  /^\.capture-stage\.[A-Za-z0-9._-]{1,128}\.[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\.(?:[0-9]|[12][0-9]|3[01])\.tmp$/iu;
+
+async function removePrivateCaptureTemps(directory, fsOps, pattern) {
+  const entries = await fsOps.readdir(directory, { withFileTypes: true });
+  let removedFiles = 0;
+  let removedBytes = 0;
+  for (const entry of entries) {
+    if (!pattern.test(entry.name)) continue;
+    const file = resolve(directory, entry.name);
+    let info;
+    try {
+      info = await fsOps.lstat(file);
+    } catch (error) {
+      if (error?.code === 'ENOENT') continue;
+      throw error;
+    }
+    if (
+      info.isSymbolicLink() ||
+      !info.isFile() ||
+      (typeof process.getuid === 'function' && info.uid !== process.getuid()) ||
+      (info.mode & 0o077) !== 0
+    )
+      continue;
+    try {
+      await fsOps.unlink(file);
+      removedFiles += 1;
+      removedBytes += info.size;
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+  }
+  return { removedFiles, removedBytes };
+}
+
+async function removeAbandonedCapturePageStages(directory, fsOps) {
+  return removePrivateCaptureTemps(directory, fsOps, CAPTURE_PAGE_STAGE_NAME);
+}
+
+async function observerKernelIdentity() {
+  try {
+    return {
+      bootId: (await readFile('/proc/sys/kernel/random/boot_id', 'utf8')).trim(),
+      pidNamespace: await readlink('/proc/self/ns/pid'),
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function processIdentity(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return { status: 'invalid' };
+  const observer = await observerKernelIdentity();
+  if (observer === null) return { status: 'unverifiable' };
+  try {
+    const ownerNamespace = await readlink(`/proc/${pid}/ns/pid`);
+    if (ownerNamespace !== observer.pidNamespace || observer.bootId.length === 0)
+      return { status: 'foreign' };
+    const stat = await readFile(`/proc/${pid}/stat`, 'utf8');
+    const closing = stat.lastIndexOf(')');
+    const fields =
+      closing < 0
+        ? []
+        : stat
+            .slice(closing + 2)
+            .trim()
+            .split(/\s+/u);
+    const startTime = fields[19];
+    if (typeof startTime !== 'string' || !/^[0-9]+$/u.test(startTime))
+      return { status: 'unverifiable' };
+    return { status: 'live', startTime, bootId: observer.bootId, pidNamespace: ownerNamespace };
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { status: 'dead' };
+    return { status: 'unverifiable' };
+  }
+}
+
+async function captureSentinelOwner(lockPath, fsOps) {
+  let info;
+  try {
+    info = await fsOps.lstat(lockPath);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { status: 'absent' };
+    throw error;
+  }
+  if (info.isSymbolicLink() || !info.isFile() || (info.mode & 0o077) !== 0)
+    throw new Error('capture lock is not a private regular file');
+  if (info.size === 0) return { status: 'legacy' };
+  if (info.size > 4096) return { status: 'unverifiable' };
+  let value;
+  try {
+    value = JSON.parse(await fsOps.readFile(lockPath, 'utf8'));
+  } catch {
+    return { status: 'unverifiable' };
+  }
+  if (
+    !isRecord(value) ||
+    !hasOnlyKeys(value, [
+      'schema',
+      'backend',
+      'pid',
+      'startTime',
+      'bootId',
+      'pidNamespace',
+      'nonce',
+    ]) ||
+    value.schema !== 1 ||
+    value.backend !== 'flock' ||
+    !isSafeBoundedInteger(value.pid, 1, 4_000_000_000) ||
+    typeof value.startTime !== 'string' ||
+    !/^[0-9]+$/u.test(value.startTime) ||
+    typeof value.bootId !== 'string' ||
+    !/^[a-f0-9-]{36}$/iu.test(value.bootId) ||
+    typeof value.pidNamespace !== 'string' ||
+    !/^pid:\[\d+\]$/u.test(value.pidNamespace) ||
+    typeof value.nonce !== 'string' ||
+    !isUuid(value.nonce)
+  )
+    return { status: 'unverifiable' };
+  const observer = await observerKernelIdentity();
+  if (observer === null) return { status: 'unverifiable' };
+  if (observer.bootId !== value.bootId) return { status: 'dead' };
+  if (observer.pidNamespace !== value.pidNamespace) return { status: 'foreign' };
+  const current = await processIdentity(value.pid);
+  if (current.status !== 'live') return { status: current.status };
+  if (current.bootId !== value.bootId || current.pidNamespace !== value.pidNamespace)
+    return { status: 'foreign' };
+  return current.startTime === value.startTime ? { status: 'live' } : { status: 'dead' };
+}
+
+async function ensureCaptureSentinel(lockPath, task) {
+  const identity = await processIdentity(process.pid);
+  if (identity.status !== 'live') throw captureLockError('capture_lock_owner_unverifiable');
+  const metadata = `${JSON.stringify({
+    schema: 1,
+    backend: 'flock',
+    pid: process.pid,
+    startTime: identity.startTime,
+    bootId: identity.bootId,
+    pidNamespace: identity.pidNamespace,
+    nonce: randomUUID(),
+  })}\n`;
+  while (true) {
+    const temporary = `${lockPath}.${process.pid}.${randomUUID()}.tmp`;
+    let contention = false;
+    let published = false;
+    try {
+      let handle;
+      try {
+        const flags =
+          fsConstants.O_WRONLY |
+          fsConstants.O_CREAT |
+          fsConstants.O_EXCL |
+          (fsConstants.O_NOFOLLOW ?? 0);
+        handle = await captureFs.open(temporary, flags, 0o600);
+        await handle.writeFile(metadata, 'utf8');
+        await handle.sync?.();
+      } finally {
+        await handle?.close().catch(() => undefined);
+      }
+      await captureFs.hardlink(temporary, lockPath);
+      published = true;
+      const publishedInfo = await captureFs.lstat(lockPath);
+      try {
+        return await task();
+      } finally {
+        const current = await captureFs.lstat(lockPath).catch(() => null);
+        if (
+          current !== null &&
+          current.dev === publishedInfo.dev &&
+          current.ino === publishedInfo.ino
+        )
+          await captureFs.unlink(lockPath).catch(() => undefined);
+      }
+    } catch (error) {
+      if (!published && error?.code === 'EEXIST') contention = true;
+      else throw error;
+    } finally {
+      await captureFs.unlink(temporary).catch(() => undefined);
+    }
+    if (!contention) throw captureLockError('capture_lock_owner_unverifiable');
+    const owner = await captureSentinelOwner(lockPath, captureFs);
+    if (owner.status === 'dead') {
+      await captureFs.unlink(lockPath).catch((unlinkError) => {
+        if (unlinkError?.code !== 'ENOENT') throw unlinkError;
+      });
+      continue;
+    }
+    if (owner.status === 'legacy') throw captureLockError('capture_lock_legacy');
+    throw captureLockError('capture_lock_owner_unverifiable');
+  }
+}
+
+async function withAdvisoryCaptureLock(directory, task) {
+  const guardPath = resolve(directory, CAPTURE_GUARD_NAME);
+  const lockPath = resolve(directory, '.capture.lock');
+  let guardHandle;
+  try {
+    const flags = fsConstants.O_RDWR | fsConstants.O_CREAT | (fsConstants.O_NOFOLLOW ?? 0);
+    guardHandle = await captureFs.open(guardPath, flags, 0o600);
+    const info = await guardHandle.stat();
+    if (
+      !info.isFile() ||
+      info.isSymbolicLink?.() ||
+      info.nlink !== 1 ||
+      (typeof process.getuid === 'function' && info.uid !== process.getuid()) ||
+      (info.mode & 0o077) !== 0 ||
+      info.size > 4096
+    )
+      throw captureLockError('capture_lock_owner_unverifiable');
+  } catch (error) {
+    await guardHandle?.close().catch(() => undefined);
+    if (error?.code === 'ENOENT') throw captureLockError('capture_lock_backend_unavailable');
+    throw error;
+  }
+  const started = Date.now();
+  while (true) {
+    let helper;
+    try {
+      helper = spawn('flock', ['-x', '-n', '3'], {
+        stdio: ['ignore', 'ignore', 'ignore', guardHandle.fd],
+      });
+      const acquired = await new Promise((resolvePromise, rejectPromise) => {
+        const timer = setTimeout(() => {
+          helper.kill('SIGKILL');
+          rejectPromise(captureLockError('capture_lock_backend_unavailable'));
+        }, 2_000);
+        helper.once('error', (error) => {
+          clearTimeout(timer);
+          if (error?.code === 'ENOENT')
+            rejectPromise(captureLockError('capture_lock_backend_unavailable'));
+          else rejectPromise(error);
+        });
+        helper.once('exit', (code) => {
+          clearTimeout(timer);
+          if (code === 0) resolvePromise(true);
+          else if (code === 1) resolvePromise(false);
+          else rejectPromise(captureLockError('capture_lock_backend_unavailable'));
+        });
+      });
+      if (acquired) {
+        let marker = await guardHandle.readFile('utf8');
+        if (marker.length === 0 || marker !== CAPTURE_LOCK_MARKER) {
+          await guardHandle.truncate(0);
+          await guardHandle.write(CAPTURE_LOCK_MARKER, 0, 'utf8');
+          await guardHandle.sync?.();
+        }
+        try {
+          return await ensureCaptureSentinel(lockPath, task);
+        } finally {
+          await guardHandle.close().catch(() => undefined);
+        }
+      }
+    } catch (error) {
+      if (helper && helper.exitCode === null) helper.kill('SIGTERM');
+      await guardHandle.close().catch(() => undefined);
+      throw error;
+    }
+    if (helper && helper.exitCode === null) helper.kill('SIGTERM');
+    if (Date.now() - started >= CAPTURE_LOCK_WAIT_MS) {
+      await guardHandle.close().catch(() => undefined);
+      throw captureLockError('capture_lock_timeout');
+    }
+    await new Promise((resolvePromise) => setTimeout(resolvePromise, 10));
+  }
+}
+
+async function withInjectedCaptureLock(directory, task, fsOps, { now, sleep }) {
+  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 captureLockError('capture_lock_owner_unverifiable');
+      await sleep(10);
+    }
+  }
+}
+
+async function withCaptureStoreLock(
+  directory,
+  task,
+  fsOps = captureFs,
+  {
+    now = Date.now,
+    sleep = (milliseconds) =>
+      new Promise((resolvePromise) => setTimeout(resolvePromise, milliseconds)),
+  } = {},
+) {
+  const nativeFs =
+    fsOps === captureFs ||
+    (fsOps.open === open && fsOps.lstat === lstat && fsOps.writeFile === writeFile);
+  const taskWithStageCleanup = async () => {
+    const reclaimed = await removeAbandonedCapturePageStages(directory, fsOps);
+    return task(reclaimed);
+  };
+  if (nativeFs) return withAdvisoryCaptureLock(directory, taskWithStageCleanup);
+  return withInjectedCaptureLock(directory, taskWithStageCleanup, fsOps, { now, sleep });
+}
+
+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', fsOps);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+  const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    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 pairedSourceTarget =
+    lockOptions.pairedSourcePath === undefined
+      ? null
+      : resolve(
+          directory,
+          lockOptions.pairedSourcePath.startsWith(directory)
+            ? lockOptions.pairedSourcePath.slice(directory.length + 1)
+            : lockOptions.pairedSourcePath,
+        );
+  const pairedSourceName = pairedSourceTarget?.slice(directory.length + 1) ?? null;
+  const sourceName = `${strictThreadName(value.threadId)}.${value.sourceRevision}.json`;
+  if (
+    pairedSourceTarget !== null &&
+    (dirname(pairedSourceTarget) !== directory ||
+      pairedSourceName !== sourceName ||
+      targetName !== captureNameForSnapshot(value))
+  )
+    throw new Error('capture publication target identity validation failed');
+  const operation = async () => {
+    const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
+    const sourceTemporary =
+      pairedSourceTarget === null
+        ? null
+        : `${pairedSourceTarget}.${process.pid}.${randomUUID()}.tmp`;
+    const expectedNames = new Set([
+      captureNameForSnapshot(value),
+      captureNameForSnapshot(value, '.completed'),
+      sourceName,
+    ]);
+    let existingTarget = null;
+    try {
+      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;
+    }
+    let existingSource = false;
+    if (pairedSourceTarget !== null) {
+      try {
+        await assertPrivateFile(pairedSourceTarget, 'immutable capture source', fsOps);
+        const immutable = JSON.parse(
+          await readPrivateFile(
+            pairedSourceTarget,
+            'immutable capture source',
+            MAX_CAPTURE_BYTES,
+            fsOps,
+          ),
+        );
+        validateCaptureSnapshot(immutable, value.sourceRevision);
+        if (immutable.threadId !== value.threadId)
+          throw new Error('immutable capture source identity validation failed');
+        existingSource = true;
+      } catch (error) {
+        if (error?.code !== 'ENOENT') throw error;
+      }
+    }
+    try {
+      if (sourceTemporary !== null && !existingSource) {
+        await fsOps.writeFile(sourceTemporary, serialized, { flag: 'wx', mode: 0o600 });
+        const writtenSource = await assertPrivateFile(
+          sourceTemporary,
+          'immutable capture candidate',
+          fsOps,
+        );
+        if (writtenSource.size !== Buffer.byteLength(serialized, 'utf8'))
+          throw new Error('immutable capture candidate read-back size mismatch');
+        validateCaptureSnapshot(
+          JSON.parse(await fsOps.readFile(sourceTemporary, 'utf8')),
+          value.sourceRevision,
+        );
+      }
+      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, {
+        ...(pairedSourceTarget === null ? {} : { replacedCurrentName: targetName }),
+      });
+      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 +
+        (sourceTemporary !== null && !existingSource ? 1 : 0) +
+        (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,
+          totalBytes: projectedSteadyBytes,
+          managedFileCount: projectedFiles,
+        });
+      const backup = existingTarget
+        ? `${target}.${process.pid}.${randomUUID()}.capture-backup`
+        : null;
+      const retiredBytes = retire.reduce((total, entry) => total + entry.size, 0);
+      const staged = [];
+      let backupCreated = false;
+      let candidatePublished = false;
+      let sourcePublished = false;
+      let committed = false;
+      try {
+        if (sourceTemporary !== null && !existingSource) {
+          await fsOps.rename(sourceTemporary, pairedSourceTarget);
+          sourcePublished = true;
+        }
+        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 });
+        }
+        const publishedSourceTarget =
+          pairedSourceTarget ?? (targetName === sourceName ? target : null);
+        if (publishedSourceTarget !== null) {
+          const sourceValue = JSON.parse(
+            await readPrivateFile(
+              publishedSourceTarget,
+              'published immutable capture source',
+              MAX_CAPTURE_BYTES,
+              fsOps,
+            ),
+          );
+          validateCaptureSnapshot(sourceValue, value.sourceRevision);
+          if (sourceValue.threadId !== value.threadId)
+            throw new Error('published capture source identity validation failed');
+        }
+        const publishedCurrent = JSON.parse(
+          await readPrivateFile(target, 'published current capture', MAX_CAPTURE_BYTES, fsOps),
+        );
+        validateCaptureSnapshot(publishedCurrent, value.sourceRevision);
+        if (publishedCurrent.threadId !== value.threadId)
+          throw new Error('published capture group identity validation failed');
+        const postState = await readCaptureDirectoryState(directory, fsOps);
+        const postSteadyBytes =
+          postState.totalBytes - (backupCreated ? replacedBytes : 0) - retiredBytes;
+        if (
+          postState.unsafeRecovery ||
+          postState.blockedEntries ||
+          postState.managedFiles.length > MAX_CAPTURE_FILES ||
+          postSteadyBytes > MAX_CAPTURE_DIRECTORY_BYTES
+        )
+          throw captureCapacityError({
+            totalBytes: postSteadyBytes,
+            managedFiles: postState.managedFiles,
+          });
+        committed = true;
+        let cleanupFailed = false;
+        const removeCommittedPath = async (path) => {
+          try {
+            await fsOps.unlink(path);
+          } catch (error) {
+            if (error?.code !== 'ENOENT') cleanupFailed = true;
+          }
+        };
+        if (backup !== null) await removeCommittedPath(backup);
+        for (const item of staged) await removeCommittedPath(item.staged);
+        if (cleanupFailed) {
+          let actualState = postState;
+          try {
+            actualState = await readCaptureDirectoryState(directory, fsOps);
+          } catch {}
+          throw captureStorageCleanupError(actualState);
+        }
+      } catch (error) {
+        if (committed) throw 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);
+        if (sourcePublished && pairedSourceTarget !== null)
+          await fsOps.unlink(pairedSourceTarget).catch(() => undefined);
+        throw error;
+      }
+    } catch (error) {
+      await fsOps.unlink(temporary).catch(() => undefined);
+      if (sourceTemporary !== null) await fsOps.unlink(sourceTemporary).catch(() => undefined);
+      throw error;
+    }
+  };
+  return lockOptions.lockHeld
+    ? operation()
+    : withCaptureStoreLock(directory, operation, fsOps, lockOptions);
+}
+
+async function retireUnreferencedCaptureGroup(
+  directory,
+  groupName,
+  fsOps = captureFs,
+  lockHeld = false,
+) {
+  const operation = async () => {
+    const state = await readCaptureDirectoryState(directory, fsOps);
+    if (state.unsafeRecovery || state.blockedEntries || state.protectedGroups.has(groupName))
+      return false;
+    const members = state.managedFiles.filter(
+      (entry) => entry.group === groupName && entry.immutable,
+    );
+    if (members.length === 0) return false;
+    const staged = [];
+    try {
+      for (const entry of members) {
+        const stagedPath = `${entry.file}.${process.pid}.${randomUUID()}.capture-retire`;
+        await fsOps.rename(entry.file, stagedPath);
+        staged.push({ original: entry.file, staged: stagedPath });
+      }
+    } catch (error) {
+      for (const item of staged)
+        await fsOps.rename(item.staged, item.original).catch(() => undefined);
+      throw error;
+    }
+    for (const item of staged) await fsOps.unlink(item.staged).catch(() => undefined);
+    return true;
+  };
+  return lockHeld ? operation() : withCaptureStoreLock(directory, operation, fsOps);
+}
+
+async function atomicWritePrivate(
+  file,
+  value,
+  {
+    maxBytes = null,
+    compact = false,
+    capture = false,
+    captureLock = false,
+    captureLockHeld = false,
+    pairedSourcePath,
+  } = {},
+) {
+  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 lockOptions = {
+      lockHeld: captureLockHeld,
+      ...(pairedSourcePath === undefined ? {} : { pairedSourcePath }),
+    };
+    const result = await writeBoundedCapture(file, serialized, value, captureFs, lockOptions);
+    return result;
+  }
+  const directory = await ensurePrivateDirectory(dirname(file));
+  if (captureLock) return withCaptureStoreLock(directory, () => writePrivateFile(file, serialized));
+  return writePrivateFile(file, serialized);
+}
+async function writeSegmentedCapture(
+  directory,
+  { threadId, sourceRevision, metadata, pages, lockHeld = false, fs = captureFs },
+) {
+  if (!lockHeld)
+    return withCaptureStoreLock(
+      directory,
+      () =>
+        writeSegmentedCapture(directory, {
+          threadId,
+          sourceRevision,
+          metadata,
+          pages,
+          lockHeld: true,
+          fs,
+        }),
+      fs,
+    );
+  if (!Array.isArray(pages) || pages.length < 1 || pages.length > MAX_CAPTURE_PAGES)
+    throw new Error('capture page count exceeds bound');
+  const segments = [];
+  const ownedStagePaths = new Set();
+  const cleanupSource = async () => {
+    for (const file of ownedStagePaths) {
+      try {
+        await assertPrivateFile(file, 'capture staged page cleanup', fs);
+      } catch {
+        continue;
+      }
+      await fs.unlink(file).catch((error) => {
+        if (error?.code !== 'ENOENT') throw error;
+      });
+    }
+  };
+  try {
+    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 stagedPath = resolve(descriptor.stagedPath);
+      if (
+        dirname(stagedPath) !== resolve(directory) ||
+        !CAPTURE_SOURCE_STAGE_NAME.test(basename(stagedPath))
+      )
+        throw new Error('capture staged page path validation failed');
+      const stagedInfo = await assertPrivateFile(stagedPath, 'capture staged page', fs);
+      ownedStagePaths.add(stagedPath);
+      const page = JSON.parse(
+        await readPrivateFile(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 - stagedInfo.size + Buffer.byteLength(serialized, 'utf8') >
+        MAX_CAPTURE_DIRECTORY_BYTES + MAX_CAPTURE_STAGING_HEADROOM_BYTES
+      )
+        throw captureCapacityError(stagedState);
+      await fs.writeFile(stagedPath, serialized, { flag: 'w', mode: 0o600 });
+      const rewritten = await assertPrivateFile(stagedPath, 'capture staged segment', fs);
+      if (rewritten.size !== Buffer.byteLength(serialized, 'utf8'))
+        throw new Error('capture staged segment read-back size mismatch');
+      validateCaptureSegment(
+        JSON.parse(await fs.readFile(stagedPath, 'utf8')),
+        threadId,
+        sourceRevision,
+      );
+      segments.push({
+        name: captureSegmentName(threadId, sourceRevision, descriptor.pageIndex),
+        pageHash: descriptor.pageHash,
+        itemCount: payload.itemCount,
+        bytes: Buffer.byteLength(serialized, 'utf8'),
+        stagedPath,
+      });
+    }
+  } catch (error) {
+    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();
+    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();
+    throw new Error('capture exceeds segmented bound');
+  }
+  const operation = async () => {
+    const state = await readCaptureDirectoryState(directory, fs);
+    if (state.unsafeRecovery || state.blockedEntries) {
+      await cleanupSource();
+      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');
+          continue;
+        } catch (error) {
+          if (error?.code !== 'ENOENT') throw error;
+        }
+        staged.push({ temporary: segment.stagedPath, 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_PUBLICATION_FILES)
+        throw captureCapacityError({
+          totalBytes: projected,
+          managedFileCount: projectedFiles,
+          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);
+        }
+        await cleanupSource();
+        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);
+      await cleanupSource();
+      throw error;
+    }
+  };
+  return operation();
+}
+
+/**
+ * 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);
+  return withCaptureStoreLock(
+    directory,
+    async () => {
+      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 + MAX_CAPTURE_STAGING_HEADROOM_BYTES
+          )
+            throw captureCapacityError(state);
+          const stagedPath = resolve(
+            directory,
+            `.capture-stage.${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,
+          lockHeld: true,
+          fs,
+        });
+      } catch (error) {
+        for (const page of staged) await fs.unlink(page.stagedPath).catch(() => undefined);
+        throw error;
+      }
+    },
+    fs,
+  );
+}
+
+export async function __testWriteSegmentedCaptureFromStages(
+  directory,
+  { threadId, sourceRevision, metadata = { thread: { id: threadId } }, pages },
+  { fs = captureFs } = {},
+) {
+  await ensurePrivateDirectory(directory, fs);
+  return withCaptureStoreLock(
+    directory,
+    () =>
+      writeSegmentedCapture(directory, {
+        threadId,
+        sourceRevision,
+        metadata,
+        pages,
+        lockHeld: true,
+        fs,
+      }),
+    fs,
   );
 }
 
-function diagnosticReasonForError(error) {
-  const message = error instanceof Error ? error.message : String(error ?? '');
-  if (/tim(?:e|ed)[ -]?out/iu.test(message)) return 'timeout';
-  if (/closed|deleted/iu.test(message)) return 'thread_closed';
-  if (/source changed|stale/iu.test(message)) return 'source_changed';
-  if (/candidate|history|thread\/read/iu.test(message)) return 'history_unavailable';
-  return 'request_failed';
+export async function __testPublishSegmentedCapture(
+  directory,
+  { threadId, sourceRevision, metadata = { thread: { id: threadId } }, pages },
+  { fs = captureFs } = {},
+) {
+  await ensurePrivateDirectory(directory, fs);
+  return withCaptureStoreLock(
+    directory,
+    async () => {
+      const staged = [];
+      let segmentsPublished = false;
+      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 + MAX_CAPTURE_STAGING_HEADROOM_BYTES
+          )
+            throw captureCapacityError(state);
+          const stagedPath = resolve(
+            directory,
+            `.capture-stage.${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'),
+          });
+        }
+        const manifest = await writeSegmentedCapture(directory, {
+          threadId,
+          sourceRevision,
+          metadata,
+          pages: staged,
+          lockHeld: true,
+          fs,
+        });
+        segmentsPublished = true;
+        const value = {
+          version: 2,
+          threadId,
+          sourceRevision,
+          threadRead: metadata,
+          captureManifest: manifest,
+        };
+        await writeBoundedCapture(
+          resolve(directory, `${strictThreadName(threadId)}.json`),
+          `${JSON.stringify(value)}\n`,
+          value,
+          fs,
+          {
+            lockHeld: true,
+            pairedSourcePath: resolve(
+              directory,
+              `${strictThreadName(threadId)}.${sourceRevision}.json`,
+            ),
+          },
+        );
+        return { manifest, value };
+      } catch (error) {
+        for (const page of staged) await fs.unlink(page.stagedPath).catch(() => undefined);
+        if (segmentsPublished)
+          await retireUnreferencedCaptureGroup(
+            directory,
+            `${threadId}.${sourceRevision}`,
+            fs,
+            true,
+          ).catch(() => undefined);
+        throw error;
+      }
+    },
+    fs,
+  );
 }
 
-async function ensurePrivateDirectory(directory) {
-  const target = resolve(directory);
-  await 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);
-    if (info.isSymbolicLink() || !info.isDirectory())
-      throw new Error('checkpoint directory is unsafe');
-  }
-  await chmod(target, 0o700);
-  return target;
-}
-async function assertPrivateFile(file, label) {
-  const info = await 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);
-  if (maxBytes !== null && info.size > maxBytes) throw new Error(`${label} exceeds its bound`);
-  return readFile(file, 'utf8');
+// 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 atomicWritePrivate(file, value) {
-  const directory = await ensurePrivateDirectory(dirname(file));
-  const target = resolve(
-    directory,
-    file.startsWith(directory) ? file.slice(directory.length + 1) : file,
+export async function maintainCaptureStorage(directory, { fs = captureFs } = {}) {
+  const target = await validatePrivateDirectoryPath(directory, fs);
+  return withCaptureStoreLock(
+    target,
+    async ({ removedFiles = 0, removedBytes = 0 } = {}) => {
+      const state = await readCaptureDirectoryState(target, fs);
+      if (state.unsafeRecovery || state.blockedEntries) throw captureCapacityError(state);
+      return {
+        reclaimedFiles: removedFiles,
+        reclaimedBytes: removedBytes,
+        managedFiles: state.managedFiles.length,
+        directoryBytes: state.totalBytes,
+        fileLimit: MAX_CAPTURE_FILES,
+        directoryByteLimit: MAX_CAPTURE_DIRECTORY_BYTES,
+      };
+    },
+    fs,
   );
-  try {
-    await assertPrivateFile(target, 'checkpoint target');
-  } 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);
-  } catch (error) {
-    try {
-      await unlink(temporary);
-    } catch {
-      /* preserve the original failure */
-    }
-    throw error;
-  }
 }
-async function atomicWriteImmutablePrivate(file, value, sourceRevision) {
-  await ensurePrivateDirectory(dirname(file));
-  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');
-  } catch (error) {
-    if (error?.code !== 'ENOENT') throw error;
-  }
-  await atomicWritePrivate(file, value);
+
+export async function __testHoldCaptureStoreLock(directory, readyPath) {
+  await ensurePrivateDirectory(directory);
+  return withCaptureStoreLock(directory, async () => {
+    await writeFile(readyPath, 'ready\n', { flag: 'wx', mode: 0o600 });
+    await new Promise((resolvePromise) => process.stdin.once('end', resolvePromise));
+  });
 }
 async function atomicWriteTextPrivate(file, text) {
   if (Buffer.byteLength(text) > MAX_NOTE_BYTES) throw new Error('recovery notes exceed bound');
@@ -599,6 +2033,125 @@ function validateThreadRead(value, threadId) {
   return value;
 }
 
+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, turnIndex) =>
@@ -613,14 +2166,23 @@ export function buildRecoveryCandidates(read, revision, policy = null, options =
     throw new Error('recovery candidate bound is invalid');
   if (rawItems.length > maxItems && options.allowWindow !== true)
     throw new Error('recovery candidate count exceeds bound');
-  if (rawItems.length > MAX_RECOVERY_SOURCE_INDEX)
-    throw new Error('recovery source index exceeds bound');
+  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 =
@@ -666,7 +2228,8 @@ export function buildRecoveryCandidates(read, revision, policy = null, options =
         ) &&
         (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 recentCount = policy?.preserveRecentMessages ?? 6;
     const recent = index >= Math.max(0, rawItems.length - recentCount);
@@ -688,7 +2251,14 @@ export function buildRecoveryCandidates(read, revision, policy = null, options =
     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),
@@ -700,7 +2270,8 @@ export function buildRecoveryCandidates(read, revision, policy = null, options =
       sourceItemId: typeof item.id === 'string' ? item.id : `item-${index + 1}`,
       sourceLocation: { flatIndex: index, turnIndex, itemIndex },
       sourceRefs: null,
-      sourceBodyChars: commandOutput.length,
+      sourceBodyChars: sourceOutputChars,
+      bodyComplete,
       kind,
     };
   });
@@ -1025,8 +2596,16 @@ export function recoveryNotesText(
           isSafeBoundedInteger(ref.itemIndex, 0, MAX_RECOVERY_SOURCE_INDEX),
       )
       .sort((left, right) => left.flatIndex - right.flatIndex);
-    const ranges = [];
+    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 });
@@ -1037,8 +2616,8 @@ export function recoveryNotesText(
           range.start === range.end ? String(range.start) : `${range.start}-${range.end}`,
         )
         .join(','),
-      locations: sorted.map((ref) => `${ref.turnIndex}:${ref.itemIndex}`).join(','),
-      ids: sorted
+      locations: unique.map((ref) => `${ref.turnIndex}:${ref.itemIndex}`).join(','),
+      ids: unique
         .map((ref) =>
           typeof ref.sourceItemId === 'string' ? escapeReference(ref.sourceItemId) : 'unknown',
         )
@@ -1076,6 +2655,7 @@ export function recoveryNotesText(
     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;
@@ -1099,27 +2679,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,
@@ -1153,6 +2712,8 @@ export function createCodexContextProxy({
   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();
@@ -1262,9 +2823,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);
@@ -1280,9 +2842,11 @@ export function createCodexContextProxy({
     emitDiagnostic({
       phase: 'thread_failure',
       stage: pending.stage ?? 'native',
-      reason: diagnosticReasonForError(new Error(reason)),
+      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`);
   }
@@ -1325,10 +2889,27 @@ export function createCodexContextProxy({
       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');
@@ -1528,6 +3109,160 @@ export function createCodexContextProxy({
     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) {
@@ -1596,6 +3331,7 @@ export function createCodexContextProxy({
     await atomicWritePrivate(
       resolve(checkpointDir, `${safeThreadName(threadId)}.recovery.json`),
       record,
+      { captureLock: true },
     );
   }
   async function readRecoveryNotes(threadId, record) {
@@ -1634,6 +3370,7 @@ export function createCodexContextProxy({
       injectSent: false,
       readId: null,
       injectId: null,
+      auxIds: [],
       deferred: injectWaiter,
       timer: null,
     };
@@ -1643,23 +3380,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');
@@ -1668,7 +3426,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');
@@ -1751,6 +3508,13 @@ export function createCodexContextProxy({
       };
       await persistRecoveryState(threadId, attached);
       state.recovery = attached;
+      emitDiagnostic({
+        phase: 'recovery_attached',
+        stage: 'recovery',
+        reason: 'attached',
+        threadId,
+        operationId: record.operationId,
+      });
       emitOutcome({ threadId, status: 'recovery_attached', turnId: record.turnId });
     } catch {
       if (attachment.injectSent) {
@@ -1784,11 +3548,17 @@ export function createCodexContextProxy({
       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)
@@ -1847,42 +3617,95 @@ export function createCodexContextProxy({
       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(),
-        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,
-        },
-      };
-      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);
+      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 immutableCapturePath = resolve(
+          checkpointDir,
+          `${safeThreadName(threadId)}.${sourceRevision}.json`,
+        );
+        try {
+          await atomicWritePrivate(
+            resolve(checkpointDir, `${safeThreadName(threadId)}.json`),
+            snapshot,
+            {
+              maxBytes: MAX_CAPTURE_BYTES,
+              compact: true,
+              capture: true,
+              captureLockHeld: true,
+              pairedSourcePath: immutableCapturePath,
+            },
+          );
+        } catch (error) {
+          await retireUnreferencedCaptureGroup(
+            checkpointDir,
+            `${threadId}.${sourceRevision}`,
+            captureFs,
+            true,
+          ).catch(() => undefined);
+          throw error;
+        }
+        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',
@@ -1894,6 +3717,15 @@ export function createCodexContextProxy({
             (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,
+                ),
+              }),
         },
       });
       assertCurrent(threadId, state, pending, revision);
@@ -2170,18 +4002,18 @@ export function createCodexContextProxy({
                 });
               }
               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);
+              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,
@@ -2240,6 +4072,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 = {
@@ -2274,8 +4107,11 @@ export function createCodexContextProxy({
         reason: diagnosticReasonForError(error),
         threadId,
         operationId: pending.operationId,
+        ...(boundedFailureCounts(error) === undefined
+          ? {}
+          : { counts: boundedFailureCounts(error) }),
       });
-      fail(threadId, 'checkpoint, request, or native completion failed');
+      fail(threadId, 'checkpoint, request, or native completion failed', error);
     } finally {
       if (pending.timer) pending.timer();
       cleanupRequest(pending.readId);
@@ -2297,6 +4133,7 @@ export function createCodexContextProxy({
       retire(message.id);
       if (
         owned.kind === 'read' ||
+        owned.kind === 'page' ||
         owned.kind === 'select' ||
         owned.kind === 'budget' ||
         owned.kind === 'inject' ||
@@ -2305,18 +4142,33 @@ export function createCodexContextProxy({
         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;
@@ -2329,17 +4181,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,
         });
       }
-      state.idle = state.status === 'idle';
-      if (!state.idle) invalidateAttachment(state);
       if (state.idle) void requestCompaction(message.params.threadId, state);
     }
     if (
@@ -2360,19 +4214,10 @@ 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();
-      telemetryFor(params.threadId).usage({
-        measurement: {
-          unit: 'tokens',
-          used: params.tokenUsage.last.totalTokens,
-          ...(hasKnownContextWindow(params.tokenUsage)
-            ? { capacity: params.tokenUsage.modelContextWindow }
-            : {}),
-        },
-        triggerPercent: effectiveThreshold,
-      });
       state.turnId = params.turnId;
       state.revision = `${state.turnId ?? 'unknown'}:${String(params.tokenUsage.last?.totalTokens ?? '')}:${String(params.tokenUsage.modelContextWindow ?? '')}`;
       if (
@@ -2384,6 +4229,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 (
@@ -2487,11 +4343,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;
@@ -2508,17 +4439,19 @@ export function createCodexContextProxy({
     }
   };
   const processLine = (line) => {
-    if (Buffer.byteLength(line) > MAX_LINE_BYTES) {
+    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');
-        failOversizedInternal(ownedId);
+        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 */
     }
@@ -2536,15 +4469,31 @@ export function createCodexContextProxy({
       if (state.pending) fail(threadId, reason);
     }
   }
-  function failOversizedInternal(id) {
+  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;
-    fail(owned.threadId, 'oversized internal response');
+    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;
@@ -2567,13 +4516,16 @@ export function createCodexContextProxy({
         passthrough = false;
       } else processLine(line);
     }
-    if (Buffer.byteLength(inputBuffer) > MAX_LINE_BYTES) {
+    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');
-        failOversizedInternal(internalRequestId(inputBuffer));
+        failOversizedInternal(
+          internalRequestId(inputBuffer),
+          Buffer.byteLength(inputBuffer, 'utf8') + 1,
+        );
         discardOversized = true;
         inputBuffer = '';
       } else {
@@ -2610,6 +4562,8 @@ export function createCodexContextProxy({
   }
   return {
     threads,
+    observeClientRequest,
+    observeClientResponse,
     async stop() {
       if (stopped) {
         await Promise.all(
@@ -2626,6 +4580,8 @@ export function createCodexContextProxy({
         void reporter.flush();
       }
       stopped = true;
+      clientRequestBindings.clear();
+      ownedThreadIds.clear();
       failAll('adapter stopped');
       await Promise.all(
         [...diagnosticSinks.values()].map((sink) =>
@@ -2693,6 +4649,35 @@ async function main() {
     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', async (code, signal) => {