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

package/dist/claude-observation.mjs

@@ -0,0 +1,1336 @@
+#!/usr/bin/env node
+// @ts-check
+
+import { createHash, randomUUID } from 'node:crypto';
+import { chmod, lstat, mkdir, open, readFile, readdir, rename, rm, stat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { claudeObservationConfigBinding, readConfig } from './state.mjs';
+import { selectContextShadow } from './mcp.mjs';
+
+export const MAX_STDIN_BYTES = 64 * 1024;
+export const MAX_RECORDS = 64;
+export const MAX_ITEMS = 16;
+export const MAX_LOG_BYTES = 1024 * 1024;
+export const MAX_LOG_FILES = 3;
+const LOCK_WAIT_MS = 250;
+const LOCK_STALE_MS = 30_000;
+const ADMISSION_MS = 60 * 60 * 1000;
+export const ADAPTER_VERSION = '0.3.0-beta.13';
+const MAX_DIAGNOSTIC_COUNT = 10_000_000;
+const MAX_DIAGNOSTIC_BYTES = 128 * 1024 * 1024;
+const CHECKPOINT_BACKENDS = new Set(['native_store', 'private_file']);
+const PROVIDER_RESPONSE_FORMATS = new Set(['structured', 'text', 'both', 'missing']);
+const DIAGNOSTIC_REASONS = new Set([
+  'all_recent',
+  'goal_missing',
+  'compact_priority',
+  'usage_unavailable',
+  'policy_unsupported',
+  'no_eligible_tools',
+  'unsupported_result',
+  'disabled',
+  'excluded',
+  'provider_not_attempted',
+  // Kept for records written by beta2/beta3 clients.
+  'unsupported_shape',
+  // Completion-proof outcomes are kept private and are never treated as
+  // provider or billing telemetry reasons.
+  'proof_expired',
+  'proof_mismatch',
+  'native_fallback_unconfirmed',
+  'native_summary_proof_expired',
+  'native_summary_host_view_mismatch',
+  'native_summary_host_view_ambiguous',
+  'native_summary_host_view_unavailable',
+  'native_summary_note_read_failed',
+  'native_summary_attachment_uncertain',
+  'plan_session_mismatch',
+  'plan_revision_mismatch',
+  'plan_projection_mismatch',
+  'plan_options_mismatch',
+  'plan_expired',
+  'plan_parse_envelope_invalid',
+  'plan_parse_metadata_invalid',
+  'plan_parse_decisions_invalid',
+  'plan_parse_fitting_invalid',
+  'plan_parse_stats_invalid',
+  'plan_parse_response_too_large',
+  'plan_parse_failed',
+  'session_changed_during_planning',
+  'snapshot_changed_during_planning',
+  'historical_notes_changed_during_planning',
+]);
+const ADMISSION_DETAILS = new Set(['state_budget_exceeded', 'shared_admission_denied']);
+const ADMISSION_REASONS = new Set([
+  'request_replayed',
+  'account_request_limit',
+  'account_token_limit',
+  'global_request_limit',
+  'global_token_limit',
+  'account_in_flight',
+  'database_unavailable',
+]);
+const CHECKPOINT_PHASES = new Set([
+  'read_existing',
+  'list_owned',
+  'read_owned',
+  'prune',
+  'write_candidate',
+  'verify_candidate',
+  'write_index',
+  'verify_index',
+  'rollback',
+]);
+const CHECKPOINT_ERRORS = new Set([
+  'checkpoint_keys_failed',
+  'checkpoint_read_failed',
+  'checkpoint_candidate_invalid',
+  'checkpoint_exceeds_retention',
+  'checkpoint_prune_failed',
+  'checkpoint_write_failed',
+  'checkpoint_readback_mismatch',
+  'checkpoint_index_failed',
+  'checkpoint_index_mismatch',
+  'checkpoint_rollback_failed',
+  'checkpoint_helper_invalid',
+  'checkpoint_helper_failed',
+  'checkpoint_helper_ack_mismatch',
+  'checkpoint_helper_input_too_large',
+  'checkpoint_binding_mismatch',
+]);
+const COMPACT_ERROR_CODES = new Set([
+  'state_budget_exceeded',
+  'shared_admission_exceeded',
+  'provider_budget_exceeded',
+  'provider_unavailable',
+  'provider_auth_denied',
+  'invalid_provider_request',
+  'provider_response_invalid',
+  'insufficient_reduction',
+  'no_eligible_items',
+  'measurement_limit_exceeded',
+  'projection_anchor_overflow',
+  'projection_message_limit',
+  'projection_budget_exceeded',
+]);
+
+/** @typedef {{id: string, kind: 'tool_result'|'reference', chars: number, protected: boolean, description?: string}} ObservationItem */
+/** @typedef {{keep_threshold: number, preserve_recent_items: number, max_state_tokens: number, max_request_tokens: number}} ObservationOptions */
+/** @typedef {{schema_version: 1, action: 'diagnostics', session_key: string, instance_id: string, records: Record<string, unknown>[]}} DiagnosticsInput */
+/** @typedef {{schema_version: 1, action: 'preview', session_key: string, instance_id: string, operation_id: string, client_version: string, observed_at: string, revision: string, goal: string, items: ObservationItem[], options: ObservationOptions}} PreviewInput */
+/** @typedef {DiagnosticsInput | PreviewInput} ObservationInput */
+/** @typedef {{endpoint: string, token: string, claudeObservation: {shadowEnabled: boolean, diagnosticsEnabled: boolean, disclosedAt: string|null}}} ObservationConfig */
+
+const DIAGNOSTIC_STAGES = new Set([
+  'entry_guard',
+  'snapshot',
+  'checkpoint',
+  'projection',
+  'budget',
+  'provider_request',
+  'provider_response',
+  'plan_validation',
+  'candidate_preparation',
+  'fallback',
+  'compact_entry',
+  'compact_exit',
+  'native_summary_proof',
+  'native_error',
+]);
+const DIAGNOSTIC_CATEGORIES = new Set([
+  'observed',
+  'provider_not_attempted',
+  'request_attempted',
+  'response_obtained',
+  'provider_decision',
+  'native_error',
+  'unsupported',
+  'timeout',
+  'rate_limited',
+  'invalid_response',
+  'skipped',
+  'logger_failure',
+  'auth_denied',
+  'permission_denied',
+  'tool_unavailable',
+]);
+const MODES = new Set(['shadow', 'compact']);
+const HEX64 = /^[a-f0-9]{64}$/u;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+const SAFE_IDENTIFIER = /^[A-Za-z0-9._:-]{1,128}$/u;
+const VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/u;
+const MAX_VERSION_LENGTH = 64;
+const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u;
+const SAFE_ERROR_CODES = new Set([
+  'invalid_arguments',
+  'state_dir_not_absolute',
+  'config_digest_invalid',
+  'state_path_invalid',
+  'state_owner_mismatch',
+  'state_permissions_invalid',
+  'diagnostics_symlink_rejected',
+  'diagnostics_path_missing',
+  'diagnostics_path_invalid',
+  'diagnostics_owner_mismatch',
+  'diagnostics_file_invalid',
+  'diagnostics_file_permissions_invalid',
+  'diagnostics_file_size_invalid',
+  'diagnostics_lock_symlink_rejected',
+  'diagnostics_lock_permissions_invalid',
+  'diagnostics_lock_timeout',
+  'diagnostics_record_too_large',
+  'invalid_input',
+  'input_too_large',
+  'observation_disabled',
+  'observation_not_disclosed',
+  'state_changed',
+  'admission_invalid',
+  'admission_denied',
+  'mcp_deadline_invalid',
+  'mcp_auth_denied',
+  'mcp_request_timeout',
+  'mcp_network_error',
+  'mcp_response_malformed',
+  'mcp_response_invalid_shape',
+  'mcp_response_too_large',
+  'mcp_response_invalid_utf8',
+  'mcp_response_id_mismatch',
+  'mcp_session_id_invalid',
+  'mcp_session_id_changed',
+  'mcp_initialize_denied',
+  'mcp_shadow_request_invalid',
+  'mcp_shadow_rejected',
+  'mcp_tool_unavailable',
+  'mcp_feature_disabled',
+  'mcp_paid_plan_required',
+  'provider_error',
+  'helper_failed',
+]);
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function object(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** @param {unknown} value @param {number} max */
+function noControlText(value, max) {
+  return (
+    typeof value === 'string' && value.length <= max && !/[\u0000-\u001f\u007f-\u009f]/u.test(value)
+  );
+}
+
+/** @param {unknown} value @returns {string} */
+function canonical(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  const objectValue = /** @type {Record<string, unknown>} */ (value);
+  return `{${Object.keys(objectValue)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${canonical(objectValue[key])}`)
+    .join(',')}}`;
+}
+
+/** @param {unknown} value */
+function hash(value) {
+  return createHash('sha256').update(canonical(value), 'utf8').digest('hex');
+}
+
+/** @param {string} value */
+function pseudonym(value) {
+  return hash({ value }).slice(0, 32);
+}
+
+/** @param {unknown} value */
+function validVersion(value) {
+  return typeof value === 'string' && value.length <= MAX_VERSION_LENGTH && VERSION.test(value);
+}
+
+/** @param {unknown} error */
+function safeProviderErrorCode(error) {
+  return error instanceof Error && SAFE_ERROR_CODES.has(error.message)
+    ? error.message
+    : 'provider_error';
+}
+
+/** @param {string} code */
+function providerFailureCategory(code) {
+  if (code === 'mcp_request_timeout') return 'timeout';
+  if (code === 'mcp_auth_denied' || code === 'mcp_paid_plan_required') return 'auth_denied';
+  if (code === 'mcp_tool_unavailable') return 'tool_unavailable';
+  if (code === 'mcp_feature_disabled') return 'unsupported';
+  if (code === 'mcp_shadow_rejected' || code === 'mcp_response_malformed')
+    return 'invalid_response';
+  return 'native_error';
+}
+
+/** @param {string[]} argv */
+function parseArgs(argv) {
+  if (argv.length !== 4 || argv[0] !== '--state-dir' || argv[2] !== '--config-digest')
+    throw new Error('invalid_arguments');
+  if (!isAbsolute(argv[1])) throw new Error('state_dir_not_absolute');
+  if (!HEX64.test(argv[3])) throw new Error('config_digest_invalid');
+  return { stateDir: resolve(argv[1]), configDigest: argv[3] };
+}
+
+/** @param {string} stateDir */
+async function assertOwnedDir(stateDir) {
+  const root = resolve(stateDir);
+  await assertNoSymlinkAncestors(root, false);
+  const entry = await lstat(root);
+  if (!entry.isDirectory() || entry.isSymbolicLink()) throw new Error('state_path_invalid');
+  if (typeof process.getuid === 'function' && entry.uid !== process.getuid())
+    throw new Error('state_owner_mismatch');
+  if ((entry.mode & 0o077) !== 0) throw new Error('state_permissions_invalid');
+  return root;
+}
+
+/** @param {string} target @param {boolean} allowMissing */
+async function assertNoSymlinkAncestors(target, allowMissing) {
+  const absolute = resolve(target);
+  const parts = absolute.split('/').filter(Boolean);
+  let current = absolute.startsWith('/') ? '/' : '';
+  for (const part of parts) {
+    current = current === '/' ? `/${part}` : join(current, part);
+    try {
+      const entry = await lstat(current);
+      if (entry.isSymbolicLink()) throw new Error('diagnostics_symlink_rejected');
+    } catch (error) {
+      if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') throw error;
+      if (!allowMissing) throw new Error('diagnostics_path_missing');
+      break;
+    }
+  }
+}
+
+/** @param {string} path @param {boolean} [create] */
+async function ownedDirectory(path, create = true) {
+  const target = resolve(path);
+  await assertNoSymlinkAncestors(target, create);
+  if (create) await mkdir(target, { recursive: true, mode: 0o700 });
+  await assertNoSymlinkAncestors(target, false);
+  const entry = await lstat(target);
+  if (!entry.isDirectory() || entry.isSymbolicLink()) throw new Error('diagnostics_path_invalid');
+  if (typeof process.getuid === 'function' && entry.uid !== process.getuid())
+    throw new Error('diagnostics_owner_mismatch');
+  await chmod(target, 0o700);
+  return target;
+}
+
+/** @param {string} path */
+async function ownedFile(path) {
+  const entry = await lstat(path);
+  if (!entry.isFile() || entry.isSymbolicLink()) throw new Error('diagnostics_file_invalid');
+  if (typeof process.getuid === 'function' && entry.uid !== process.getuid())
+    throw new Error('diagnostics_owner_mismatch');
+  if ((entry.mode & 0o077) !== 0) throw new Error('diagnostics_file_permissions_invalid');
+  if (entry.size > MAX_LOG_BYTES) throw new Error('diagnostics_file_size_invalid');
+  return entry;
+}
+
+/** @param {string} path @param {string} payload */
+async function writeOwnedJson(path, payload) {
+  await assertNoSymlinkAncestors(dirname(path), false);
+  const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
+  const handle = await open(
+    temporary,
+    constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
+    0o600,
+  );
+  try {
+    await handle.write(payload, undefined, 'utf8');
+  } finally {
+    await handle.close();
+  }
+  await chmod(temporary, 0o600);
+  try {
+    const existing = await lstat(path);
+    if (existing.isSymbolicLink()) throw new Error('diagnostics_file_invalid');
+    if (!existing.isFile()) throw new Error('diagnostics_file_invalid');
+  } catch (error) {
+    if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') {
+      await rm(temporary, { force: true }).catch(() => undefined);
+      throw error;
+    }
+  }
+  try {
+    await rename(temporary, path);
+  } catch (error) {
+    await rm(temporary, { force: true }).catch(() => undefined);
+    throw error;
+  }
+}
+
+/** @param {Record<string, unknown>} record */
+function isSafeLogRecord(record) {
+  const keys = new Set([
+    'schema_version',
+    'operation_id',
+    'stage',
+    'category',
+    'mode',
+    'adapter_version',
+    'client_version',
+    'observed_at',
+    'session_key',
+    'instance_id',
+    'item_id',
+    'duration_ms',
+    'item_count',
+    'captured_count',
+    'excluded_count',
+    'unsupported_count',
+    'checkpoint_phase',
+    'checkpoint_error',
+    'compact_error_code',
+    'hook_version',
+    'checkpoint_backend',
+    'projection_total',
+    'selected_count',
+    'deferred_count',
+    'admission_detail',
+    'admission_reason',
+    'request_id',
+    'correlation_id',
+    'retry_after_ms',
+    'proof_expected_count',
+    'proof_actual_count',
+    'proof_match',
+    'proof_match_offset',
+    'proof_view_source',
+    'proof_api_view_match',
+    'proof_api_count',
+    'proof_delivery_source',
+    'proof_delivery_match_count',
+    'byte_count',
+    'char_count',
+    'rpc_status',
+    'provider_response_format',
+    'would_keep',
+    'applied',
+    'provider_confirmed',
+    'chars',
+    'outcome',
+    'reason',
+  ]);
+  if (
+    record.schema_version !== 1 ||
+    Object.keys(record).some((key) => !keys.has(key)) ||
+    !UUID.test(String(record.operation_id)) ||
+    !DIAGNOSTIC_STAGES.has(String(record.stage)) ||
+    !DIAGNOSTIC_CATEGORIES.has(String(record.category)) ||
+    !MODES.has(String(record.mode)) ||
+    !validVersion(record.adapter_version) ||
+    !validVersion(record.client_version) ||
+    !ISO.test(String(record.observed_at)) ||
+    !Number.isFinite(Date.parse(String(record.observed_at))) ||
+    (record.session_key !== undefined && !/^[a-f0-9]{64}$/u.test(String(record.session_key))) ||
+    (record.instance_id !== undefined && !/^[a-f0-9]{32}$/u.test(String(record.instance_id))) ||
+    (record.item_id !== undefined && !/^[a-f0-9]{32}$/u.test(String(record.item_id))) ||
+    (record.applied !== undefined && record.applied !== false) ||
+    (record.outcome !== undefined &&
+      !['protected', 'would_keep', 'would_omit_result'].includes(String(record.outcome))) ||
+    (record.reason !== undefined && !DIAGNOSTIC_REASONS.has(String(record.reason))) ||
+    (record.checkpoint_phase !== undefined &&
+      (typeof record.checkpoint_phase !== 'string' ||
+        !CHECKPOINT_PHASES.has(record.checkpoint_phase))) ||
+    (record.checkpoint_error !== undefined &&
+      (typeof record.checkpoint_error !== 'string' ||
+        !CHECKPOINT_ERRORS.has(record.checkpoint_error))) ||
+    (record.compact_error_code !== undefined &&
+      (typeof record.compact_error_code !== 'string' ||
+        !COMPACT_ERROR_CODES.has(record.compact_error_code))) ||
+    (record.admission_detail !== undefined &&
+      (typeof record.admission_detail !== 'string' ||
+        !ADMISSION_DETAILS.has(record.admission_detail))) ||
+    (record.admission_reason !== undefined &&
+      (typeof record.admission_reason !== 'string' ||
+        !ADMISSION_REASONS.has(record.admission_reason))) ||
+    (record.request_id !== undefined && !UUID.test(String(record.request_id))) ||
+    (record.correlation_id !== undefined &&
+      (typeof record.correlation_id !== 'string' ||
+        !SAFE_IDENTIFIER.test(record.correlation_id))) ||
+    (record.retry_after_ms !== undefined &&
+      (typeof record.retry_after_ms !== 'number' ||
+        !Number.isSafeInteger(record.retry_after_ms) ||
+        record.retry_after_ms < 0 ||
+        record.retry_after_ms > 3_600_000)) ||
+    (record.proof_match !== undefined &&
+      (typeof record.proof_match !== 'string' ||
+        !['exact', 'active_suffix', 'mismatch', 'ambiguous'].includes(record.proof_match))) ||
+    (record.proof_view_source !== undefined &&
+      (typeof record.proof_view_source !== 'string' ||
+        !['default', 'api'].includes(record.proof_view_source))) ||
+    (record.proof_api_view_match !== undefined &&
+      (typeof record.proof_api_view_match !== 'string' ||
+        !['exact', 'mismatch', 'unavailable', 'not_checked'].includes(
+          record.proof_api_view_match,
+        ))) ||
+    (record.proof_delivery_source !== undefined &&
+      (typeof record.proof_delivery_source !== 'string' ||
+        !['atomic_result', 'legacy_append'].includes(record.proof_delivery_source))) ||
+    (record.hook_version !== undefined && !validVersion(record.hook_version)) ||
+    (record.checkpoint_backend !== undefined &&
+      (typeof record.checkpoint_backend !== 'string' ||
+        !CHECKPOINT_BACKENDS.has(record.checkpoint_backend))) ||
+    (record.provider_response_format !== undefined &&
+      !PROVIDER_RESPONSE_FORMATS.has(String(record.provider_response_format)))
+  )
+    return false;
+  for (const key of [
+    'duration_ms',
+    'item_count',
+    'captured_count',
+    'excluded_count',
+    'unsupported_count',
+    'byte_count',
+    'char_count',
+    'rpc_status',
+    'chars',
+    'projection_total',
+    'selected_count',
+    'deferred_count',
+    'proof_expected_count',
+    'proof_actual_count',
+    'proof_match_offset',
+    'proof_api_count',
+    'proof_delivery_match_count',
+  ]) {
+    const value = record[key];
+    const lowerBound = key === 'rpc_status' ? -100_000 : 0;
+    if (
+      value !== undefined &&
+      (typeof value !== 'number' ||
+        !Number.isSafeInteger(value) ||
+        value < lowerBound ||
+        value > (key === 'byte_count' ? MAX_DIAGNOSTIC_BYTES : MAX_DIAGNOSTIC_COUNT))
+    )
+      return false;
+  }
+  for (const key of ['would_keep', 'provider_confirmed']) {
+    if (record[key] !== undefined && typeof record[key] !== 'boolean') return false;
+  }
+  return true;
+}
+
+/** @param {string} lockPath @param {() => Promise<unknown>} operation */
+async function withLock(lockPath, operation) {
+  const started = Date.now();
+  let acquired = false;
+  while (!acquired) {
+    try {
+      await mkdir(lockPath, { mode: 0o700 });
+      acquired = true;
+      try {
+        await writeOwnedJson(
+          join(lockPath, 'owner.json'),
+          `${JSON.stringify({ pid: process.pid, created_at: Date.now() })}\n`,
+        );
+      } catch (error) {
+        await rm(lockPath, { recursive: true, force: true }).catch(() => undefined);
+        throw error;
+      }
+    } catch (error) {
+      if (!(error instanceof Error) || !('code' in error) || error.code !== 'EEXIST') throw error;
+      const lockEntry = await lstat(lockPath).catch((lockError) => {
+        if (lockError instanceof Error && 'code' in lockError && lockError.code === 'ENOENT')
+          return null;
+        throw lockError;
+      });
+      if (lockEntry?.isSymbolicLink()) throw new Error('diagnostics_lock_symlink_rejected');
+      if (
+        lockEntry &&
+        ((typeof process.getuid === 'function' && lockEntry.uid !== process.getuid()) ||
+          (lockEntry.mode & 0o077) !== 0)
+      )
+        throw new Error('diagnostics_lock_permissions_invalid');
+      let stale = false;
+      if (lockEntry?.isDirectory()) {
+        try {
+          const ownerPath = join(lockPath, 'owner.json');
+          await ownedFile(ownerPath);
+          const owner = JSON.parse(await readFile(ownerPath, 'utf8'));
+          let ownerAlive = false;
+          if (Number.isSafeInteger(owner.pid) && owner.pid > 0) {
+            try {
+              process.kill(owner.pid, 0);
+              ownerAlive = true;
+            } catch (processError) {
+              if (
+                !(processError instanceof Error) ||
+                !('code' in processError) ||
+                processError.code !== 'ESRCH'
+              )
+                ownerAlive = true;
+            }
+          }
+          stale =
+            !ownerAlive &&
+            Number.isSafeInteger(owner.created_at) &&
+            Date.now() - owner.created_at > LOCK_STALE_MS;
+        } catch (ownerError) {
+          if (ownerError instanceof Error && 'code' in ownerError && ownerError.code === 'ENOENT') {
+            try {
+              const metadata = await stat(lockPath);
+              stale = Date.now() - metadata.mtimeMs > LOCK_STALE_MS;
+            } catch (metadataError) {
+              if (
+                !(metadataError instanceof Error) ||
+                !('code' in metadataError) ||
+                metadataError.code !== 'ENOENT'
+              )
+                throw metadataError;
+              continue;
+            }
+          } else {
+            throw ownerError;
+          }
+        }
+      }
+      if (stale) {
+        await rm(lockPath, { recursive: true, force: true });
+        continue;
+      }
+      if (Date.now() - started >= LOCK_WAIT_MS) throw new Error('diagnostics_lock_timeout');
+      await new Promise((resolvePromise) => setTimeout(resolvePromise, 10));
+    }
+  }
+  try {
+    return await operation();
+  } finally {
+    await rm(lockPath, { recursive: true, force: true }).catch(() => undefined);
+  }
+}
+
+/** @param {string} root @param {string} file @param {unknown[]} records */
+async function appendRecords(root, file, records) {
+  if (records.length === 0) return 0;
+  const directory = await ownedDirectory(join(root, 'diagnostics', 'claude'));
+  const lock = join(directory, '.lock');
+  return withLock(lock, async () => {
+    const files = Array.from({ length: MAX_LOG_FILES }, (_, index) =>
+      join(directory, `${file}.${index}.jsonl`),
+    );
+    let current = files[0];
+    for (const candidate of files) {
+      try {
+        const entry = await ownedFile(candidate);
+        if (entry.size < MAX_LOG_BYTES) {
+          current = candidate;
+          break;
+        }
+      } catch (error) {
+        if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') throw error;
+        current = candidate;
+        break;
+      }
+    }
+    let payload = records.map((record) => `${JSON.stringify(record)}\n`).join('');
+    if (Buffer.byteLength(payload, 'utf8') > MAX_LOG_BYTES)
+      throw new Error('diagnostics_record_too_large');
+    let entry;
+    try {
+      entry = await ownedFile(current);
+    } catch (error) {
+      if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') throw error;
+      entry = null;
+    }
+    if (entry && entry.size + Buffer.byteLength(payload, 'utf8') > MAX_LOG_BYTES) {
+      await rotateFiles(files);
+      current = files[0];
+    }
+    const handle = await open(
+      current,
+      constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW,
+      0o600,
+    );
+    try {
+      await handle.write(payload, undefined, 'utf8');
+    } finally {
+      await handle.close();
+    }
+    await chmod(current, 0o600);
+    return records.length;
+  });
+}
+
+/** @param {string[]} files */
+async function rotateFiles(files) {
+  for (let index = files.length - 1; index > 0; index -= 1) {
+    await rename(files[index - 1], files[index]).catch((error) => {
+      if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') throw error;
+    });
+  }
+  await rm(files[0], { force: true });
+}
+
+/** @param {unknown} input @returns {ObservationInput} */
+function validateInput(input) {
+  if (
+    !object(input) ||
+    input.schema_version !== 1 ||
+    !['diagnostics', 'preview'].includes(String(input.action))
+  )
+    throw new Error('invalid_input');
+  const topLevelKeys =
+    input.action === 'diagnostics'
+      ? new Set(['schema_version', 'action', 'session_key', 'instance_id', 'records'])
+      : new Set([
+          'schema_version',
+          'action',
+          'session_key',
+          'instance_id',
+          'operation_id',
+          'client_version',
+          'observed_at',
+          'revision',
+          'goal',
+          'items',
+          'options',
+        ]);
+  if (Object.keys(input).some((key) => !topLevelKeys.has(key))) throw new Error('invalid_input');
+  if (!HEX64.test(String(input.session_key)) || !UUID.test(String(input.instance_id)))
+    throw new Error('invalid_input');
+  if (input.action === 'diagnostics') {
+    const diagnosticsInput = /** @type {Record<string, unknown>} */ (input);
+    if (!Array.isArray(diagnosticsInput.records) || diagnosticsInput.records.length > MAX_RECORDS)
+      throw new Error('invalid_input');
+    return /** @type {DiagnosticsInput} */ (input);
+  }
+  const previewInput = /** @type {Record<string, unknown>} */ (input);
+  if (
+    !UUID.test(String(previewInput.operation_id)) ||
+    !validVersion(previewInput.client_version) ||
+    !ISO.test(String(previewInput.observed_at)) ||
+    !Number.isFinite(Date.parse(String(previewInput.observed_at))) ||
+    !HEX64.test(String(previewInput.revision)) ||
+    !noControlText(previewInput.goal, 4000) ||
+    !Array.isArray(previewInput.items) ||
+    previewInput.items.length === 0 ||
+    previewInput.items.length > MAX_ITEMS ||
+    !object(previewInput.options)
+  )
+    throw new Error('invalid_input');
+  const items = /** @type {ObservationItem[]} */ (previewInput.items);
+  for (const item of items) {
+    if (
+      !object(item) ||
+      !noControlText(item.id, 128) ||
+      !['tool_result', 'reference'].includes(item.kind) ||
+      !Number.isSafeInteger(item.chars) ||
+      item.chars < 0 ||
+      item.chars > 10_000_000 ||
+      typeof item.protected !== 'boolean' ||
+      Object.keys(item).some(
+        (key) => !['id', 'kind', 'chars', 'protected', 'description'].includes(key),
+      ) ||
+      (item.description !== undefined && !noControlText(item.description, 256))
+    )
+      throw new Error('invalid_input');
+  }
+  const options = /** @type {ObservationOptions} */ (previewInput.options);
+  if (
+    Object.keys(options).some(
+      (key) =>
+        ![
+          'keep_threshold',
+          'preserve_recent_items',
+          'max_state_tokens',
+          'max_request_tokens',
+        ].includes(key),
+    )
+  )
+    throw new Error('invalid_input');
+  if (
+    typeof options.keep_threshold !== 'number' ||
+    !Number.isFinite(options.keep_threshold) ||
+    options.keep_threshold < 0 ||
+    options.keep_threshold > 1 ||
+    !Number.isSafeInteger(options.preserve_recent_items) ||
+    options.preserve_recent_items < 1 ||
+    options.preserve_recent_items > 100 ||
+    !Number.isSafeInteger(options.max_state_tokens) ||
+    options.max_state_tokens < 1000 ||
+    options.max_state_tokens > 25000 ||
+    !Number.isSafeInteger(options.max_request_tokens) ||
+    options.max_request_tokens <= options.max_state_tokens + 256 ||
+    options.max_request_tokens > 30000
+  )
+    throw new Error('invalid_input');
+  return /** @type {PreviewInput} */ (input);
+}
+
+/** @param {Record<string, unknown>} record @returns {Record<string, unknown>} */
+function diagnosticRecord(record) {
+  const allowedKeys = new Set([
+    'operation_id',
+    'stage',
+    'category',
+    'mode',
+    'client_version',
+    'observed_at',
+    'duration_ms',
+    'item_count',
+    'captured_count',
+    'excluded_count',
+    'unsupported_count',
+    'checkpoint_phase',
+    'checkpoint_error',
+    'compact_error_code',
+    'hook_version',
+    'checkpoint_backend',
+    'projection_total',
+    'selected_count',
+    'deferred_count',
+    'admission_detail',
+    'admission_reason',
+    'request_id',
+    'correlation_id',
+    'retry_after_ms',
+    'proof_expected_count',
+    'proof_actual_count',
+    'proof_match',
+    'proof_match_offset',
+    'proof_view_source',
+    'proof_api_view_match',
+    'proof_api_count',
+    'proof_delivery_source',
+    'proof_delivery_match_count',
+    'byte_count',
+    'rpc_status',
+    'provider_response_format',
+    'reason',
+  ]);
+  if (
+    Object.keys(record).some((key) => !allowedKeys.has(key)) ||
+    !UUID.test(String(record.operation_id)) ||
+    !DIAGNOSTIC_STAGES.has(String(record.stage)) ||
+    !DIAGNOSTIC_CATEGORIES.has(String(record.category)) ||
+    !MODES.has(String(record.mode)) ||
+    !validVersion(record.client_version) ||
+    !ISO.test(String(record.observed_at)) ||
+    !Number.isFinite(Date.parse(String(record.observed_at))) ||
+    (record.proof_match !== undefined &&
+      (typeof record.proof_match !== 'string' ||
+        !['exact', 'active_suffix', 'mismatch', 'ambiguous'].includes(record.proof_match))) ||
+    (record.proof_view_source !== undefined &&
+      (typeof record.proof_view_source !== 'string' ||
+        !['default', 'api'].includes(record.proof_view_source))) ||
+    (record.proof_api_view_match !== undefined &&
+      (typeof record.proof_api_view_match !== 'string' ||
+        !['exact', 'mismatch', 'unavailable', 'not_checked'].includes(
+          record.proof_api_view_match,
+        ))) ||
+    (record.proof_delivery_source !== undefined &&
+      (typeof record.proof_delivery_source !== 'string' ||
+        !['atomic_result', 'legacy_append'].includes(record.proof_delivery_source))) ||
+    (record.provider_response_format !== undefined &&
+      !PROVIDER_RESPONSE_FORMATS.has(String(record.provider_response_format)))
+  )
+    throw new Error('invalid_input');
+  /** @type {Record<string, unknown>} */
+  const output = {
+    schema_version: 1,
+    operation_id: String(record.operation_id),
+    stage: String(record.stage),
+    category: String(record.category),
+    mode: String(record.mode),
+    adapter_version: ADAPTER_VERSION,
+    client_version: String(record.client_version),
+    observed_at: String(record.observed_at),
+  };
+  if (record.reason !== undefined) {
+    if (!noControlText(record.reason, 64) || !DIAGNOSTIC_REASONS.has(String(record.reason)))
+      throw new Error('invalid_input');
+    output.reason = String(record.reason);
+  }
+  if (record.checkpoint_phase !== undefined) {
+    if (
+      typeof record.checkpoint_phase !== 'string' ||
+      !CHECKPOINT_PHASES.has(record.checkpoint_phase)
+    )
+      throw new Error('invalid_input');
+    output.checkpoint_phase = record.checkpoint_phase;
+  }
+  if (record.checkpoint_error !== undefined) {
+    if (
+      typeof record.checkpoint_error !== 'string' ||
+      !CHECKPOINT_ERRORS.has(record.checkpoint_error)
+    )
+      throw new Error('invalid_input');
+    output.checkpoint_error = record.checkpoint_error;
+  }
+  if (record.compact_error_code !== undefined) {
+    if (
+      typeof record.compact_error_code !== 'string' ||
+      !COMPACT_ERROR_CODES.has(record.compact_error_code)
+    )
+      throw new Error('invalid_input');
+    output.compact_error_code = record.compact_error_code;
+  }
+  if (record.admission_detail !== undefined) {
+    if (
+      typeof record.admission_detail !== 'string' ||
+      !ADMISSION_DETAILS.has(record.admission_detail)
+    )
+      throw new Error('invalid_input');
+    output.admission_detail = record.admission_detail;
+  }
+  if (record.admission_reason !== undefined) {
+    if (
+      typeof record.admission_reason !== 'string' ||
+      !ADMISSION_REASONS.has(record.admission_reason)
+    )
+      throw new Error('invalid_input');
+    output.admission_reason = record.admission_reason;
+  }
+  if (record.request_id !== undefined) {
+    if (typeof record.request_id !== 'string' || !UUID.test(record.request_id))
+      throw new Error('invalid_input');
+    output.request_id = record.request_id;
+  }
+  if (record.correlation_id !== undefined) {
+    if (typeof record.correlation_id !== 'string' || !SAFE_IDENTIFIER.test(record.correlation_id))
+      throw new Error('invalid_input');
+    output.correlation_id = record.correlation_id;
+  }
+  if (record.retry_after_ms !== undefined) {
+    if (
+      typeof record.retry_after_ms !== 'number' ||
+      !Number.isSafeInteger(record.retry_after_ms) ||
+      record.retry_after_ms < 0 ||
+      record.retry_after_ms > 3_600_000
+    )
+      throw new Error('invalid_input');
+    output.retry_after_ms = record.retry_after_ms;
+  }
+  for (const key of ['proof_expected_count', 'proof_actual_count', 'proof_match_offset']) {
+    const value = record[key];
+    if (
+      value !== undefined &&
+      (typeof value !== 'number' ||
+        !Number.isSafeInteger(value) ||
+        value < 0 ||
+        value > MAX_DIAGNOSTIC_COUNT)
+    )
+      throw new Error('invalid_input');
+    if (value !== undefined) output[key] = value;
+  }
+  if (record.proof_match !== undefined) output.proof_match = String(record.proof_match);
+  if (record.proof_view_source !== undefined)
+    output.proof_view_source = String(record.proof_view_source);
+  if (record.proof_api_view_match !== undefined)
+    output.proof_api_view_match = String(record.proof_api_view_match);
+  if (record.proof_delivery_source !== undefined)
+    output.proof_delivery_source = String(record.proof_delivery_source);
+  if (record.hook_version !== undefined) {
+    if (!validVersion(record.hook_version)) throw new Error('invalid_input');
+    output.hook_version = record.hook_version;
+  }
+  if (record.checkpoint_backend !== undefined) {
+    if (
+      typeof record.checkpoint_backend !== 'string' ||
+      !CHECKPOINT_BACKENDS.has(record.checkpoint_backend)
+    )
+      throw new Error('invalid_input');
+    output.checkpoint_backend = record.checkpoint_backend;
+  }
+  if (record.provider_response_format !== undefined) {
+    if (
+      typeof record.provider_response_format !== 'string' ||
+      !PROVIDER_RESPONSE_FORMATS.has(record.provider_response_format)
+    )
+      throw new Error('invalid_input');
+    output.provider_response_format = record.provider_response_format;
+  }
+  for (const key of [
+    'duration_ms',
+    'item_count',
+    'captured_count',
+    'excluded_count',
+    'unsupported_count',
+    'byte_count',
+    'rpc_status',
+    'projection_total',
+    'selected_count',
+    'deferred_count',
+    'proof_expected_count',
+    'proof_actual_count',
+    'proof_match_offset',
+    'proof_api_count',
+    'proof_delivery_match_count',
+  ]) {
+    const numeric = record[key];
+    if (numeric !== undefined) {
+      const lowerBound = key === 'rpc_status' ? -100_000 : 0;
+      if (typeof numeric !== 'number' || !Number.isSafeInteger(numeric) || numeric < lowerBound)
+        throw new Error('invalid_input');
+      if (numeric <= (key === 'byte_count' ? MAX_DIAGNOSTIC_BYTES : MAX_DIAGNOSTIC_COUNT))
+        output[key] = numeric;
+    }
+  }
+  return output;
+}
+
+/** @param {string} root @param {string} digest @returns {Promise<ObservationConfig>} */
+async function currentConfig(root, digest) {
+  const config = await readConfig(root);
+  if (!config || !config.claudeObservation) throw new Error('observation_disabled');
+  const observation = config.claudeObservation;
+  if (observation.disclosedAt === null) throw new Error('observation_not_disclosed');
+  if (claudeObservationConfigBinding(config) !== digest) throw new Error('state_changed');
+  return /** @type {ObservationConfig} */ (config);
+}
+
+/** @param {DiagnosticsInput} input @param {ObservationConfig} config @param {string} root */
+async function diagnostics(input, config, root) {
+  if (config.claudeObservation?.diagnosticsEnabled !== true)
+    throw new Error('observation_disabled');
+  const records = input.records.map((record) => {
+    if (!object(record)) throw new Error('invalid_input');
+    return {
+      ...diagnosticRecord(record),
+      session_key: String(input.session_key),
+      instance_id: pseudonym(String(input.instance_id)),
+    };
+  });
+  try {
+    const written = await appendRecords(root, 'events', records);
+    return { schema_version: 1, accepted: true, action: 'diagnostics', written };
+  } catch {
+    return { schema_version: 1, accepted: false, error_code: 'logger_failure' };
+  }
+}
+
+/** @param {PreviewInput} input @param {ObservationConfig} config @param {string} root */
+async function preview(input, config, root) {
+  if (config.claudeObservation?.shadowEnabled !== true) throw new Error('observation_disabled');
+  const recentStart = Math.max(0, input.items.length - input.options.preserve_recent_items);
+  const items = input.items.map((item, index) => ({
+    ...item,
+    protected: item.protected || item.kind === 'reference' || index >= recentStart,
+  }));
+  const eligible = items.filter((item) => item.protected !== true);
+  if (eligible.length === 0)
+    return {
+      schema_version: 1,
+      accepted: true,
+      action: 'preview',
+      applied: false,
+      skipped: 'all_recent',
+      decisions: [],
+    };
+  const directory = await ownedDirectory(join(root, 'diagnostics', 'claude'));
+  const lock = join(directory, '.admission.lock');
+  return withLock(lock, async () => {
+    const admissionPath = join(directory, 'preview-admission.json');
+    let last = 0;
+    try {
+      const entry = await ownedFile(admissionPath);
+      if (entry.size > 4096) throw new Error('admission_invalid');
+      const data = JSON.parse(await readFile(admissionPath, 'utf8'));
+      if (
+        data.binding ===
+          hash({
+            endpoint: config.endpoint,
+            token: config.token,
+            disclosedAt: config.claudeObservation.disclosedAt,
+          }) &&
+        Number.isSafeInteger(data.attempted_at)
+      )
+        last = data.attempted_at;
+    } catch (error) {
+      if (error instanceof Error && 'code' in error && error.code === 'ENOENT') last = 0;
+      else throw error;
+    }
+    if (Date.now() - last < ADMISSION_MS) throw new Error('admission_denied');
+    await writeOwnedJson(
+      admissionPath,
+      `${JSON.stringify({ binding: hash({ endpoint: config.endpoint, token: config.token, disclosedAt: config.claudeObservation.disclosedAt }), attempted_at: Date.now() })}\n`,
+    );
+    await chmod(admissionPath, 0o600);
+    const projection = {
+      goal: input.goal,
+      items: items.map((item) => ({
+        id: String(item.id),
+        kind: item.kind,
+        text: item.description ?? `${item.kind} (${item.chars} chars)`,
+        local_chars: item.chars,
+        protected: item.protected,
+        pin_reasons: item.protected ? ['recent'] : [],
+      })),
+    };
+    const request = {
+      schema_version: 2,
+      client: 'claude_code',
+      client_version: String(input.client_version),
+      session_ref: `claude-shadow-${String(input.session_key).slice(0, 32)}`,
+      revision: String(input.revision),
+      observed_at: String(input.observed_at),
+      request_id: String(input.operation_id),
+      policy_version: 'context-recovery-v2',
+      projection,
+      options: input.options,
+    };
+    const commonLog = {
+      schema_version: 1,
+      operation_id: input.operation_id,
+      mode: 'shadow',
+      adapter_version: ADAPTER_VERSION,
+      client_version: input.client_version,
+      observed_at: input.observed_at,
+      session_key: String(input.session_key),
+      instance_id: pseudonym(String(input.instance_id)),
+      item_count: items.length,
+      char_count: items.reduce((total, item) => total + item.chars, 0),
+      applied: false,
+    };
+    await appendRecords(root, 'events', [
+      {
+        ...commonLog,
+        stage: 'provider_request',
+        category: 'request_attempted',
+      },
+    ]).catch(() => undefined);
+    let response;
+    try {
+      response = await selectContextShadow(config.endpoint, config.token, request, 15_000);
+    } catch (error) {
+      const code = safeProviderErrorCode(error);
+      await appendRecords(root, 'events', [
+        {
+          ...commonLog,
+          stage: 'provider_response',
+          category: providerFailureCategory(code),
+        },
+      ]).catch(() => undefined);
+      return {
+        schema_version: 1,
+        accepted: false,
+        action: 'preview',
+        applied: false,
+        error_code: code,
+      };
+    }
+    const expectedProjectionHash = hash(projection);
+    const expectedOptionsHash = hash(input.options);
+    const responseDecisions = Array.isArray(response.decisions)
+      ? /** @type {Record<string, unknown>[]} */ (response.decisions)
+      : [];
+    const createdAt = Date.parse(String(response.created_at));
+    const expiresAt = Date.parse(String(response.expires_at));
+    const responseNow = Date.now();
+    const responseStats = object(response.stats)
+      ? /** @type {Record<string, unknown>} */ (response.stats)
+      : {};
+    /** @param {unknown} value */
+    const count = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+    /** @param {unknown} value */
+    const nullableCount = (value) => value === null || count(value);
+    const statsValid =
+      count(responseStats.selected_count) &&
+      count(responseStats.protected_count) &&
+      count(responseStats.eligible_count) &&
+      count(responseStats.batch_count) &&
+      typeof responseStats.batch_count === 'number' &&
+      responseStats.batch_count <= 4 &&
+      nullableCount(responseStats.provider_input_tokens) &&
+      nullableCount(responseStats.provider_output_tokens);
+    const decisionsValid = responseDecisions.every((decision, index) => {
+      if (!object(decision)) return false;
+      const candidate = /** @type {Record<string, unknown>} */ (decision);
+      const protectedItem = items[index]?.protected === true;
+      const probability = candidate.probability;
+      if (
+        !noControlText(candidate.id, 128) ||
+        typeof candidate.keep !== 'boolean' ||
+        !['protected', 'relevant', 'below_threshold'].includes(String(candidate.reason))
+      )
+        return false;
+      if (protectedItem)
+        return candidate.keep === true && candidate.reason === 'protected' && probability === null;
+      if (
+        candidate.reason === 'protected' ||
+        typeof probability !== 'number' ||
+        !Number.isFinite(probability) ||
+        probability < 0 ||
+        probability > 1
+      )
+        return false;
+      return candidate.keep === probability >= input.options.keep_threshold;
+    });
+    if (
+      response.schema_version !== 2 ||
+      !['planned', 'noop'].includes(String(response.status)) ||
+      response.applied !== false ||
+      response.persisted !== false ||
+      response.request_id !== request.request_id ||
+      response.session_ref !== request.session_ref ||
+      response.revision !== request.revision ||
+      response.projection_hash !== expectedProjectionHash ||
+      response.options_hash !== expectedOptionsHash ||
+      response.policy_version !== request.policy_version ||
+      !Number.isFinite(createdAt) ||
+      !Number.isFinite(expiresAt) ||
+      createdAt > responseNow + 60_000 ||
+      createdAt > expiresAt ||
+      expiresAt <= responseNow ||
+      expiresAt > createdAt + 60_000 ||
+      (response.provider_model !== null &&
+        (typeof response.provider_model !== 'string' || response.provider_model.length > 128)) ||
+      !statsValid ||
+      responseDecisions.length !== items.length ||
+      !decisionsValid
+    ) {
+      await appendRecords(root, 'events', [
+        { ...commonLog, stage: 'provider_response', category: 'invalid_response' },
+      ]).catch(() => undefined);
+      return {
+        schema_version: 1,
+        accepted: false,
+        action: 'preview',
+        applied: false,
+        error_code: 'invalid_response',
+      };
+    }
+    const batchCount = responseStats.batch_count;
+    const providerConfirmed =
+      typeof response.provider_model === 'string' &&
+      response.provider_model.length > 0 &&
+      typeof batchCount === 'number' &&
+      Number.isSafeInteger(batchCount) &&
+      batchCount > 0;
+    const orderedIds = responseDecisions.map((decision) => String(decision.id));
+    if (
+      orderedIds.some((id, index) => id !== items[index]?.id) ||
+      Number(responseStats.protected_count) !== items.filter((item) => item.protected).length ||
+      Number(responseStats.eligible_count) !== items.filter((item) => !item.protected).length ||
+      Number(responseStats.selected_count) !==
+        responseDecisions.filter((decision) => decision.keep === true).length ||
+      (response.status === 'planned') !==
+        responseDecisions.some(
+          (decision, index) => items[index]?.protected !== true && decision.keep === false,
+        )
+    ) {
+      await appendRecords(root, 'events', [
+        { ...commonLog, stage: 'provider_response', category: 'invalid_response' },
+      ]).catch(() => undefined);
+      return {
+        schema_version: 1,
+        accepted: false,
+        action: 'preview',
+        applied: false,
+        error_code: 'invalid_response',
+      };
+    }
+    await appendRecords(root, 'events', [
+      {
+        ...commonLog,
+        stage: 'provider_response',
+        category: providerConfirmed ? 'provider_decision' : 'response_obtained',
+        provider_confirmed: providerConfirmed,
+      },
+    ]).catch(() => undefined);
+    const decisions = responseDecisions.map((decision) => ({
+      id: pseudonym(String(decision.id)),
+      outcome:
+        decision.reason === 'protected'
+          ? 'protected'
+          : decision.keep === true
+            ? 'would_keep'
+            : 'would_omit_result',
+    }));
+    await appendRecords(
+      root,
+      'events',
+      items.map((item, index) => ({
+        schema_version: 1,
+        operation_id: input.operation_id,
+        mode: 'shadow',
+        stage: 'provider_response',
+        category: providerConfirmed ? 'provider_decision' : 'response_obtained',
+        adapter_version: ADAPTER_VERSION,
+        client_version: input.client_version,
+        observed_at: input.observed_at,
+        session_key: String(input.session_key),
+        instance_id: pseudonym(String(input.instance_id)),
+        item_id: pseudonym(String(item.id)),
+        provider_confirmed: providerConfirmed,
+        outcome: decisions[index].outcome,
+        would_keep: decisions[index].outcome === 'would_keep',
+        applied: false,
+        chars: item.chars,
+      })),
+    );
+    return { schema_version: 1, accepted: true, action: 'preview', applied: false, decisions };
+  });
+}
+
+/** @param {string[]} argv @param {string} inputText */
+export async function executeObservation(argv, inputText) {
+  const { stateDir, configDigest } = parseArgs(argv);
+  await assertOwnedDir(stateDir);
+  if (Buffer.byteLength(inputText, 'utf8') > MAX_STDIN_BYTES) throw new Error('input_too_large');
+  const input = validateInput(JSON.parse(inputText));
+  const config = await currentConfig(stateDir, configDigest);
+  return input.action === 'diagnostics'
+    ? diagnostics(input, config, stateDir)
+    : preview(input, config, stateDir);
+}
+
+/** @param {string} stateDir @param {number} tail */
+export async function readDiagnostics(stateDir, tail = 20) {
+  const root = await assertOwnedDir(stateDir);
+  let directory;
+  try {
+    directory = await ownedDirectory(join(root, 'diagnostics', 'claude'), false);
+  } catch (error) {
+    if (
+      (error instanceof Error && 'code' in error && error.code === 'ENOENT') ||
+      (error instanceof Error && error.message === 'diagnostics_path_missing')
+    )
+      return [];
+    throw error;
+  }
+  const files = (await readdir(directory))
+    .filter((file) => /^events\.[012]\.jsonl$/u.test(file))
+    .sort((left, right) => Number(right[7]) - Number(left[7]));
+  const records = [];
+  for (const file of files) {
+    const path = join(directory, file);
+    await ownedFile(path);
+    const lines = (await readFile(path, 'utf8')).split('\n').filter(Boolean);
+    for (const line of lines) {
+      try {
+        const record = JSON.parse(line);
+        if (object(record) && isSafeLogRecord(record)) records.push(record);
+      } catch {
+        // Ignore only malformed owned lines; never surface their contents.
+      }
+    }
+  }
+  return records.slice(-Math.max(1, Math.min(100, tail)));
+}
+
+async function main() {
+  let input = '';
+  for await (const chunk of process.stdin) {
+    input += String(chunk);
+    if (Buffer.byteLength(input, 'utf8') > MAX_STDIN_BYTES) throw new Error('input_too_large');
+  }
+  const result = await executeObservation(process.argv.slice(2), input);
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname)) {
+  main().catch((error) => {
+    const code =
+      error instanceof Error && SAFE_ERROR_CODES.has(error.message)
+        ? error.message
+        : 'helper_failed';
+    process.stdout.write(
+      `${JSON.stringify({ schema_version: 1, accepted: false, error_code: code })}\n`,
+    );
+    process.exitCode = 1;
+  });
+}