@brunobracaioli/aibrain 0.4.0-beta.2 → 0.4.0-beta.3

package/README.md

@@ -21,6 +21,13 @@ 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`.
+
 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

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.2';
+export const ADAPTER_VERSION = '0.4.0-beta.3';
 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

@@ -37,7 +37,7 @@ import {
   writeStoredLocale,
 } from './engineering-pack.mjs';
 
-const VERSION = '0.4.0-beta.2';
+const VERSION = '0.4.0-beta.3';
 // 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';
@@ -55,7 +55,7 @@ function usage() {
     'Claude shadow: setup --claude-shadow on|off and --claude-diagnostics on|off (preview stays applied=false).',
   );
   console.log(
-    'AISAC Engineering: `aisac claude` loads 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`.',
+    '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`.',
   );
 }
 

package/dist/codex-engineering.mjs

@@ -0,0 +1,165 @@
+// @ts-check
+
+/**
+ * AISAC Engineering for Codex (ADR-0047 wave E4c, spec FR4).
+ *
+ * Codex has no session plugin directory, so the method reaches only the
+ * app-server this launch owns, and nothing is written to `~/.codex`,
+ * `~/.agents` or the project:
+ * - skills: the adapter sends `skills/extraRoots/set` with the pack's
+ *   `skills/` directory right after the client's initialize (in-memory in that
+ *   process);
+ * - agents: one role file per pack agent, declared with `-c agents.<name>.*`
+ *   overrides on the owned app-server (the session-flags config layer).
+ * The launcher hands the monitor one JSON value; the monitor validates it
+ * again before turning it into arguments.
+ */
+
+import { basename, dirname, join, resolve } from 'node:path';
+
+export const CODEX_ENGINEERING_ENV = 'AISAC_ENGINEERING_CODEX';
+export const CODEX_ENGINEERING_SKILLS_ROOT_ENV = 'AISAC_ENGINEERING_SKILLS_ROOT';
+export const CODEX_AGENTS_DIRECTORY = 'codex-agents';
+const SKILLS_DIRECTORY = 'skills';
+const PACK_DIRECTORY = 'engineering';
+const RUNTIME_DIRECTORY = 'runtime';
+const CODEX_LAUNCH_DIRECTORY = /^codex-[A-Za-z0-9]{6}$/u;
+const SCHEMA_VERSION = 1;
+const MAX_SPEC_BYTES = 16 * 1024;
+const MAX_AGENTS = 16;
+const MAX_PATH_LENGTH = 4096;
+export const MAX_AGENT_DESCRIPTION_LENGTH = 1024;
+export const AGENT_NAME = /^[a-z][a-z0-9-]{0,63}$/u;
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/u;
+/** First Codex release whose session mechanism was verified (spike Q4, 2026-11-03). */
+const MIN_CODEX_VERSION = /** @type {const} */ ([0, 164, 0]);
+
+/** @typedef {{ name: string, description: string, configFile: string }} CodexAgentRole */
+/** @typedef {{ schemaVersion: 1, skillsRoot: string, agents: CodexAgentRole[] }} CodexEngineering */
+
+/** @param {string} code @returns {never} */
+function fail(code) {
+  throw new Error(`codex_engineering_${code}`);
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Whether this Codex version receives the pack. A null or malformed version
+ * never does.
+ * @param {string | null | undefined} version
+ */
+export function supportsCodexEngineering(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/u.exec(version ?? '');
+  if (match === null) return false;
+  const parts = match.slice(1).map(Number);
+  for (let index = 0; index < MIN_CODEX_VERSION.length; index += 1) {
+    const part = /** @type {number} */ (parts[index]);
+    const minimum = MIN_CODEX_VERSION[index] ?? 0;
+    if (part !== minimum) return part > minimum;
+  }
+  return true;
+}
+
+/** @param {unknown} value */
+function isCleanAbsolutePath(value) {
+  return (
+    typeof value === 'string' &&
+    value.length > 0 &&
+    value.length <= MAX_PATH_LENGTH &&
+    !CONTROL_CHARACTERS.test(value) &&
+    value.startsWith('/') &&
+    resolve(value) === value
+  );
+}
+
+/**
+ * @param {unknown} value
+ * @param {{ stateDir?: string }} [options] when given, the pack must sit in a
+ *   Codex launch directory of that state directory
+ * @returns {CodexEngineering}
+ */
+export function validateCodexEngineering(value, options = {}) {
+  if (!isRecord(value)) fail('invalid');
+  const keys = Object.keys(value).sort().join(',');
+  if (keys !== 'agents,schemaVersion,skillsRoot') fail('invalid');
+  if (value.schemaVersion !== SCHEMA_VERSION) fail('schema');
+  const skillsRoot = value.skillsRoot;
+  if (!isCleanAbsolutePath(skillsRoot)) fail('path');
+  const skills = /** @type {string} */ (skillsRoot);
+  if (basename(skills) !== SKILLS_DIRECTORY) fail('path');
+  const base = dirname(skills);
+  if (basename(base) !== PACK_DIRECTORY) fail('path');
+  if (options.stateDir !== undefined) {
+    const launch = dirname(base);
+    if (
+      !CODEX_LAUNCH_DIRECTORY.test(basename(launch)) ||
+      dirname(launch) !== join(resolve(options.stateDir), RUNTIME_DIRECTORY)
+    )
+      fail('path');
+  }
+  if (!Array.isArray(value.agents) || value.agents.length > MAX_AGENTS) fail('agents');
+  const seen = new Set();
+  /** @type {CodexAgentRole[]} */
+  const agents = [];
+  for (const agent of value.agents) {
+    if (!isRecord(agent) || Object.keys(agent).sort().join(',') !== 'configFile,description,name')
+      fail('agents');
+    const { name, description, configFile } = agent;
+    if (typeof name !== 'string' || !AGENT_NAME.test(name) || seen.has(name)) fail('agents');
+    if (
+      typeof description !== 'string' ||
+      description.trim().length === 0 ||
+      description.length > MAX_AGENT_DESCRIPTION_LENGTH ||
+      CONTROL_CHARACTERS.test(description)
+    )
+      fail('agents');
+    if (configFile !== join(base, CODEX_AGENTS_DIRECTORY, `${name}.toml`)) fail('agents');
+    seen.add(name);
+    agents.push({ name, description, configFile });
+  }
+  return { schemaVersion: SCHEMA_VERSION, skillsRoot: skills, agents };
+}
+
+/**
+ * Parse the monitor's environment value; null when absent.
+ * @param {string | undefined} raw
+ * @param {{ stateDir?: string }} [options]
+ * @returns {CodexEngineering | null}
+ */
+export function parseCodexEngineering(raw, options = {}) {
+  if (raw === undefined || raw === '') return null;
+  if (Buffer.byteLength(raw, 'utf8') > MAX_SPEC_BYTES) fail('too_large');
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    fail('invalid');
+  }
+  return validateCodexEngineering(value, options);
+}
+
+/**
+ * A TOML basic string. JSON escapes are TOML escapes; DEL is escaped too.
+ * @param {string} value
+ */
+export function tomlBasicString(value) {
+  return JSON.stringify(value).replace(/\u007f/gu, '\\u007F');
+}
+
+/**
+ * Session-only `-c` overrides for the owned app-server, one role per agent.
+ * @param {CodexEngineering} engineering
+ * @returns {string[]}
+ */
+export function codexEngineeringConfigArgs(engineering) {
+  return engineering.agents.flatMap((agent) => [
+    '-c',
+    `agents.${agent.name}.description=${tomlBasicString(agent.description)}`,
+    '-c',
+    `agents.${agent.name}.config_file=${tomlBasicString(agent.configFile)}`,
+  ]);
+}

package/dist/engineering-pack.mjs

@@ -1,13 +1,15 @@
 // @ts-check
 
 /**
- * AISAC Engineering pack for Claude Code (ADR-0047 wave E4b, spec FR4/FR8).
+ * AISAC Engineering pack for Claude Code (ADR-0047 wave E4b) and Codex (E4c),
+ * spec FR4/FR8.
  *
  * One request per launch fetches the account's pack; it doubles as the live
  * license check. The pack is trusted instruction for the user's agent, so it
  * is accepted only when it is signed by a pinned key, matches the requested
  * locale and passes the FR3 rules again here. It is written into the launch's
- * private directory and handed to Claude Code as a second `--plugin-dir`.
+ * private directory and handed to Claude Code as a second `--plugin-dir`, or
+ * to the Codex app-server this launch owns (see codex-engineering.mjs).
  * Any failure starts the session without the pack; nothing here can block a
  * launch or treat a failure as licensed.
  */
@@ -35,6 +37,13 @@ import {
   unavailableReasonFor,
 } from './engineering.mjs';
 import { atomicJson } from './state.mjs';
+import {
+  AGENT_NAME,
+  CODEX_AGENTS_DIRECTORY,
+  MAX_AGENT_DESCRIPTION_LENGTH,
+  tomlBasicString,
+  validateCodexEngineering,
+} from './codex-engineering.mjs';
 
 const PACK_PATH = '/engineering/v1/pack';
 export const PACK_TIMEOUT_MS = 10_000;
@@ -86,6 +95,10 @@ const PLUGIN_NAME = 'aisac-engineering';
 const PLUGIN_LICENSE = 'LicenseRef-AISAC-Engineering';
 const PACK_DIRECTORY = 'engineering';
 const OUTPUT_STYLES_PREFIX = 'output-styles/';
+const SKILLS_DIRECTORY = 'skills';
+const AGENT_FILE = /^agents\/([a-z][a-z0-9-]{0,63})\.md$/u;
+const WATERMARK_KEY = 'aisac_watermark';
+const WATERMARK_VALUE = /^[0-9a-f]{16}$/u;
 export const PUBLIC_KEY_FILE = 'engineering-pack-public-key.json';
 const LOCALE_FILE = 'engineering-locale.json';
 const LAST_LAUNCH_FILE = 'engineering-last-launch.json';
@@ -113,11 +126,12 @@ const SAFE_REASON = /^[a-z][a-z0-9_]{0,63}$/u;
  *   | { outcome: 'unavailable', reason: string }
  *   | { outcome: 'rejected', reason: string }} PackOutcome
  */
+/** @typedef {'claude' | 'codex'} PackClient */
 /**
  * @typedef {{
  *   schemaVersion: 1,
  *   at: string,
- *   client: 'claude',
+ *   client: PackClient,
  *   state: PackOutcome['outcome'],
  *   reason: string | null,
  *   packVersion: string | null,
@@ -198,7 +212,7 @@ export async function readLastLaunch(root) {
     value.schemaVersion !== 1 ||
     typeof value.at !== 'string' ||
     !ISO_INSTANT.test(value.at) ||
-    value.client !== 'claude' ||
+    (value.client !== 'claude' && value.client !== 'codex') ||
     !['loaded', 'inactive', 'not_offered', 'unavailable', 'rejected'].includes(
       /** @type {string} */ (value.state),
     ) ||
@@ -519,12 +533,13 @@ const PLUGIN_DESCRIPTION = {
 };
 
 /**
- * Write a verified pack as a Claude Code plugin inside the launch's private
- * directory and return the plugin root. The manifest is the client's own.
+ * Write the pack files into `engineering/` of the launch's private directory:
+ * `0700` directories, `0600` files, exclusive creation, contained paths.
  * @param {VerifiedPack} pack
  * @param {string} launchDirectory
+ * @returns {Promise<string>} the pack root
  */
-export async function materializePack(pack, launchDirectory) {
+async function writePackFiles(pack, launchDirectory) {
   const base = resolve(launchDirectory, PACK_DIRECTORY);
   await mkdir(base, { mode: 0o700 });
   for (const file of pack.files) {
@@ -534,6 +549,17 @@ export async function materializePack(pack, launchDirectory) {
     await mkdir(dirname(target), { recursive: true, mode: 0o700 });
     await writeFile(target, file.content, { mode: 0o600, flag: 'wx' });
   }
+  return base;
+}
+
+/**
+ * Write a verified pack as a Claude Code plugin inside the launch's private
+ * directory and return the plugin root. The manifest is the client's own.
+ * @param {VerifiedPack} pack
+ * @param {string} launchDirectory
+ */
+export async function materializePack(pack, launchDirectory) {
+  const base = await writePackFiles(pack, launchDirectory);
   const manifest = {
     name: PLUGIN_NAME,
     version: `0.0.0-${pack.packVersion}`,
@@ -553,6 +579,92 @@ export async function materializePack(pack, launchDirectory) {
   return base;
 }
 
+/**
+ * Front-matter values (one `key: value` per line, lower-cased keys, matching
+ * outer quotes removed) and the body after it; null without front matter.
+ * @param {string} content
+ * @returns {{ values: Map<string, string>, body: string } | null}
+ */
+export function splitFrontMatter(content) {
+  if (!content.startsWith(FRONT_MATTER_FENCE)) return null;
+  const end = content.indexOf(FRONT_MATTER_CLOSE, FRONT_MATTER_FENCE.length - 1);
+  if (end === -1) return null;
+  /** @type {Map<string, string>} */
+  const values = new Map();
+  for (const line of content.slice(FRONT_MATTER_FENCE.length, end + 1).split('\n')) {
+    const key = FRONT_MATTER_KEY.exec(line)?.[1];
+    if (key === undefined) continue;
+    let value = line.slice(line.indexOf(':') + 1).trim();
+    if (value.length >= 2 && (value[0] === '"' || value[0] === "'") && value.at(-1) === value[0])
+      value = value.slice(1, -1);
+    values.set(key.toLowerCase(), value);
+  }
+  return { values, body: content.slice(end + FRONT_MATTER_CLOSE.length).replace(/^\n+/u, '') };
+}
+
+/**
+ * A Codex agent role file from a pack agent (`agents/<name>.md`): the front
+ * matter's name and description, the body as developer instructions, and the
+ * origin mark kept as a comment. Null when the agent cannot be a role.
+ * @param {PackFile} file
+ * @returns {{ name: string, description: string, toml: string } | null}
+ */
+export function codexRoleOf(file) {
+  const fileName = AGENT_FILE.exec(file.path)?.[1];
+  const parsed = splitFrontMatter(file.content);
+  if (fileName === undefined || parsed === null) return null;
+  const name = parsed.values.get('name');
+  const description = parsed.values.get('description');
+  if (name !== fileName || !AGENT_NAME.test(name)) return null;
+  if (
+    description === undefined ||
+    description.length === 0 ||
+    description.length > MAX_AGENT_DESCRIPTION_LENGTH ||
+    description === '>' ||
+    description === '|' ||
+    parsed.body.trim().length === 0
+  )
+    return null;
+  const watermark = parsed.values.get(WATERMARK_KEY);
+  const lines = [
+    '# AISAC Engineering. Licensed to your account; do not redistribute.',
+    ...(watermark !== undefined && WATERMARK_VALUE.test(watermark)
+      ? [`# ${WATERMARK_KEY}: ${watermark}`]
+      : []),
+    `name = ${tomlBasicString(name)}`,
+    `description = ${tomlBasicString(description)}`,
+    `developer_instructions = ${tomlBasicString(parsed.body)}`,
+  ];
+  return { name, description, toml: `${lines.join('\n')}\n` };
+}
+
+/**
+ * Write a verified pack for the Codex app-server this launch owns: the files
+ * as for Claude (without the Claude manifest), one role file per agent in
+ * `codex-agents/`, and the description the monitor turns into session
+ * arguments. Output styles have no Codex equivalent and stay unused.
+ * @param {VerifiedPack} pack
+ * @param {string} launchDirectory
+ * @returns {Promise<import('./codex-engineering.mjs').CodexEngineering>}
+ */
+export async function materializeCodexPack(pack, launchDirectory) {
+  const base = await writePackFiles(pack, launchDirectory);
+  const skillsRoot = join(base, SKILLS_DIRECTORY);
+  await mkdir(skillsRoot, { recursive: true, mode: 0o700 });
+  const rolesDirectory = join(base, CODEX_AGENTS_DIRECTORY);
+  await mkdir(rolesDirectory, { mode: 0o700 });
+  /** @type {import('./codex-engineering.mjs').CodexAgentRole[]} */
+  const agents = [];
+  for (const file of pack.files) {
+    const role = codexRoleOf(file);
+    if (role === null) continue;
+    const configFile = join(rolesDirectory, `${role.name}.toml`);
+    await writeFile(configFile, role.toml, { mode: 0o600, flag: 'wx' });
+    agents.push({ name: role.name, description: role.description, configFile });
+  }
+  return validateCodexEngineering({ schemaVersion: 1, skillsRoot, agents });
+}
+
 /**
  * One line for the launch, in the pack locale; null when the capability is
  * not offered, so memory-only users see no change.
@@ -594,13 +706,14 @@ export function packNotice(outcome, locale) {
 /**
  * @param {PackOutcome} outcome
  * @param {PackLocale} locale
+ * @param {PackClient} client
  * @returns {LastLaunch}
  */
-function lastLaunchOf(outcome, locale) {
+function lastLaunchOf(outcome, locale, client) {
   return {
     schemaVersion: 1,
     at: new Date().toISOString(),
-    client: 'claude',
+    client,
     state: outcome.outcome,
     reason:
       outcome.outcome === 'unavailable' || outcome.outcome === 'rejected' ? outcome.reason : null,
@@ -610,13 +723,17 @@ function lastLaunchOf(outcome, locale) {
 }
 
 /**
- * Fetch, verify and write the pack for one Claude Code launch. Never throws.
+ * Fetch, verify and write the pack for one Claude Code or Codex launch. Never
+ * throws. `hostSupported: false` (a Codex release older than the verified
+ * mechanism) still checks the license but loads nothing.
  * @param {{ endpoint: string, token: string, root: string, directory: string,
- *   packageRoot: string, env?: NodeJS.ProcessEnv, fetchImpl?: typeof fetch,
- *   timeoutMs?: number }} input
- * @returns {Promise<{ pluginRoot: string | null, line: string | null }>}
+ *   packageRoot: string, client?: PackClient, hostSupported?: boolean,
+ *   env?: NodeJS.ProcessEnv, fetchImpl?: typeof fetch, timeoutMs?: number }} input
+ * @returns {Promise<{ pluginRoot: string | null,
+ *   codex: import('./codex-engineering.mjs').CodexEngineering | null, line: string | null }>}
  */
 export async function prepareEngineeringPack(input) {
+  const client = input.client ?? 'claude';
   const locale = resolvePackLocale(await readStoredLocale(input.root), input.env);
   /** @type {PackOutcome} */
   let outcome;
@@ -632,21 +749,27 @@ export async function prepareEngineeringPack(input) {
   } catch {
     outcome = { outcome: 'unavailable', reason: 'client_error' };
   }
+  if (outcome.outcome === 'loaded' && input.hostSupported === false)
+    outcome = { outcome: 'unavailable', reason: `${client}_outdated` };
   let pluginRoot = null;
+  /** @type {import('./codex-engineering.mjs').CodexEngineering | null} */
+  let codex = null;
   if (outcome.outcome === 'loaded') {
     try {
-      pluginRoot = await materializePack(outcome.pack, input.directory);
+      if (client === 'codex') codex = await materializeCodexPack(outcome.pack, input.directory);
+      else pluginRoot = await materializePack(outcome.pack, input.directory);
     } catch {
+      codex = null;
       await rm(join(input.directory, PACK_DIRECTORY), { recursive: true, force: true }).catch(
         () => undefined,
       );
       outcome = { outcome: 'rejected', reason: 'materialize_failed' };
     }
   }
-  await atomicJson(join(input.root, LAST_LAUNCH_FILE), lastLaunchOf(outcome, locale)).catch(
+  await atomicJson(join(input.root, LAST_LAUNCH_FILE), lastLaunchOf(outcome, locale, client)).catch(
     () => undefined,
   );
-  return { pluginRoot, line: packNotice(outcome, locale) };
+  return { pluginRoot, codex, line: packNotice(outcome, locale) };
 }
 
 /**

package/dist/launch.mjs

@@ -18,6 +18,11 @@ import {
   sweepStaleLaunches,
   writeLaunchMarker,
 } from './engineering-pack.mjs';
+import {
+  CODEX_ENGINEERING_ENV,
+  CODEX_ENGINEERING_SKILLS_ROOT_ENV,
+  supportsCodexEngineering,
+} from './codex-engineering.mjs';
 import {
   CODEX_LAUNCH_ENVELOPE,
   CODEX_MONITOR_CWD,
@@ -132,6 +137,8 @@ function childEnvironment(root) {
   delete environment.CODEX_CONTEXT_COMPACT_AT;
   delete environment[CODEX_LAUNCH_ENVELOPE];
   delete environment[CODEX_MONITOR_CWD];
+  delete environment[CODEX_ENGINEERING_ENV];
+  delete environment[CODEX_ENGINEERING_SKILLS_ROOT_ENV];
   environment.AIBRAIN_STATE_DIR = resolve(root);
   return environment;
 }
@@ -602,8 +609,14 @@ export async function launchClaude(config, root, args, dependencies = {}) {
   return finished;
 }
 
-/** @param {LaunchConfig} config @param {string} root @param {string[]} args */
-export async function launchCodex(config, root, args) {
+/**
+ * @param {LaunchConfig} config
+ * @param {string} root
+ * @param {string[]} args
+ * @param {LaunchDependencies} [dependencies]
+ */
+export async function launchCodex(config, root, args, dependencies = {}) {
+  const preparePack = dependencies.preparePack ?? prepareEngineeringPack;
   const validated = assertConfig(config);
   assertCodexArgs(args);
   const captureLockPlatform = captureLockPlatformCheck();
@@ -654,6 +667,19 @@ export async function launchCodex(config, root, args) {
     await rm(directory, { recursive: true, force: true });
     throw error;
   }
+  // The pack never blocks the launch: every failure starts Codex without it.
+  const engineering = await preparePack({
+    endpoint: validated.endpoint,
+    token: validated.token,
+    root,
+    directory,
+    packageRoot: validated.packageRoot,
+    client: 'codex',
+    hostSupported: supportsCodexEngineering(compatibility.version),
+  }).catch(() => ({ pluginRoot: null, codex: null, line: null }));
+  if (engineering.line !== null) process.stderr.write(`${engineering.line}\n`);
+  if (engineering.codex != null)
+    environment[CODEX_ENGINEERING_ENV] = JSON.stringify(engineering.codex);
   environment.AI_BRAIN_MCP_SERVER = MCP_ALIAS;
   environment.CODEX_BIN = executable;
   environment.CODEX_MONITOR_COMMAND = monitor;

package/dist/monitor.mjs

@@ -12,6 +12,12 @@ import {
   ownedAppServerConfigArgs,
   parseCodexLaunchEnvelope,
 } from './codex-permissions.mjs';
+import {
+  CODEX_ENGINEERING_ENV,
+  CODEX_ENGINEERING_SKILLS_ROOT_ENV,
+  codexEngineeringConfigArgs,
+  parseCodexEngineering,
+} from './codex-engineering.mjs';
 
 const root = dirname(fileURLToPath(import.meta.url));
 const endpoint = process.env.AIBRAIN_MCP_URL?.trim();
@@ -32,6 +38,17 @@ if (parsed.search) throw new Error('aibrain_monitor_endpoint_query');
 const canonical = join(root, 'assets', 'codex-context-compaction.mjs');
 await access(canonical, constants.R_OK);
 const launchEnvelope = parseCodexLaunchEnvelope(process.env[CODEX_LAUNCH_ENVELOPE]);
+// AISAC Engineering (E4c): a malformed value starts the session without the pack.
+let engineering = null;
+try {
+  const stateDir = process.env.AIBRAIN_STATE_DIR;
+  engineering = parseCodexEngineering(
+    process.env[CODEX_ENGINEERING_ENV],
+    stateDir === undefined ? {} : { stateDir },
+  );
+} catch {
+  engineering = null;
+}
 const policyText = process.env.CODEX_CONTEXT_POLICY_JSON;
 let policy;
 if (policyText === undefined) {
@@ -89,6 +106,9 @@ const env = {
 };
 delete env[CODEX_LAUNCH_ENVELOPE];
 delete env[CODEX_APP_SERVER_PROFILE];
+delete env[CODEX_ENGINEERING_ENV];
+delete env[CODEX_ENGINEERING_SKILLS_ROOT_ENV];
+if (engineering !== null) env[CODEX_ENGINEERING_SKILLS_ROOT_ENV] = engineering.skillsRoot;
 if (launchEnvelope?.profile !== undefined) env[CODEX_APP_SERVER_PROFILE] = launchEnvelope.profile;
 if (policy !== null) env.CODEX_CONTEXT_POLICY_JSON = JSON.stringify(policy);
 else delete env.CODEX_CONTEXT_POLICY_JSON;
@@ -109,6 +129,7 @@ const child = spawn(
     '-c',
     'mcp_servers.aibrain_context.bearer_token_env_var="CODEX_RECOVERY_MCP_TOKEN"',
     ...(launchEnvelope === null ? [] : ownedAppServerConfigArgs(launchEnvelope)),
+    ...(engineering === null ? [] : codexEngineeringConfigArgs(engineering)),
   ],
   { cwd: process.cwd(), env, stdio: 'inherit' },
 );

package/dist/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@brunobracaioli/aibrain",
-  "version": "0.4.0-beta.2",
+  "version": "0.4.0-beta.3",
   "type": "module"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunobracaioli/aibrain",
-  "version": "0.4.0-beta.2",
+  "version": "0.4.0-beta.3",
   "private": false,
   "description": "AISAC client for Claude Code and Codex: AI Brain memory, context management and AISAC Engineering",
   "license": "UNLICENSED",