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

package/README.md

@@ -14,6 +14,13 @@ 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.
+
 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/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.2';
 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

@@ -29,8 +29,15 @@ 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';
 
-const VERSION = '0.4.0-beta.1';
+const VERSION = '0.4.0-beta.2';
 // 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 +55,7 @@ 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` 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`.',
   );
 }
 
@@ -310,6 +317,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 +412,7 @@ async function setup(args) {
       '--telemetry',
       '--claude-shadow',
       '--claude-diagnostics',
+      '--lang',
     ]),
     new Set([
       '--client',
@@ -396,10 +424,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 =
@@ -501,6 +533,7 @@ 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);
@@ -599,6 +632,7 @@ async function doctor(json) {
         config?.claudeObservation?.disclosedAt !== undefined,
     },
     engineering,
+    engineeringPack: await engineeringPackState(),
     paidOrPilot: probe?.ok
       ? 'provider_free_probe_ok; paid entitlement or pilot invitation remains server-enforced'
       : config
@@ -634,6 +668,7 @@ async function status(json) {
         config?.claudeObservation?.disclosedAt !== null &&
         config?.claudeObservation?.disclosedAt !== undefined,
     },
+    engineeringPack: await engineeringPackState(),
     monitoredSession: null,
     monitoringStatus: 'not_observed',
   };

package/dist/engineering-pack-public-key.json

@@ -0,0 +1,10 @@
+{
+  "schema_version": 1,
+  "keys": [
+    {
+      "key_id": "c197814f9e4884ac",
+      "x": "Oict0CKYWwgmFovl3TDPJUJ3C4do9Nu6xXU6m4PPOQc",
+      "created": "2026-11-02"
+    }
+  ]
+}

package/dist/engineering-pack.mjs

@@ -0,0 +1,722 @@
+// @ts-check
+
+/**
+ * AISAC Engineering pack for Claude Code (ADR-0047 wave E4b, 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`.
+ * Any failure starts the session without the pack; nothing here can block a
+ * launch or treat a failure as licensed.
+ */
+
+import { createHash, createPublicKey, verify } from 'node:crypto';
+import { constants } from 'node:fs';
+import {
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  stat,
+  unlink,
+  writeFile,
+} from 'node:fs/promises';
+import { dirname, join, resolve, sep } from 'node:path';
+import {
+  isPurchaseUrl,
+  isRecord,
+  isTimeout,
+  readBoundedText,
+  unavailableReasonFor,
+} from './engineering.mjs';
+import { atomicJson } from './state.mjs';
+
+const PACK_PATH = '/engineering/v1/pack';
+export const PACK_TIMEOUT_MS = 10_000;
+/** Vercel caps a function response at 4.5 MB; the pack itself is at most 2 MiB. */
+const MAX_PACK_BODY_BYTES = 5 * 1024 * 1024;
+const MAX_ERROR_BODY_BYTES = 16 * 1024;
+const PACK_SCHEMA_VERSION = 1;
+export const PACK_LOCALES = /** @type {const} */ (['pt-BR', 'en']);
+const DEFAULT_LOCALE = 'pt-BR';
+const DEFAULT_PURCHASE_URL = 'https://aisac.community/';
+
+// FR3 bounds, mirrored from the server; served files carry one extra
+// watermark line in their front matter.
+const MAX_PACK_FILES = 200;
+const MAX_PACK_FILE_BYTES = 64 * 1024;
+const MAX_PACK_TOTAL_BYTES = 2 * 1024 * 1024;
+const WATERMARK_ALLOWANCE_BYTES = 64;
+const MAX_PACK_PATH_LENGTH = 256;
+const PATH_CHARACTERS = /^[A-Za-z0-9._/-]+$/u;
+const MARKDOWN_EXTENSION = '.md';
+const PACK_VERSION = /^sha256-[0-9a-f]{12}$/u;
+const HEX_16 = /^[0-9a-f]{16}$/u;
+const SHA256_HEX = /^[0-9a-f]{64}$/u;
+const BASE64 = /^[A-Za-z0-9+/]{86}==$/u;
+const ISO_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u;
+const ED25519_SIGNATURE_BYTES = 64;
+const ED25519_RAW_KEY_BYTES = 32;
+const KEY_ID_HEX_LENGTH = 16;
+const MAX_PINNED_KEYS = 4;
+const DYNAMIC_SHELL_MARKER = '!`';
+const FRONT_MATTER_FENCE = '---\n';
+const FRONT_MATTER_CLOSE = '\n---\n';
+const FRONT_MATTER_TRAILING_CLOSE = '\n---';
+const FRONT_MATTER_KEY = /^([A-Za-z0-9_-]+)[ \t]*:/u;
+const FORBIDDEN_FRONT_MATTER_KEYS = new Set([
+  'allowed-tools',
+  'allowed_tools',
+  'hooks',
+  'mcpservers',
+  'mcp-servers',
+  'mcp_servers',
+  'permissionmode',
+  'permission-mode',
+  'permission_mode',
+  'permissions',
+]);
+
+const PLUGIN_NAME = 'aisac-engineering';
+const PLUGIN_LICENSE = 'LicenseRef-AISAC-Engineering';
+const PACK_DIRECTORY = 'engineering';
+const OUTPUT_STYLES_PREFIX = 'output-styles/';
+export const PUBLIC_KEY_FILE = 'engineering-pack-public-key.json';
+const LOCALE_FILE = 'engineering-locale.json';
+const LAST_LAUNCH_FILE = 'engineering-last-launch.json';
+export const LAUNCH_MARKER_FILE = 'launch.json';
+const MAX_SMALL_STATE_BYTES = 4 * 1024;
+const LAUNCH_DIRECTORY = /^(?:claude|codex)-[A-Za-z0-9]{6}$/u;
+const SAFE_REASON = /^[a-z][a-z0-9_]{0,63}$/u;
+
+/** @typedef {(typeof PACK_LOCALES)[number]} PackLocale */
+/** @typedef {{ path: string, sha256: string, content: string }} PackFile */
+/**
+ * @typedef {{
+ *   packVersion: string,
+ *   locale: PackLocale,
+ *   issuedAt: string,
+ *   keyId: string,
+ *   files: PackFile[]
+ * }} VerifiedPack
+ */
+/** @typedef {{ keyId: string, key: import('node:crypto').KeyObject }} PinnedKey */
+/**
+ * @typedef {{ outcome: 'loaded', pack: VerifiedPack }
+ *   | { outcome: 'inactive', purchaseUrl: string }
+ *   | { outcome: 'not_offered' }
+ *   | { outcome: 'unavailable', reason: string }
+ *   | { outcome: 'rejected', reason: string }} PackOutcome
+ */
+/**
+ * @typedef {{
+ *   schemaVersion: 1,
+ *   at: string,
+ *   client: 'claude',
+ *   state: PackOutcome['outcome'],
+ *   reason: string | null,
+ *   packVersion: string | null,
+ *   locale: PackLocale
+ * }} LastLaunch
+ */
+
+/** @param {unknown} value @returns {value is PackLocale} */
+export function isPackLocale(value) {
+  return value === 'pt-BR' || value === 'en';
+}
+
+/**
+ * The stored choice first, then the OS locale, then pt-BR (spec FR3).
+ * @param {string | null} stored
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {PackLocale}
+ */
+export function resolvePackLocale(stored, env = process.env) {
+  if (isPackLocale(stored)) return stored;
+  const candidates = [
+    env.LC_ALL,
+    env.LC_MESSAGES,
+    env.LANG,
+    Intl.DateTimeFormat().resolvedOptions().locale,
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate !== 'string') continue;
+    const value = candidate.trim().toLowerCase();
+    if (value === '' || value === 'c' || value === 'posix' || value.startsWith('c.')) continue;
+    if (value.startsWith('pt')) return 'pt-BR';
+    if (value.startsWith('en')) return 'en';
+    return DEFAULT_LOCALE;
+  }
+  return DEFAULT_LOCALE;
+}
+
+/**
+ * Read a small owned JSON state file; null when it is missing or not a plain,
+ * owned, private file.
+ * @param {string} path
+ * @returns {Promise<unknown>}
+ */
+async function readSmallStateJson(path) {
+  let handle;
+  try {
+    const link = await lstat(path);
+    if (!link.isFile() || link.size > MAX_SMALL_STATE_BYTES) return null;
+    if (typeof process.getuid === 'function' && link.uid !== process.getuid()) return null;
+    handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    return JSON.parse(await handle.readFile('utf8'));
+  } catch {
+    return null;
+  } finally {
+    await handle?.close().catch(() => undefined);
+  }
+}
+
+/** @param {string} root @returns {Promise<PackLocale | null>} */
+export async function readStoredLocale(root) {
+  const value = await readSmallStateJson(join(root, LOCALE_FILE));
+  return isRecord(value) && value.schemaVersion === 1 && isPackLocale(value.locale)
+    ? value.locale
+    : null;
+}
+
+/** @param {string} root @param {PackLocale} locale */
+export async function writeStoredLocale(root, locale) {
+  if (!isPackLocale(locale)) throw new Error('invalid_lang');
+  await atomicJson(join(root, LOCALE_FILE), { schemaVersion: 1, locale });
+}
+
+/** @param {string} root @returns {Promise<LastLaunch | null>} */
+export async function readLastLaunch(root) {
+  const value = await readSmallStateJson(join(root, LAST_LAUNCH_FILE));
+  if (
+    !isRecord(value) ||
+    value.schemaVersion !== 1 ||
+    typeof value.at !== 'string' ||
+    !ISO_INSTANT.test(value.at) ||
+    value.client !== 'claude' ||
+    !['loaded', 'inactive', 'not_offered', 'unavailable', 'rejected'].includes(
+      /** @type {string} */ (value.state),
+    ) ||
+    (value.reason !== null &&
+      (typeof value.reason !== 'string' || !SAFE_REASON.test(value.reason))) ||
+    (value.packVersion !== null &&
+      (typeof value.packVersion !== 'string' || !PACK_VERSION.test(value.packVersion))) ||
+    !isPackLocale(value.locale)
+  )
+    return null;
+  return /** @type {LastLaunch} */ (value);
+}
+
+/** @param {string} endpoint @param {PackLocale} locale */
+export function engineeringPackUrl(endpoint, locale) {
+  const url = new URL(PACK_PATH, endpoint);
+  url.searchParams.set('locale', locale);
+  return url.toString();
+}
+
+/** @param {Buffer} raw */
+function keyIdOfRaw(raw) {
+  return createHash('sha256').update(raw).digest('hex').slice(0, KEY_ID_HEX_LENGTH);
+}
+
+/**
+ * Parse the pinned public keys shipped with the client release.
+ * @param {string} text
+ * @returns {PinnedKey[]}
+ */
+export function parsePinnedKeys(text) {
+  const document = JSON.parse(text);
+  if (
+    !isRecord(document) ||
+    document.schema_version !== 1 ||
+    !Array.isArray(document.keys) ||
+    document.keys.length < 1 ||
+    document.keys.length > MAX_PINNED_KEYS
+  )
+    throw new Error('pinned_keys_invalid');
+  return document.keys.map((entry) => {
+    if (!isRecord(entry) || typeof entry.key_id !== 'string' || typeof entry.x !== 'string')
+      throw new Error('pinned_keys_invalid');
+    const raw = Buffer.from(entry.x, 'base64url');
+    if (raw.length !== ED25519_RAW_KEY_BYTES || raw.toString('base64url') !== entry.x)
+      throw new Error('pinned_keys_invalid');
+    if (keyIdOfRaw(raw) !== entry.key_id) throw new Error('pinned_key_id_mismatch');
+    const key = createPublicKey({
+      key: { kty: 'OKP', crv: 'Ed25519', x: entry.x },
+      format: 'jwk',
+    });
+    return { keyId: entry.key_id, key };
+  });
+}
+
+/**
+ * The keys ship inside the installed package, which a global install may own
+ * as root, so only the size is bounded here (unlike private state files).
+ * @param {string} packageRoot
+ * @returns {Promise<PinnedKey[]>}
+ */
+export async function loadPinnedKeys(packageRoot) {
+  const path = join(packageRoot, PUBLIC_KEY_FILE);
+  const entry = await stat(path);
+  if (!entry.isFile() || entry.size > MAX_SMALL_STATE_BYTES) throw new Error('pinned_keys_invalid');
+  return parsePinnedKeys(await readFile(path, 'utf8'));
+}
+
+/**
+ * Canonical JSON, identical to the server's: object keys sorted by UTF-16
+ * code unit, no whitespace, JSON.stringify string escaping, safe integers.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function canonicalJson(value) {
+  if (typeof value === 'number') {
+    if (!Number.isSafeInteger(value)) throw new Error('canonical_json_number');
+    return JSON.stringify(value);
+  }
+  if (value === null || typeof value === 'string' || typeof value === 'boolean')
+    return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (isRecord(value)) {
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`;
+  }
+  throw new Error('canonical_json_value');
+}
+
+/** Top-level front-matter keys, lower-cased (same parser as the server). @param {string} content */
+export function frontMatterKeys(content) {
+  if (!content.startsWith(FRONT_MATTER_FENCE)) return [];
+  const searchFrom = FRONT_MATTER_FENCE.length - 1;
+  let end = content.indexOf(FRONT_MATTER_CLOSE, searchFrom);
+  if (end === -1 && content.endsWith(FRONT_MATTER_TRAILING_CLOSE))
+    end = content.length - FRONT_MATTER_TRAILING_CLOSE.length;
+  if (end < searchFrom) return [];
+  return content
+    .slice(FRONT_MATTER_FENCE.length, end + 1)
+    .split('\n')
+    .flatMap((line) => {
+      const key = FRONT_MATTER_KEY.exec(line)?.[1];
+      return key === undefined ? [] : [key.toLowerCase()];
+    });
+}
+
+/** Relative, `[A-Za-z0-9._/-]`, `.md`, no empty, dot or hidden segment. @param {unknown} path */
+export function isValidPackPath(path) {
+  if (typeof path !== 'string' || path.length === 0 || path.length > MAX_PACK_PATH_LENGTH)
+    return false;
+  if (!PATH_CHARACTERS.test(path) || !path.endsWith(MARKDOWN_EXTENSION)) return false;
+  return path.split('/').every((segment) => segment.length > 0 && !segment.startsWith('.'));
+}
+
+/** @param {string} reason @returns {{ ok: false, reason: string }} */
+function refused(reason) {
+  return { ok: false, reason };
+}
+
+/**
+ * FR3 rules re-applied on the client, then each file's hash.
+ * @param {unknown} files
+ * @returns {{ ok: true, files: PackFile[] } | { ok: false, reason: string }}
+ */
+function checkFiles(files) {
+  if (!Array.isArray(files) || files.length === 0) return refused('invalid_response');
+  if (files.length > MAX_PACK_FILES) return refused('bounds_exceeded');
+  const seen = new Set();
+  /** @type {PackFile[]} */
+  const accepted = [];
+  let total = 0;
+  for (const file of files) {
+    if (!isRecord(file) || typeof file.content !== 'string' || typeof file.sha256 !== 'string')
+      return refused('invalid_response');
+    if (!isValidPackPath(file.path)) return refused('invalid_path');
+    const path = /** @type {string} */ (file.path);
+    if (seen.has(path)) return refused('invalid_path');
+    seen.add(path);
+    if (!SHA256_HEX.test(file.sha256)) return refused('invalid_response');
+    const bytes = Buffer.byteLength(file.content, 'utf8');
+    if (bytes > MAX_PACK_FILE_BYTES + WATERMARK_ALLOWANCE_BYTES) return refused('bounds_exceeded');
+    total += bytes;
+    if (file.content.includes('\r')) return refused('forbidden_content');
+    if (frontMatterKeys(file.content).some((key) => FORBIDDEN_FRONT_MATTER_KEYS.has(key)))
+      return refused('forbidden_content');
+    if (file.content.includes(DYNAMIC_SHELL_MARKER)) return refused('forbidden_content');
+    const digest = createHash('sha256').update(file.content, 'utf8').digest('hex');
+    if (digest !== file.sha256) return refused('file_hash_mismatch');
+    accepted.push({ path, sha256: file.sha256, content: file.content });
+  }
+  if (total > MAX_PACK_TOTAL_BYTES + MAX_PACK_FILES * WATERMARK_ALLOWANCE_BYTES)
+    return refused('bounds_exceeded');
+  return { ok: true, files: accepted };
+}
+
+/**
+ * Verify a `200` pack body. Any failure rejects the whole pack.
+ * @param {string} text
+ * @param {readonly PinnedKey[]} keys
+ * @param {PackLocale} expectedLocale
+ * @returns {{ ok: true, pack: VerifiedPack } | { ok: false, reason: string }}
+ */
+export function verifyPack(text, keys, expectedLocale) {
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    return refused('invalid_response');
+  }
+  if (!isRecord(body)) return refused('invalid_response');
+  if (body.schema_version !== PACK_SCHEMA_VERSION)
+    return refused(
+      Number.isSafeInteger(body.schema_version) &&
+        /** @type {number} */ (body.schema_version) > PACK_SCHEMA_VERSION
+        ? 'client_outdated'
+        : 'invalid_response',
+    );
+  const { signature, ...unsigned } = body;
+  if (typeof signature !== 'string' || !BASE64.test(signature)) return refused('invalid_response');
+  if (typeof body.key_id !== 'string' || !HEX_16.test(body.key_id))
+    return refused('invalid_response');
+  const keyId = body.key_id;
+  const pinned = keys.find((candidate) => candidate.keyId === keyId);
+  if (pinned === undefined) return refused('unknown_key');
+  let message;
+  try {
+    message = canonicalJson(unsigned);
+  } catch {
+    return refused('invalid_response');
+  }
+  const signatureBytes = Buffer.from(signature, 'base64');
+  if (signatureBytes.length !== ED25519_SIGNATURE_BYTES) return refused('invalid_response');
+  let valid;
+  try {
+    valid = verify(null, Buffer.from(message, 'utf8'), pinned.key, signatureBytes);
+  } catch {
+    valid = false;
+  }
+  if (!valid) return refused('bad_signature');
+  if (body.locale !== expectedLocale) return refused('locale_mismatch');
+  if (
+    typeof body.pack_version !== 'string' ||
+    !PACK_VERSION.test(body.pack_version) ||
+    typeof body.issued_at !== 'string' ||
+    !ISO_INSTANT.test(body.issued_at) ||
+    typeof body.watermark !== 'string' ||
+    !HEX_16.test(body.watermark)
+  )
+    return refused('invalid_response');
+  const checked = checkFiles(body.files);
+  if (!checked.ok) return checked;
+  return {
+    ok: true,
+    pack: {
+      packVersion: body.pack_version,
+      locale: expectedLocale,
+      issuedAt: body.issued_at,
+      keyId,
+      files: checked.files,
+    },
+  };
+}
+
+/** @param {string} text */
+function errorCodeOf(text) {
+  try {
+    const value = JSON.parse(text);
+    return isRecord(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Ask the server for the pack. The answer is the live license decision.
+ * @param {string} endpoint
+ * @param {string} token
+ * @param {PackLocale} locale
+ * @param {{ fetchImpl?: typeof fetch, timeoutMs?: number }} [options]
+ * @returns {Promise<PackOutcome | { outcome: 'received', text: string }>}
+ */
+export async function fetchPack(endpoint, token, locale, options = {}) {
+  const { fetchImpl = fetch, timeoutMs = PACK_TIMEOUT_MS } = options;
+  let url;
+  try {
+    url = engineeringPackUrl(endpoint, locale);
+  } catch {
+    return { outcome: 'unavailable', reason: 'invalid_endpoint' };
+  }
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      method: 'GET',
+      redirect: 'error',
+      signal: AbortSignal.timeout(timeoutMs),
+      headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
+    });
+  } catch (error) {
+    return { outcome: 'unavailable', reason: isTimeout(error) ? 'timeout' : 'unreachable' };
+  }
+  if (response.status === 404) {
+    await response.body?.cancel().catch(() => undefined);
+    return { outcome: 'not_offered' };
+  }
+  let text;
+  try {
+    text = await readBoundedText(
+      response,
+      response.status === 200 ? MAX_PACK_BODY_BYTES : MAX_ERROR_BODY_BYTES,
+    );
+  } catch (error) {
+    return {
+      outcome: 'unavailable',
+      reason: isTimeout(error) ? 'timeout' : 'invalid_response',
+    };
+  }
+  if (response.status === 200) return { outcome: 'received', text };
+  const error = errorCodeOf(text);
+  if (response.status === 403 && error?.error === 'license_inactive') {
+    return {
+      outcome: 'inactive',
+      purchaseUrl: isPurchaseUrl(error.purchase_url) ? error.purchase_url : DEFAULT_PURCHASE_URL,
+    };
+  }
+  if (response.status === 503 && error?.error === 'pack_unavailable')
+    return { outcome: 'unavailable', reason: 'pack_unavailable' };
+  if (response.status === 403) return { outcome: 'unavailable', reason: 'unexpected_status' };
+  return { outcome: 'unavailable', reason: unavailableReasonFor(response.status) };
+}
+
+/**
+ * @param {{ endpoint: string, token: string, locale: PackLocale, packageRoot: string,
+ *   fetchImpl?: typeof fetch, timeoutMs?: number }} input
+ * @returns {Promise<PackOutcome>}
+ */
+export async function obtainPack(input) {
+  let keys;
+  try {
+    keys = await loadPinnedKeys(input.packageRoot);
+  } catch {
+    return { outcome: 'rejected', reason: 'pinned_keys_invalid' };
+  }
+  const answer = await fetchPack(input.endpoint, input.token, input.locale, {
+    ...(input.fetchImpl === undefined ? {} : { fetchImpl: input.fetchImpl }),
+    ...(input.timeoutMs === undefined ? {} : { timeoutMs: input.timeoutMs }),
+  });
+  if (answer.outcome !== 'received') return answer;
+  const verified = verifyPack(answer.text, keys, input.locale);
+  return verified.ok
+    ? { outcome: 'loaded', pack: verified.pack }
+    : { outcome: 'rejected', reason: verified.reason };
+}
+
+/** @type {Readonly<Record<PackLocale, string>>} */
+const PLUGIN_DESCRIPTION = {
+  'pt-BR': 'Método AISAC Engineering, licenciado para a sua conta. Não redistribua.',
+  en: 'AISAC Engineering method, licensed to your account. Do not redistribute.',
+};
+
+/**
+ * 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 = resolve(launchDirectory, PACK_DIRECTORY);
+  await mkdir(base, { mode: 0o700 });
+  for (const file of pack.files) {
+    if (!isValidPackPath(file.path)) throw new Error('pack_path_invalid');
+    const target = resolve(base, ...file.path.split('/'));
+    if (!target.startsWith(`${base}${sep}`)) throw new Error('pack_path_escape');
+    await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+    await writeFile(target, file.content, { mode: 0o600, flag: 'wx' });
+  }
+  const manifest = {
+    name: PLUGIN_NAME,
+    version: `0.0.0-${pack.packVersion}`,
+    description: PLUGIN_DESCRIPTION[pack.locale],
+    author: { name: 'AISAC' },
+    license: PLUGIN_LICENSE,
+    ...(pack.files.some((file) => file.path.startsWith(OUTPUT_STYLES_PREFIX))
+      ? { outputStyles: `./${OUTPUT_STYLES_PREFIX}` }
+      : {}),
+  };
+  await mkdir(join(base, '.claude-plugin'), { mode: 0o700 });
+  await writeFile(
+    join(base, '.claude-plugin', 'plugin.json'),
+    `${JSON.stringify(manifest, null, 2)}\n`,
+    { mode: 0o600, flag: 'wx' },
+  );
+  return base;
+}
+
+/**
+ * One line for the launch, in the pack locale; null when the capability is
+ * not offered, so memory-only users see no change.
+ * @param {PackOutcome} outcome
+ * @param {PackLocale} locale
+ * @returns {string | null}
+ */
+export function packNotice(outcome, locale) {
+  const pt = locale === 'pt-BR';
+  const without = pt ? 'a sessão começa sem o método.' : 'the session starts without the method.';
+  switch (outcome.outcome) {
+    case 'not_offered':
+      return null;
+    case 'loaded':
+      return pt
+        ? `AISAC Engineering: método carregado (${outcome.pack.packVersion}, ${locale}).`
+        : `AISAC Engineering: method loaded (${outcome.pack.packVersion}, ${locale}).`;
+    case 'inactive':
+      return pt
+        ? `AISAC Engineering: licença inativa — ${outcome.purchaseUrl}`
+        : `AISAC Engineering: license inactive — ${outcome.purchaseUrl}`;
+    case 'unavailable':
+      return pt
+        ? `AISAC Engineering: indisponível (${outcome.reason}); ${without}`
+        : `AISAC Engineering: unavailable (${outcome.reason}); ${without}`;
+    case 'rejected':
+      if (outcome.reason === 'client_outdated')
+        return pt
+          ? `AISAC Engineering: atualize o aisac (npm install -g @aisac/cli@beta); ${without}`
+          : `AISAC Engineering: update aisac (npm install -g @aisac/cli@beta); ${without}`;
+      return pt
+        ? `AISAC Engineering: pacote recusado (${outcome.reason}); ${without}`
+        : `AISAC Engineering: pack rejected (${outcome.reason}); ${without}`;
+    default:
+      return null;
+  }
+}
+
+/**
+ * @param {PackOutcome} outcome
+ * @param {PackLocale} locale
+ * @returns {LastLaunch}
+ */
+function lastLaunchOf(outcome, locale) {
+  return {
+    schemaVersion: 1,
+    at: new Date().toISOString(),
+    client: 'claude',
+    state: outcome.outcome,
+    reason:
+      outcome.outcome === 'unavailable' || outcome.outcome === 'rejected' ? outcome.reason : null,
+    packVersion: outcome.outcome === 'loaded' ? outcome.pack.packVersion : null,
+    locale,
+  };
+}
+
+/**
+ * Fetch, verify and write the pack for one Claude Code launch. Never throws.
+ * @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 }>}
+ */
+export async function prepareEngineeringPack(input) {
+  const locale = resolvePackLocale(await readStoredLocale(input.root), input.env);
+  /** @type {PackOutcome} */
+  let outcome;
+  try {
+    outcome = await obtainPack({
+      endpoint: input.endpoint,
+      token: input.token,
+      locale,
+      packageRoot: input.packageRoot,
+      ...(input.fetchImpl === undefined ? {} : { fetchImpl: input.fetchImpl }),
+      ...(input.timeoutMs === undefined ? {} : { timeoutMs: input.timeoutMs }),
+    });
+  } catch {
+    outcome = { outcome: 'unavailable', reason: 'client_error' };
+  }
+  let pluginRoot = null;
+  if (outcome.outcome === 'loaded') {
+    try {
+      pluginRoot = await materializePack(outcome.pack, input.directory);
+    } catch {
+      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(
+    () => undefined,
+  );
+  return { pluginRoot, line: packNotice(outcome, locale) };
+}
+
+/**
+ * Record who owns a launch directory, so a later launch can sweep it once
+ * both processes are gone (spec FR4 step 7).
+ * @param {string} directory
+ * @param {{ launcherPid: number, childPid: number | null }} owners
+ */
+export async function writeLaunchMarker(directory, owners) {
+  const path = join(directory, LAUNCH_MARKER_FILE);
+  const temp = `${path}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    await writeFile(
+      temp,
+      `${JSON.stringify({ schemaVersion: 1, ...owners, startedAt: new Date().toISOString() })}\n`,
+      { mode: 0o600, flag: 'wx' },
+    );
+    await rename(temp, path);
+  } catch (error) {
+    await unlink(temp).catch(() => undefined);
+    throw error;
+  }
+}
+
+/** @param {number} pid */
+export function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return isRecord(error) && error.code === 'EPERM';
+  }
+}
+
+/** @param {unknown} value */
+function isPid(value) {
+  return Number.isSafeInteger(value) && /** @type {number} */ (value) > 0;
+}
+
+/**
+ * Remove launch directories left by crashed launches: only directories with
+ * a marker whose launcher and child are both gone. Never throws.
+ * @param {string} root
+ * @param {(pid: number) => boolean} [alive]
+ * @returns {Promise<number>} directories removed
+ */
+export async function sweepStaleLaunches(root, alive = processAlive) {
+  const runtime = join(root, 'runtime');
+  let entries;
+  try {
+    entries = await readdir(runtime, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  let removed = 0;
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !LAUNCH_DIRECTORY.test(entry.name)) continue;
+    const directory = join(runtime, entry.name);
+    const marker = await readSmallStateJson(join(directory, LAUNCH_MARKER_FILE));
+    if (!isRecord(marker) || marker.schemaVersion !== 1 || !isPid(marker.launcherPid)) continue;
+    const launcherPid = /** @type {number} */ (marker.launcherPid);
+    if (marker.childPid !== null && !isPid(marker.childPid)) continue;
+    const childPid = /** @type {number | null} */ (marker.childPid);
+    if (alive(launcherPid) || (childPid !== null && alive(childPid))) continue;
+    try {
+      await rm(directory, { recursive: true, force: true });
+      removed += 1;
+    } catch {
+      // Left for a later sweep.
+    }
+  }
+  return removed;
+}

package/dist/engineering.mjs

@@ -47,12 +47,12 @@ export function engineeringLicenseUrl(endpoint) {
 }
 
 /** @param {unknown} value @returns {value is Record<string, unknown>} */
-function isRecord(value) {
+export function isRecord(value) {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-/** @param {unknown} value */
-function isPurchaseUrl(value) {
+/** @param {unknown} value @returns {value is string} */
+export function isPurchaseUrl(value) {
   if (typeof value !== 'string' || value.length > MAX_URL_LENGTH) return false;
   try {
     const url = new URL(value);
@@ -97,10 +97,14 @@ export function parseLicenseBody(text) {
   };
 }
 
-/** @param {Response} response */
-async function boundedText(response) {
+/**
+ * Read a response body as UTF-8, refusing anything above `limit` bytes.
+ * @param {Response} response
+ * @param {number} [limit]
+ */
+export async function readBoundedText(response, limit = MAX_LICENSE_BODY_BYTES) {
   const declared = Number(response.headers.get('content-length') ?? '0');
-  if (declared > MAX_LICENSE_BODY_BYTES) throw new Error('license_body_too_large');
+  if (declared > limit) throw new Error('body_too_large');
   if (response.body === null) return '';
   const reader = response.body.getReader();
   /** @type {Uint8Array[]} */
@@ -110,9 +114,9 @@ async function boundedText(response) {
     const { done, value } = await reader.read();
     if (done) break;
     size += value.byteLength;
-    if (size > MAX_LICENSE_BODY_BYTES) {
+    if (size > limit) {
       await reader.cancel().catch(() => undefined);
-      throw new Error('license_body_too_large');
+      throw new Error('body_too_large');
     }
     chunks.push(value);
   }
@@ -120,12 +124,12 @@ async function boundedText(response) {
 }
 
 /** @param {unknown} error */
-function isTimeout(error) {
+export function isTimeout(error) {
   return error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError');
 }
 
 /** @param {number} status */
-function unavailableReasonFor(status) {
+export function unavailableReasonFor(status) {
   return (
     UNAVAILABLE_BY_STATUS.get(status) ??
     (status >= SERVER_ERROR_STATUS ? 'server_error' : 'unexpected_status')
@@ -165,7 +169,7 @@ export async function checkEngineeringLicense(endpoint, token, options = {}) {
   }
   let text;
   try {
-    text = await boundedText(response);
+    text = await readBoundedText(response);
   } catch (error) {
     return unavailableLicense(isTimeout(error) ? 'timeout' : 'invalid_response');
   }

package/dist/launch.mjs

@@ -13,6 +13,11 @@ import {
   telemetryConfigBinding,
 } from './state.mjs';
 import { codexPolicyJson, makePolicy } from './policy.mjs';
+import {
+  prepareEngineeringPack,
+  sweepStaleLaunches,
+  writeLaunchMarker,
+} from './engineering-pack.mjs';
 import {
   CODEX_LAUNCH_ENVELOPE,
   CODEX_MONITOR_CWD,
@@ -361,14 +366,26 @@ async function assertClaudeCheckpointHelper(packageRoot) {
   return helperPath;
 }
 
-/** @param {string} root @param {string} prefix */
+/**
+ * A fresh private directory for one launch. Directories left by launches whose
+ * processes are gone are swept first; this one records its launcher.
+ * @param {string} root @param {string} prefix
+ */
 async function launchDirectory(root, prefix) {
+  await sweepStaleLaunches(root);
   const parent = await privateDirectory(join(root, 'runtime'));
   const directory = await mkdtemp(join(parent, `${prefix}-`));
   await chmod(directory, 0o700);
+  await writeLaunchMarker(directory, { launcherPid: process.pid, childPid: null });
   return directory;
 }
 
+/** @param {string} directory @param {number | undefined} childPid */
+async function recordChild(directory, childPid) {
+  if (childPid === undefined) return;
+  await writeLaunchMarker(directory, { launcherPid: process.pid, childPid }).catch(() => undefined);
+}
+
 /** @param {import('node:child_process').ChildProcess} child @param {string} directory */
 function waitForChild(child, directory) {
   return new Promise((resolvePromise) => {
@@ -401,8 +418,19 @@ function waitForChild(child, directory) {
   });
 }
 
-/** @param {LaunchConfig} config @param {string} root @param {string[]} args */
-export async function launchClaude(config, root, args) {
+/**
+ * @typedef {object} LaunchDependencies
+ * @property {typeof prepareEngineeringPack} [preparePack] AISAC Engineering pack loader (E4b)
+ */
+
+/**
+ * @param {LaunchConfig} config
+ * @param {string} root
+ * @param {string[]} args
+ * @param {LaunchDependencies} [dependencies]
+ */
+export async function launchClaude(config, root, args, dependencies = {}) {
+  const preparePack = dependencies.preparePack ?? prepareEngineeringPack;
   const validated = assertConfig(config);
   const launchArgs = await parseClaudeLaunchArgs(args, process.cwd());
   assertClaudeArgs(launchArgs.args);
@@ -534,6 +562,15 @@ export async function launchClaude(config, root, args) {
     await rm(directory, { recursive: true, force: true });
     throw error;
   }
+  // The pack never blocks the launch: every failure starts Claude without it.
+  const engineering = await preparePack({
+    endpoint: validated.endpoint,
+    token: validated.token,
+    root,
+    directory,
+    packageRoot: validated.packageRoot,
+  }).catch(() => ({ pluginRoot: null, line: null }));
+  if (engineering.line !== null) process.stderr.write(`${engineering.line}\n`);
   const environment = childEnvironment(root);
   environment.CLAUDE_CODE_ENABLE_FUNCTION_HOOKS = '1';
   /** @type {import('node:child_process').ChildProcess} */
@@ -550,6 +587,7 @@ export async function launchClaude(config, root, args) {
         requiredAllow.join(','),
         '--plugin-dir',
         pluginRoot,
+        ...(engineering.pluginRoot === null ? [] : ['--plugin-dir', engineering.pluginRoot]),
         ...launchArgs.args,
       ],
       { cwd: process.cwd(), env: environment, stdio: 'inherit' },
@@ -558,7 +596,10 @@ export async function launchClaude(config, root, args) {
     await rm(directory, { recursive: true, force: true }).catch(() => undefined);
     throw error;
   }
-  return waitForChild(child, directory);
+  // Listen for exit before any await, so a child that exits at once is not missed.
+  const finished = waitForChild(child, directory);
+  await recordChild(directory, child.pid);
+  return finished;
 }
 
 /** @param {LaunchConfig} config @param {string} root @param {string[]} args */
@@ -640,7 +681,10 @@ export async function launchCodex(config, root, args) {
     env: environment,
     stdio: 'inherit',
   });
-  return waitForChild(child, directory);
+  // Listen for exit before any await, so a child that exits at once is not missed.
+  const finished = waitForChild(child, directory);
+  await recordChild(directory, child.pid);
+  return finished;
 }
 
 export const launchInternals = { MCP_ALIAS, PLUGIN_NAME, PLUGIN_INLINE_NAME };

package/dist/package.json

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

package/package.json

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