@brunobracaioli/aibrain 0.3.0-beta.15 → 0.3.0-beta.16

package/README.md

@@ -2,6 +2,13 @@
 
 Assisted AI Brain context beta client for Linux/WSL with Node.js 22 or newer.
 
+Codex capture also requires the `flock` utility from `util-linux`, normally
+included in Linux/WSL. The launcher and doctor check availability before a
+monitored Codex session starts. Capture coordination is released by the kernel
+after a process exits unexpectedly. An unidentifiable empty lock left by an
+older client requires a verified support migration; do not delete checkpoints,
+notes or lock files to work around a reported storage error.
+
 The reviewed native compatibility set is Claude Code 2.1.294, 2.1.295, 2.1.296,
 2.1.299, 2.1.300, 2.1.301, 2.1.302 or 2.1.303, and Codex CLI 0.161.0,
 0.162.0, 0.162.1 or 0.163.0. A newer stable Codex 0.x release may continue only

package/dist/assets/claude/hooks/context-compaction.ts

@@ -150,7 +150,7 @@ type Register = (
 ) => void;
 
 const MAX_RESULT_BYTES = 256 * 1024;
-const CLAUDE_HOOK_VERSION = '0.3.0-beta.13';
+const CLAUDE_HOOK_VERSION = '0.3.0-beta.16';
 const MAX_DIAGNOSTIC_BYTE_COUNT = 128 * 1024 * 1024;
 const COOLDOWN_MS = 60_000;
 const MAX_TRUNCATED_CODE_POINTS = 300;
@@ -974,6 +974,7 @@ type ObservationRecord = {
     | 'compact_entry'
     | 'compact_exit'
     | 'native_summary_proof'
+    | 'native_fallback_proof'
     | 'native_error';
   readonly category:
     | 'observed'
@@ -1790,6 +1791,37 @@ async function flushProofDiagnostic(
   ]);
 }
 
+async function flushNativeFallbackProofDiagnostic(
+  api: HookApi,
+  options: ObservationOptions,
+  operationId: string,
+  sessionId: string,
+  instanceId: string,
+  clientVersion: string,
+  fields: Pick<
+    ObservationRecord,
+    | 'proof_expected_count'
+    | 'proof_actual_count'
+    | 'proof_match'
+    | 'proof_match_offset'
+    | 'proof_view_source'
+    | 'proof_api_view_match'
+    | 'proof_api_count'
+  >,
+): Promise<void> {
+  if (!options.diagnosticsEnabled) return;
+  await flushObservationDiagnostics(api, options, operationId, sessionId, instanceId, [
+    observationRecord(
+      operationId,
+      'native_fallback_proof',
+      'observed',
+      clientVersion,
+      undefined,
+      fields,
+    ),
+  ]);
+}
+
 async function flushNativeSummaryProofDiagnostic(
   api: HookApi,
   options: ObservationOptions,
@@ -3590,6 +3622,8 @@ type PendingFallbackProof = {
   readonly expected_hash?: string;
   readonly expected_count?: number;
   readonly expected_message_hashes?: readonly string[];
+  readonly delivery_mode?: 'atomic_marker';
+  readonly marker_digest?: string;
   readonly anchor_counts?: readonly number[];
   readonly anchor_hashes?: readonly string[];
   readonly expires_at: string;
@@ -4131,6 +4165,8 @@ function structurallyValidPendingProof(value: unknown): value is PendingProof {
           'expected_hash',
           'expected_count',
           'expected_message_hashes',
+          'delivery_mode',
+          'marker_digest',
           'anchor_counts',
           'anchor_hashes',
           'expires_at',
@@ -4161,6 +4197,10 @@ function structurallyValidPendingProof(value: unknown): value is PendingProof {
           value.expected_message_hashes.every(
             (hash): hash is string => typeof hash === 'string' && /^[a-f0-9]{16}$/u.test(hash),
           ))) &&
+      (value.delivery_mode === undefined || value.delivery_mode === 'atomic_marker') &&
+      (value.marker_digest === undefined || /^[a-f0-9]{64}$/u.test(String(value.marker_digest))) &&
+      ((value.delivery_mode === undefined && value.marker_digest === undefined) ||
+        (value.delivery_mode === 'atomic_marker' && typeof value.marker_digest === 'string')) &&
       ((value.anchor_counts === undefined && value.anchor_hashes === undefined) ||
         (Array.isArray(value.anchor_counts) &&
           Array.isArray(value.anchor_hashes) &&
@@ -4803,6 +4843,26 @@ function getTelemetry(
   return state.current;
 }
 
+async function nativeFallbackMarker(
+  operationId: string,
+  sessionRef: string,
+  baselineHash: string,
+): Promise<{ readonly text: string; readonly digest: string }> {
+  const digest = await sha256(
+    `aibrain-native-fallback-v1|${operationId}|${sessionRef}|${baselineHash}`,
+  );
+  return { digest, text: `[AI Brain native fallback receipt v1:${digest}]` };
+}
+
+function nativeFallbackDeliveryResult(nativeResult: unknown, marker: string): unknown {
+  const messages = nativeResultMessages(nativeResult);
+  if (messages === undefined || messages.length === 0) return nativeResult;
+  return {
+    ...(nativeResult as Record<string, unknown>),
+    messages: [...messages, { role: 'user', text: marker, toolUses: [] }],
+  };
+}
+
 async function queueNativeFallbackProof(
   api: HookApi,
   runtime: ProofRuntimeState,
@@ -4813,7 +4873,7 @@ async function queueNativeFallbackProof(
   nativeResult: unknown,
   beforeVisibleMessages: readonly string[] | undefined,
   activeOffset: number | undefined,
-): Promise<void> {
+): Promise<unknown> {
   const expectedMessages = nativeResultMessages(nativeResult);
   const expectedHash =
     expectedMessages === undefined
@@ -4831,6 +4891,10 @@ async function queueNativeFallbackProof(
     beforeVisibleMessages === undefined || expectedMessages === undefined
       ? undefined
       : await nativeProofAnchors(beforeVisibleMessages, expectedMessages.length, activeOffset);
+  const marker =
+    expectedMessages === undefined
+      ? undefined
+      : await nativeFallbackMarker(operationId, sessionRef, baselineHash);
   const proof: PendingFallbackProof = {
     schema_version: 1,
     kind: 'native_fallback',
@@ -4844,6 +4908,9 @@ async function queueNativeFallbackProof(
     ...(expectedMessageHashes === undefined
       ? {}
       : { expected_message_hashes: expectedMessageHashes }),
+    ...(marker === undefined
+      ? {}
+      : { delivery_mode: 'atomic_marker' as const, marker_digest: marker.digest }),
     ...(anchors === undefined
       ? {}
       : { anchor_counts: anchors.counts, anchor_hashes: anchors.hashes }),
@@ -4854,6 +4921,9 @@ async function queueNativeFallbackProof(
   };
   runtime.pendingProofMemory = proof;
   runtime.pendingProofPersistenceFailed = !(await savePendingProof(api, proof));
+  return runtime.pendingProofPersistenceFailed || marker === undefined
+    ? nativeResult
+    : nativeFallbackDeliveryResult(nativeResult, marker.text);
 }
 
 async function confirmPendingProof(
@@ -4937,38 +5007,83 @@ async function confirmPendingProof(
       proof_actual_count: messages.length,
     };
     if (proof.expected_hash !== undefined && expectedCount !== undefined) {
-      fallbackMatch = await nativeSummaryViewMatch(
-        messages,
-        expectedCount,
-        proof.expected_hash,
-        proof.expected_message_hashes,
-        proof.anchor_counts,
-        proof.anchor_hashes,
-      );
-      const fallbackOffset =
-        fallbackMatch === 'active_suffix'
-          ? await nativeSummaryMatchedOffset(
-              messages,
-              expectedCount,
-              proof.expected_hash,
-              proof.expected_message_hashes,
-              proof.anchor_counts,
-              proof.anchor_hashes,
-            )
-          : undefined;
-      fallbackProofFields = {
-        ...fallbackProofFields,
-        proof_match: fallbackMatch,
-        ...(fallbackMatch === 'exact' ? { proof_match_offset: 0 } : {}),
-        ...(fallbackOffset === undefined ? {} : { proof_match_offset: fallbackOffset }),
-      };
-      verified = fallbackMatch === 'exact' || fallbackMatch === 'active_suffix';
+      if (proof.delivery_mode === 'atomic_marker' && proof.marker_digest !== undefined) {
+        try {
+          const apiView = await boundedApiMessages(api);
+          const marker = await nativeFallbackMarker(
+            proof.operation_id,
+            sessionRef,
+            proof.baseline_hash,
+          );
+          const markerValid = marker.digest === proof.marker_digest;
+          const markerCount = exactTextCount(apiView, marker.text);
+          fallbackProofFields = {
+            ...fallbackProofFields,
+            proof_view_source: 'api',
+            proof_api_view_match: markerValid && markerCount === 1 ? 'exact' : 'mismatch',
+            proof_api_count: apiView.length,
+          };
+          if (markerValid && markerCount === 1) {
+            fallbackMatch = 'exact';
+            fallbackProofFields = {
+              ...fallbackProofFields,
+              proof_match: 'exact',
+              proof_match_offset: 0,
+            };
+            verified = true;
+          }
+        } catch {
+          fallbackProofFields = {
+            ...fallbackProofFields,
+            proof_view_source: 'api',
+            proof_api_view_match: 'unavailable',
+          };
+        }
+      } else {
+        // Compatibility with proofs written by beta15 and earlier. These
+        // proofs predate the API-view fingerprint and retain the old strict
+        // default-view check.
+        fallbackMatch = await nativeSummaryViewMatch(
+          messages,
+          expectedCount,
+          proof.expected_hash,
+          proof.expected_message_hashes,
+          proof.anchor_counts,
+          proof.anchor_hashes,
+        );
+        const fallbackOffset =
+          fallbackMatch === 'active_suffix'
+            ? await nativeSummaryMatchedOffset(
+                messages,
+                expectedCount,
+                proof.expected_hash,
+                proof.expected_message_hashes,
+                proof.anchor_counts,
+                proof.anchor_hashes,
+              )
+            : undefined;
+        fallbackProofFields = {
+          ...fallbackProofFields,
+          proof_view_source: 'default',
+          proof_match: fallbackMatch,
+          ...(fallbackMatch === 'exact' ? { proof_match_offset: 0 } : {}),
+          ...(fallbackOffset === undefined ? {} : { proof_match_offset: fallbackOffset }),
+        };
+        verified = fallbackMatch === 'exact' || fallbackMatch === 'active_suffix';
+      }
     }
   }
   if (runtime.pendingProofPersistenceFailed) verified = false;
   const telemetry = getTelemetry(api, runtime.brainServer, runtime.options, runtime.telemetryState);
   if (!verified) {
-    if (deferMismatch) return;
+    // Only the atomic native fallback marker may wait for the host's active
+    // API view. A prepared JEV capsule remains strict at every callback.
+    if (
+      deferMismatch &&
+      proof.kind === 'native_fallback' &&
+      proof.delivery_mode === 'atomic_marker'
+    )
+      return;
     runtime.pendingProofMemory = undefined;
     runtime.pendingProofPersistenceFailed = false;
     await clearPendingProof(api, sessionRef);
@@ -4993,6 +5108,16 @@ async function confirmPendingProof(
   runtime.pendingProofMemory = undefined;
   runtime.pendingProofPersistenceFailed = false;
   await clearPendingProof(api, sessionRef);
+  if (proof.kind === 'native_fallback')
+    await flushNativeFallbackProofDiagnostic(
+      api,
+      runtime.observation,
+      proof.operation_id,
+      sessionRef,
+      runtime.observationInstanceId,
+      nativeClientVersion(runtime.options),
+      fallbackProofFields,
+    );
   if (proof.kind === 'custom') {
     const dropped = proof.pairs.filter((pair) => pair.action === 'drop_pair').length;
     const reduced = proof.pairs.filter((pair) => pair.action === 'truncate_result').length;
@@ -5579,7 +5704,10 @@ export const register: Register = (on, options) => {
 
   on('prompt.submit', async (api, rawEvent, next) => {
     const event = rawEvent as unknown as PromptSubmitHookEvent;
-    await confirmPendingProof(api, proofRuntime, true);
+    // The host has completed the prior native turn before accepting a new
+    // prompt. This is the final proof opportunity for a fallback whose first
+    // turn.complete callback observed the retired/default view.
+    await confirmPendingProof(api, proofRuntime);
     if (
       proofRuntime.compactionStrategy === 'native_summary_notes' &&
       enabled &&
@@ -5654,7 +5782,10 @@ export const register: Register = (on, options) => {
   });
 
   on('turn.complete', async (api, event, next) => {
-    await confirmPendingProof(api, proofRuntime);
+    // The native host can publish the result before its active API view catches
+    // up. Keep only the atomic fallback marker pending through this lifecycle
+    // edge; prompt.submit performs the strict confirmation on the next turn.
+    await confirmPendingProof(api, proofRuntime, true);
     if (
       proofRuntime.compactionStrategy === 'native_summary_notes' &&
       enabled &&
@@ -5826,7 +5957,7 @@ export const register: Register = (on, options) => {
       nativeContinuationStarted = true;
       const nativeResult = await next(event);
       if (fallbackCapture !== undefined)
-        await queueNativeFallbackProof(
+        return queueNativeFallbackProof(
           api,
           proofRuntime,
           fallbackCapture.operationId,

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

@@ -2,15 +2,18 @@
 
 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';
@@ -21,6 +24,7 @@ import { preflightSelectionState } from './context-selection-fitting.mjs';
 
 const captureFs = {
   chmod,
+  hardlink,
   lstat,
   mkdir,
   open,
@@ -116,6 +120,10 @@ const DIAGNOSTIC_REASONS = new Set([
   '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',
@@ -613,7 +621,12 @@ async function ensurePrivateDirectory(directory, fsOps = captureFs) {
 }
 async function assertPrivateFile(file, label, fsOps = captureFs) {
   const info = await fsOps.lstat(file);
-  if (info.isSymbolicLink() || !info.isFile() || (info.mode & 0o077) !== 0)
+  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;
 }
@@ -844,16 +857,250 @@ async function readCaptureDirectoryState(directory, fsOps = captureFs) {
   return state;
 }
 
-async function withCaptureStoreLock(
-  directory,
-  task,
-  fsOps = captureFs,
-  {
-    now = Date.now,
-    sleep = (milliseconds) =>
-      new Promise((resolvePromise) => setTimeout(resolvePromise, milliseconds)),
-  } = {},
-) {
+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';
+
+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) {
@@ -870,12 +1117,29 @@ async function withCaptureStoreLock(
       if (handle) throw error;
       if (error?.code !== 'EEXIST') throw error;
       if (now() - started >= CAPTURE_LOCK_WAIT_MS)
-        throw captureCapacityError({ totalBytes: 0, managedFiles: [] });
+        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);
+  if (nativeFs) return withAdvisoryCaptureLock(directory, task);
+  return withInjectedCaptureLock(directory, task, fsOps, { now, sleep });
+}
+
 async function writePrivateFile(file, serialized, fsOps = captureFs) {
   const directory = await ensurePrivateDirectory(dirname(file), fsOps);
   const target = resolve(
@@ -1324,6 +1588,14 @@ export async function __testWriteBoundedCapture(
   validateCaptureSnapshot(value, value.sourceRevision);
   return writeBoundedCapture(file, serialized, value, fs, { now, sleep });
 }
+
+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');
   const directory = await ensurePrivateDirectory(dirname(file));

package/dist/claude-observation.mjs

@@ -16,7 +16,7 @@ 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';
+export const ADAPTER_VERSION = '0.3.0-beta.16';
 const MAX_DIAGNOSTIC_COUNT = 10_000_000;
 const MAX_DIAGNOSTIC_BYTES = 128 * 1024 * 1024;
 const CHECKPOINT_BACKENDS = new Set(['native_store', 'private_file']);
@@ -136,6 +136,7 @@ const DIAGNOSTIC_STAGES = new Set([
   'compact_entry',
   'compact_exit',
   'native_summary_proof',
+  'native_fallback_proof',
   'native_error',
 ]);
 const DIAGNOSTIC_CATEGORIES = new Set([

package/dist/cli.mjs

@@ -15,7 +15,12 @@ import {
   stateRoot,
   tokenDigest,
 } from './state.mjs';
-import { nativeVersion, platformCheck, resolveNative } from './platform.mjs';
+import {
+  captureLockPlatformCheck,
+  nativeVersion,
+  platformCheck,
+  resolveNative,
+} from './platform.mjs';
 import { launchClaude, launchCodex } from './launch.mjs';
 import { claudeCompatibilityError, resolveClaudeCompatibility } from './claude-compatibility.mjs';
 import { codexCompatibilityError, resolveCodexCompatibility } from './codex-compatibility.mjs';
@@ -24,7 +29,7 @@ import { codexPolicyJson, makePolicy, publicPolicy, isProfile } from './policy.m
 import { readDiagnostics } from './claude-observation.mjs';
 import { readCodexDiagnostics } from './codex-diagnostics.mjs';
 
-const VERSION = '0.3.0-beta.15';
+const VERSION = '0.3.0-beta.16';
 const ENDPOINT = 'https://mcp.ai-brain.aisac.cloud/mcp';
 const PACKAGE_ROOT = dirname(fileURLToPath(import.meta.url));
 const LEGACY_DISCLOSURE_VERSION = 'aibrain-paid-context-v1-2026-10-09';
@@ -531,6 +536,7 @@ async function doctor(json) {
   };
   const needsClaude = config?.clientSelection === 'claude' || config?.clientSelection === 'both';
   const needsCodex = config?.clientSelection === 'codex' || config?.clientSelection === 'both';
+  const captureLockPlatform = needsCodex ? captureLockPlatformCheck() : null;
   const nativeReady =
     (!needsClaude ||
       (native.claude !== null &&
@@ -539,6 +545,7 @@ async function doctor(json) {
     (!needsCodex ||
       (native.codex !== null &&
         native.node !== null &&
+        captureLockPlatform?.ok === true &&
         (codexCompatibility?.status === 'qualified' ||
           codexCompatibility?.status === 'protocol_match')));
   const result = {
@@ -560,6 +567,10 @@ async function doctor(json) {
     codexCompatibility: codexCompatibility?.status ?? 'unavailable',
     codexCompatibilityReason: codexCompatibility?.reason ?? 'codex_not_found',
     codexCompatibilityVersion: codexCompatibility?.version ?? null,
+    captureLockBackend:
+      captureLockPlatform?.ok === true
+        ? 'available'
+        : (captureLockPlatform?.code ?? 'not_required'),
     nativeReady,
     context: publicPolicy(policy),
     telemetry: {

package/dist/codex-diagnostics.mjs

@@ -85,6 +85,10 @@ const REASONS = new Set([
   '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',

package/dist/launch.mjs

@@ -4,7 +4,7 @@ import { access, chmod, lstat, mkdir, mkdtemp, open, rm, writeFile } from 'node:
 import { spawn } from 'node:child_process';
 import { constants } from 'node:fs';
 import { isAbsolute, join, resolve, sep } from 'node:path';
-import { nativeVersion, resolveNative } from './platform.mjs';
+import { captureLockPlatformCheck, nativeVersion, resolveNative } from './platform.mjs';
 import { claudeCompatibilityError, resolveClaudeCompatibility } from './claude-compatibility.mjs';
 import { codexCompatibilityError, resolveCodexCompatibility } from './codex-compatibility.mjs';
 import {
@@ -565,6 +565,8 @@ export async function launchClaude(config, root, args) {
 export async function launchCodex(config, root, args) {
   const validated = assertConfig(config);
   assertCodexArgs(args);
+  const captureLockPlatform = captureLockPlatformCheck();
+  if (!captureLockPlatform.ok) throw new Error(captureLockPlatform.code);
   const executable = resolveNative('codex');
   const node = resolveNative('node');
   if (!executable || !node) throw new Error('codex_or_node_not_found');

package/dist/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@brunobracaioli/aibrain",
-  "version": "0.3.0-beta.15",
+  "version": "0.3.0-beta.16",
   "type": "module"
 }

package/dist/platform.mjs

@@ -23,6 +23,19 @@ export function platformCheck() {
   return { ok: true };
 }
 
+/** @param {NodeJS.ProcessEnv} [environment] */
+export function captureLockPlatformCheck(environment = process.env) {
+  const platform = platformCheck();
+  if (!platform.ok) return platform;
+  if (resolveNative('flock', environment) === null)
+    return {
+      ok: false,
+      code: 'CODEX_CAPTURE_LOCK_BACKEND_UNAVAILABLE',
+      message: 'Codex capture requires util-linux flock on Linux/WSL.',
+    };
+  return { ok: true };
+}
+
 /** @param {string} name @param {NodeJS.ProcessEnv} [environment] */
 export function resolveNative(name, environment = process.env) {
   if (!/^[A-Za-z0-9._+-]+$/u.test(name)) return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunobracaioli/aibrain",
-  "version": "0.3.0-beta.15",
+  "version": "0.3.0-beta.16",
   "private": false,
   "description": "AI Brain assisted context beta client for Claude Code and Codex",
   "license": "UNLICENSED",