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

package/README.md

@@ -1,7 +1,7 @@
 # aisac
 
-The AISAC client for Claude Code and Codex on Linux/WSL, and for Claude Code on
-macOS, 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.
 
@@ -50,8 +50,9 @@ servers: `github` (read-only, token in `GITHUB_PERSONAL_ACCESS_TOKEN`), `supabas
 - **Login:** the host does it (`/mcp` in Claude Code, `aisac mcp login <id>` for Codex)
   and keeps it in its own store. No token reaches `~/.aibrain` or AISAC.
 
-Codex capture also requires the `flock` utility from `util-linux`, normally
-included in Linux/WSL. The launcher and doctor check availability before a
+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,
@@ -102,10 +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. On macOS, `aisac setup` configures Claude Code, and
-`aisac codex` is refused with `CODEX_MACOS_UNSUPPORTED`. Codex capture needs
-Linux procfs and `flock`, so use Codex from Linux/WSL. Pricing and general customer activation are outside
-this beta.
+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/codex-context-compaction.mjs

@@ -1007,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 {
@@ -1025,6 +1147,7 @@ async function captureSentinelOwner(lockPath, fsOps) {
   } catch {
     return { status: 'unverifiable' };
   }
+  if (captureLockHost.platform === 'darwin') return darwinSentinelOwner(value);
   if (
     !isRecord(value) ||
     !hasOnlyKeys(value, [
@@ -1060,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,
@@ -1071,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;
@@ -1149,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) => {

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.10';
+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']);

package/dist/cli.mjs

@@ -17,8 +17,6 @@ import {
 } from './state.mjs';
 import {
   captureLockPlatformCheck,
-  codexPlatformCheck,
-  defaultClientSelection,
   nativeVersion,
   platformCheck,
   resolveNative,
@@ -27,6 +25,7 @@ import { launchClaude, launchCodex } from './launch.mjs';
 import { claudeCompatibilityError, resolveClaudeCompatibility } from './claude-compatibility.mjs';
 import { codexCompatibilityError, resolveCodexCompatibility } from './codex-compatibility.mjs';
 import { providerFreeProbe } from './mcp.mjs';
+import { tokenFailureGuide, tokenPromptGuide } from './token-guide.mjs';
 import { codexPolicyJson, makePolicy, publicPolicy, isProfile } from './policy.mjs';
 import { readDiagnostics } from './claude-observation.mjs';
 import { readCodexDiagnostics } from './codex-diagnostics.mjs';
@@ -42,7 +41,7 @@ import { extensionsSummary, hooksCommand, mcpCommand } from './extensions-cli.mj
 import { sessionServers } from './mcp-servers.mjs';
 import { anyFormatter } from './guardrails/format.mjs';
 
-const VERSION = '0.4.0-beta.10';
+const VERSION = '0.4.0-beta.11';
 // 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';
@@ -117,6 +116,18 @@ async function maskedPrompt() {
   }
 }
 
+/**
+ * A setup error that carries the PAT step-by-step guide when the failure means
+ * the subscriber needs a (different) token.
+ * @param {string} code @param {'pt-BR' | 'en'} locale @param {string} endpoint
+ */
+function setupTokenError(code, locale, endpoint) {
+  const error = new Error(code);
+  const guide = tokenFailureGuide(code, locale, endpoint);
+  if (guide !== null) Object.defineProperty(error, 'guide', { value: guide });
+  return error;
+}
+
 /** @param {string[]} args @param {string} name */
 function option(args, name) {
   const index = args.indexOf(name);
@@ -216,7 +227,7 @@ function selectedPolicy(args, previous) {
     if (option(args, '--goal') === undefined && inherited.goal !== undefined)
       overrides.goal = inherited.goal;
   }
-  const clients = option(args, '--client') ?? defaultClientSelection();
+  const clients = option(args, '--client') ?? 'both';
   if (
     clients === 'codex' &&
     args.some(
@@ -451,12 +462,8 @@ async function setup(args) {
   if (localOptOut) return disableTelemetryLocally(previous);
   const platform = platformCheck();
   if (!platform.ok) throw new Error(`${platform.code}:${platform.message}`);
-  const clients = option(args, '--client') ?? defaultClientSelection();
+  const clients = option(args, '--client') ?? 'both';
   if (!['claude', 'codex', 'both'].includes(clients)) throw new Error('invalid_client');
-  if (clients !== 'claude') {
-    const codexPlatform = codexPlatformCheck();
-    if (!codexPlatform.ok) throw new Error(`${codexPlatform.code}:${codexPlatform.message}`);
-  }
   if (
     clients === 'codex' &&
     (option(args, '--claude-shadow') !== undefined ||
@@ -487,10 +494,18 @@ async function setup(args) {
   )
     throw new Error('disclosure_not_accepted');
   const root = await ensureStateRoot();
+  const locale = resolvePackLocale(lang ?? (await readStoredLocale(root)));
   const tokenPath = option(args, '--token-file');
-  let token = tokenPath ? await readPrivateToken(tokenPath) : await maskedPrompt();
+  if (!tokenPath && stdin.isTTY && stdout.isTTY)
+    console.log(`\n${tokenPromptGuide(locale, endpoint)}\n`);
+  let token;
+  try {
+    token = tokenPath ? await readPrivateToken(tokenPath) : await maskedPrompt();
+  } catch (error) {
+    throw setupTokenError(errorMessage(error), locale, endpoint);
+  }
   token = token.trim();
-  if (!token) throw new Error('empty_token');
+  if (!token) throw setupTokenError('empty_token', locale, endpoint);
   const claude = resolveNative('claude');
   const codex = resolveNative('codex');
   const node = resolveNative('node');
@@ -536,7 +551,7 @@ async function setup(args) {
       ? await providerFreeProbe(endpoint, token, policy, clients)
       : await providerFreeProbe(endpoint, token);
   } catch (error) {
-    throw new Error(`provider_free_probe_failed:${errorMessage(error)}`);
+    throw setupTokenError(`provider_free_probe_failed:${errorMessage(error)}`, locale, endpoint);
   }
   try {
     const configWithToken = { ...config, token, tokenSha256: await tokenDigest(token), probe };
@@ -800,6 +815,8 @@ main(cliArgs).catch((error) => {
     );
   } else {
     console.error(`${COMMAND}: ${errorMessage(error)}`);
+    const guide = /** @type {{ guide?: unknown }} */ (error ?? {}).guide;
+    if (typeof guide === 'string') console.error(`\n${guide}`);
   }
   process.exitCode = 1;
 });

package/dist/launch.mjs

@@ -678,12 +678,7 @@ export async function launchCodex(config, root, args, dependencies = {}) {
   const validated = assertConfig(config);
   assertCodexArgs(args);
   const captureLockPlatform = captureLockPlatformCheck();
-  if (!captureLockPlatform.ok)
-    throw new Error(
-      captureLockPlatform.code === 'CODEX_MACOS_UNSUPPORTED'
-        ? `${captureLockPlatform.code}:${captureLockPlatform.message}`
-        : captureLockPlatform.code,
-    );
+  if (!captureLockPlatform.ok) throw new Error(captureLockPlatform.code);
   const executable = resolveNative('codex');
   const node = resolveNative('node');
   if (!executable || !node) throw new Error('codex_or_node_not_found');

package/dist/package.json

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

package/dist/platform.mjs

@@ -5,8 +5,8 @@ import { spawnSync } from 'node:child_process';
 import { delimiter, isAbsolute, join } from 'node:path';
 
 /**
- * Host operating system gate shared by every command. Linux (including WSL)
- * and macOS run the Claude Code path; Codex has its own gate below.
+ * Host operating system gate shared by every command: Linux (including WSL)
+ * and macOS. Codex capture adds its lock-backend check below.
  * @param {NodeJS.Platform} [platform]
  */
 export function platformCheck(platform = process.platform) {
@@ -29,34 +29,44 @@ export function platformCheck(platform = process.platform) {
 }
 
 /**
- * Codex capture identifies lock owners through Linux procfs (boot id, PID
- * namespace, process start time) and coordinates through util-linux flock.
- * macOS has neither, so Codex stays Linux/WSL-only until a reviewed backend
- * exists (docs/specs/aisac-macos-claude.md).
+ * System tools the macOS capture lock runs by absolute path (ADR-0049): perl
+ * takes flock(2) on the guard descriptor; sysctl and ps identify the owner.
+ */
+export const DARWIN_CAPTURE_TOOLS = Object.freeze(['/usr/bin/perl', '/usr/sbin/sysctl', '/bin/ps']);
+
+/** @param {string} path */
+function isExecutableFile(path) {
+  try {
+    if (!statSync(path).isFile()) return false;
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Codex capture needs a kernel-owned guard lock: util-linux flock on Linux/WSL,
+ * the system perl's flock(2) on macOS (spec codex-macos).
+ * @param {NodeJS.ProcessEnv} [environment]
  * @param {NodeJS.Platform} [platform]
+ * @param {readonly string[]} [darwinTools]
  */
-export function codexPlatformCheck(platform = process.platform) {
+export function captureLockPlatformCheck(
+  environment = process.env,
+  platform = process.platform,
+  darwinTools = DARWIN_CAPTURE_TOOLS,
+) {
   const host = platformCheck(platform);
   if (!host.ok) return host;
-  if (platform === 'darwin')
+  if (platform === 'darwin') {
+    if (darwinTools.every(isExecutableFile)) return { ok: true };
     return {
       ok: false,
-      code: 'CODEX_MACOS_UNSUPPORTED',
-      message:
-        'aisac codex is not available on macOS yet. Use `aisac setup --client claude` and `aisac claude`, or run Codex from Linux/WSL.',
+      code: 'CODEX_CAPTURE_LOCK_BACKEND_UNAVAILABLE',
+      message: `Codex capture on macOS requires ${darwinTools.join(', ')}.`,
     };
-  return { ok: true };
-}
-
-/** Clients configured when `--client` is omitted: only those this OS can run. */
-export function defaultClientSelection(platform = process.platform) {
-  return codexPlatformCheck(platform).ok ? 'both' : 'claude';
-}
-
-/** @param {NodeJS.ProcessEnv} [environment] @param {NodeJS.Platform} [platform] */
-export function captureLockPlatformCheck(environment = process.env, platform = process.platform) {
-  const codex = codexPlatformCheck(platform);
-  if (!codex.ok) return codex;
+  }
   if (resolveNative('flock', environment) === null)
     return {
       ok: false,

package/dist/token-guide.mjs

@@ -0,0 +1,105 @@
+// Step-by-step guidance for obtaining an AI Brain PAT during `aisac setup`.
+// Spec aibrain-subscriber-beta § Setup step 3: guide users to the existing
+// dashboard token flow instead of failing with a bare error code. The text
+// never contains the token or any account data; the URL is the endpoint origin.
+
+const DEFAULT_DASHBOARD = 'https://mcp.ai-brain.aisac.cloud';
+
+/** @typedef {'pt-BR' | 'en'} GuideLocale */
+
+/** Setup failures that mean "you need a (different) token", mapped to a reason key. */
+const TOKEN_FAILURES = Object.freeze({
+  empty_token: 'empty',
+  token_file_required_in_noninteractive_mode: 'noninteractive',
+  'provider_free_probe_failed:mcp_auth_denied': 'denied',
+  'provider_free_probe_failed:mcp_paid_plan_required': 'unlicensed',
+});
+
+const TEXT = Object.freeze({
+  'pt-BR': {
+    intro: 'O aisac precisa de um token pessoal (PAT) do seu AI Brain.',
+    missing: 'Não tem um? Gere em um minuto:',
+    login: (/** @type {string} */ url) =>
+      `  1. Abra ${url} e entre com o MESMO e-mail usado na compra\n     (chega um código de 6 dígitos). A licença fica vinculada a esse e-mail.`,
+    label:
+      '  2. No painel, dê um rótulo (ex.: meu-mac) e escolha o agente\n     (Anthropic para Claude Code, OpenAI para Codex). Isso só organiza a atribuição.',
+    generate: '  3. Clique em "Gerar token" e copie na hora: ele aparece uma única vez.',
+    pasteHere: '  4. Cole abaixo em "AI Brain PAT". A digitação fica oculta.',
+    rerun: '  4. Rode `aisac setup` de novo e cole o token em "AI Brain PAT" (fica oculto).',
+    safety:
+      'Nunca coloque o token em argumento de comando, arquivo do repositório ou perfil do shell.',
+    support: 'Se o e-mail da compra não entrar ou não tiver a licença, fale com o suporte AISAC.',
+    reasons: {
+      empty: 'Nenhum token foi informado.',
+      noninteractive:
+        'Sem um terminal interativo, o token precisa vir de `--token-file` (um arquivo privado, modo 600).',
+      denied:
+        'O AI Brain recusou este token: ele está incompleto, foi revogado ou não existe. Gere um novo.',
+      unlicensed:
+        'Este token pertence a uma conta sem a licença. Gere o token entrando com o e-mail usado na compra.',
+    },
+  },
+  en: {
+    intro: 'aisac needs a personal access token (PAT) from your AI Brain.',
+    missing: "Don't have one? Create it in a minute:",
+    login: (/** @type {string} */ url) =>
+      `  1. Open ${url} and sign in with the SAME email you used to buy\n     (a 6-digit code arrives by email). The license is tied to that email.`,
+    label:
+      '  2. In the dashboard, enter a label (e.g. my-mac) and pick the agent\n     (Anthropic for Claude Code, OpenAI for Codex). It only organizes attribution.',
+    generate: '  3. Click "Gerar token" and copy it right away: it is shown only once.',
+    pasteHere: '  4. Paste it below at "AI Brain PAT". Typing stays hidden.',
+    rerun: '  4. Run `aisac setup` again and paste the token at "AI Brain PAT" (hidden).',
+    safety: 'Never put the token in command arguments, a repository file or a shell profile.',
+    support: 'If the purchase email cannot sign in or has no license, contact AISAC support.',
+    reasons: {
+      empty: 'No token was entered.',
+      noninteractive:
+        'Without an interactive terminal the token must come from `--token-file` (a private file, mode 600).',
+      denied:
+        'AI Brain rejected this token: it is incomplete, revoked or unknown. Create a new one.',
+      unlicensed:
+        'This token belongs to an account without the license. Create the token signed in with the purchase email.',
+    },
+  },
+});
+
+/** The dashboard origin derived from an https endpoint, else the production dashboard. @param {string} endpoint */
+export function dashboardUrl(endpoint) {
+  try {
+    const url = new URL(endpoint);
+    return url.protocol === 'https:' ? url.origin : DEFAULT_DASHBOARD;
+  } catch {
+    return DEFAULT_DASHBOARD;
+  }
+}
+
+/** @param {GuideLocale} locale @param {string} endpoint @param {'prompt' | 'rerun'} step */
+function steps(locale, endpoint, step) {
+  const text = TEXT[locale];
+  return [
+    text.intro,
+    text.missing,
+    text.login(dashboardUrl(endpoint)),
+    text.label,
+    text.generate,
+    step === 'prompt' ? text.pasteHere : text.rerun,
+    text.safety,
+  ].join('\n');
+}
+
+/** Guidance printed right before the masked PAT prompt. @param {GuideLocale} locale @param {string} endpoint */
+export function tokenPromptGuide(locale, endpoint) {
+  return steps(locale, endpoint, 'prompt');
+}
+
+/**
+ * Guidance for a setup failure caused by a missing, rejected or unlicensed token,
+ * or null when the failure has another cause.
+ * @param {string} code @param {GuideLocale} locale @param {string} endpoint
+ */
+export function tokenFailureGuide(code, locale, endpoint) {
+  const reason = /** @type {Record<string, keyof typeof TEXT.en.reasons>} */ (TOKEN_FAILURES)[code];
+  if (reason === undefined) return null;
+  const text = TEXT[locale];
+  return [text.reasons[reason], '', steps(locale, endpoint, 'rerun'), text.support].join('\n');
+}

package/package.json

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