@brunobracaioli/aibrain 0.4.0-beta.1 → 0.4.0-beta.10

package/README.md

@@ -1,6 +1,7 @@
 # aisac
 
-The AISAC client for Claude Code and Codex on Linux/WSL with Node.js 22 or newer:
+The AISAC client for Claude Code and Codex on Linux/WSL, and for Claude Code on
+macOS, with Node.js 22 or newer:
 AI Brain memory, context management and, for AISAC Founding Cohort members,
 AISAC Engineering.
 
@@ -14,6 +15,41 @@ both provide the `aisac` and `aibrain` commands. State stays in `~/.aibrain`.
 shows the answer and sends the request only to the configured AI Brain address.
 `aisac status` stays offline.
 
+For licensed accounts, `aisac claude` downloads the AISAC Engineering pack for
+the session, verifies its Ed25519 signature against the key pinned in this
+release, and loads it as the `aisac-engineering` plugin from the session's
+private folder, which is deleted on exit. Any failure starts Claude without the
+pack. `aisac setup --lang pt-BR|en` picks the pack language without a network
+call. The pack is never part of this npm package.
+
+`aisac codex` (Codex 0.164.0 or later) loads the same verified pack for that
+session only: its skills are added to the Codex app-server the launch owns
+(call one with `$`, for example `$spec`) and its agents become session agent
+roles. Nothing is written to `~/.codex`, `~/.agents` or the project, and the
+session's folder is deleted on exit. An older Codex starts without the pack and
+says `codex_outdated`.
+
+Licensed `aisac claude` sessions also load guardrail hooks as the session plugin
+`aisac-guardrails`.
+- **Default on:** `secrets-guard` refuses secret files by name. Four more hooks
+  keep continuity: a repository snapshot at start and after a compaction, a
+  docs reminder, and the NOTES/spec/CHANGELOG pass.
+- **Default off:** `git-guard`, `destructive-guard` and `format-on-edit`.
+- **Changing them:** `aisac hooks` lists them, and `aisac hooks enable|disable
+  <id>` or `aisac hooks reset` changes the next session. The agent cannot change
+  them from inside a session.
+- **Code:** it ships in this package and runs locally. Nothing comes from the
+  server.
+
+Licensed sessions of `aisac claude` and `aisac codex` can also load reviewed MCP
+servers: `github` (read-only, token in `GITHUB_PERSONAL_ACCESS_TOKEN`), `supabase`
+(read-only), `vercel`, `playwright` (pinned, isolated) and `context7`.
+- **Default:** every server is off. `aisac mcp` lists them, `aisac mcp enable|disable
+  <id>` or `aisac mcp reset` changes the next session, and `aisac mcp info <id>` says
+  what a server reaches and how to log in.
+- **Login:** the host does it (`/mcp` in Claude Code, `aisac mcp login <id>` for Codex)
+  and keeps it in its own store. No token reaches `~/.aibrain` or AISAC.
+
 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
@@ -23,7 +59,7 @@ 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, 0.163.0 or 0.164.0. A newer stable Codex 0.x release may continue only
+0.162.0, 0.162.1, 0.163.0, 0.164.0 or 0.166.0 (0.165.0 was never qualified). A newer stable Codex 0.x release may continue only
 after its locally generated experimental protocol schemas and transport flags
 match the bundled adapter contract; prereleases, older releases and new majors
 remain rejected. Starting with beta14, newer stable Claude 2.1 patches can
@@ -39,6 +75,11 @@ record formats. Native launch/resume qualification is separate from a new
 model/JEV compaction qualification. A later native release that changes the
 consumed contract can still require an AI Brain compatibility update.
 
+`0.4.0-beta.9` refreshes the bundled contract to Codex 0.166.0. Its delta is
+additive: optional item timing, an image generation id, an attach-to-source fork
+flag and two error codes. See the
+[Codex 0.166 qualification record](../../docs/reference/codex-166-compatibility-2026-11-04.md).
+
 The Codex terminal bridge permits the native session picker's separate read-only
 connection while keeping the primary conversation and monitor intact. A picker
 cannot compact, start a turn, inject history or take ownership of the primary
@@ -61,7 +102,9 @@ Installation does not contact AI Brain, change native client configuration, or
 enable all paid accounts. Setup requires an existing AI Brain PAT, explicit
 versioned disclosure, and successful provider-free pilot access. Claude and
 Codex continue to own their own authentication. Windows native is unsupported;
-run the beta inside WSL. Pricing and general customer activation are outside
+run the beta inside WSL. On macOS, `aisac setup` configures Claude Code, and
+`aisac codex` is refused with `CODEX_MACOS_UNSUPPORTED`. Codex capture needs
+Linux procfs and `flock`, so use Codex from Linux/WSL. Pricing and general customer activation are outside
 this beta.
 
 For reviewed noninteractive automation only, use a private token file and

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

@@ -151,7 +151,7 @@ type Register = (
 ) => void;
 
 const MAX_RESULT_BYTES = 256 * 1024;
-const CLAUDE_HOOK_VERSION = '0.4.0-beta.1';
+const CLAUDE_HOOK_VERSION = '0.4.0-beta.7';
 const MAX_DIAGNOSTIC_BYTE_COUNT = 128 * 1024 * 1024;
 const COOLDOWN_MS = 60_000;
 const MAX_TRUNCATED_CODE_POINTS = 300;
@@ -463,6 +463,10 @@ function v2WireOptions(options: V2Options): Record<string, unknown> {
 
 function safeErrorCategory(error: unknown): string {
   const record = isRecord(error) ? error : {};
+  // A coded error names its own reason; the keyword guess below would read
+  // "AI Brain plan does not meet the minimum estimated reduction" as invalid_plan.
+  if (COMPACT_ERROR_CODES.includes(record.compactErrorCode as CompactErrorCode))
+    return record.compactErrorCode as CompactErrorCode;
   const code = typeof record.code === 'string' ? record.code.toLowerCase() : '';
   const name = typeof record.name === 'string' ? record.name.toLowerCase() : '';
   const message = typeof record.message === 'string' ? record.message.toLowerCase() : '';

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

@@ -54,6 +54,12 @@ const MAX_OWNED_REQUESTS = 1_000;
 const MAX_RETIRED_REQUESTS = 2_000;
 const MAX_CLIENT_REQUEST_BINDINGS = 128;
 const MAX_OWNED_THREAD_IDS = 256;
+// AISAC Engineering (ADR-0047 E4c): the launcher's skills root is added to the
+// owned app-server before the client sees its initialize answer.
+const ENGINEERING_SKILLS_ROOT_ENV = 'AISAC_ENGINEERING_SKILLS_ROOT';
+const ENGINEERING_SKILLS_ACK_TIMEOUT_MS = 2_000;
+const MAX_ENGINEERING_PATH_LENGTH = 4_096;
+const MAX_TRACKED_INITIALIZE_REQUESTS = 4;
 const MAX_RECOVERY_ITEMS = 128;
 const MAX_RECOVERY_SOURCE_INDEX = 65_536;
 const MAX_NOTE_BYTES = 128 * 1024;
@@ -2707,6 +2713,8 @@ export function createCodexContextProxy({
   createDiagnosticSink = null,
   brainServer = process.env.AI_BRAIN_MCP_SERVER ?? 'brain',
   clientVersion = process.env.CODEX_CLIENT_VERSION ?? '0.161.0',
+  engineeringSkillsRoot = null,
+  engineeringAckTimeoutMs = ENGINEERING_SKILLS_ACK_TIMEOUT_MS,
 }) {
   const contextPolicy = normalizeContextPolicy(policy);
   const effectiveThreshold = contextPolicy?.compactAtPercent ?? threshold;
@@ -2719,6 +2727,15 @@ export function createCodexContextProxy({
   const telemetryByThread = new Map();
   const diagnosticSinks = new Map();
   let stopped = false;
+  // AISAC Engineering skills root: 'off' without a root; 'waiting' for the
+  // client's first successful initialize; 'holding' app-server output until
+  // skills/extraRoots/set is answered (or times out); then 'done'.
+  let engineeringState =
+    typeof engineeringSkillsRoot === 'string' && engineeringSkillsRoot.length > 0
+      ? 'waiting'
+      : 'off';
+  const initializeRequestKeys = new Set();
+  let engineeringHeld = null;
   function emitDiagnostic(event) {
     try {
       const phase = typeof event?.phase === 'string' ? event.phase : '';
@@ -4131,6 +4148,11 @@ export function createCodexContextProxy({
       const owned = ownedRequests.get(message.id);
       ownedRequests.delete(message.id);
       retire(message.id);
+      if (owned.kind === 'engineering') {
+        // An error leaves the session without the pack skills; it is never shown.
+        releaseEngineering();
+        return false;
+      }
       if (
         owned.kind === 'read' ||
         owned.kind === 'page' ||
@@ -4364,6 +4386,14 @@ export function createCodexContextProxy({
     if (!validRequestId) return;
     const requestKey = clientRequestKey(requestId);
     if (requestKey === null) return;
+    if (
+      message.method === 'initialize' &&
+      engineeringState === 'waiting' &&
+      initializeRequestKeys.size < MAX_TRACKED_INITIALIZE_REQUESTS
+    ) {
+      initializeRequestKeys.add(requestKey);
+      return;
+    }
     if (['thread/start', 'thread/resume', 'thread/fork'].includes(message.method)) {
       const threadId =
         isRecord(message.params) && typeof message.params.threadId === 'string'
@@ -4428,7 +4458,7 @@ export function createCodexContextProxy({
   let passthrough = false;
   let discardOversized = false;
   let pausedForBackpressure = false;
-  const forward = (text) => {
+  const writeOut = (text) => {
     if (!stdout.write(text) && !pausedForBackpressure) {
       pausedForBackpressure = true;
       child.stdout.pause();
@@ -4438,6 +4468,54 @@ export function createCodexContextProxy({
       });
     }
   };
+  const forward = (text) => {
+    if (engineeringHeld === null) {
+      writeOut(text);
+      return;
+    }
+    engineeringHeld.lines.push(text);
+    engineeringHeld.bytes += Buffer.byteLength(text, 'utf8');
+    if (engineeringHeld.bytes > MAX_LINE_BYTES) releaseEngineering();
+  };
+  /** The client's first successful initialize answer, which starts the hold. */
+  function isEngineeringTrigger(message) {
+    if (engineeringState !== 'waiting' || !isRecord(message)) return false;
+    if (message.method !== undefined || !('result' in message)) return false;
+    const key = clientRequestKey(message.id);
+    return key !== null && initializeRequestKeys.has(key);
+  }
+  function holdForEngineering(text) {
+    engineeringState = 'holding';
+    initializeRequestKeys.clear();
+    engineeringHeld = {
+      lines: [text],
+      bytes: Buffer.byteLength(text, 'utf8'),
+      id: null,
+      cancel: null,
+    };
+    try {
+      engineeringHeld.id = sendOwned(
+        'skills/extraRoots/set',
+        { extraRoots: [engineeringSkillsRoot] },
+        'engineering',
+        null,
+      );
+    } catch {
+      releaseEngineering();
+      return;
+    }
+    engineeringHeld.cancel = scheduleTimeout(() => releaseEngineering(), engineeringAckTimeoutMs);
+  }
+  /** Forward everything held, in order. Idempotent; the session never waits on the pack. */
+  function releaseEngineering() {
+    if (engineeringHeld === null) return;
+    const held = engineeringHeld;
+    engineeringHeld = null;
+    engineeringState = 'done';
+    held.cancel?.();
+    if (held.id !== null && ownedRequests.has(held.id)) cleanupRequest(held.id);
+    for (const text of held.lines) writeOut(text);
+  }
   const processLine = (line) => {
     if (Buffer.byteLength(line, 'utf8') + 1 > MAX_LINE_BYTES) {
       const ownedId = internalRequestId(line);
@@ -4451,6 +4529,10 @@ export function createCodexContextProxy({
     try {
       const message = JSON.parse(line.endsWith('\r') ? line.slice(0, -1) : line);
       observeClientResponse(message);
+      if (isEngineeringTrigger(message)) {
+        holdForEngineering(`${line}\n`);
+        return;
+      }
       forwardLine = handle(message);
     } catch {
       /* preserve malformed external protocol lines */
@@ -4536,6 +4618,7 @@ export function createCodexContextProxy({
     }
   });
   child.stdout.on('end', () => {
+    releaseEngineering();
     const tail = inputBuffer + decoder.end();
     if (tail && !discardOversized) forward(tail);
     inputBuffer = '';
@@ -4565,6 +4648,7 @@ export function createCodexContextProxy({
     observeClientRequest,
     observeClientResponse,
     async stop() {
+      releaseEngineering();
       if (stopped) {
         await Promise.all(
           [...diagnosticSinks.values()].map((sink) =>
@@ -4594,6 +4678,18 @@ export function createCodexContextProxy({
   };
 }
 
+/**
+ * The launcher's AISAC Engineering skills root, or null. Only an absolute,
+ * normalized path without control characters is used.
+ */
+export function engineeringSkillsRootFrom(value) {
+  if (typeof value !== 'string' || value.length === 0) return null;
+  if (value.length > MAX_ENGINEERING_PATH_LENGTH || /[\u0000-\u001f\u007f]/u.test(value))
+    return null;
+  if (!value.startsWith('/') || resolve(value) !== value) return null;
+  return value;
+}
+
 async function main() {
   if (process.argv.includes('--help')) {
     process.stderr.write(
@@ -4648,6 +4744,7 @@ async function main() {
     timeoutMs: numberEnv('CODEX_CONTEXT_COMPACT_TIMEOUT_MS', DEFAULT_TIMEOUT_MS),
     policy,
     createDiagnosticSink: diagnosticFactory,
+    engineeringSkillsRoot: engineeringSkillsRootFrom(process.env[ENGINEERING_SKILLS_ROOT_ENV]),
   });
   const clientDecoder = new StringDecoder('utf8');
   let clientInputBuffer = '';

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.4.0-beta.1';
+export const ADAPTER_VERSION = '0.4.0-beta.10';
 const MAX_DIAGNOSTIC_COUNT = 10_000_000;
 const MAX_DIAGNOSTIC_BYTES = 128 * 1024 * 1024;
 const CHECKPOINT_BACKENDS = new Set(['native_store', 'private_file']);

package/dist/cli.mjs

@@ -17,6 +17,8 @@ import {
 } from './state.mjs';
 import {
   captureLockPlatformCheck,
+  codexPlatformCheck,
+  defaultClientSelection,
   nativeVersion,
   platformCheck,
   resolveNative,
@@ -29,8 +31,18 @@ import { codexPolicyJson, makePolicy, publicPolicy, isProfile } from './policy.m
 import { readDiagnostics } from './claude-observation.mjs';
 import { readCodexDiagnostics } from './codex-diagnostics.mjs';
 import { checkEngineeringLicense, licenseLine, unavailableLicense } from './engineering.mjs';
+import {
+  isPackLocale,
+  readLastLaunch,
+  readStoredLocale,
+  resolvePackLocale,
+  writeStoredLocale,
+} from './engineering-pack.mjs';
+import { extensionsSummary, hooksCommand, mcpCommand } from './extensions-cli.mjs';
+import { sessionServers } from './mcp-servers.mjs';
+import { anyFormatter } from './guardrails/format.mjs';
 
-const VERSION = '0.4.0-beta.1';
+const VERSION = '0.4.0-beta.10';
 // The command is `aisac`; `aibrain` is an alias installed from the same entry.
 const COMMAND = 'aisac';
 const ENDPOINT = 'https://mcp.ai-brain.aisac.cloud/mcp';
@@ -48,7 +60,13 @@ function usage() {
     'Claude shadow: setup --claude-shadow on|off and --claude-diagnostics on|off (preview stays applied=false).',
   );
   console.log(
-    'AISAC Engineering: setup and doctor report the license; status stays offline. `aibrain` is an alias of `aisac`.',
+    'AISAC Engineering: `aisac claude` and `aisac codex` (Codex 0.164+) load the licensed method; setup --lang pt-BR|en picks its language; setup and doctor report the license; status stays offline. `aibrain` is an alias of `aisac`.',
+  );
+  console.log(
+    'Guardrails: `aisac hooks` lists them (a checklist on a terminal); `aisac hooks enable|disable <id>...` and `aisac hooks reset` change the next `aisac claude` session.',
+  );
+  console.log(
+    'MCP catalog: `aisac mcp` lists the reviewed servers (GitHub, Supabase, Vercel, Playwright, Context7); `aisac mcp enable|disable <id>...`, `aisac mcp reset`, `aisac mcp info <id>` and `aisac mcp login <id>` (Codex) change or explain the next session.',
   );
 }
 
@@ -198,7 +216,7 @@ function selectedPolicy(args, previous) {
     if (option(args, '--goal') === undefined && inherited.goal !== undefined)
       overrides.goal = inherited.goal;
   }
-  const clients = option(args, '--client') ?? 'both';
+  const clients = option(args, '--client') ?? defaultClientSelection();
   if (
     clients === 'codex' &&
     args.some(
@@ -310,6 +328,26 @@ async function updateLocalOptOut(previous, args) {
   return true;
 }
 
+/** Store the AISAC Engineering pack language; local only, no network call. @param {'pt-BR' | 'en'} locale */
+async function setPackLocale(locale) {
+  const root = await ensureStateRoot();
+  await writeStoredLocale(root, locale);
+  console.log(
+    `AISAC Engineering pack language set to ${locale} for future launches; no network call was made.`,
+  );
+}
+
+/** Offline view of the pack language and the last launch (status, doctor). */
+async function engineeringPackState() {
+  const root = stateRoot();
+  const stored = await readStoredLocale(root);
+  return {
+    locale: resolvePackLocale(stored),
+    localeSource: stored === null ? 'system' : 'setup',
+    lastLaunch: await readLastLaunch(root),
+  };
+}
+
 /** @param {string} endpoint */
 function validateEndpoint(endpoint) {
   if (endpoint.length > 2048) throw new Error('endpoint_too_long');
@@ -385,6 +423,7 @@ async function setup(args) {
       '--telemetry',
       '--claude-shadow',
       '--claude-diagnostics',
+      '--lang',
     ]),
     new Set([
       '--client',
@@ -396,10 +435,14 @@ async function setup(args) {
       '--telemetry',
       '--claude-shadow',
       '--claude-diagnostics',
+      '--lang',
     ]),
   );
   if (args.includes('--undo') && args.length !== 1)
     throw new Error('setup_undo_cannot_have_options');
+  const lang = option(args, '--lang');
+  if (lang !== undefined && !isPackLocale(lang)) throw new Error('invalid_lang');
+  if (lang !== undefined && args.length === 2) return setPackLocale(lang);
   const previous = await readConfig();
   if (await updateLocalOptOut(previous, args)) return;
   const localOptOut =
@@ -408,8 +451,12 @@ async function setup(args) {
   if (localOptOut) return disableTelemetryLocally(previous);
   const platform = platformCheck();
   if (!platform.ok) throw new Error(`${platform.code}:${platform.message}`);
-  const clients = option(args, '--client') ?? 'both';
+  const clients = option(args, '--client') ?? defaultClientSelection();
   if (!['claude', 'codex', 'both'].includes(clients)) throw new Error('invalid_client');
+  if (clients !== 'claude') {
+    const codexPlatform = codexPlatformCheck();
+    if (!codexPlatform.ok) throw new Error(`${codexPlatform.code}:${codexPlatform.message}`);
+  }
   if (
     clients === 'codex' &&
     (option(args, '--claude-shadow') !== undefined ||
@@ -501,11 +548,27 @@ async function setup(args) {
   console.log(
     `Configured ${clients} in ${root}. Provider-free access verified; no provider batch was used.`,
   );
+  if (lang !== undefined) await setPackLocale(lang);
   // Display only: the server decides again on every pack request (ADR-0047).
   const line = licenseLine(await checkEngineeringLicense(endpoint, token));
   if (line !== null) console.log(line);
 }
 
+/** Extension state plus whether `format-on-edit` has a formatter in this folder (FR8). */
+async function doctorExtensions() {
+  const summary = await extensionsSummary(stateRoot());
+  // A token server is skipped at launch when its variable is unset (names only).
+  const mcpMissingEnv = sessionServers(summary.mcp, 'claude', process.env).missingEnv.map(
+    (skipped) => skipped.id,
+  );
+  const formatOnEdit = !summary.hooks.includes('format-on-edit')
+    ? 'off'
+    : (await anyFormatter(process.cwd()))
+      ? 'ready'
+      : 'no_formatter_found';
+  return { ...summary, formatOnEdit, mcpMissingEnv };
+}
+
 /** @param {boolean} json */
 async function doctor(json) {
   const platform = platformCheck();
@@ -599,6 +662,8 @@ async function doctor(json) {
         config?.claudeObservation?.disclosedAt !== undefined,
     },
     engineering,
+    engineeringPack: await engineeringPackState(),
+    extensions: await doctorExtensions(),
     paidOrPilot: probe?.ok
       ? 'provider_free_probe_ok; paid entitlement or pilot invitation remains server-enforced'
       : config
@@ -634,6 +699,8 @@ async function status(json) {
         config?.claudeObservation?.disclosedAt !== null &&
         config?.claudeObservation?.disclosedAt !== undefined,
     },
+    engineeringPack: await engineeringPackState(),
+    extensions: await extensionsSummary(stateRoot()),
     monitoredSession: null,
     monitoringStatus: 'not_observed',
   };
@@ -682,6 +749,8 @@ async function main(argv) {
     else console.log(records);
     return;
   }
+  if (command === 'hooks') return hooksCommand(rest);
+  if (command === 'mcp') return mcpCommand(rest);
   if (command === 'disable') {
     if (rest.length > 0) throw new Error('disable_does_not_accept_options');
     return removeOwnedSetup();

package/dist/codex-compatibility.mjs

@@ -26,7 +26,14 @@ const PAGINATION_CONTRACT_VALID =
       fingerprint.roots[PAGINATION_CONTRACT.response_schema]?.sha256 &&
     typeof PAGINATION_CONTRACT.graph_sha256 === 'string' &&
     PAGINATION_CONTRACT.graph_sha256.length === 64);
-const QUALIFIED_VERSIONS = new Set(['0.161.0', '0.162.0', '0.162.1', '0.163.0', '0.164.0']);
+const QUALIFIED_VERSIONS = new Set([
+  '0.161.0',
+  '0.162.0',
+  '0.162.1',
+  '0.163.0',
+  '0.164.0',
+  '0.166.0',
+]);
 const ANNOTATIONS = new Set([
   '$comment',
   'title',
@@ -475,7 +482,50 @@ export async function resolveCodexCompatibility(executable, baseEnvironment = pr
   }
 }
 
+/** @param {string} left @param {string} right */
+function compareStableVersions(left, right) {
+  const a = left.split('.').map(Number);
+  const b = right.split('.').map(Number);
+  for (let index = 0; index < 3; index += 1) {
+    const difference = (a[index] ?? 0) - (b[index] ?? 0);
+    if (difference !== 0) return difference;
+  }
+  return 0;
+}
+
+/** The newest Codex release this client was qualified against. */
+export const LATEST_QUALIFIED_CODEX = /** @type {string} */ (
+  [...QUALIFIED_VERSIONS].sort(compareStableVersions).at(-1)
+);
+
+// Rejections a user fixes by installing a qualified Codex (or a newer aisac):
+// the installed release's contract or transport differs from the bundled one.
+const CONTRACT_REJECTIONS = new Set([
+  'protocol_schema_mismatch',
+  'protocol_method_missing',
+  'schema_root_missing_or_invalid',
+  'schema_set_too_large',
+  'schema_generation_failed',
+  'transport_flags_missing',
+  'protocol_probe_failed',
+]);
+
+/** @param {{reason:string, version:string|null}} decision @returns {string|null} */
+export function codexCompatibilityRemedy(decision) {
+  const detected = decision.version === null ? 'The installed Codex' : `Codex ${decision.version}`;
+  const reinstall = `npm install -g @openai/codex@${LATEST_QUALIFIED_CODEX}`;
+  if (CONTRACT_REJECTIONS.has(decision.reason))
+    return `${detected} is not qualified by this aisac (newest qualified: ${LATEST_QUALIFIED_CODEX}). Install the qualified Codex with \`${reinstall}\`, or check for an aisac release that qualifies it with \`npm install -g @aisac/cli@beta\`.`;
+  if (decision.reason === 'version_unqualified')
+    return `${detected} is older than this aisac supports. Update it with \`${reinstall}\`.`;
+  if (decision.reason === 'version_not_stable_0x')
+    return `${detected} is not a stable 0.x release. Install a qualified one with \`${reinstall}\`.`;
+  return null;
+}
+
 /** @param {{reason:string, version:string|null}} decision @returns {string} */
 export function codexCompatibilityError(decision) {
-  return `codex_protocol_incompatible:${decision.reason}:detected=${decision.version ?? 'unavailable'};run aisac doctor --json`;
+  const coded = `codex_protocol_incompatible:${decision.reason}:detected=${decision.version ?? 'unavailable'};run aisac doctor --json`;
+  const remedy = codexCompatibilityRemedy(decision);
+  return remedy === null ? coded : `${coded}\n${remedy}`;
 }