@brunobracaioli/aibrain 0.3.0-beta.7 → 0.4.0-beta.2

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;
+}