@ornexus/neocortex 4.59.1

package/postinstall.js

@@ -0,0 +1,754 @@
+#!/usr/bin/env node
+
+/**
+ * Neocortex - Postinstall Hook
+ *
+ * For global installs: auto-runs the installer in quiet/auto mode.
+ * For local installs: prints usage message.
+ *
+ * NEVER fails npm install -- always exits 0.
+ *
+ * Epic 62 - GAP 6
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+
+const DEFAULT_INITIAL_CHILD_TIMEOUT_MS = 3 * 60 * 1000;
+const DEFAULT_RETRY_CHILD_TIMEOUT_MS = 60 * 1000;
+const DEFAULT_CLEANUP_TIMEOUT_MS = 2 * 1000;
+const DEFAULT_KILL_SIGNAL = 'SIGTERM';
+
+const liveChildren = new Set();
+const PUBLIC_DIAGNOSTIC_PREFIX = '[neocortex-installer]';
+const DEFAULT_OPTIONAL_TOOL_DOC = 'docs/install/coderabbit-manual-setup.md';
+const RAW_DIAGNOSTIC_FIELDS = [
+  'stdout',
+  'stderr',
+  'output',
+  'rawOutput',
+  'rawLog',
+  'logs',
+  'message',
+  'stack',
+];
+
+function clampPublicText(value, maxLength = 160) {
+  const text = String(value ?? '')
+    .replace(/[\r\n\t]+/g, ' ')
+    .replace(/[\x00-\x1F\x7F]/g, '')
+    .replace(/\/home\/[^\s"']+/g, '<redacted-path>')
+    .replace(/\/Users\/[^\s"']+/g, '<redacted-path>')
+    .replace(/C:\\Users\\[^\s"']+/gi, '<redacted-path>')
+    .replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, '<redacted-email>')
+    .replace(/\b(?:NX|ghp|github_pat|ctx7sk|sk|pk)[_-][A-Za-z0-9_.-]{8,}\b/g, '<redacted-token>')
+    .trim();
+  return text.length > maxLength ? `${text.slice(0, Math.max(0, maxLength - 3))}...` : text;
+}
+
+function sanitizeDiagnosticToken(value, fallback = 'unknown', maxLength = 80) {
+  const cleaned = clampPublicText(value ?? fallback, maxLength)
+    .replace(/[^A-Za-z0-9_.:/-]/g, '_')
+    .replace(/_+/g, '_')
+    .replace(/^_+|_+$/g, '');
+  return cleaned || fallback;
+}
+
+function sanitizeReasonCode(value) {
+  return sanitizeDiagnosticToken(value || 'P177_MANDATORY_INSTALL_FAILED', 'P177_MANDATORY_INSTALL_FAILED', 96)
+    .toUpperCase();
+}
+
+function normalizePublicCode(value) {
+  if (value === null || value === undefined) return 'null';
+  if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+  return sanitizeDiagnosticToken(value, 'unknown', 48);
+}
+
+function normalizePublicSignal(value) {
+  if (value === null || value === undefined || value === '') return 'null';
+  return sanitizeDiagnosticToken(value, 'unknown', 48).toUpperCase();
+}
+
+function normalizeRetryAttempt(value) {
+  const parsed = Number.parseInt(String(value ?? 0), 10);
+  if (!Number.isFinite(parsed) || parsed < 0) return 0;
+  return Math.min(parsed, 99);
+}
+
+function normalizeTimeoutMs(value) {
+  const parsed = Number.parseInt(String(value ?? ''), 10);
+  if (!Number.isFinite(parsed) || parsed < 0) return null;
+  return Math.min(parsed, 24 * 60 * 60 * 1000);
+}
+
+function hasRawDiagnosticFields(result = {}) {
+  return RAW_DIAGNOSTIC_FIELDS.some((field) => result[field] !== undefined && result[field] !== null && result[field] !== '');
+}
+
+function deriveDiagnosticStatus(result = {}, reasonCode = '') {
+  if (reasonCode === 'P177_CHILD_SUCCESS') return 'success';
+  if (reasonCode.includes('SKIPPED') || reasonCode.includes('OPT_IN_REQUIRED')) return 'skipped';
+  if (reasonCode.includes('ROOT_HOME') || reasonCode.includes('PARENT_INTERRUPTED')) return 'warning';
+  if (result.timedOut || reasonCode.includes('TIMEOUT')) return 'failed';
+  if (result.signal || reasonCode.includes('SIGNAL')) return 'failed';
+  if (result.errorReason || reasonCode.includes('SPAWN_ERROR')) return 'failed';
+  if (result.code !== 0 && result.code !== null && result.code !== undefined) return 'failed';
+  return 'info';
+}
+
+function buildPublicInstallerDiagnostic(result = {}, options = {}) {
+  const raw = result && typeof result === 'object' ? result : {};
+  const optional = options.optional === true || raw.optional === true;
+  const reasonCode = sanitizeReasonCode(
+    options.reasonCode || raw.reasonCode || classifyChildResult(raw, { optional }),
+  );
+  const tool = sanitizeDiagnosticToken(
+    options.tool || raw.tool || (optional ? 'optional-tool' : 'neocortex'),
+    'neocortex',
+    64,
+  );
+  const phase = sanitizeDiagnosticToken(
+    options.phase || raw.phase || (optional ? 'optional-tool-setup' : 'postinstall-child'),
+    'postinstall-child',
+    96,
+  );
+  const timeoutMs = normalizeTimeoutMs(options.timeoutMs ?? raw.timeoutMs);
+  const redacted = options.redacted === true || hasRawDiagnosticFields(raw);
+  const diagnostic = {
+    tool,
+    phase,
+    status: sanitizeDiagnosticToken(
+      options.status || raw.status || deriveDiagnosticStatus(raw, reasonCode),
+      'info',
+      32,
+    ),
+    reasonCode,
+    code: normalizePublicCode(options.code ?? raw.code),
+    signal: normalizePublicSignal(options.signal ?? raw.signal),
+    timedOut: (options.timedOut ?? raw.timedOut) === true,
+    retryAttempt: normalizeRetryAttempt(options.retryAttempt ?? raw.retryAttempt),
+    optional,
+    summary: clampPublicText(
+      options.summary || raw.summary || publicDiagnosticSummary(reasonCode),
+      220,
+    ),
+  };
+
+  if (timeoutMs !== null) diagnostic.timeoutMs = timeoutMs;
+  if (raw.cleanupTimedOut === true || options.cleanupTimedOut === true) diagnostic.cleanupTimedOut = true;
+  if (raw.errorCode || options.errorCode) {
+    diagnostic.errorCode = sanitizeDiagnosticToken(options.errorCode || raw.errorCode, 'spawn-error', 80);
+  }
+  if (options.docPath || raw.docPath) {
+    diagnostic.docPath = sanitizeDiagnosticToken(options.docPath || raw.docPath, DEFAULT_OPTIONAL_TOOL_DOC, 120);
+  }
+  if (redacted) {
+    diagnostic.redacted = true;
+    diagnostic.redactionReasonCode = 'P177_PUBLIC_SAFE_LOG_REDACTED';
+  }
+
+  return diagnostic;
+}
+
+function publicDiagnosticSummary(reasonCode) {
+  switch (reasonCode) {
+    case 'P177_OPTIONAL_TOOL_SKIPPED_CI':
+      return 'Optional third-party setup skipped in CI; no external installer invoked.';
+    case 'P177_OPTIONAL_TOOL_SKIPPED_NONINTERACTIVE':
+      return 'Optional third-party setup skipped in non-interactive install; no external installer invoked.';
+    case 'P177_OPTIONAL_TOOL_OPT_IN_REQUIRED':
+      return 'Optional third-party setup requires explicit manual opt-in.';
+    case 'P177_OPTIONAL_TOOL_SIGNAL':
+    case 'P177_CHILD_SIGNAL':
+      return 'Child process ended due to a signal; diagnostic is sanitized and bounded.';
+    case 'P177_OPTIONAL_TOOL_TIMEOUT':
+    case 'P177_CHILD_TIMEOUT':
+      return 'Child process exceeded a bounded timeout; raw child output is omitted.';
+    case 'P177_OPTIONAL_TOOL_SPAWN_ERROR':
+    case 'P177_CHILD_SPAWN_ERROR':
+      return 'Child process could not be spawned; diagnostic includes only public error metadata.';
+    case 'P177_PARENT_INTERRUPTED':
+      return 'Parent lifecycle received an interruption and attempted child cleanup.';
+    case 'P177_ROOT_HOME_DETECTED':
+      return 'Elevated install context may target an unintended root-owned HOME.';
+    case 'P177_CHILD_RETRY_EXHAUSTED':
+      return 'Bounded retry budget was exhausted; raw retry output is not persisted.';
+    default:
+      return 'Installer diagnostic emitted with public-safe bounded metadata.';
+  }
+}
+
+function formatPublicInstallerDiagnostic(diagnostic) {
+  const fields = [
+    `tool=${diagnostic.tool}`,
+    `phase=${diagnostic.phase}`,
+    `status=${diagnostic.status}`,
+    `reasonCode=${diagnostic.reasonCode}`,
+    `code=${diagnostic.code}`,
+    `signal=${diagnostic.signal}`,
+    `timedOut=${diagnostic.timedOut === true}`,
+    `retryAttempt=${diagnostic.retryAttempt}`,
+  ];
+  if (diagnostic.timeoutMs !== undefined) fields.push(`timeoutMs=${diagnostic.timeoutMs}`);
+  if (diagnostic.cleanupTimedOut) fields.push('cleanupTimedOut=true');
+  if (diagnostic.errorCode) fields.push(`errorCode=${diagnostic.errorCode}`);
+  if (diagnostic.docPath) fields.push(`docPath=${diagnostic.docPath}`);
+  if (diagnostic.redacted) fields.push(`redactionReasonCode=${diagnostic.redactionReasonCode}`);
+  fields.push(`summary=${JSON.stringify(diagnostic.summary)}`);
+  return `${PUBLIC_DIAGNOSTIC_PREFIX} ${fields.join(' ')}`;
+}
+
+function getSanitizedTroubleshootingText(reasonCode) {
+  const code = sanitizeReasonCode(reasonCode);
+  if (code.includes('SIGNAL') || code === 'P177_PARENT_INTERRUPTED') {
+    return [
+      'Troubleshooting: npm lifecycle observed a sanitized interruption after installer output.',
+      'Retry in a fresh non-sudo shell; optional third-party setup remains manual and raw child output is intentionally omitted.',
+    ];
+  }
+  if (code.includes('TIMEOUT')) {
+    return [
+      'Troubleshooting: a bounded installer child timed out; retry after checking network and shell availability.',
+      'Diagnostics include timeout metadata only and exclude raw child output.',
+    ];
+  }
+  if (code.includes('SPAWN_ERROR')) {
+    return [
+      'Troubleshooting: an installer child could not start; verify required shell tooling is available.',
+      'Diagnostics include sanitized spawn metadata only and exclude local paths or raw error output.',
+    ];
+  }
+  return [];
+}
+
+function parsePositiveInteger(value, fallback) {
+  const parsed = Number.parseInt(String(value || ''), 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function getPostinstallTimeouts(env = process.env) {
+  return {
+    initialMs: parsePositiveInteger(
+      env.NEOCORTEX_POSTINSTALL_TIMEOUT_MS,
+      DEFAULT_INITIAL_CHILD_TIMEOUT_MS,
+    ),
+    retryMs: parsePositiveInteger(
+      env.NEOCORTEX_POSTINSTALL_RETRY_TIMEOUT_MS,
+      DEFAULT_RETRY_CHILD_TIMEOUT_MS,
+    ),
+    cleanupMs: parsePositiveInteger(
+      env.NEOCORTEX_POSTINSTALL_CLEANUP_TIMEOUT_MS,
+      DEFAULT_CLEANUP_TIMEOUT_MS,
+    ),
+  };
+}
+
+function isSuccessfulChildResult(result) {
+  return Boolean(result)
+    && result.code === 0
+    && result.signal === null
+    && result.timedOut !== true
+    && !result.errorReason;
+}
+
+function classifyChildResult(result, options = {}) {
+  const optional = options.optional === true || result?.optional === true;
+  if (!result) return optional ? 'P177_OPTIONAL_TOOL_MISSING_DEPENDENCY' : 'P177_MANDATORY_INSTALL_FAILED';
+  if (result.timedOut) return optional ? 'P177_OPTIONAL_TOOL_TIMEOUT' : 'P177_CHILD_TIMEOUT';
+  if (result.errorReason) return optional ? 'P177_OPTIONAL_TOOL_SPAWN_ERROR' : 'P177_CHILD_SPAWN_ERROR';
+  if (result.signal) return optional ? 'P177_OPTIONAL_TOOL_SIGNAL' : 'P177_CHILD_SIGNAL';
+  if (result.code === 0) return 'P177_CHILD_SUCCESS';
+  if (result.code !== null && result.code !== undefined) return 'P177_CHILD_NONZERO';
+  return optional ? 'P177_OPTIONAL_TOOL_MISSING_DEPENDENCY' : 'P177_MANDATORY_INSTALL_FAILED';
+}
+
+function sanitizeErrorCode(error) {
+  const code = typeof error?.code === 'string' ? error.code : 'spawn-error';
+  return code.replace(/[^A-Z0-9_.-]/gi, '_').slice(0, 80);
+}
+
+function emitPublicDiagnostic(result, runtime = {}) {
+  if (!result?.reasonCode || result.reasonCode === 'P177_CHILD_SUCCESS') return null;
+  const logger = runtime.console || console;
+  const diagnostic = buildPublicInstallerDiagnostic(result, {
+    tool: result.tool || (result.optional ? 'optional-tool' : 'neocortex'),
+  });
+  logger.error(formatPublicInstallerDiagnostic(diagnostic));
+  return diagnostic;
+}
+
+function killChild(child, signal = DEFAULT_KILL_SIGNAL) {
+  try {
+    if (child && typeof child.kill === 'function' && child.killed !== true) {
+      child.kill(signal);
+      return true;
+    }
+  } catch { /* public-safe best effort */ }
+  return false;
+}
+
+function terminateLiveChildren(signal = DEFAULT_KILL_SIGNAL, runtime = {}) {
+  const children = runtime.liveChildren || liveChildren;
+  for (const child of Array.from(children)) {
+    killChild(child, signal);
+  }
+}
+
+function installParentSignalHandlers(runtime = {}) {
+  const processLike = runtime.process || process;
+  const signals = ['SIGINT', 'SIGTERM'];
+  const handlers = [];
+
+  for (const signal of signals) {
+    const handler = () => {
+      const diagnostic = {
+        reasonCode: 'P177_PARENT_INTERRUPTED',
+        phase: 'parent-signal-cleanup',
+        code: null,
+        signal,
+        timedOut: false,
+        retryAttempt: 0,
+      };
+      emitPublicDiagnostic(diagnostic, runtime);
+      terminateLiveChildren(DEFAULT_KILL_SIGNAL, runtime);
+      try { processLike.exitCode = 0; } catch { /* ignore */ }
+      const exitFn = typeof processLike.exit === 'function' ? processLike.exit.bind(processLike) : null;
+      if (exitFn) {
+        const timer = setTimeout(() => exitFn(0), 25);
+        if (typeof timer.unref === 'function') timer.unref();
+      }
+    };
+
+    if (typeof processLike.once === 'function') {
+      processLike.once(signal, handler);
+      handlers.push([signal, handler]);
+    }
+  }
+
+  return () => {
+    for (const [signal, handler] of handlers) {
+      try {
+        if (typeof processLike.off === 'function') processLike.off(signal, handler);
+        else if (typeof processLike.removeListener === 'function') processLike.removeListener(signal, handler);
+      } catch { /* ignore */ }
+    }
+  };
+}
+
+function runBoundedChild(command, args = [], options = {}, runtime = {}) {
+  const spawnFn = runtime.spawn || spawn;
+  const children = runtime.liveChildren || liveChildren;
+  const timeoutMs = parsePositiveInteger(options.timeoutMs, DEFAULT_INITIAL_CHILD_TIMEOUT_MS);
+  const cleanupTimeoutMs = parsePositiveInteger(options.cleanupTimeoutMs, DEFAULT_CLEANUP_TIMEOUT_MS);
+  const killSignal = options.killSignal || DEFAULT_KILL_SIGNAL;
+  const phase = options.phase || 'postinstall-child';
+  const retryAttempt = options.retryAttempt || 0;
+  const optional = options.optional === true;
+  const commandLabel = options.commandLabel || path.basename(String(command || 'child'));
+  const spawnOptions = { ...(options.spawnOptions || {}) };
+
+  return new Promise((resolve) => {
+    let child;
+    let settled = false;
+    let timeout;
+    let cleanupTimeout;
+    const baseResult = {
+      command: commandLabel,
+      phase,
+      code: null,
+      signal: null,
+      timedOut: false,
+      cleanupTimedOut: false,
+      errorReason: null,
+      errorCode: null,
+      retryAttempt,
+      optional,
+      reasonCode: null,
+    };
+
+    const settle = (patch = {}) => {
+      if (settled) return;
+      settled = true;
+      if (timeout) clearTimeout(timeout);
+      if (cleanupTimeout) clearTimeout(cleanupTimeout);
+      const result = { ...baseResult, ...patch };
+      result.reasonCode = result.reasonCode || classifyChildResult(result, { optional });
+      if (child) children.delete(child);
+      resolve(result);
+    };
+
+    try {
+      child = spawnFn(command, args, spawnOptions);
+    } catch (error) {
+      settle({ errorReason: 'spawn-error', errorCode: sanitizeErrorCode(error) });
+      return;
+    }
+
+    if (!child || typeof child.once !== 'function') {
+      settle({ errorReason: 'spawn-error', errorCode: 'invalid-child-process' });
+      return;
+    }
+
+    children.add(child);
+
+    timeout = setTimeout(() => {
+      baseResult.timedOut = true;
+      killChild(child, killSignal);
+      cleanupTimeout = setTimeout(() => {
+        settle({ timedOut: true, cleanupTimedOut: true, signal: killSignal });
+      }, cleanupTimeoutMs);
+      if (runtime.unrefTimers !== false && typeof cleanupTimeout.unref === 'function') cleanupTimeout.unref();
+    }, timeoutMs);
+    if (runtime.unrefTimers !== false && typeof timeout.unref === 'function') timeout.unref();
+
+    child.once('error', (error) => {
+      settle({ errorReason: 'spawn-error', errorCode: sanitizeErrorCode(error) });
+    });
+
+    child.once('close', (code, signal) => {
+      settle({
+        code: code ?? null,
+        signal: signal ?? null,
+        timedOut: baseResult.timedOut,
+      });
+    });
+  });
+}
+
+function isGlobalInstall() {
+  // npm sets npm_config_global=true for global installs
+  if (process.env.npm_config_global === 'true') return true;
+  // Fallback: check if our location is in a global prefix
+  try {
+    const globalPrefix = process.env.npm_config_prefix || '';
+    if (globalPrefix && __dirname.startsWith(globalPrefix)) return true;
+  } catch { /* ignore */ }
+  return false;
+}
+
+function showUsageMessage(runtime = {}) {
+  const logger = runtime.console || console;
+  logger.log('\nNeocortex instalado!\n');
+  logger.log('Uso:');
+  logger.log('  @neocortex @docs/stories/1.1.story.md');
+  logger.log('  @neocortex @epic-1');
+  logger.log('  @neocortex *status\n');
+
+  // Story 32.09: Force stub refresh after successful install
+  if (runtime.forceStubRefresh) runtime.forceStubRefresh();
+  else forceStubRefresh();
+
+  // Story 32.07: Check server compatibility (fire-and-forget)
+  if (runtime.checkServerCompatibility) runtime.checkServerCompatibility();
+  else checkServerCompatibility();
+}
+
+function showErrorMessage(result, runtime = {}) {
+  const logger = runtime.console || console;
+  if (result?.reasonCode) emitPublicDiagnostic(result, runtime);
+  const reasonCode = result?.reasonCode || classifyChildResult(result || {});
+  for (const line of getSanitizedTroubleshootingText(reasonCode)) {
+    logger.error(line);
+  }
+  logger.error('\n[x] Neocortex installation failed.\n');
+  logger.error('Troubleshooting:');
+  logger.error('  1. Try again: npm install -g @ornexus/neocortex');
+  logger.error('  2. Check file permissions in your home directory');
+  logger.error('  3. Report at: https://neocortex.sh/support\n');
+}
+
+async function runInstaller(runtime = {}) {
+  const osRuntime = runtime.os || os;
+  const fsRuntime = runtime.fs || fs;
+  const env = runtime.env || process.env;
+  const logger = runtime.console || console;
+  const platform = runtime.platform || osRuntime.platform();
+  const timeouts = {
+    ...getPostinstallTimeouts(env),
+    ...(runtime.timeouts || {}),
+  };
+
+  // Epic 64: Check NEOCORTEX_DEBUG env var for debug mode
+  const debugMode = env.NEOCORTEX_DEBUG === '1';
+
+  if (platform === 'win32') {
+    // Windows: run install.ps1
+    const scriptPath = path.join(__dirname, 'install.ps1');
+    if (!fsRuntime.existsSync(scriptPath)) {
+      showUsageMessage(runtime);
+      return;
+    }
+
+    const baseFlags = ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', scriptPath];
+    const quietFlags = ['-Yes', '-Quiet', '-SkipProject'];
+    const retryFlags = ['-Yes', '-SkipProject'];
+    if (debugMode) {
+      quietFlags.push('-Debug');
+      retryFlags.push('-Debug');
+    }
+
+    const shells = ['pwsh', 'powershell'];
+    let hasRetried = false;
+
+    async function retryWithoutQuiet(shellCmd) {
+      if (hasRetried) {
+        showErrorMessage({
+          phase: 'windows-retry-exhausted',
+          code: null,
+          signal: null,
+          timedOut: false,
+          retryAttempt: 1,
+          reasonCode: 'P177_CHILD_RETRY_EXHAUSTED',
+        }, runtime);
+        return;
+      }
+      hasRetried = true;
+      logger.log('\nInstalacao falhou. Re-executando com output detalhado...\n');
+      const retryResult = await runBoundedChild(shellCmd, [...baseFlags, ...retryFlags], {
+        phase: 'windows-retry',
+        retryAttempt: 1,
+        timeoutMs: timeouts.retryMs,
+        cleanupTimeoutMs: timeouts.cleanupMs,
+        spawnOptions: { stdio: 'inherit', shell: false },
+      }, runtime);
+      if (isSuccessfulChildResult(retryResult)) {
+        showUsageMessage(runtime);
+      } else {
+        showErrorMessage({ ...retryResult, reasonCode: 'P177_CHILD_RETRY_EXHAUSTED' }, runtime);
+      }
+    }
+
+    async function tryShell(index) {
+      if (index >= shells.length) {
+        // Epic 65: Don't show "Neocortex instalado!" when no shell was found
+        logger.error('\n[!] PowerShell nao encontrado (pwsh ou powershell).');
+        logger.error('    Instale manualmente: npx @ornexus/neocortex\n');
+        emitPublicDiagnostic({
+          phase: 'windows-shell-dispatch',
+          code: null,
+          signal: null,
+          timedOut: false,
+          retryAttempt: 0,
+          reasonCode: 'P177_MANDATORY_INSTALL_FAILED',
+          errorCode: 'powershell-not-found',
+        }, runtime);
+        return;
+      }
+      const result = await runBoundedChild(shells[index], [...baseFlags, ...quietFlags], {
+        phase: 'windows-initial',
+        timeoutMs: timeouts.initialMs,
+        cleanupTimeoutMs: timeouts.cleanupMs,
+        spawnOptions: { stdio: 'inherit', shell: false },
+      }, runtime);
+
+      if (result.errorReason) {
+        await tryShell(index + 1);
+        return;
+      }
+
+      if (isSuccessfulChildResult(result)) {
+        showUsageMessage(runtime);
+      } else {
+        await retryWithoutQuiet(shells[index]);
+      }
+    }
+    await tryShell(0);
+  } else {
+    // Unix: run install.sh
+    const scriptPath = path.join(__dirname, 'install.sh');
+    if (!fsRuntime.existsSync(scriptPath)) {
+      showUsageMessage(runtime);
+      return;
+    }
+
+    try { fsRuntime.chmodSync(scriptPath, '755'); } catch { /* ignore */ }
+
+    const quietArgs = [scriptPath, '--yes', '--quiet', '--skip-project'];
+    const retryArgs = [scriptPath, '--yes', '--skip-project'];
+    if (debugMode) {
+      quietArgs.push('--debug');
+      retryArgs.push('--debug');
+    }
+    let hasRetried = false;
+
+    async function retryUnixWithoutQuiet(shellCmd) {
+      if (hasRetried) {
+        showErrorMessage({
+          phase: 'unix-retry-exhausted',
+          code: null,
+          signal: null,
+          timedOut: false,
+          retryAttempt: 1,
+          reasonCode: 'P177_CHILD_RETRY_EXHAUSTED',
+        }, runtime);
+        return;
+      }
+      hasRetried = true;
+      logger.log('\nInstalacao falhou. Re-executando com output detalhado...\n');
+      const retryResult = await runBoundedChild(shellCmd, retryArgs, {
+        phase: 'unix-retry',
+        retryAttempt: 1,
+        timeoutMs: timeouts.retryMs,
+        cleanupTimeoutMs: timeouts.cleanupMs,
+        spawnOptions: { stdio: 'inherit', shell: false },
+      }, runtime);
+      if (isSuccessfulChildResult(retryResult)) {
+        showUsageMessage(runtime);
+      } else {
+        showErrorMessage({ ...retryResult, reasonCode: 'P177_CHILD_RETRY_EXHAUSTED' }, runtime);
+      }
+    }
+
+    async function tryUnixShell(shellCmd, fallbackShellCmd) {
+      const result = await runBoundedChild(shellCmd, quietArgs, {
+        phase: 'unix-initial',
+        timeoutMs: timeouts.initialMs,
+        cleanupTimeoutMs: timeouts.cleanupMs,
+        spawnOptions: { stdio: 'inherit', shell: false },
+      }, runtime);
+
+      if (result.errorReason && fallbackShellCmd) {
+        const fallbackResult = await runBoundedChild(fallbackShellCmd, quietArgs, {
+          phase: 'unix-fallback',
+          timeoutMs: timeouts.initialMs,
+          cleanupTimeoutMs: timeouts.cleanupMs,
+          spawnOptions: { stdio: 'inherit', shell: false },
+        }, runtime);
+        if (fallbackResult.errorReason) {
+          showErrorMessage(fallbackResult, runtime);
+        } else if (isSuccessfulChildResult(fallbackResult)) {
+          showUsageMessage(runtime);
+        } else {
+          await retryUnixWithoutQuiet(fallbackShellCmd);
+        }
+        return;
+      }
+
+      if (isSuccessfulChildResult(result)) {
+        showUsageMessage(runtime);
+      } else {
+        await retryUnixWithoutQuiet(shellCmd);
+      }
+    }
+
+    await tryUnixShell('bash', 'sh');
+  }
+}
+
+/**
+ * Story 32.09: Force stub refresh by deleting .version files from target directories.
+ * This ensures next invoke detects version mismatch and copies updated stubs.
+ * Fire-and-forget, fail-open.
+ */
+function forceStubRefresh() {
+  try {
+    const homeDir = os.homedir();
+    const targets = [
+      path.join(homeDir, '.claude', 'agents', 'neocortex', '.version'),
+      path.join(homeDir, '.cursor', 'agents', '.version'),
+      path.join(homeDir, '.gemini', 'agents', '.version'),
+      path.join(homeDir, '.codex', '.version'),
+      path.join(homeDir, '.codex', 'agents', '.version'),
+      path.join(homeDir, '.vscode', '.version'),
+      path.join(homeDir, '.agent', 'skills', 'neocortex', '.version'),
+    ];
+
+    for (const versionFile of targets) {
+      try {
+        if (fs.existsSync(versionFile)) {
+          fs.unlinkSync(versionFile);
+        }
+      } catch { /* ignore per-file errors */ }
+    }
+  } catch { /* ignore */ }
+}
+
+/**
+ * Story 32.07: Check server compatibility after install.
+ * Informative only -- never blocks. Timeout 5s, all errors ignored.
+ */
+function checkServerCompatibility() {
+  try {
+    const https = require('https');
+    let clientVersion;
+    try {
+      const pkg = require('./package.json');
+      clientVersion = pkg.version;
+    } catch { return; }
+
+    const serverUrl = 'https://api.neocortex.sh/health';
+
+    const req = https.get(serverUrl, { timeout: 5000 }, (res) => {
+      let data = '';
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => {
+        try {
+          const health = JSON.parse(data);
+          if (health.minClientVersion && !isVersionAtLeastInline(clientVersion, health.minClientVersion)) {
+            console.log('\n[!] Aviso: esta versao do client (' + clientVersion + ') pode nao ser compativel.');
+            console.log('    Versao minima do server: ' + health.minClientVersion);
+            console.log('    Atualize: npm install -g @ornexus/neocortex@latest\n');
+          }
+        } catch { /* ignore */ }
+      });
+    });
+
+    req.on('error', () => { /* ignore - network may not be available */ });
+    req.on('timeout', () => { req.destroy(); });
+  } catch { /* ignore */ }
+}
+
+/**
+ * Story 32.07: Inline semver comparison (no external deps).
+ */
+function isVersionAtLeastInline(version, minVersion) {
+  try {
+    const parse = (v) => {
+      const m = v.replace(/^v/, '').match(/^(\d+)\.(\d+)\.(\d+)/);
+      return m ? [parseInt(m[1]), parseInt(m[2]), parseInt(m[3])] : null;
+    };
+    const v = parse(version);
+    const min = parse(minVersion);
+    if (!v || !min) return true;
+    if (v[0] !== min[0]) return v[0] > min[0];
+    if (v[1] !== min[1]) return v[1] > min[1];
+    return v[2] >= min[2];
+  } catch { return true; }
+}
+
+async function main(runtime = {}) {
+  try {
+    installParentSignalHandlers(runtime);
+    if (isGlobalInstall()) {
+      await runInstaller(runtime);
+    } else {
+      showUsageMessage(runtime);
+    }
+  } catch {
+    // NEVER fail npm install
+    showUsageMessage(runtime);
+  }
+}
+
+if (require.main === module) {
+  // Always exit 0 for npm lifecycle compatibility.
+  process.on('exit', () => { process.exitCode = 0; });
+  main();
+}
+
+module.exports = {
+  buildPublicInstallerDiagnostic,
+  classifyChildResult,
+  formatPublicInstallerDiagnostic,
+  getSanitizedTroubleshootingText,
+  getPostinstallTimeouts,
+  installParentSignalHandlers,
+  isSuccessfulChildResult,
+  main,
+  runBoundedChild,
+  runInstaller,
+  terminateLiveChildren,
+};