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

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 macOS, with
+Node.js 22 or newer:
 AI Brain memory, context management and, for AISAC Founding Cohort members,
 AISAC Engineering.
 
@@ -14,8 +15,44 @@ 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.
 
-Codex capture also requires the `flock` utility from `util-linux`, normally
-included in Linux/WSL. The launcher and doctor check availability before a
+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.
+
+On Linux/WSL, Codex capture also requires the `flock` utility from `util-linux`,
+normally included. On macOS it uses `/usr/bin/perl`, `/usr/sbin/sysctl` and
+`/bin/ps` instead. 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,
@@ -23,7 +60,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 +76,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,8 +103,10 @@ 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
-this beta.
+run the beta inside WSL. On macOS, Codex capture locks with the system
+`/usr/bin/perl` (`flock(2)`) and identifies the lock owner with `sysctl` and
+`ps`, so nothing extra needs installing. Pricing and general customer
+activation are outside this beta.
 
 For reviewed noninteractive automation only, use a private token file and
 explicitly acknowledge the displayed disclosure with

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;
@@ -1001,6 +1007,128 @@ async function processIdentity(pid) {
   }
 }
 
+// macOS has flock(2) but no util-linux helper and no /proc (ADR-0049, spec
+// codex-macos). The guard helper and the owner identity use fixed system paths:
+// never PATH lookups, never a shell.
+const DARWIN_CAPTURE_TOOLS = Object.freeze({
+  perl: '/usr/bin/perl',
+  sysctl: '/usr/sbin/sysctl',
+  ps: '/bin/ps',
+});
+const DARWIN_FLOCK_ARGS = Object.freeze([
+  '-MFcntl=:flock',
+  '-e',
+  'open(my $f, "+<&=", 3) or exit 2; exit(flock($f, LOCK_EX | LOCK_NB) ? 0 : 1)',
+]);
+const DARWIN_TOOL_ENV = Object.freeze({ LC_ALL: 'C', TZ: 'UTC', PATH: '/usr/bin:/bin:/usr/sbin' });
+const DARWIN_TOOL_TIMEOUT_MS = 2_000;
+const DARWIN_TOOL_MAX_OUTPUT_BYTES = 4096;
+const DARWIN_START_TIME = /^[\x20-\x7e]{1,64}$/u;
+const BOOT_SESSION = /^[a-f0-9-]{36}$/iu;
+const PS_NO_MATCHING_PROCESS = 1;
+
+/** Platform and tool paths of the capture lock; replaced only by tests. */
+let captureLockHost = { platform: process.platform, tools: DARWIN_CAPTURE_TOOLS };
+
+export function __testSetCaptureLockHost(host) {
+  const previous = captureLockHost;
+  captureLockHost = host;
+  return previous;
+}
+
+function guardHelperCommand() {
+  return captureLockHost.platform === 'darwin'
+    ? [captureLockHost.tools.perl, [...DARWIN_FLOCK_ARGS]]
+    : ['flock', ['-x', '-n', '3']];
+}
+
+/** @returns {Promise<{ code: number | null, stdout: string }>} */
+function runDarwinTool(command, args) {
+  return new Promise((resolvePromise) => {
+    const child = spawn(command, args, {
+      env: DARWIN_TOOL_ENV,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    let stdout = '';
+    let settled = false;
+    const finish = (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolvePromise({ code, stdout });
+    };
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      finish(null);
+    }, DARWIN_TOOL_TIMEOUT_MS);
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk;
+      if (Buffer.byteLength(stdout) > DARWIN_TOOL_MAX_OUTPUT_BYTES) {
+        child.kill('SIGKILL');
+        finish(null);
+      }
+    });
+    child.once('error', () => finish(null));
+    child.once('close', (code) => finish(code));
+  });
+}
+
+async function darwinBootSession() {
+  const result = await runDarwinTool(captureLockHost.tools.sysctl, ['-n', 'kern.bootsessionuuid']);
+  const value = result.stdout.trim();
+  return result.code === 0 && BOOT_SESSION.test(value) ? value.toUpperCase() : null;
+}
+
+async function darwinProcessIdentity(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return { status: 'invalid' };
+  const bootSession = await darwinBootSession();
+  if (bootSession === null) return { status: 'unverifiable' };
+  const result = await runDarwinTool(captureLockHost.tools.ps, [
+    '-o',
+    'lstart=',
+    '-p',
+    String(pid),
+  ]);
+  const startTime = result.stdout.trim();
+  // BSD ps exits 1 with no output when no process matches the pid.
+  if (result.code === PS_NO_MATCHING_PROCESS && startTime === '') return { status: 'dead' };
+  if (result.code !== 0 || !DARWIN_START_TIME.test(startTime)) return { status: 'unverifiable' };
+  return { status: 'live', startTime, bootSession };
+}
+
+async function darwinSentinelOwner(value) {
+  if (
+    !isRecord(value) ||
+    !hasOnlyKeys(value, [
+      'schema',
+      'backend',
+      'platform',
+      'pid',
+      'startTime',
+      'bootSession',
+      'nonce',
+    ]) ||
+    value.schema !== 1 ||
+    value.backend !== 'flock' ||
+    value.platform !== 'darwin' ||
+    !isSafeBoundedInteger(value.pid, 1, 4_000_000_000) ||
+    typeof value.startTime !== 'string' ||
+    !DARWIN_START_TIME.test(value.startTime) ||
+    typeof value.bootSession !== 'string' ||
+    !BOOT_SESSION.test(value.bootSession) ||
+    typeof value.nonce !== 'string' ||
+    !isUuid(value.nonce)
+  )
+    return { status: 'unverifiable' };
+  const observer = await darwinBootSession();
+  if (observer === null) return { status: 'unverifiable' };
+  if (observer !== value.bootSession.toUpperCase()) return { status: 'dead' };
+  const current = await darwinProcessIdentity(value.pid);
+  if (current.status !== 'live') return { status: current.status };
+  return current.startTime === value.startTime ? { status: 'live' } : { status: 'dead' };
+}
+
 async function captureSentinelOwner(lockPath, fsOps) {
   let info;
   try {
@@ -1019,6 +1147,7 @@ async function captureSentinelOwner(lockPath, fsOps) {
   } catch {
     return { status: 'unverifiable' };
   }
+  if (captureLockHost.platform === 'darwin') return darwinSentinelOwner(value);
   if (
     !isRecord(value) ||
     !hasOnlyKeys(value, [
@@ -1054,10 +1183,23 @@ async function captureSentinelOwner(lockPath, fsOps) {
   return current.startTime === value.startTime ? { status: 'live' } : { status: 'dead' };
 }
 
-async function ensureCaptureSentinel(lockPath, task) {
+async function ownSentinelRecord() {
+  if (captureLockHost.platform === 'darwin') {
+    const identity = await darwinProcessIdentity(process.pid);
+    if (identity.status !== 'live') throw captureLockError('capture_lock_owner_unverifiable');
+    return {
+      schema: 1,
+      backend: 'flock',
+      platform: 'darwin',
+      pid: process.pid,
+      startTime: identity.startTime,
+      bootSession: identity.bootSession,
+      nonce: randomUUID(),
+    };
+  }
   const identity = await processIdentity(process.pid);
   if (identity.status !== 'live') throw captureLockError('capture_lock_owner_unverifiable');
-  const metadata = `${JSON.stringify({
+  return {
     schema: 1,
     backend: 'flock',
     pid: process.pid,
@@ -1065,7 +1207,11 @@ async function ensureCaptureSentinel(lockPath, task) {
     bootId: identity.bootId,
     pidNamespace: identity.pidNamespace,
     nonce: randomUUID(),
-  })}\n`;
+  };
+}
+
+async function ensureCaptureSentinel(lockPath, task) {
+  const metadata = `${JSON.stringify(await ownSentinelRecord())}\n`;
   while (true) {
     const temporary = `${lockPath}.${process.pid}.${randomUUID()}.tmp`;
     let contention = false;
@@ -1143,7 +1289,8 @@ async function withAdvisoryCaptureLock(directory, task) {
   while (true) {
     let helper;
     try {
-      helper = spawn('flock', ['-x', '-n', '3'], {
+      const [command, args] = guardHelperCommand();
+      helper = spawn(command, args, {
         stdio: ['ignore', 'ignore', 'ignore', guardHandle.fd],
       });
       const acquired = await new Promise((resolvePromise, rejectPromise) => {
@@ -2707,6 +2854,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 +2868,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 +4289,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 +4527,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 +4599,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 +4609,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 +4670,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 +4759,7 @@ export function createCodexContextProxy({
     }
   });
   child.stdout.on('end', () => {
+    releaseEngineering();
     const tail = inputBuffer + decoder.end();
     if (tail && !discardOversized) forward(tail);
     inputBuffer = '';
@@ -4565,6 +4789,7 @@ export function createCodexContextProxy({
     observeClientRequest,
     observeClientResponse,
     async stop() {
+      releaseEngineering();
       if (stopped) {
         await Promise.all(
           [...diagnosticSinks.values()].map((sink) =>
@@ -4594,6 +4819,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 +4885,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/assets/jev-paid-pilot-terminal.mjs

@@ -20,6 +20,8 @@ const MAX_AUXILIARY_IN_FLIGHT = 32;
 const MAX_AUXILIARY_NOTIFICATIONS = 256;
 const DEFAULT_AUXILIARY_IDLE_TIMEOUT_MS = 120_000;
 const NORMAL_DISCOVERY_CLOSE_CODES = new Set([1000, 1001, 1005]);
+// Smallest sun_path among supported hosts: macOS 104 bytes, minus the terminator.
+const UNIX_SOCKET_PATH_MAX_BYTES = 103;
 
 function repoRoot() {
   return fileURLToPath(new URL('..', import.meta.url)).replace(/\/$/u, '');
@@ -1022,6 +1024,10 @@ async function main() {
     });
   });
   try {
+    // macOS sun_path holds 104 bytes including the terminator (Linux 108); refuse a
+    // path that the kernel would truncate or reject instead of binding elsewhere.
+    if (Buffer.byteLength(socketPath) > UNIX_SOCKET_PATH_MAX_BYTES)
+      throw new Error('terminal_bridge_socket_path_too_long');
     await new Promise((resolve, reject) => {
       server.once('error', reject);
       server.listen(socketPath, async () => {

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.11';
 const MAX_DIAGNOSTIC_COUNT = 10_000_000;
 const MAX_DIAGNOSTIC_BYTES = 128 * 1024 * 1024;
 const CHECKPOINT_BACKENDS = new Set(['native_store', 'private_file']);