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

package/dist/claude-compatibility.mjs

@@ -0,0 +1,506 @@
+// @ts-check
+
+import {
+  chmod,
+  cp,
+  lstat,
+  mkdir,
+  mkdtemp,
+  readdir,
+  realpath,
+  rm,
+  writeFile,
+} from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { spawn } from 'node:child_process';
+
+const MAX_OUTPUT_BYTES = 96 * 1024;
+const PROBE_TIMEOUT_MS = 30_000;
+const MAX_PLUGIN_ASSET_BYTES = 4 * 1024 * 1024;
+const MAX_PLUGIN_TOTAL_BYTES = 16 * 1024 * 1024;
+const HOST_MAJOR = 2;
+const HOST_MINOR = 1;
+const QUALIFIED_VERSIONS = new Set([
+  '2.1.294',
+  '2.1.295',
+  '2.1.296',
+  '2.1.299',
+  '2.1.300',
+  '2.1.301',
+  '2.1.302',
+  '2.1.303',
+]);
+const REQUIRED_FLAGS = ['--settings', '--mcp-config', '--allowedTools', '--plugin-dir'];
+const REQUIRED_INVENTORY = [
+  'prompt.submit',
+  'tool.call',
+  'session.end',
+  'turn.complete',
+  'session.compact',
+  '$.mcp.call',
+  '$.process.run',
+  '$.session.id',
+  '$.session.messages',
+  '$.session.usage',
+  '$.session.append',
+  '$.session.compact',
+  '$.store.get',
+  '$.store.set',
+  '$.store.delete',
+  '$.store.keys',
+  '$.ui.log',
+  '$.ui.toast',
+];
+const ALLOWED_PLUGIN_FILES = Object.freeze([
+  '.claude-plugin/plugin.json',
+  'hooks/hooks.json',
+  'hooks/context-compaction.ts',
+  'hooks/provider-window.js',
+  'hooks/state-fitting.mjs',
+  'hooks/state-fitting.d.mts',
+  'hooks/native-host-contract.test.ts',
+  'hooks/native-host-contract-runtime.ts',
+]);
+
+/** @param {string} executable */
+function safePath(executable) {
+  return [...new Set([dirname(executable), dirname(process.execPath), '/usr/bin', '/bin'])].join(
+    ':',
+  );
+}
+
+/** @param {string} executable @returns {Promise<string>} */
+async function readNativeVersion(executable) {
+  const root = await mkdtemp(join(tmpdir(), 'aibrain-claude-version-'));
+  const cwd = join(root, 'cwd');
+  const home = join(root, 'home');
+  const config = join(root, 'config');
+  await mkdir(cwd, { recursive: true, mode: 0o700 });
+  try {
+    /** @type {NodeJS.ProcessEnv} */
+    const environment = {
+      PATH: safePath(executable),
+      HOME: home,
+      CLAUDE_CONFIG_DIR: config,
+      CLAUDE_COMPAT_CWD: cwd,
+      NO_COLOR: '1',
+      CI: '1',
+      CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1',
+    };
+    await mkdir(home, { recursive: true, mode: 0o700 });
+    await mkdir(config, { recursive: true, mode: 0o700 });
+    const result = await runBounded(executable, ['--version'], environment, {
+      timeoutMs: 10_000,
+      maxOutputBytes: 2_048,
+    });
+    if (result.code !== 0 || result.overflow || result.timedOut) return '';
+    return result.stdout.split(/\r?\n/u, 1)[0]?.trim() ?? '';
+  } finally {
+    try {
+      await rm(root, { recursive: true, force: true });
+    } catch {
+      throw new Error('probe_cleanup_failed');
+    }
+  }
+}
+
+/** @typedef {'qualified'|'host_checked'|'rejected'} ClaudeCompatibilityStatus */
+
+/** @typedef {object} ClaudeCompatibility
+ * @property {ClaudeCompatibilityStatus} status
+ * @property {string|null} executable
+ * @property {string|null} version
+ * @property {string} reason
+ * @property {string[]} [checks]
+ */
+
+/** @param {string} output */
+export function parseClaudeStableVersion(output) {
+  const match = output
+    .trim()
+    .match(
+      /^(?:(?:claude(?:\s+code)?)\s+)?(0|[1-9]\d{0,2})\.(0|[1-9]\d{0,2})\.(0|[1-9]\d{0,2})(-[A-Za-z0-9.-]+)?(?:\s+\(Claude\s+Code\))?$/iu,
+    );
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] !== undefined,
+    text: `${match[1]}.${match[2]}.${match[3]}`,
+  };
+}
+
+/** @param {string} output */
+function parseVersion(output) {
+  return parseClaudeStableVersion(output) ?? null;
+}
+
+/** @param {string} executable @param {string[]} args @param {NodeJS.ProcessEnv} environment @param {{timeoutMs?:number,maxOutputBytes?:number}} [limits] */
+function runBounded(executable, args, environment, limits = {}) {
+  const timeoutMs = limits.timeoutMs ?? PROBE_TIMEOUT_MS;
+  const maxOutputBytes = limits.maxOutputBytes ?? MAX_OUTPUT_BYTES;
+  return new Promise((resolvePromise) => {
+    const child = spawn(executable, args, {
+      cwd: environment.CLAUDE_COMPAT_CWD,
+      env: environment,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: process.platform !== 'win32',
+    });
+    let stdout = '';
+    let stderr = '';
+    let bytes = 0;
+    let overflow = false;
+    let settled = false;
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      if (process.platform !== 'win32' && child.pid !== undefined) {
+        try {
+          process.kill(-child.pid, 'SIGKILL');
+        } catch {
+          child.kill('SIGKILL');
+        }
+      } else child.kill('SIGKILL');
+    }, timeoutMs);
+    /** @param {string} target @param {Buffer} chunk */
+    const append = (target, chunk) => {
+      bytes += chunk.byteLength;
+      if (bytes > maxOutputBytes) {
+        overflow = true;
+        return target;
+      }
+      return `${target}${chunk.toString('utf8')}`;
+    };
+    /** @param {number|null} code */
+    const finish = (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolvePromise({ code, stdout, stderr, overflow, timedOut });
+    };
+    child.stdout.on('data', (chunk) => {
+      stdout = append(stdout, chunk);
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr = append(stderr, chunk);
+    });
+    child.once('error', () => finish(null));
+    child.once('close', (code) => finish(code));
+  });
+}
+
+/** @param {string} root @param {string} relativePath */
+async function assertNoSymlinkPath(root, relativePath) {
+  let current = resolve(root);
+  const parts = relativePath.split('/');
+  for (const part of parts) {
+    current = join(current, part);
+    const info = await lstat(current);
+    if (info.isSymbolicLink()) throw new Error('plugin_asset_symlink_rejected');
+  }
+}
+
+/** @param {string} source @param {string} destination */
+async function copyAllowlistedPlugin(source, destination) {
+  await mkdir(destination, { recursive: true, mode: 0o700 });
+  let totalBytes = 0;
+  for (const file of ALLOWED_PLUGIN_FILES) {
+    const input = join(source, file);
+    await assertNoSymlinkPath(source, file);
+    const info = await lstat(input);
+    if (!info.isFile() || info.isSymbolicLink()) throw new Error('plugin_asset_invalid');
+    const uid = process.getuid?.();
+    if (uid !== undefined && info.uid !== uid) throw new Error('plugin_asset_owner_mismatch');
+    if (info.size > MAX_PLUGIN_ASSET_BYTES) throw new Error('plugin_asset_too_large');
+    totalBytes += info.size;
+    if (totalBytes > MAX_PLUGIN_TOTAL_BYTES) throw new Error('plugin_assets_too_large');
+    const output = join(destination, file);
+    await mkdir(dirname(output), { recursive: true, mode: 0o700 });
+    await cp(input, output, { force: true, errorOnExist: true, verbatimSymlinks: true });
+    await chmod(output, 0o600);
+  }
+}
+
+/** @param {string} directory */
+async function assertEmptyDirectory(directory) {
+  const entries = await readdir(directory);
+  if (entries.length !== 0) throw new Error('probe_directory_not_empty');
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function record(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** @param {unknown} value @returns {value is string[]} */
+function stringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+
+/** @param {string} executable @param {string} pluginRoot @param {{timeoutMs?:number,maxOutputBytes?:number}} [limits] */
+async function runHostProbe(executable, pluginRoot, limits = {}) {
+  const root = await mkdtemp(join(tmpdir(), 'aibrain-claude-host-'));
+  const home = join(root, 'home');
+  const config = join(root, 'config');
+  const cwd = join(root, 'cwd');
+  const copiedPlugin = join(root, 'plugin');
+  const contractPlugin = join(root, 'contract-plugin');
+  await Promise.all([
+    mkdir(home, { recursive: true, mode: 0o700 }),
+    mkdir(config, { recursive: true, mode: 0o700 }),
+    mkdir(cwd, { recursive: true, mode: 0o700 }),
+  ]);
+  try {
+    await copyAllowlistedPlugin(pluginRoot, copiedPlugin);
+    await copyAllowlistedPlugin(pluginRoot, contractPlugin);
+    await writeFile(
+      join(contractPlugin, 'hooks', 'hooks.json'),
+      JSON.stringify({ modules: ['./native-host-contract-runtime.ts'] }),
+      { mode: 0o600 },
+    );
+    /** @type {NodeJS.ProcessEnv} */
+    const environment = {
+      PATH: safePath(executable),
+      HOME: home,
+      CLAUDE_CONFIG_DIR: config,
+      CLAUDE_COMPAT_CWD: cwd,
+      CLAUDE_CODE_ENABLE_FUNCTION_HOOKS: '1',
+      AIBRAIN_NATIVE_CONTRACT: '1',
+      CLAUDE_CODE_DISABLE_AUTO_MEMORY: '1',
+      CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1',
+      NO_COLOR: '1',
+      CI: '1',
+    };
+    const help = await runBounded(executable, ['--help'], environment, limits);
+    if (
+      help.code !== 0 ||
+      help.overflow ||
+      REQUIRED_FLAGS.some((flag) => !help.stdout.includes(flag))
+    )
+      return { ok: false, reason: 'launch_flags_missing' };
+    const validate = await runBounded(
+      executable,
+      ['plugin', 'validate', '--strict', '--json', copiedPlugin],
+      environment,
+      limits,
+    );
+    if (validate.code !== 0 || validate.overflow)
+      return { ok: false, reason: 'plugin_validation_failed' };
+    /** @type {Record<string, unknown>} */
+    let report;
+    try {
+      const parsed = JSON.parse(validate.stdout);
+      if (!record(parsed)) return { ok: false, reason: 'plugin_validation_malformed' };
+      report = parsed;
+    } catch {
+      return { ok: false, reason: 'plugin_validation_malformed' };
+    }
+    if (report.success !== true || report.strict !== true)
+      return { ok: false, reason: 'plugin_validation_failed' };
+    if (
+      !record(report.manifest) ||
+      !stringArray(report.manifest.errors) ||
+      !stringArray(report.manifest.warnings)
+    )
+      return { ok: false, reason: 'plugin_validation_malformed' };
+    if (
+      !Array.isArray(report.contents) ||
+      report.contents.length !== 1 ||
+      !report.contents.every(record)
+    )
+      return { ok: false, reason: 'plugin_validation_malformed' };
+    const contents = report.contents;
+    if (
+      !contents.every(
+        (item) => stringArray(item.errors) && stringArray(item.warnings) && stringArray(item.notes),
+      )
+    )
+      return { ok: false, reason: 'plugin_validation_malformed' };
+    const manifest = report.manifest;
+    const errors = [
+      ...(Array.isArray(manifest.errors) ? manifest.errors : []),
+      ...(Array.isArray(manifest.warnings) ? manifest.warnings : []),
+      ...contents.flatMap((item) => [
+        ...(Array.isArray(item.errors) ? item.errors : []),
+        ...(Array.isArray(item.warnings) ? item.warnings : []),
+      ]),
+    ];
+    if (errors.length > 0) return { ok: false, reason: 'plugin_validation_failed' };
+    const notes = contents.flatMap((item) => item.notes);
+    const hookNote = notes.find((note) => typeof note === 'string' && note.includes(' hooks: '));
+    const callNote = notes.find((note) => typeof note === 'string' && note.includes(' calls: '));
+    const hooks = new Set(
+      typeof hookNote === 'string'
+        ? hookNote
+            .split(' hooks: ', 2)[1]
+            .split(', ')
+            .map((item) => item.trim())
+        : [],
+    );
+    const calls = new Set(
+      typeof callNote === 'string'
+        ? callNote
+            .split(' calls: ', 2)[1]
+            .replace(/\s+\(via[^)]*\)/gu, '')
+            .split(', ')
+            .map((item) => item.trim())
+        : [],
+    );
+    const inventory = new Set([...hooks, ...calls]);
+    if (inventory.size === 0 || REQUIRED_INVENTORY.some((item) => !inventory.has(item)))
+      return { ok: false, reason: 'host_inventory_incomplete' };
+    const test = await runBounded(
+      executable,
+      ['plugin', 'test', contractPlugin],
+      environment,
+      limits,
+    );
+    const passMatch = (test.stdout + test.stderr).match(/(?:^|\s)(\d+)\s+pass(?:ed)?(?:\s|$)/iu);
+    const failMatch = (test.stdout + test.stderr).match(/(?:^|\s)(\d+)\s+fail(?:ed)?(?:\s|$)/iu);
+    if (test.timedOut) return { ok: false, reason: 'native_plugin_tests_failed' };
+    if (test.code !== 0) return { ok: false, reason: 'native_plugin_tests_failed' };
+    if (test.overflow) return { ok: false, reason: 'native_plugin_tests_failed' };
+    if (passMatch === null || Number(passMatch[1]) < 1)
+      return { ok: false, reason: 'native_plugin_tests_failed' };
+    if (failMatch === null || Number(failMatch[1]) !== 0)
+      return { ok: false, reason: 'native_plugin_tests_failed' };
+    if (
+      !test.stdout.includes(
+        'AI Brain enabled host contract invokes usage and native compaction through the dispatcher',
+      )
+    )
+      return { ok: false, reason: 'native_plugin_tests_failed' };
+    await assertEmptyDirectory(cwd);
+    return {
+      ok: true,
+      checks: [
+        'launch_flags',
+        'plugin_validate_strict',
+        'native_plugin_test',
+        'isolated_filesystem',
+      ],
+    };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : '';
+    const allowedReasons = new Set([
+      'plugin_asset_invalid',
+      'plugin_asset_symlink_rejected',
+      'plugin_asset_owner_mismatch',
+      'plugin_asset_too_large',
+      'plugin_assets_too_large',
+      'probe_directory_not_empty',
+    ]);
+    return { ok: false, reason: allowedReasons.has(reason) ? reason : 'host_probe_failed' };
+  } finally {
+    try {
+      await rm(root, { recursive: true, force: true });
+    } catch {
+      throw new Error('probe_cleanup_failed');
+    }
+  }
+}
+
+/** @param {string} executable @param {string} packageRoot */
+/** @param {string} executable @param {string} packageRoot @returns {Promise<ClaudeCompatibility>} */
+export async function resolveClaudeCompatibility(executable, packageRoot) {
+  let pinnedExecutable;
+  try {
+    pinnedExecutable = await realpath(executable);
+  } catch {
+    return {
+      status: 'rejected',
+      executable: null,
+      version: null,
+      reason: 'executable_unavailable',
+    };
+  }
+  let raw;
+  try {
+    raw = await readNativeVersion(pinnedExecutable);
+  } catch {
+    return {
+      status: 'rejected',
+      executable: pinnedExecutable,
+      version: null,
+      reason: 'version_probe_cleanup_failed',
+    };
+  }
+  const version = parseVersion(raw);
+  if (!version)
+    return {
+      status: 'rejected',
+      executable: pinnedExecutable,
+      version: null,
+      reason: 'version_unavailable',
+    };
+  if (version.prerelease)
+    return {
+      status: 'rejected',
+      executable: pinnedExecutable,
+      version: version.text,
+      reason: 'prerelease',
+    };
+  if (version.major !== HOST_MAJOR || version.minor !== HOST_MINOR) {
+    return {
+      status: 'rejected',
+      executable: pinnedExecutable,
+      version: version.text,
+      reason: 'major_minor_unsupported',
+    };
+  }
+  if (QUALIFIED_VERSIONS.has(version.text))
+    return {
+      status: 'qualified',
+      executable: pinnedExecutable,
+      version: version.text,
+      reason: 'known_stable',
+    };
+  if (version.patch < 303)
+    return {
+      status: 'rejected',
+      executable: pinnedExecutable,
+      version: version.text,
+      reason: 'unsupported_stable_patch',
+    };
+  let probe;
+  try {
+    probe = await runHostProbe(pinnedExecutable, join(resolve(packageRoot), 'assets', 'claude'));
+  } catch {
+    return {
+      status: 'rejected',
+      executable: pinnedExecutable,
+      version: version.text,
+      reason: 'host_probe_cleanup_failed',
+    };
+  }
+  if (!probe.ok)
+    return {
+      status: 'rejected',
+      executable: pinnedExecutable,
+      version: version.text,
+      reason: probe.reason ?? 'host_probe_failed',
+    };
+  return {
+    status: 'host_checked',
+    executable: pinnedExecutable,
+    version: version.text,
+    reason: 'native_host_contract',
+    ...(probe.checks === undefined ? {} : { checks: probe.checks }),
+  };
+}
+
+/** @param {ClaudeCompatibility} decision */
+export function claudeCompatibilityError(decision) {
+  const detected = decision.version ?? 'unavailable';
+  return `claude_version_unverified: Claude Code detected version ${detected}; reason ${decision.reason}; run aibrain doctor --json or install a compatible stable native version.`;
+}
+
+export const claudeCompatibilityInternals = Object.freeze({
+  REQUIRED_FLAGS,
+  REQUIRED_INVENTORY,
+  ALLOWED_PLUGIN_FILES,
+  parseVersion,
+  runHostProbe,
+});

package/dist/cli.mjs

@@ -15,21 +15,16 @@ import {
   stateRoot,
   tokenDigest,
 } from './state.mjs';
-import {
-  isTestedNativeVersion,
-  nativeVersion,
-  nativeVersionDiagnostic,
-  platformCheck,
-  resolveNative,
-} from './platform.mjs';
+import { 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';
 import { providerFreeProbe } from './mcp.mjs';
 import { codexPolicyJson, makePolicy, publicPolicy, isProfile } from './policy.mjs';
 import { readDiagnostics } from './claude-observation.mjs';
 import { readCodexDiagnostics } from './codex-diagnostics.mjs';
 
-const VERSION = '0.3.0-beta.13';
+const VERSION = '0.3.0-beta.15';
 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';
@@ -444,10 +439,13 @@ async function setup(args) {
   if ((clients === 'claude' || clients === 'both') && !claude) throw new Error('claude_not_found');
   if ((clients === 'codex' || clients === 'both') && (!codex || !node))
     throw new Error('codex_or_node_not_found');
-  const claudeVersion = claude ? nativeVersion(claude) : null;
-  const claudeSupported = claudeVersion !== null && isTestedNativeVersion('claude', claudeVersion);
-  if ((clients === 'claude' || clients === 'both') && !claudeSupported)
-    throw new Error(nativeVersionDiagnostic('claude', claudeVersion ?? ''));
+  const claudeCompatibility =
+    (clients === 'claude' || clients === 'both') && claude !== null
+      ? await resolveClaudeCompatibility(claude, PACKAGE_ROOT)
+      : null;
+  if (claudeCompatibility?.status === 'rejected')
+    throw new Error(claudeCompatibilityError(claudeCompatibility));
+  const claudeVersion = claudeCompatibility?.version ?? (claude ? nativeVersion(claude) : null);
   let codexCompatibility = null;
   if (clients === 'codex' || clients === 'both') {
     codexCompatibility = codex ? await resolveCodexCompatibility(codex) : null;
@@ -519,12 +517,14 @@ async function doctor(json) {
     codex: resolveNative('codex'),
     node: resolveNative('node'),
   };
+  const claudeCompatibility =
+    native.claude !== null ? await resolveClaudeCompatibility(native.claude, PACKAGE_ROOT) : null;
+  const codexCompatibility =
+    native.codex !== null ? await resolveCodexCompatibility(native.codex) : null;
   const rawNativeVersions = {
-    claude: native.claude ? nativeVersion(native.claude) : '',
+    claude: claudeCompatibility?.version ?? '',
     codex: native.codex ? nativeVersion(native.codex) : '',
   };
-  const codexCompatibility =
-    native.codex !== null ? await resolveCodexCompatibility(native.codex) : null;
   const nativeVersions = {
     ...rawNativeVersions,
     codex: codexCompatibility?.version ?? rawNativeVersions.codex,
@@ -533,7 +533,9 @@ async function doctor(json) {
   const needsCodex = config?.clientSelection === 'codex' || config?.clientSelection === 'both';
   const nativeReady =
     (!needsClaude ||
-      (native.claude !== null && isTestedNativeVersion('claude', nativeVersions.claude))) &&
+      (native.claude !== null &&
+        (claudeCompatibility?.status === 'qualified' ||
+          claudeCompatibility?.status === 'host_checked'))) &&
     (!needsCodex ||
       (native.codex !== null &&
         native.node !== null &&
@@ -552,6 +554,9 @@ async function doctor(json) {
       node: native.node !== null,
     },
     nativeVersions,
+    claudeCompatibility: claudeCompatibility?.status ?? 'unavailable',
+    claudeCompatibilityReason: claudeCompatibility?.reason ?? 'claude_not_found',
+    claudeCompatibilityVersion: claudeCompatibility?.version ?? null,
     codexCompatibility: codexCompatibility?.status ?? 'unavailable',
     codexCompatibilityReason: codexCompatibility?.reason ?? 'codex_not_found',
     codexCompatibilityVersion: codexCompatibility?.version ?? null,
@@ -663,17 +668,8 @@ async function main(argv) {
       throw new Error('disclosure_outdated');
     if (config.clientSelection !== command && config.clientSelection !== 'both')
       throw new Error('client_not_configured');
-    if (
-      command === 'claude' &&
-      (typeof config.claudeVersion !== 'string' ||
-        !isTestedNativeVersion('claude', config.claudeVersion))
-    )
-      throw new Error(
-        nativeVersionDiagnostic(
-          'claude',
-          typeof config.claudeVersion === 'string' ? config.claudeVersion : '',
-        ),
-      );
+    // The native executable is authoritative. The stored setup version is
+    // metadata only, so patch updates do not block a fresh compatibility check.
     if (command === 'codex' && typeof config.codexVersion !== 'string')
       throw new Error('codex_version_unverified');
     const root = stateRoot();

package/dist/codex-diagnostics.mjs

@@ -2,11 +2,28 @@
 
 import { createHash } from 'node:crypto';
 import { chmod, lstat, mkdir, open, readFile, readdir, rename, rm, stat } from 'node:fs/promises';
-import { constants } from 'node:fs';
+import { constants, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 
 export const CODEX_DIAGNOSTIC_SCHEMA_VERSION = 1;
-export const CODEX_DIAGNOSTIC_ADAPTER_VERSION = '0.3.0-beta.13';
+const PACKAGE_VERSION_PATTERN =
+  /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/u;
+function packageVersion() {
+  for (const packageUrl of [
+    new URL('./package.json', import.meta.url),
+    new URL('../package.json', import.meta.url),
+  ]) {
+    try {
+      const value = JSON.parse(readFileSync(packageUrl, 'utf8'));
+      if (typeof value?.version === 'string' && PACKAGE_VERSION_PATTERN.test(value.version))
+        return value.version;
+    } catch {
+      // Source and packaged dist use different relative package metadata locations.
+    }
+  }
+  throw new Error('codex_diagnostics_package_version_unavailable');
+}
+export const CODEX_DIAGNOSTIC_ADAPTER_VERSION = packageVersion();
 export const CODEX_DIAGNOSTIC_MAX_LOG_BYTES = 512 * 1024;
 export const CODEX_DIAGNOSTIC_MAX_LOG_FILES = 3;
 export const CODEX_DIAGNOSTIC_MAX_RECORDS = 128;

package/dist/launch.mjs

@@ -4,7 +4,8 @@ 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 { assertTestedNativeVersion, nativeVersion, resolveNative } from './platform.mjs';
+import { nativeVersion, resolveNative } from './platform.mjs';
+import { claudeCompatibilityError, resolveClaudeCompatibility } from './claude-compatibility.mjs';
 import { codexCompatibilityError, resolveCodexCompatibility } from './codex-compatibility.mjs';
 import {
   claudeCheckpointConfigBinding,
@@ -407,8 +408,14 @@ export async function launchClaude(config, root, args) {
   assertClaudeArgs(launchArgs.args);
   const executable = resolveNative('claude');
   if (!executable) throw new Error('claude_not_found');
-  const currentVersion = nativeVersion(executable);
-  assertTestedNativeVersion('claude', currentVersion);
+  const compatibility = await resolveClaudeCompatibility(executable, validated.packageRoot);
+  if (compatibility.status === 'rejected') throw new Error(claudeCompatibilityError(compatibility));
+  const pinnedExecutable = compatibility.executable ?? executable;
+  if (compatibility.status === 'host_checked')
+    process.stderr.write(
+      `aibrain: Claude ${compatibility.version ?? 'unknown'} accepted by the local native host contract; end-to-end recovery remains separately qualified.\n`,
+    );
+  const currentVersion = compatibility.version ?? nativeVersion(pinnedExecutable);
   const pluginRoot = await assertClaudeAssets(validated.packageRoot);
   const telemetryActive =
     validated.telemetry?.enabled === true && validated.telemetry?.disclosedAt != null;
@@ -533,7 +540,7 @@ export async function launchClaude(config, root, args) {
   let child;
   try {
     child = spawn(
-      executable,
+      pinnedExecutable,
       [
         '--settings',
         settingsPath,

package/dist/package.json

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